accessibility-engineering · git:20261116.f9e7e19 · 2026-11-16 · sha256 db13af2af8be2a33
accessibility-engineering git:20261116.f9e7e19A
Immutable. This exact content never changes and is served at /api/v1/blob/db13af2af8be2a33.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_xkfjodwxawriteiu/db13af2af8be2a3342adf4c4c930cf205241ae6a17dcc566a9cffbee01319557.json
Then /plugin install accessibility-engineering@markdownregistry-xkfjodwxawriteiu in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- 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 <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 `<div>` with `<button>`, add `<label>`, set `alt` text 2. **Add ARIA as bridge** — If native HTML can't express the pattern, add ARIA attributes 3. **Test the fix** — Re-run the automated check and manual verification Apply the accessibility checklist (`../../references/accessibility-checklist.md`) as a minimal baseline. ## Common Rationalizations | Rationalization | Reality | |---|---| | "We'll fix a11y later" | Delayed remediation compounds across components and can create legal liability. Audit before shipping. | | "Automated tools caught everything" | Automated checks cannot prove keyboard or screen reader behavior. Manual testing is mandatory. | | "Screen reader users are a tiny minority" | Accessibility is a requirement, not a usage-share calculation. Keyboard navigation, captions, and clear structure also help users across contexts. | | "This is an internal tool, it doesn't need a11y" | Internal tools are subject to the same regulations. Disabled employees and contractors need access. | | "I'll just use aria-label everywhere" | ARIA is a bridge, not a foundation. Semantic HTML first. Overusing ARIA creates maintenance burden and can make things worse. | | "The design system handles accessibility" | Design systems provide accessible primitives. How you compose them determines whether the result is accessible. | | "The audit passed axe-core, so we're done" | Pass axe-core as a smoke test, then test with screen readers and keyboard. A green lighthouse score is not a clean bill of health. | ## Red Flags - Elements that look clickable but aren't keyboard-focusable - Color as the sole indicator of state (red for error, green for success) - Focus outline removed without a visible replacement - Missing labels on form inputs - No heading hierarchy or skipped heading levels - Empty or unlabeled buttons and links - Modals that don't trap focus or restore focus on close - No `alt` text on meaningful images (or `alt=""` missing on decorative ones) - Touch targets that fail SC 2.5.8's 24x24 CSS px size-or-spacing requirement and do not qualify for an exception (AA; 44x44 is the AAA target, SC 2.5.5) - Autoplaying video or audio without controls - Low contrast text (especially on hover, disabled states, placeholders) ## See Also - `../../references/accessibility-checklist.md` — Quick reference for WCAG 2.2 AA - `../frontend-ui-engineering/SKILL.md` — Building accessible components from the start - `../../agents/accessibility-auditor.md` — Dedicated a11y audit persona for deep reviews ## Verification After completing the accessibility workflow: - [ ] Automated audit passes with no Critical or Serious violations - [ ] All interactive elements are keyboard accessible (Tab, Enter, Escape, Arrow keys) - [ ] Screen reader navigation by heading, landmark, and link verified with a named browser + AT pair (or recorded as `manual` and untested — never reported as verified) - [ ] Focus order matches visual order - [ ] Color contrast passes 4.5:1 text / 3:1 large text / 3:1 UI components - [ ] All form inputs have associated labels - [ ] All images have appropriate `alt` text - [ ] Dynamic content changes are announced (aria-live) - [ ] Page is usable at 200% zoom with no content loss - [ ] Touch targets satisfy SC 2.5.8's 24x24 CSS px size-or-spacing requirement or a normative exception (AA); 44x44 is the enhanced AAA target (SC 2.5.5)