A11y gate

Accessibility gate (WCAG 2.2 AA, verified)

Make a web UI accessible and prove it — conformance is gated by checks that run (axe-core, scripted keyboard/reflow audits) plus a mandatory human checklist, not by assertion.

Core principle

Conformance is measured, not claimed. The loop is: scan → triage by severity → fix the root cause → re-scan, until the automated gate is green; then complete the manual + screen-reader checklist before sign-off.

Be honest about scope (this is the rule that keeps the skill correct): automated tools catch only ~30–50% of WCAG issues. A green scan is necessary, not sufficient. Never report "WCAG AA conformant" on automated results alone — report "0 blocking automated violations; manual checklist completed and attested." → references/01-standards-and-scope.md

When to use vs. not

• Use for: auditing/fixing accessibility of a site, app, page, or component; adding an a11y CI gate; keyboard/contrast/ARIA/screen-reader review; WCAG / ADA / Section 508 / EAA remediation.
• Not for: native-mobile-only a11y (different tooling), or general UI design with no accessibility ask.

Inputs to gather first

1. What to audit — URL(s)/routes, and key interactive states (menus, modals, tabs). The app must be runnable locally (prefer the production build).
2. Target level — default WCAG 2.2 AA; confirm if a different standard (2.1 AA, AAA, Section 508) is required.
3. Severity bar — default gate blocks on critical + serious; tighten to include moderate for strict sign-off.

Workflow

Load each reference when you reach its step.

1. Set the standard & scope. Confirm WCAG 2.2 AA (or other), and that automated ≠ full conformance. → references/01-standards-and-scope.md

2. Set up the harness. Copy scripts/ into the project, install deps, configure routes + interactive states. → references/02-running-the-audit.md

   npm i -D @playwright/test playwright @axe-core/playwright && npx playwright install chromium
   cp scripts/a11y.config.example.json scripts/a11y.config.json   # edit baseUrl, routes, states
   

3. Run the automated gate against the running app; triage by severity. → references/03-automated-coverage.md

   npm run build && npm run preview &
   npm run a11y:scan        # axe gate -> a11y-report/axe-summary.md
   npm run a11y:keyboard    # keyboard traps / reachability / focus
   npm run a11y:reflow      # 320px reflow (WCAG 1.4.10)
   

4. Fix root causes, semantic HTML first, ARIA only when needed ("no ARIA is better than bad ARIA"); re-scan after each fix. → references/05-remediation-patterns.md

5. Verify keyboard & focus by hand for custom widgets and SPA navigation — the part automation covers least. → references/04-keyboard-and-focus.md

6. Complete the manual + screen-reader checklist (VoiceOver/NVDA, zoom, text spacing, reduced motion, media). → references/06-manual-and-screen-reader.md

7. Gate in CI and record the attestation. → references/07-wcag22-aa-checklist.md

   npm run a11y:test        # CI-grade gate + HTML report (npm run a11y:report)
   

What's in this skill

• scripts/a11y-scan.mjs — axe-core over every route + interactive state; the gate backbone. Writes axe-summary.md + axe-report.json, exits non-zero on blocking impacts.
• scripts/keyboard-audit.mjs — Tab-walks each route: keyboard traps (hard fail), unreachable controls, missing focus indicators (review).
• scripts/reflow-check.mjs — 320px reflow check (WCAG 1.4.10), names the overflowing elements.
• scripts/a11y.spec.ts + playwright.config.ts — CI gate with an HTML report and axe JSON attached.
• scripts/lib/ — config loader + browser/state helpers.
• scripts/a11y.config.example.json — routes, states, tags, severity gate, reflow viewport.
• references/01–07 — standards, running the audit, automated coverage limits, keyboard/focus, remediation patterns, the manual/screen-reader checklist, and the full WCAG 2.2 AA checklist with per-SC test method.

Definition of done

• a11y:scan reports 0 critical/serious violations across all routes and key interactive states (menus, modals open).
• a11y:keyboard finds no keyboard traps; reachability + focus-visibility findings reviewed; custom widgets manually operated.
• a11y:reflow passes at 320px (documented 2D exceptions only).
• axe incomplete items reviewed (contrast over images, etc.).
• Manual + screen-reader checklist (06) completed and attested.
• CI runs a11y:test; report archived; attestation recorded.

Guardrails — avoid these mistakes

• Don't claim "WCAG conformant" from a green scan. State "0 blocking automated violations; manual checklist complete." Overclaiming is the cardinal error here.
• Semantic HTML first. <button>/<a>/<label>/<select> give you keyboard, focus, and roles for free. No ARIA is better than bad ARIA.
• Never remove focus outlines without a visible replacement (use :focus-visible).
• Scan interactive states, not just initial load — most real violations hide in opened menus/modals.
• Don't suppress a rule to go green — disableRules only for verified false positives, with a written reason.
• Audit the production build, not the dev server (overlays cause false positives).
• Placeholders are not labels; color alone is not information.