A11y Compliance Testing

Your company just received a demand letter citing ADA non-compliance on your web application. The legal team is alarmed, and engineering discovers that the signup form has no label associations, the navigation is unusable with a keyboard, and the color contrast on half the call-to-action buttons fails WCAG AA standards. Accessibility is not a nice-to-have — it is a legal requirement and an engineering discipline that AI tools can dramatically accelerate.

What You’ll Walk Away With

• Automated WCAG 2.2 AA compliance testing integrated into your CI pipeline
• AI-powered accessibility auditing that explains violations and generates fixes
• Playwright-based accessibility test patterns for E2E flows
• Keyboard navigation and screen reader testing workflows
• Prompts that generate accessible code from the start

Automated WCAG Auditing

Using axe-core with AI Analysis

Cursor

Set up automated accessibility testing for our Next.js application:

1. Install @axe-core/playwright for Playwright integration
2. Create an accessibility test helper at /tests/a11y/audit-helper.ts that:
   - Runs axe-core on any page
   - Filters results by WCAG 2.2 AA criteria
   - Categorizes violations by severity (critical, serious, moderate, minor)
   - Generates fix suggestions for each violation

3. Create accessibility tests for our critical pages:
   - /tests/a11y/pages/homepage.a11y.spec.ts
   - /tests/a11y/pages/login.a11y.spec.ts
   - /tests/a11y/pages/dashboard.a11y.spec.ts
   - /tests/a11y/pages/settings.a11y.spec.ts

4. Each test should:
   - Run the full axe audit
   - Fail on critical and serious violations
   - Report moderate violations as warnings
   - Test at both desktop and mobile viewports

Follow our Playwright config in playwright.config.ts

Claude Code

claude "Set up accessibility testing infrastructure:

1. Install: npm install -D @axe-core/playwright
2. Create /tests/a11y/run-audit.ts:
   - Accept a URL and Playwright page
   - Run axe-core with WCAG 2.2 AA rules
   - Return structured results with fix suggestions
3. Create tests for all routes in our application:
   - Discover routes from /src/pages/ directory
   - Generate an a11y test for each page
   - Save to /tests/a11y/pages/
4. Run all accessibility tests
5. Generate a compliance report at /docs/a11y-report.md

For each violation found, include:
- The WCAG criterion it violates
- The HTML element causing the violation
- A specific code fix"

Codex

Set up WCAG 2.2 AA compliance testing:
1. Add axe-core to our Playwright test infrastructure
2. Create accessibility tests for every page
3. Run the audit and generate a compliance report
4. Create fixes for any critical violations found
5. Create a PR with tests, fixes, and the compliance report

Tip

Copy-paste prompt for accessibility audit and fix:

Run an accessibility audit on our React component library (/src/components/ui/).

For each component, check:
1. Do all interactive elements have accessible names? (buttons, links, inputs)
2. Do all form inputs have associated labels? (not just placeholder text)
3. Do all images have meaningful alt text? (or alt="" for decorative)
4. Are ARIA roles used correctly? (no redundant roles on semantic HTML)
5. Is the focus order logical? (follows visual layout)
6. Do custom components (dropdowns, modals, tabs) have correct ARIA patterns?
7. Are color contrast ratios at least 4.5:1 for text and 3:1 for large text?

For each violation:
- Show the current code
- Show the fixed code
- Explain which WCAG criterion it violates and why it matters

Keyboard Navigation Testing

Tip

Copy-paste prompt for keyboard navigation tests:

Generate Playwright tests that verify keyboard navigation for our application:

1. Tab order test:
   - Start at the top of the page
   - Tab through every interactive element
   - Verify the focus order matches visual order
   - Verify no elements are skipped
   - Verify focus is visible on every element

2. Modal keyboard trap:
   - Open a modal dialog
   - Verify focus moves to the modal
   - Tab should cycle within the modal (not escape to the page behind)
   - Escape key should close the modal
   - Focus should return to the trigger element

3. Form navigation:
   - Tab through all form fields
   - Enter should submit the form
   - Error messages should be announced (use aria-live or role="alert")
   - Required field indicators should be accessible

4. Dropdown/menu navigation:
   - Arrow keys navigate between items
   - Enter/Space selects an item
   - Escape closes the dropdown
   - Home/End jump to first/last item

Save to /tests/a11y/keyboard-navigation.spec.ts

Generating Accessible Code from the Start

Instead of auditing and fixing, generate accessible code from the beginning.

Tip

Copy-paste prompt for accessible component generation:

Create an accessible dropdown select component for React (TypeScript):

Requirements:
- Follows the ARIA combobox pattern (WAI-ARIA 1.2)
- Keyboard navigation: Arrow Up/Down to navigate, Enter to select, Escape to close
- Screen reader announcements for: opening, closing, selection changes, option count
- Visual focus indicator that meets WCAG 2.2 AA (3:1 contrast, 2px minimum)
- Support for grouped options with group labels
- Support for disabled options
- Search/filter functionality with aria-live announcements

Do NOT use a native select element - this is a custom implementation.
Include all ARIA attributes: role, aria-expanded, aria-activedescendant,
aria-haspopup, aria-label, aria-selected, aria-disabled.

Include a Storybook story showing all states: default, open, with selection,
disabled, with groups, with search.
Include unit tests that verify ARIA attribute states change correctly.

CI Integration for Accessibility

1. Run axe-core on every PR

   Add accessibility testing to your CI pipeline. Fail the build on critical and serious violations.

2. Track compliance over time

   Store audit results and trend them. Your compliance score should improve over time, not degrade.

3. Prevent new violations

   The most important gate: no new critical or serious accessibility violations in any PR. Existing violations can be tracked in a backlog.

4. Weekly accessibility report

   Generate a report showing: total violations by severity, new violations this week, resolved violations, compliance percentage by page.

When This Breaks

“axe-core reports hundreds of violations and it is overwhelming.” Start by fixing only critical violations. These are the ones that completely block users from accessing content. Move to serious, then moderate. Do not try to fix everything at once.

“The AI generates accessible code but it looks different from our design system.” Add your design system constraints to the prompt: “Use our existing color palette. Focus indicator must be our brand blue (#2563eb) with a 2px offset.” Accessible does not mean ugly — it means intentional.

“Screen reader testing is manual and slow.” Automated tests catch 30-40% of accessibility issues. The rest require manual testing with screen readers (VoiceOver, NVDA). Use AI to generate a manual test checklist for QA, focusing on the interactions that automated tools miss.

“Developers do not know enough about accessibility to fix violations.” The AI prompts in this guide generate both the fix and the explanation. Developers learn accessibility by fixing real violations with context, not by reading documentation.

What’s Next

E2E Testing Integrate accessibility checks into your E2E test flows.

Mobile Testing Accessibility testing on mobile platforms.

Code Quality Add accessibility as a quality gate in your pipeline.