# A11Y Gate > Audit and fix web accessibility to WCAG 2.2 AA, gated by automated checks that actually run — axe-core via Playwright for violations, scripted keyboard/focus and reflow audits, plus a mandatory manual + screen-reader checklist. Use when the user wants to make a site/app/page accessible, fix a11y or WCAG/ADA/Section 508 issues, add an accessibility CI gate, run an axe/Lighthouse-style audit, check keyboard navigation, color contrast, ARIA, screen-reader support, or remediate accessibility violations. Triggers: "accessibility", "a11y", "WCAG", "ADA compliance", "screen reader", "keyboard navigation", "axe audit". - Skill: `neuralmedic-de/a11y-gate` (Agent Skill, multi-file: 18 files) - Install (CLI): `npx skillmds@latest add neuralmedic-de/a11y-gate` - Raw SKILL.md: https://api.skillmd.com/api/skills/neuralmedic-de/a11y-gate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: NeuralMedic-DE (https://skillmd.com/u/neuralmedic-de) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/neuralmedic-de/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` ```bash 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` ```bash 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` ```bash 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.** `