# 19. Accessibility Audit & WCAG Compliance

meta:
  id: web-production-19
  feature: web-production
  priority: P2
  depends_on: []
  tags: [testing, accessibility, compliance]

objective:
- Ensure the web application meets WCAG 2.1 AA standards and is usable by people with disabilities

deliverables:
- Automated accessibility testing with axe-core
- Manual keyboard navigation audit
- Screen reader testing
- Accessibility statement page

steps:
1. Set up automated accessibility testing:
   - Install @axe-core/react or jest-axe
   - Add accessibility tests to component test suite
   - Integrate axe-core with Playwright E2E tests
   - Fail build on critical accessibility violations
2. Run automated audit:
   - Test all pages: landing, auth, dashboard, settings
   - Check for: missing alt text, low contrast, missing labels, focus issues
   - Generate report with violation severity
3. Manual keyboard navigation audit:
   - Navigate entire app using only Tab, Enter, Space, Escape
   - Verify focus indicators visible on all interactive elements
   - Test skip links and logical tab order
   - Verify no keyboard traps
4. Screen reader testing:
   - Test with NVDA (Windows) or VoiceOver (macOS)
   - Verify all interactive elements have accessible names
   - Test live regions for dynamic content (alerts, toasts)
   - Verify form error messages announced
5. Fix critical issues:
   - Add missing aria-labels and aria-describedby
   - Fix color contrast ratios (minimum 4.5:1 for normal text)
   - Ensure all images have alt text
   - Add proper heading hierarchy (h1 → h2 → h3)
6. Create accessibility statement:
   - Page at /accessibility
   - Commitment to WCAG 2.1 AA
   - Known limitations
   - Contact for accessibility feedback
7. Add accessibility CI check:
   - Lighthouse accessibility audit >95
   - axe-core scan in CI pipeline

tests:
- Automated: axe-core scan passes with 0 violations
- Manual: Keyboard navigation completes all flows
- Screen reader: All critical paths navigable

acceptance_criteria:
- WCAG 2.1 AA compliance on all pages
- Lighthouse accessibility score ≥ 95
- 0 critical or serious axe-core violations
- All interactive elements keyboard accessible
- Focus indicators visible and logical
- All images have descriptive alt text
- Color contrast ratios ≥ 4.5:1 for normal text
- Accessibility statement page live

validation:
- Run axe-core → 0 critical/serious violations
- Lighthouse CI → Accessibility score ≥ 95
- Navigate with keyboard only → complete signup flow
- Screen reader test → all elements announced correctly

notes:
- Current app has some accessibility features (skip link, aria-live) but needs audit
- SolidJS components need proper aria attributes
- Consider using Radix UI primitives for built-in accessibility
- Test with actual assistive technology, not just automated tools