--- name: frontend-web-accessibility description: Building accessible web applications --- # Web Accessibility **Scope**: WCAG 2.1 AA, ARIA, keyboard navigation, screen readers, color contrast **Lines**: ~300 **Last Updated**: 2025-10-18 ## When to Use This Skill Activate this skill when: - Building accessible web applications - Implementing WCAG compliance - Supporting keyboard navigation - Designing for screen readers - Testing accessibility - Fixing accessibility issues ## Core Concepts ### WCAG Principles (POUR) **Perceivable** - Information must be presentable to users **Operable** - UI must be operable by all users **Understandable** - Information must be understandable **Robust** - Content must work across technologies ### Conformance Levels **Level A** - Minimum (basic accessibility) **Level AA** - Recommended (target for most sites) **Level AAA** - Enhanced (not always achievable) **Target: WCAG 2.1 AA** for production applications. --- ## Semantic HTML ### Use Correct Elements ```tsx // ❌ Bad: Divs for everything
Click me
Important message
// ✅ Good: Semantic elements
Important message
``` ### Document Structure ```tsx

Page Title

Section Title

Content...

``` ### Heading Hierarchy ```tsx // ❌ Bad: Skipping levels

Page Title

Subsection

Detail
// ✅ Good: Proper hierarchy

Page Title

Section

Subsection

``` **Rules**: - One `

` per page - Don't skip levels (h1 → h3) - Headings describe content --- ## ARIA (Accessible Rich Internet Applications) ### When to Use ARIA **First Rule of ARIA**: Don't use ARIA if you can use native HTML. ```tsx // ❌ Bad: ARIA on native element
Click
// ✅ Good: Native element ``` ### Common ARIA Attributes **aria-label** - Accessible name ```tsx ``` **aria-labelledby** - Reference to label ```tsx

Confirm Delete

...
``` **aria-describedby** - Additional description ```tsx

Must be at least 8 characters

``` **aria-live** - Announce dynamic content ```tsx
{status}
``` **aria-expanded** - Disclosure state ```tsx ``` **aria-hidden** - Hide from screen readers ```tsx 5 stars ``` ### ARIA Roles ```tsx // Navigation landmark // Search landmark
...
// Alert (announces to screen reader)
Error: Form submission failed
// Tab interface
Content
``` --- ## Keyboard Navigation ### Focus Management **Tab Order** - Follow DOM order ```tsx // ❌ Bad: Breaking tab order with CSS
// ✅ Good: DOM order matches visual order
``` **tabIndex** ```tsx // 0 = Natural tab order
Focusable
// -1 = Programmatically focusable (not in tab order)
Not in tab order
// Positive numbers = Custom tab order (avoid!) ``` ### Keyboard Event Handlers ```tsx function KeyboardAccessibleButton({ onClick, children }: { onClick: () => void; children: React.ReactNode; }) { const handleKeyDown = (e: React.KeyboardEvent) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onClick(); } }; return (
{children}
); } // ✅ Better: Just use ``` ### Focus Trap (Modals) ```tsx import { useEffect, useRef } from 'react'; function Modal({ isOpen, onClose, children }: { isOpen: boolean; onClose: () => void; children: React.ReactNode; }) { const dialogRef = useRef(null); useEffect(() => { if (!isOpen) return; const dialog = dialogRef.current; if (!dialog) return; // Focus first focusable element const focusableElements = dialog.querySelectorAll( 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])' ); const firstElement = focusableElements[0] as HTMLElement; const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement; firstElement?.focus(); // Trap focus inside modal const handleTabKey = (e: KeyboardEvent) => { if (e.key !== 'Tab') return; if (e.shiftKey) { if (document.activeElement === firstElement) { e.preventDefault(); lastElement?.focus(); } } else { if (document.activeElement === lastElement) { e.preventDefault(); firstElement?.focus(); } } }; // Close on Escape const handleEscape = (e: KeyboardEvent) => { if (e.key === 'Escape') onClose(); }; dialog.addEventListener('keydown', handleTabKey); dialog.addEventListener('keydown', handleEscape); return () => { dialog.removeEventListener('keydown', handleTabKey); dialog.removeEventListener('keydown', handleEscape); }; }, [isOpen, onClose]); if (!isOpen) return null; return (

