Accessibility Testing skill for Codex

Done well means: every page and interactive component has an automated axe scan that blocks new serious or critical violations, every release gets a short manual pass for what scanners cannot see (focus order, announcements, meaningful names), and each finding names the WCAG success criterion, the element, and the user who is blocked.

Automated rules catch only part of real barriers (Deque’s own estimate is roughly half by issue volume, far less by criteria). A green axe run means “no machine-detectable defects”, never “accessible”.

Inspect first

1. Read AGENTS.md for the test runner, package manager and CI command.
2. Find existing tooling: rg -n "axe|pa11y|toHaveNoViolations|checkA11y|AxeBuilder" -g '!node_modules'.
3. Identify the surfaces: component tests (Jest/Vitest + Testing Library), E2E (Playwright, Cypress), Storybook (@storybook/addon-a11y), or a list of public URLs.
4. Ask which conformance target applies. Default to WCAG 2.2 level AA unless the user names another (EN 301 549 and Section 508 map onto 2.1 AA).
5. Installing axe packages needs network; in a sandbox with network off, ask for approval or check whether they are already in the lockfile.

Choose where to scan

Surface	Tool	Catches	Misses
Unit/component (jsdom)	jest-axe or vitest-axe	Missing names, bad ARIA, label associations	Contrast (no layout in jsdom), focus, real CSS
Real browser, app flows	@axe-core/playwright	Contrast, hidden content, states after interaction	Anything needing human judgement
Cypress suites	cypress-axe	Same as browser	Same
Storybook	addon-a11y + test runner	Every story state	Page-level landmarks, flows
Static URL list / crawl	pa11y-ci or @axe-core/cli	Quick site sweep	States behind login or interaction

Default: browser-level scans on key pages and states in the existing E2E suite, plus jsdom scans for shared components. jsdom scans alone are not enough because color-contrast is skipped without a real layout.

Component scans (jsdom)

// vitest or jest with Testing Library
import { render } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { axe } from "jest-axe";            // vitest: import { axe } from "vitest-axe"
import { SignupForm } from "./SignupForm";

it("has no detectable a11y violations, including the error state", async () => {
  const { container, getByRole } = render(<SignupForm />);
  await userEvent.click(getByRole("button", { name: /create account/i }));
  expect(await axe(container)).toHaveNoViolations();
});

Register the matcher once in setup (expect.extend(toHaveNoViolations) from jest-axe, or the vitest-axe/extend-expect entry). Scan after interaction too: error messages, open menus and dialogs are where most defects hide.

Browser scans (Playwright)

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

const WCAG = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];

test("checkout page passes axe at WCAG 2.2 AA", async ({ page }) => {
  await page.goto("/checkout");
  await page.getByRole("button", { name: "Apply coupon" }).click();
  const results = await new AxeBuilder({ page })
    .withTags(WCAG)
    .exclude("#third-party-chat")          // not ours; track separately
    .analyze();
  const blocking = results.violations.filter(v => ["serious", "critical"].includes(v.impact ?? ""));
  expect(blocking, JSON.stringify(blocking.map(v => ({ id: v.id, nodes: v.nodes.map(n => n.target) })), null, 2)).toEqual([]);
});

Wrap this in a fixture (makeAxeBuilder) so tags and exclusions live in one place. Cypress equivalent: cy.injectAxe() after cy.visit(), then cy.checkA11y(null, { runOnly: { type: "tag", values: WCAG }, includedImpacts: ["serious", "critical"] }).

Gating policy

Situation	Gate
New suite on a clean app	Fail on any violation
Legacy app with many existing violations	Fail on serious and critical; record the rest in a baseline file keyed by rule id + selector; fail when the baseline grows
incomplete results (axe “needs review”)	Never fail CI; list them for the manual pass
Third-party widgets	Exclude by selector with a comment and an owner; report upstream

Never disable a rule globally to get green. Disable per scan, with a comment naming the reason and an issue link, and only when the rule is a confirmed false positive.

Manual pass

Run it per release and for every new interactive component. The full checklist with WCAG references is in references/manual-checklist.md; read it when doing a release pass or writing up findings. Minimum:

• Keyboard only: reach and operate everything with Tab, Shift+Tab, Enter, Space, arrows, Escape; focus is always visible and never trapped (except inside open modals)
• Focus order follows visual order; focus moves into dialogs and returns on close
• Screen reader (VoiceOver on macOS/iOS, NVDA on Windows): names, roles, states and live announcements (form errors, toasts, cart count) make sense without seeing the screen
• Zoom to 200% and reflow at 320 CSS px width: no loss of content, no two-axis scrolling
• Contrast: text 4.5:1 (3:1 for 18.66px bold / 24px+), UI component and focus indicators 3:1
• Pointer targets at least 24x24 CSS px or adequately spaced (WCAG 2.2, 2.5.8)
• Motion respects prefers-reduced-motion; nothing flashes more than 3 times a second
• Forms: visible labels, errors tied to fields (aria-describedby), no colour-only cues

Codex cannot operate a screen reader. When the pass needs one, write the exact steps and expected announcements for the user to run, and record their results.

Triage a violation

1. Read the rule id and helpUrl in the axe result, then the failing target selector.
2. Reproduce in the browser; confirm it is real (axe false positives are rare but happen with custom shadow DOM and off-screen content).
3. Fix at the shared component when possible, not per page.
4. Add or keep a test that scans the state where it occurred.

Common rule	Usual fix
button-name, link-name	Visible text or aria-label on icon buttons
label	<label for> or wrap the input; placeholder is not a label
color-contrast	Adjust tokens in the design system, not one-off overrides
aria-* attribute rules	Remove ARIA that native elements already provide
region, landmark-*	Wrap content in main, nav, header, footer
nested-interactive	Do not put a button inside a link or clickable card

Verification

• Introduce a deliberate defect (remove a label) and confirm the test fails with a readable message naming the rule and selector; then revert.
• Run the suite twice; scans must be deterministic. Wait for content to settle before analyze() (use a web-first assertion on the final element, not a timeout).
• Confirm CI uploads the violations JSON or HTML report as an artifact.

Output template

## Accessibility test report: <scope>
Target: WCAG 2.2 AA | Tools: axe-core <version> via <runner> | Manual: keyboard, VoiceOver
### Automated
| Page/state | Critical | Serious | Moderate | Minor | Needs review |
### Findings
1. [serious] `color-contrast` - `.price--sale` 3.1:1 on #fff (SC 1.4.3). Users with low
   vision cannot read sale prices. Fix: use `--color-sale-700` (5.2:1).
### Manual pass
- Keyboard: <result>   - Screen reader: <result or steps handed to user>
### Not covered
<states not scanned, third-party widgets excluded, criteria needing human review>

Gotchas

• Scanning only the initial page load misses modals, menus, validation errors and loaded data.
• aria-hidden="true" on a focusable element creates a ghost tab stop; axe flags it, fix it.
• jsdom passes contrast trivially. A component suite with zero contrast failures proves nothing.
• Adding role and aria-* to fix a rule often makes it worse. Prefer the native element.
• Axe versions add rules; pin the version and update deliberately so a dependency bump does not suddenly fail every build.