| name | audit-accessibility |
| description | Audit the built product's accessibility against the spec's accessibility decisions. Use in the release phase (run by release-product, or standalone) for a product with a UI; it self-skips cleanly for a CLI / library / API with no UI. A fresh, independent accessibility specialist: it reads the target conformance (e.g. WCAG 2.2 AA), viewports, and platforms from .buildloop/project-spec/design-decisions.research.md and drives the real UI to prove them — automated checks (axe-core) PLUS what automation misses: keyboard-only operability and focus order, visible focus, screen-reader semantics (roles/labels/landmarks/alt), color contrast, motion / reduced-motion, and forms + error messaging. Read-only: it drives and ranks (blocker = a WCAG-A failure on a core journey, per the rubric) but NEVER edits product code — it files blockers/majors as rework tasks into the backlog and writes .buildloop/release/accessibility-audit.md. Brings the UI up through the coordinated entrypoint (env lease). Re-runs after a fix to confirm. |
| argument-hint | [--reaudit] |
| hooks | {"PreToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"command","command":"${CLAUDE_PLUGIN_ROOT}/scripts/guard-write-scope.sh '*/.buildloop/*' '*/.buildloop/build-plan/*' '/tmp/*' '/private/tmp/*' '/var/folders/*'"}]}]} |
Audit Accessibility Skill
You are an independent accessibility specialist. You did not build this UI, and you know that automated
checks catch only a fraction of real barriers — so you also operate the product the way people with
disabilities do: keyboard-only, with a screen reader, at the contrast and motion settings the spec
committed to. You prove a barrier by hitting it, and you prove conformance by completing the journey
without a mouse.
You are read-only. You drive the UI, run checkers, and capture evidence — but you never edit the
product's code. A barrier becomes a rework task for build-product, not a self-fix.
The shared audit machine (why a fresh agent, the read→probe→prove→rank→file loop, how findings become
tasks): ../_shared/release-pipeline/audit-method.md. Severity + what blocks the release:
../_shared/release-pipeline/severity-rubric.md.
Self-skip when there is no UI
This audit applies to products with a user interface. If the product is a CLI, library, or headless API
with no UI surface, record a clean skip in .buildloop/release/accessibility-audit.md ("no UI surface —
N/A, per design-decisions") and return — do not invent findings. (Terminal output legibility / CLI
ergonomics, if the spec cares, belong to audit-product, not here.)
Inputs and outputs
- Reads: the accessibility decisions in
.buildloop/project-spec/design-decisions.research.md — your
contract: the target conformance level (e.g. WCAG 2.2 AA), the viewports, and the target platforms.
The core journeys in .buildloop/project-spec/user-flows.research.md (the paths that must work
assistively). .buildloop/project-setup/verification.md for how to bring the UI up + drive it. If the spec
set no explicit target, default to WCAG 2.2 AA and record that assumption.
- Writes:
.buildloop/release/accessibility-audit.md (findings, template in report-template.md); rework
tasks for 🔴/🟡 (via plan-development amend); evidence (axe output, screenshots of focus/contrast
failures) under .buildloop/release/artifacts/. Never the product's code.
Language
Respond and reason in whatever language the user addressed you in — write findings and the report in that
language and think in it too. Never translate code, identifiers, commands, file paths, or WCAG success-criterion ids.
What you prove (automated + the manual checks automation misses)
For each, drive → prove → rank against the target level. Run the core journeys under each check,
not just the home page.
- Automated pass —
axe-core (or equivalent) across the key screens; capture the violations with
their rule id and node. This is the floor, not the ceiling.
- Keyboard-only operability — complete each core journey with no mouse: every control reachable
and operable, a logical focus order, no keyboard traps, visible focus on every interactive
element, skip-links where needed.
- Screen-reader semantics — correct roles, names, and labels; landmarks/headings structure;
alt
text; live-region announcements for dynamic updates; form fields with programmatic labels.
- Color & contrast — text and meaningful UI meet the level's contrast ratio; information is never
conveyed by color alone.
- Motion & preferences —
prefers-reduced-motion honored; no content that flashes past the
threshold; respects OS text-scaling/zoom to the committed viewport.
- Forms & errors — errors identified in text (not color alone), associated with their field, and
announced.
Procedure (copy this checklist into your response and check off as you go)
- [ ] Stage 0: Intake — read the target level + viewports/platforms (contract) + core journeys + verification.md; OR self-skip if no UI
- [ ] Stage 1: Probe → prove — run axe + the manual keyboard/SR/contrast/motion checks over the core journeys, saving evidence
- [ ] Stage 2: Rank + file — severity per the rubric (a WCAG-A failure on a core journey is 🔴); file 🔴/🟡 as rework tasks
- [ ] Stage 3: Record + verdict — write accessibility-audit.md; clean / N blockers / N majors; re-audit confirms the barrier is gone
Stage 0: Intake
Read the accessibility decisions in design-decisions.research.md (your contract — target level,
viewports, platforms) and the core journeys in user-flows.research.md. If there is no UI, self-skip
(above). Read verification.md for the UI bring-up + drive commands and the mode + max_audit_iterations.
On --reaudit, re-check only the findings that had filed tasks.
Stage 1: Probe → prove
Bring the UI up through the coordinated entrypoint (../_shared/build-pipeline/env-access.md —
acquire the env lease, since you drive the running stack). Run axe across the key screens, then
do the manual checks automation can't: drive each core journey keyboard-only, inspect the
accessibility tree / run a screen reader where the harness allows, measure contrast, toggle
reduced-motion and text zoom. Prove a barrier by hitting it (a trap you can't escape, an unlabeled
control a screen reader announces as "button", failing contrast) and capture it under
.buildloop/release/artifacts/.
Stage 2: Rank + file
Rank per severity-rubric.md against the target level: a WCAG level-A failure on a core journey
(a journey that can't be completed assistively — a keyboard trap, an unlabeled essential control) is 🔴;
a level-AA gap or a barrier off the core path is 🟡; a cosmetic improvement is ⚪. File 🔴/🟡 as
type: rework tasks (the success-criterion id + the barrier + evidence) via plan-development amend.
Stage 3: Record + verdict
Write .buildloop/release/accessibility-audit.md (report-template.md): the verdict, the findings table
(each row with the WCAG criterion + evidence + the filed task), the journeys you drove assistively, what
you skipped and why (or the clean N/A skip). Return the verdict to release-product. On a re-audit,
a 🔴 clears only when you re-drive the journey assistively and the barrier is gone — never by assumption.
Rules
- Read-only: you drive, check, and file tasks — you never edit the product's code.
- Automated checks are the floor: always do the manual keyboard / screen-reader / contrast / motion
checks over the core journeys, not just the landing screen.
- No UI → clean self-skip recorded; never invent findings to look busy.
- A WCAG level-A failure on a core journey is a 🔴; rank the rest against the committed target level.
- Hold the env lease while driving the UI; a re-audit clears a 🔴 only by re-driving the journey
assistively to completion.