Dialog Title

{children}
); } ``` --- ## Screen Reader Support ### Hidden Text for Screen Readers ```tsx // CSS approach ``` ### Live Regions ```tsx function Toast({ message }: { message: string }) { return (
{message}
); } function ErrorAlert({ error }: { error: string }) { return (
{error}
); } ``` **aria-live values**: - `off` - No announcements - `polite` - Announce when idle (default) - `assertive` - Interrupt and announce immediately ### Form Labels ```tsx // ❌ Bad: No label // ✅ Good: Explicit label // ✅ Good: Implicit label // ✅ Good: aria-label (when visual label not desired) ``` --- ## Color and Contrast ### Contrast Ratios (WCAG AA) **Normal text** (< 18pt): 4.5:1 minimum **Large text** (≥ 18pt or 14pt bold): 3:1 minimum ```tsx // ❌ Bad: Insufficient contrast
Text (2.8:1 - fails AA)
// ✅ Good: Sufficient contrast
Text (4.5:1 - passes AA)
``` **Tools**: - Chrome DevTools (Lighthouse) - WebAIM Contrast Checker - Stark (Figma plugin) ### Don't Rely on Color Alone ```tsx // ❌ Bad: Color only Error // ✅ Good: Color + icon + text ``` --- ## Images and Media ### Alt Text ```tsx // ❌ Bad: Missing alt // ❌ Bad: Redundant alt Image of a photo // ✅ Good: Descriptive alt Company Logo // ✅ Good: Decorative image ``` **Alt text guidelines**: - Describe content and function - Keep under 125 characters - Don't start with "Image of" - Empty alt (`alt=""`) for decorative images ### Video Captions ```tsx ``` --- ## Common Accessible Components ### Accessible Button ```tsx ``` ### Accessible Link ```tsx // ❌ Bad: Non-descriptive link Click here // ✅ Good: Descriptive link Download 2025 Annual Report (PDF, 2MB) // ✅ Good: External link Visit Example (opens in new tab) ``` ### Accessible Dropdown ```tsx import { useState } from 'react'; function Dropdown({ label, items }: { label: string; items: Array<{ id: string; label: string; onClick: () => void }>; }) { const [isOpen, setIsOpen] = useState(false); return (
{isOpen && (
    {items.map(item => (
    • ))}
)}
); } ``` --- ## Testing Accessibility ### Automated Testing ```tsx // Jest + Testing Library import { render } from '@testing-library/react'; import { axe, toHaveNoViolations } from 'jest-axe'; expect.extend(toHaveNoViolations); test('should have no accessibility violations', async () => { const { container } = render(); const results = await axe(container); expect(results).toHaveNoViolations(); }); ``` ### Manual Testing **Keyboard navigation**: 1. Tab through all interactive elements 2. Shift+Tab to go backward 3. Enter/Space to activate 4. Arrow keys for custom widgets **Screen reader testing**: - NVDA (Windows, free) - JAWS (Windows, paid) - VoiceOver (macOS, built-in) **Browser DevTools**: - Lighthouse accessibility audit - Accessibility tree inspector - Color contrast checker --- ## Quick Reference ### Accessibility Checklist ``` [ ] Semantic HTML (header, nav, main, footer) [ ] Heading hierarchy (h1 → h6, no skipping) [ ] Alt text for images [ ] Labels for form inputs [ ] Keyboard navigation (Tab, Enter, Space, Esc) [ ] Focus indicators (visible outline) [ ] Color contrast (4.5:1 for text) [ ] ARIA labels for icon buttons [ ] aria-live for dynamic content [ ] Focus trap in modals [ ] Skip navigation link [ ] No reliance on color alone [ ] Descriptive link text [ ] Captions for video ``` ### Common ARIA Patterns ```tsx // Button // Toggle // Expandable // Live region
{message}
// Dialog
// Tab
Content
``` --- ## Common Anti-Patterns ❌ **Div/span as button**: Use `