accessibility-auditor

Audit a UI surface against WCAG 2.2 AA, keyboard-only operation, and screen-reader semantics. Output is a verdict with cited failures, not a vibes check. Pair with tailwind-engineer for token-level contrast fixes and ui-component-architect for structural fixes (landmarks, heading order).

When to use

• A new screen, component, or form lands and a11y has not been reviewed yet.
• A bug report mentions keyboard, screen reader, focus order, contrast, or "user can't reach the X button".
• A modal, dropdown, popover, tab strip, or tree view is being introduced — these are the highest-yield bug zones.
• German triggers: "barrierefrei prüfen", "Tastatur-Bedienung", "Screenreader testen".

Do NOT use when:

• The visual design itself is the question (palette, type scale) — route to fe-design.
• The diff has no UI surface — accessibility audits without a UI are speculation.
• A specific component spec is missing entirely — get the component built first via the stack-specific skill, then audit.

Procedure

1. Identify the interaction surfaces

List every interactive element on the screen: links, buttons, inputs, custom widgets (combobox, tab, dialog, tree). Each row gets a verdict in step 5; missing one is a coverage failure.

2. Walk the four checklists

Perceivable — text alternatives for non-text (alt, aria-label), contrast ≥ 4.5:1 for body / 3:1 for large or UI components, no colour-only state ("error in red" must also be iconic or text). Grounded reference for palette + chart verdicts: the adopted corpus's WCAG-adjusted token sets (--domain color), chart a11y grades + colorblind fallbacks (--domain chart), and mobile touch/a11y rules (--domain web, 44pt targets) via design-intelligence — cite the corpus row; the WCAG 2.2 AA method stays this skill's own checklists. Widget-pattern selection (dialog, combobox, tabs, toast, table, form errors, drag-reorder …) grounds in the ARIA-APG corpus: ./scripts-run <skills-root>/corpus-grounding/scripts/ground search --manifest <skills-root>/accessibility-auditor/data/manifest.json "<component>" → pattern, implementation, WCAG refs, anti-patterns (data/aria-patterns.csv).

Operable — every interactive element reachable by Tab, focus order matches visual order, focus indicator visible (≥ 3:1 against adjacent), Esc closes overlays, no keyboard traps.

Understandable — labels associated (label[for] or wrapping), errors named in text (not just border colour), language attribute on <html>, predictable navigation across pages.

Robust — landmarks present (<header>, <nav>, <main>, <footer>), heading order without skips, ARIA only when no native element exists, custom widgets follow ARIA-APG patterns.

Reduced motion — audit the PRESENTATION, not the presence of the query. A prefers-reduced-motion block is easy to grep and proves nothing: animation: none on a scroll-revealed section leaves the content invisible, and a scrubbed sequence with its motion removed leaves the story untold. So the finding is about what the surface shows instead:

Motion carries	Reduced-motion presentation	Failure
A reveal (content fades/slides in)	The content at its final state, visible from the start	opacity: 0 left standing — the content never appears
A scrubbed sequence (scroll drives progress)	Each beat at its resting state, reachable by ordinary scrolling	Motion disabled and the beats collapse onto each other
A transition between states	An instant state change, still announced	The state changes with no perceivable feedback
Decoration (parallax, drift, ambient)	Nothing — removal is the correct presentation	—

Decoration is the only case where removal is the answer, which is why animation: none reads as correct so often and is wrong so often. Ask per block: if the motion never plays, is the content still there and still understandable? Record the answer, not the query.

WCAG 2.2 additions — the six criteria 2.1 did not have. An AA claim is cumulative: AA conformance means every level-A criterion and every level-AA one, so the two level-A rows below sit inside the claim, not beneath it. Each is audited on its own; a surface that skips one is not AA under 2.2.

SC	Level	Testable condition	Failure
2.4.11 Focus Not Obscured (Min.)	AA	Tab through every focusable element with sticky headers / footers / cookie bars present — the focused element stays at least partially visible, never fully covered	A sticky bar hides the focused row; the keyboard user cannot see where they are
2.5.7 Dragging Movements	AA	Every drag interaction (reorder, slider, map pan, kanban) has a single-pointer alternative that is not a drag — buttons, a menu, or arrow keys	Reorder is drag-only, so a user who cannot drag cannot reorder
2.5.8 Target Size (Min.)	AA	Every pointer target is ≥ 24×24 CSS px, or carries ≥ 24 px spacing to its neighbours, or is one of the stated exceptions (inline text, user-agent-controlled, essential)	16 px icon buttons packed edge-to-edge in a toolbar
3.3.8 Accessible Authentication (Min.)	AA	No login step requires a cognitive function test (remembering, transcribing, puzzle-solving) without an alternative — a password manager can paste, and paste is not blocked	An OTP field that blocks paste, or "type the 3rd character of your memorable word"
3.2.6 Consistent Help	A	Where a help mechanism (contact link, chat, self-help) repeats across pages, it appears in the same relative order on each	Support link in the header on one page, buried in the footer on the next
3.3.7 Redundant Entry	A	Information already entered in the same process is auto-populated or selectable, unless re-entry is essential (confirming a password is essential)	A 4-step checkout asking for the same address twice

