--- name: accessibility-engineering description: Audits existing interfaces for WCAG 2.2 AA conformance and remediates the violations found. Use when auditing a page or component for accessibility, running axe-core or pa11y, triaging a11y violations, or checking screen reader and contrast issues before shipping. --- # Accessibility Engineering ## Overview Accessibility is not a polish step — it's a legal requirement in many jurisdictions, an engineering quality standard, and a prerequisite for shipping. This skill audits existing interfaces, triages the findings, and remediates verified violations. The goal is WCAG 2.2 AA compliance supported by automated tools and manual testing. ## When to Use - Before shipping a user-facing change that needs an accessibility audit - When a11y issues are reported (e.g., "screen reader can't read this", "keyboard navigation broken") - When auditing an existing interface for compliance - When triaging axe-core or pa11y findings - When remediating verified accessibility violations **Do NOT use** for building new UI components from scratch; use `frontend-ui-engineering` for construction guidance. Do not use for backend-only changes, CLIs, or library code with no UI output. ## Workflow ### Phase 1: Route New UI Work For component construction, interaction patterns, and focus-management guidance, use `../frontend-ui-engineering/SKILL.md`. Do not restate that skill here. Return to this workflow once an interface exists and needs auditing or remediation. ### Phase 2: Run Automated Audit Execute accessibility checks in this order: ```bash # axe-core rules through pinned @axe-core/cli (the axe-core package ships no CLI) npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --exit # Keep the JSON for the accessibility-auditor npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --dir ./a11y-reports --save axe.json # Pinned pa11y for HTML validation (WCAG2AA rules via HTML_CodeSniffer) npx --yes pa11y@9.1.1 http://localhost:3000 ``` For a combined report, run `bash skills/accessibility-engineering/scripts/audit-a11y.sh url --json`. It runs both pinned tools, records their status and versions, and fails rather than reporting a clean result when either tool does not produce a valid report. Review the violations grouped by severity: - **Critical** — Blocks screen reader access entirely (missing alt text on info images, empty buttons) - **Serious** — Makes content difficult or impossible to access (low contrast, missing labels) - **Moderate** — Causes confusion or extra effort (heading level skips, redundant ARIA) - **Minor** — Cosmetic or progressive enhancement (missing lang attribute on inner elements) For each violation, verify it's a real issue (not a false positive) by inspecting the element in the browser. ### Phase 3: Manual Testing Automated checks are a smoke test, not proof of conformance. Complete the audit manually. **Keyboard audit:** 1. Tab through every interactive element — can you see where you are? 2. Activate buttons and links with Enter/Space 3. Close modals with Escape 4. Navigate lists with Arrow keys 5. Verify no keyboard traps exist **Screen reader audit (VoiceOver on macOS, NVDA on Windows):** 1. Navigate by heading (VoiceOver: Ctrl+Option+Cmd+H) — is the structure logical? 2. Navigate by landmark (open the rotor with Ctrl+Option+U, choose Landmarks) — are regions labeled? 3. Navigate by link (open the rotor with Ctrl+Option+U, choose Links) — do link descriptions make sense out of context? 4. Interact with a form — are labels announced? Are error messages read? 5. Navigate a dynamic update — are changes announced? **Visual audit:** 1. Verify color contrast (4.5:1 text, 3:1 large text, 3:1 UI components) 2. Zoom to 200% — does layout break or overlap? 3. Test with forced colors / high contrast mode (Windows High Contrast) 4. Reduce motion (prefers-reduced-motion) — are animations disabled? 5. Test focus visibility — is the focus ring visible against all backgrounds? ### Phase 4: Fix Violations For each finding, apply the remediation in order: 1. **Fix the root cause** — Replace a `
` with `