Accessibility

Accessibility

Overview

WCAG 2.1 AA compliance for React + shadcn/ui — keyboard navigation, screen readers, color contrast, semantic HTML.

When to Use

• Building any new UI component or page
• Before production launch
• When accessibility audit fails
• When adding forms, modals, or interactive elements

Workflow

Phase 1: Semantic HTML

1. Correct heading hierarchy (h1 > h2 > h3, one h1/page)
2. Landmarks: <nav>, <main>, <aside>, <section>
3. <button> for actions, <a> for navigation (never <div onClick>)
4. <label> for all form inputs

Phase 2: Keyboard

1. All interactive elements focusable via Tab
2. Visible focus indicators (shadcn focus-visible ring)
3. Escape closes modals/dropdowns
4. Arrow keys in menus/tabs
5. Test: navigate entire page with keyboard only

Phase 3: Screen Readers

1. aria-label on icon-only buttons:

   <Button variant="ghost" size="icon" aria-label="Close dialog">
     <X className="h-4 w-4" />
   </Button>
   

2. aria-live="polite" on dynamic regions (toasts, loading)
3. role="alert" on error messages
4. aria-hidden="true" on decorative elements

Phase 4: Color & Contrast

1. Text contrast: 4.5:1 minimum (AA)
2. Large text (18px+): 3:1 minimum
3. Never color alone to convey meaning (add icons/text)
4. Test: DevTools > Rendering > Emulate vision deficiencies

Phase 5: Forms

1. Visible labels on every input
2. aria-required="true" on required fields
3. Errors linked with aria-describedby + aria-invalid="true"

Phase 6: Audit

1. Lighthouse Accessibility > 90
2. axe DevTools extension
3. Keyboard-only walkthrough
4. 200% zoom — layout intact

Checklist

• Semantic landmarks and heading hierarchy
• All elements keyboard-accessible
• Visible focus indicators
• aria-label on icon buttons
• aria-live on dynamic content
• 4.5:1 contrast ratios
• Color not sole indicator
• Form labels and error linking
• Lighthouse Accessibility > 90
• Tested keyboard-only + 200% zoom