Kordant/tasks/web-production/19-accessibility-audit.md

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