Outside an AA claim, and stated here rather than left silent: 2.4.12 Focus Not Obscured (Enhanced) and 2.4.13 Focus Appearance are level AAA. Audit them on request; their absence is not an AA failure.

3. Run the keyboard pass

Tab from page start: every interactive element receives focus, in visual order, with a visible indicator. Shift-Tab reverses cleanly. Enter / Space activate per role. Arrow keys work in composite widgets (tab strip, listbox, menu). Esc dismisses the top-most overlay only.

4. Run the screen-reader pass

Use VoiceOver (macOS), NVDA (Windows), or aria-live log inspection. Each surface announces: role, name, state, value, description (in that order). State changes (loading, expanded, selected, error) announce. Decorative images are silent.

5. Score and report

For each surface from step 1:

Surface	WCAG SC	Pass / Fail	Evidence
Submit button	1.4.3	Fail	contrast 3.1:1, expected 4.5:1
Modal	2.1.2	Fail	Tab leaves modal — focus trap missing

Verdict at the bottom: AA-pass (zero fails), AA-pass-with-risk (non-blocking gaps + plan), or AA-fail (blocking — fix before ship).

Output format

Scope:        <screen / component / route>
Surfaces:     <count from step 1>
Tools used:   <axe-core | manual | VoiceOver | NVDA — pick at least 2>

Findings:
  1. <SC>  <Pass/Fail>  <Evidence + file:line if known>
  2. ...

Verdict:      <AA-pass | AA-pass-with-risk | AA-fail>
Top 3 fixes:  <ordered by user impact>

Same-ramp contrast + dark-mode self-test (procedures, not a palette)

Two deterministic procedures — they reference the consumer's tokens / an upstream color ramp, they never vendor a hex table:

• Same-ramp contrast. Text on a colored fill uses a darker stop of the same color family, never plain black/gray dropped on top — same-ramp keeps the contrast on-brand and predictable. Title and subtitle are two different stops of that ramp (hierarchy from the ramp, not from an off-ramp gray).
• Mandatory dark-mode self-test. Before finalizing, ask: "if the background were near-black, would every text element still meet 4.5:1 (body) / 3:1 (large/UI)?" A ramp that only works on light is a fail. Run the test even when the brief is light-only — dark mode arrives later.

The ramp itself is authoritative in design-tokens (token derivation) and the consumer's brand-consistency tokens — this procedure sits beside that authority, it does not duplicate the values.

Gotcha

• aria-label on a <button> overrides its text content for screen readers — only use when the visible text is not descriptive (icon-only buttons).
• tabindex="-1" removes from tab order and allows programmatic focus; tabindex="0" adds to tab order. tabindex >= 1 is almost always wrong — fix the source order.
• Native <button> and <a> come with role + keyboard for free; reaching for role="button" on a <div> is a regression.
• Contrast on disabled state has no WCAG threshold — but if the user cannot tell it is disabled, that is a 1.4.1 failure on state cue.

Do NOT

• Do NOT declare AA-pass without a keyboard-only pass; an axe-core green is necessary, not sufficient.
• Do NOT add ARIA "to be safe" — wrong ARIA is worse than no ARIA. Native semantics first.
• Do NOT silence the audit on "internal-only tool" or "small user base"; legal exposure does not scale with audience size in most jurisdictions.
• Do NOT close a finding by adjusting the test instead of the UI; the user's experience is the ground truth, not the test report.

Why this skill is rich

WCAG 2.2 AA compliance is non-negotiable detail — each success criterion has a specific testable condition, failure mode, and remediation path. The skill carries the WCAG 2.2 additions with concrete test procedures per criterion (not just "check contrast"), keyboard-navigation patterns (roving tabindex, trap management, escape-key handling), ARIA role/ property/state tables, and screen-reader-specific edge cases per assistive technology. Condensing to "check contrast and add aria-labels" loses the test procedures that turn a vague finding into a reproducible failure with a specific remedy. Accessibility bugs that are described vaguely cannot be verified as fixed.