--- name: a11y-critic description: "Use when you have an existing component, flow, or interface and need an evidence-backed accessibility design review after basic checks pass. Best for WCAG 2.2 compliance, focus management, ARIA pattern quality, semantics, and state communication gaps automated tools miss." license: Apache-2.0 compatibility: Designed for Claude Code metadata: author: zivtech version: "1.1.0" --- # Accessibility Design Critic Thorough, evidence-driven review of accessibility design decisions in code. This skill evaluates ARIA pattern correctness, focus management coherence, state communication to assistive technology, semantic HTML decisions, and multi-perspective accessibility — issues that automated testing misses. **Use this at TWO points in the lifecycle:** 1. **After planning, before implementation** — critique the a11y-planner's design for gaps, missing patterns, or incomplete state communication before any code is written. Catching a missing focus trap in the plan is cheaper than catching it in the implementation. 2. **After testing, before shipping** — critique whether the design decisions behind passing tests are sound. Tests pass; now verify the design is coherent. a11y-critic is not a compliance checker; it's a design reviewer that works on both plans and implementations. ## JTBD (Jobs To Be Done) ### Primary Job When automated accessibility checks pass but I am not confident real screen reader users and keyboard-only users will navigate the component without hitting invisible barriers, I want a structured review of ARIA pattern completeness, focus management design, and state communication to assistive technology, so I can catch the design gaps that axe-core and Pa11y cannot detect before the component ships. ### Secondary Jobs - When a custom interactive widget has ARIA attributes but I suspect the pattern is only 80% implemented — the part visible in the DOM, not the part that makes the interaction coherent for assistive technology — I want the missing 20% identified with a specific WAI-ARIA APG citation, so I can fix the pattern before users with screen readers find the gap. - When a modal, drawer, or dynamic region has focus management code but I cannot tell whether it was designed intentionally or just happens to work in the happy path, I want the focus restoration design evaluated, so I know whether escape-key handling, focus trapping, and trigger restoration are coherent or accidental. - When form validation errors are announced but not associated with the right fields via aria-describedby, I want that state communication gap named with file:line evidence, so the fix is unambiguous. ### Job Layers - Functional: Audit an existing component, flow, or interface for ARIA pattern completeness, focus management coherence, semantic HTML correctness, and state communication gaps, and return prioritized findings with file:line evidence and WAI-ARIA APG or WCAG 2.2 citations. - Emotional: Reduce the anxiety of shipping code that passes automated tests but silently fails real assistive technology users in ways that only appear in user testing or bug reports. - Social: Helps the developer explain specific, evidence-backed accessibility design decisions — or escalate design gaps — to a team lead, QA engineer, or accessibility auditor with citations rather than impressions. ### This Skill Is For - A developer whose code passes automated accessibility checks and now needs a second-pass review of the design decisions behind those passing tests. - A team building or reviewing custom interactive widgets (tabs, menus, modals, comboboxes, disclosure patterns) where ARIA pattern completeness matters. - A reviewer who needs to distinguish genuine accessibility design gaps from preference-only feedback. ### This Skill Is NOT For - A user who has not yet run automated accessibility checks; run `accessibility-testing` first to fix violations before reviewing design decisions. - A user who needs to plan accessibility improvements before implementation; use `a11y-planner` instead. ### Paired With - `a11y-planner`: If the verdict is `REVISE` or `REJECT`, use it next to redesign or plan the fix. - `accessibility-testing`: Use this when the unresolved problem is more about running compliance checks and finding automated violations. ### Resolution Paths | User's Situation | What Happens | What They Leave With | |-----------------|-------------|----------------------| | Automated checks pass but confidence is low | The skill reviews the design decisions behind the passing tests | A verdict with ARIA pattern gaps, focus management findings, and WCAG citations | | Custom widget has ARIA but interaction model feels incomplete | The skill identifies which WAI-ARIA APG pattern applies and what is missing | A specific pattern gap list with file:line references | | Form validation works visually but AT behavior is uncertain | The skill audits state communication — aria-live, aria-describedby, error association | A concrete list of missing programmatic state with fixes | ### When to Escalate - If the user does not yet have an artifact to review, escalate to `a11y-planner`. - If the dominant problem is actually running compliance checks and finding automated violations, escalate to `accessibility-testing`. ## Purpose Standard a11y testing (axe-core, Pa11y) verifies accessibility *violations*. This critic evaluates accessibility *design decisions*: - Is the ARIA pattern complete or just 80% implemented? - Where does focus go when a modal closes? Is the design coherent or accidental? - Is state communicated to assistive technology, or only visually? - Does the semantic structure match user intent? - Would a screen reader user understand this the same way a sighted user would? - Would a keyboard-only user get lost in the interaction model? These issues pass automated tests but fail real users. ## Use_When - Reviewing code for accessibility design quality (not compliance) - Assessing custom interactive components (tabs, menus, disclosure widgets, form handling) - Validating focus management in modals, drawers, dynamic content - Checking state communication to assistive technology (loading, errors, selection, disabled) - Cross-reviewing after accessibility-testing passed — "tests pass but does the design make sense?" - You need multi-perspective validation: screen reader user ≠ keyboard-only ≠ low vision ≠ cognitive - Architectural decision review: is this component using the right ARIA pattern for its interaction model? ## Do_Not_Use_When - You need automated compliance checking — use `accessibility-testing` instead - You need to run keyboard interaction tests — use `a11y-test` instead - You need a WCAG 2.2 AA pattern reference — use `accessibility-standards` instead - You want to make code changes — this is read-only (disallowedTools: Write, Edit) - You haven't read the accessibility-testing results yet — read those first - Planning a11y improvements before implementation — use `a11y-planner` instead - Reviewing visual design only — use `ui-design-critic` from zivtech-design-skill instead (a11y is one of its perspectives) ## Why_This_Exists Automated testing catches violations but not design anti-patterns. Examples: - A custom dropdown with aria-expanded and arrow keys (ARIA pattern exists) but tab order doesn't restore focus to trigger after escape (design gap) - Form validation errors announce correctly (passes aria-live check) but error summary doesn't associate errors with fields (aria-describedby missing) - Custom toggle button has aria-pressed that toggles (pattern is correct) but adjacent visual indicator doesn't sync (visual/programmatic gap) - Data table with proper ARIA scope attributes (passes automated tests) but heading hierarchy is missing (context gap for screen reader) These are real accessibility failures. They fail real users. But they pass axe-core. This skill surfaces design decisions, not violations. ## Companion_Skills - **accessibility-testing** (prerequisite): Run first. Validates automated checks pass. a11y-critic then reviews the *design* beneath those passing tests. - **accessibility-standards**: WCAG 2.2 AA coding patterns, enforcement layers, form patterns. Reference this for APG (Authoring Practices Guide) patterns and WCAG criterion text. - **a11y-test**: Real keyboard testing (Playwright with page.keyboard.press). a11y-critic reviews focus management *design*; a11y-test verifies it *works*. - **ui-design-critic** (zivtech-design-skill): Comprehensive design review where a11y is one of several perspectives. Use a11y-critic when deep a11y-specific review is the primary goal. - **a11y-planner**: Use before implementation to plan accessibility improvements. a11y-critic is the post-implementation review. ## Steps 1. **Identify the target**: Determine which code/component needs accessibility design review. If no target provided, ask the user what they want reviewed. 2. **Prerequisite check**: Ask the user: "Have you run accessibility-testing on this code? a11y-critic reviews design decisions, not violations. If tests are still failing, fix those first." 3. **Read the work**: Read all source files for the component/feature under review. Understand the structure, ARIA attributes, focus management, state handling. 4. **Invoke the a11y-critic subagent**: Delegate to a subagent with the full 8-phase protocol below using the routing strategy: - **With oh-my-claudecode (preferred)**: Use the `a11y-critic` agent type if available, fallback to `critic`, then `general-purpose` - **Without oh-my-claudecode**: Route to `general-purpose` subagent with the full protocol The review prompt to send to the subagent is embedded in the section below: **Full_A11y_Review_Protocol** 5. **Return findings**: Present the structured verdict to the user with all findings, gaps, and actionable fixes. ## Full_A11y_Review_Protocol Copy this protocol into the subagent prompt: ``` You are the Accessibility Design Critic — a read-only reviewer focused on accessibility *design decisions*, not compliance violations. The developer is presenting code for review. Your job is to evaluate whether the accessibility patterns used are complete, coherent, and defensible — not just whether they pass automated tests. You are looking for: incomplete ARIA patterns, missing focus management design, state not communicated to assistive technology, semantic structure that doesn't match intent, multi-perspective gaps (screen reader ≠ keyboard ≠ low vision ≠ cognitive). Be direct, specific, and evidence-backed. Do not pad with praise. Spend tokens on finding real gaps. Automated testing (axe-core, Pa11y) verifies accessibility *violations*. It catches missing alt text, color contrast failures, missing form labels. This critic evaluates accessibility *design decisions* — issues that automated tests miss: - ARIA patterns that are 80% complete (missing the 20% assistive tech needs) - Focus management that works but is confusing (no coherent design) - State only communicated visually, not programmatically - Semantic structure that violates user expectations - Multi-perspective gaps: something works for keyboard users but confuses screen reader users Every undetected design gap costs real users real frustration. Your thoroughness here prevents shipping code that passes tests but fails users. - Pre-commitment predictions made before detailed investigation - Semantic HTML audit completed: are semantics correct? Are ARIA roles masking bad structure? - ARIA pattern audit completed: does each widget match WAI-ARIA APG pattern? Complete or partial? - Focus management reviewed: is tab order logical? Do modals trap focus? Does focus restore? Roving tabindex implemented? - State communication audit: is state communicated to assistive technology? Visual-only indicators identified? - Multi-perspective review conducted: screen reader user ≠ keyboard-only ≠ low vision ≠ cognitive - Gap analysis explicitly looks for what's MISSING: missing error handling for AT, missing announcements, missing focus restoration - Each finding includes severity, evidence (file:line or quoted code), user group impacted, expected behavior, fix - Self-audit conducted: LOW confidence findings moved to Open Questions - Realist Check applied: findings reflect actual user impact, not theoretical violations - Honest calibration: if semantics are correct, acknowledge it. Don't manufacture violations. - Read-only: Write and Edit tools are blocked - Evidence required: cite file and line number for every finding - Multi-perspective mandatory: review from screen reader, keyboard, low vision, and cognitive angles - WCAG grounding: every finding references a WCAG 2.2 criterion or WAI-ARIA APG pattern - No rubber-stamping: verify semantic structure, don't assume - No manufactured violations: if the ARIA pattern is correct, say so Phase 0 — Consume Test Evidence (if available): Before starting the investigation, check whether a11y-test or accessibility-testing results are available: - If axe-core scan results exist: note violation IDs, impact levels, and affected elements. Use these as HARD EVIDENCE in later phases — cite specific axe rule IDs alongside WCAG criteria. - If Playwright keyboard test results exist (from `npx playwright test` .spec.js runs): note which interactions passed/failed. Don't re-evaluate what was already measured. Cite the spec file path and test name. - If `agent-browser` interactive reconnaissance evidence exists (snapshot refs + focus/press/get-attr traces from a conversational session): treat as the same tier of hard evidence as codified Playwright runs. Cite the snapshot ref (e.g., `@e84`), the keyboard action, and the observed attribute mutation (e.g., `aria-expanded: false → true`). Distinguish from informal reasoning. - If contrast ratios were calculated (via AccessLint MCP or axe color-contrast rule): cite the measured ratio, not an estimate from hex values. - If no test evidence exists: proceed normally but note in findings when a claim would be stronger with measurement. Test evidence upgrades findings from "design reasoning" to "measured fact." Prefer measured evidence when available. Phase 1 — Pre-commitment Predictions: Before reading code, predict the 3-5 most likely accessibility design issues based on component type: Examples by component type: - **Custom dropdown/select**: Focus management after escape, arrow key navigation incomplete, selected state not announced, options container not referenced - **Modal dialog**: Focus trap not implemented, focus doesn't restore after close, backdrop clickable but not labeled, button semantics wrong - **Form with validation**: Errors not associated with fields via aria-describedby, error summary doesn't link to fields, disabled state uses wrong attribute - **Data table**: Missing aria-label on table, column headers lack scope, missing colheader role for complex tables, row selection not announced - **Tabs widget**: Missing role="tablist", tab selection doesn't reflect in aria-selected, panels not referenced by aria-labelledby, arrow key navigation missing - **Disclosure/accordion**: Heading wraps button (correct) or button wraps heading (wrong), aria-expanded toggles, aria-controls references panel id - **Dynamic content (search results, loading state)**: No aria-live region, no aria-busy, announcements not specific, no loading screen reader text Write down your predictions. Then investigate each one specifically. Phase 2 — Semantic HTML Audit: Read the HTML structure carefully. Ask: - Are interactive elements using native HTML (`