A React application demonstrating accessibility best practices side-by-side with common accessibility problems. Perfect for learning sessions and training on web accessibility.
This demo is designed for educational purposes to:
- Show common accessibility mistakes developers make
- Demonstrate the correct, accessible way to implement features
- Provide hands-on experience with accessibility testing tools
- Help developers understand WCAG guidelines in practice
- Node.js 14+ installed
- npm or yarn package manager
# Install dependencies
npm install
# Start the development server
npm startThe application will open in your browser at http://localhost:3000
-
Headings Structure
- ❌ Bad: Divs styled to look like headings
- ✅ Good: Semantic heading hierarchy (h1, h2, h3)
-
Images & Alt Text
- ❌ Bad: Images without alt attributes
- ✅ Good: Descriptive alt text that conveys meaning
-
Form Accessibility
- ❌ Bad: Inputs without labels, unclear error messages
- ✅ Good: Proper labels, clear error messages, field relationships
-
Button Implementation
- ❌ Bad: Divs styled as buttons (no keyboard support)
- ✅ Good: Semantic button elements with full keyboard support
-
Color Contrast
- ❌ Bad: Low contrast text (WCAG failures)
- ✅ Good: High contrast meeting WCAG AA standards
-
Focus Indicators
- ❌ Bad: No visible focus styles
- ✅ Good: Clear, high-contrast focus indicators
-
Link Accessibility
- ❌ Bad: "Click here" and non-descriptive links
- ✅ Good: Descriptive link text with context
-
List Structure
- ❌ Bad: Divs with bullet characters
- ✅ Good: Semantic ul/li markup
-
Navigation
- ❌ Bad: Non-semantic navigation divs
- ✅ Good: Semantic nav with skip links and proper structure
-
Complex Forms
- ❌ Bad: No field relationships or instructions
- ✅ Good: Fieldsets, legends, and clear instructions
The application includes toggles at the top to show/hide columns:
- Show Bad Examples: Toggle the left column on/off
- Show Good Examples: Toggle the right column on/off
This allows you to focus on one side at a time during presentations.
-
axe DevTools (Browser Extension)
- Chrome: axe DevTools
- Firefox: axe DevTools
-
Lighthouse (Built into Chrome DevTools)
- Open DevTools → Lighthouse tab
- Select "Accessibility" category
- Generate report
-
WAVE (Browser Extension)
-
Screen Readers
- macOS: VoiceOver (built-in) -
Cmd + F5 - Windows: NVDA (free) - Download NVDA
- Windows: JAWS (commercial)
- macOS: VoiceOver (built-in) -
-
Run axe DevTools:
- Open the demo in Chrome
- Open DevTools (F12)
- Go to axe DevTools tab
- Click "Scan ALL of my page"
- Compare results between Bad and Good examples
-
Test with Keyboard Navigation:
- Use
Tabto navigate through interactive elements - Use
Shift + Tabto navigate backwards - Notice the difference in focus indicators
- Try activating buttons with
EnterorSpace
- Use
-
Test with Screen Reader:
- Enable VoiceOver (macOS) or NVDA (Windows)
- Navigate through the page and hear how content is announced
- Compare how headings, forms, and lists are read aloud
-
Check Color Contrast:
- Use browser zoom to 200%
- Notice readability differences
- Use Lighthouse to check contrast ratios
After using this demo, participants should understand:
- Why semantic HTML matters for accessibility with live feedback
- How to write proper alt text for images through interactive demos
- The importance of form labels and error handling
- How color contrast affects readability
- Why keyboard navigation support is crucial with real-time tracking
- How to structure content for screen readers with simulation
- WCAG 2.1 Guidelines and compliance levels
- New: Real-time accessibility testing and scoring
- New: What screen readers actually announce
- New: How to identify accessibility barriers quickly
-
Start with Bad Examples:
- Show only the bad column initially
- Run accessibility tests to show failures
- Demonstrate keyboard navigation problems
-
Reveal Good Examples:
- Toggle on the good column
- Run tests again to show improvements
- Demonstrate proper keyboard navigation
-
Interactive Elements:
- Have participants test with keyboard navigation
- Let them run accessibility scanning tools
- Encourage screen reader testing
-
Code Review:
- Show the source code differences
- Explain the comments in each example
- Discuss WCAG guideline connections
- Legal Requirements: ADA compliance and lawsuits
- User Impact: How accessibility barriers affect real users
- SEO Benefits: Many accessibility practices improve SEO
- Developer Experience: Tools and workflows for accessible development
- Progressive Enhancement: Building accessible from the start
The demo is designed to be easily customizable:
- Toggle Columns: Comment out sections in
App.js - Add Examples: Create new sections in
BadExamples.jsandGoodExamples.js - Modify Styles: Edit
Examples.cssto change visual presentation - Update Content: Modify text and examples to match your audience
- Some npm dependencies may show security warnings (common with React projects)
- The demo intentionally includes accessibility violations in the "Bad" column
- Focus styles may look different across browsers (this is expected)
This project is open source and available under the MIT License.
Happy Learning! 🌟
Use this demo to create more accessible web experiences and help spread awareness about the importance of web accessibility.