10 KiB
name, effort, description, argument-hint
| name | effort | description | argument-hint |
|---|---|---|---|
| a11y | high | Use when a web project needs its accessibility baseline checked and fixed: everything reachable by keyboard with a visible focus, an alt on every image, a label on every field. Full WCAG conformance (axe, pa11y, W3C) → /web-validate; security guardrails → /guardrails. Deterministic scanner (A11Y-* rules: img alt, field label, click without keyboard, focus outline removed, positive tabindex), judgment, a Tab-only walk of the main flow on --live (through /browse, else marked not done), report .claude/audits/A11Y.md, then fixes proposed with the alt and label wording as visible choices, applied only on acceptance (bugfixer executor, fresh verifier and security gates, the scanner as oracle) and re-scanned to prove each one. Triggers: "a11y", "accessibilité", "accessibility basics", "clavier", "focus visible", "alt manquant", "label sur les champs", "tab order", "corrige l'accessibilité". | [project path] [--exclude paths] [--live <url you own>] [--report-only] |
/a11y
Checks a project's accessibility baseline (rules/a11y.md), then fixes what
the user accepts and proves each fix. A scanner reads the tree as data and
finds what text can prove: a missing alt, an unlabeled field, a click with no
keyboard path, a focus outline removed, a positive tabindex. This skill judges
the hits, walks the main flow with the keyboard when a browser is available,
proposes fixes, applies the accepted ones and scans again until every accepted
fix is proven.
The scanner proves absence of a baseline, never presence of accessibility. A
clean scan means "no static finding", and the report says exactly that. Full
WCAG conformance (contrast, structure, ARIA semantics, axe or pa11y runs) is
/web-validate's job.
MODEL GATE (blocking, before any other step)
Run $HOME/.claude/lib/model-gate.md. Judging hits and writing alt and label
text requires Fable or Opus. Verdict small → STOP: the gate prints the
remedy. ROUTING: follow $HOME/.claude/lib/effort-shift.md (phases via
mcp__model-router__route); each step below names its phase.
STEP 1: Scope
Work in the project the user names, else the current directory. Say in one
line what you will scan. --report-only stops after STEP 5: audit, no fix.
STEP 2: Run the scanner
python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" <path>
Add --exclude a/b,c to skip copies or vendored code, --json for machine
output. Exit 0 means no FAIL, 1 means at least one, 2 is a usage error. It
never executes project code. Severities: FAIL, the baseline is provably
missing; WARN, a pattern that is often wrong, judgment needed.
STEP 3: Judge every FAIL and WARN
Read the file around each line. Label it CONFIRMED, FALSE POSITIVE (say why)
or ACCEPTED RISK (the user decides, never you). The scanner already
stays silent on a decorative alt="", a role="presentation" overlay and an
outline swapped for a border or ring; the hits that are often false are a
label wired through aria-labelledby in another file and an outline removal
that a :focus-visible rule elsewhere covers (WARN); references/checks.md lists the blind
spots. Check them before calling a hit false.
STEP 4: Keyboard walk (on --live, read-only)
With a dev server the user names, walk the main flow with Tab only through
/browse: every control reached in a sensible order, the focus visible at
each stop, Enter and Space working on what looks clickable, Escape closing
what opened. Record each stop that fails with the page and the element.
Without a browser tool, or without --live, the report marks the walk
"not done": a static scan cannot see a keyboard trap, a focus order or a
modal that loses focus.
STEP 5: Report
Write .claude/audits/A11Y.md: one table with status PASS, FAIL, WARN or
N/A per rule, the evidence, the fix in one line, and the keyboard walk's
result (done, with its stops, or not done). PASS means "no static finding".
Keep it short; no filler sections. --report-only, or nothing CONFIRMED:
reply with counts, the FAILs with file:line and the walk's stops, then stop.
STEP 6: Propose fixes
mcp__model-router__route(phase="plan"): wording is the deepest thinking in
this run, it goes to the plan row.
One proposal per CONFIRMED finding, grouped by rule and file; merge pairs
that one change closes (one :focus-visible rule closes every outline
removal in a stylesheet). FALSE POSITIVE and ACCEPTED RISK get no proposal.
Each proposal:
- number, rule, file(s), and the problem in one line;
- the fix, concrete: file:line and the change. A missing alt gets a
description of what the image shows, or
alt=""when it is decorative; an unlabeled field gets alabel for, a wrapping label oraria-label; a clickabledivbecomes abutton, or gainsrole,tabindexand a key handler; a removed outline gets a:focus-visiblestyle; - choices the user sees: the alt text and the label wording, each with your proposed value, named so the user can change it. These are content, never invented silently: they ship only with the user's acceptance;
- risk: what it can break (
buttonreset styles, a changed tab order).DECISIONwhen no wording is defensible (an image you cannot describe); - proof: the scanner pairs that must disappear (
RULE:path), and the walk stop that must pass when--liveran.
Save the proposals to .claude/tasks/plans/<YYYY-MM-DD>-a11y-<HHMM>.md and
append them to the report. In the reply, show them as a numbered list, one or
two lines each, DECISION marked.
STEP 7: Approval (gate, ends the turn)
Nothing is applied without the user's explicit acceptance. Ask once, then stop the turn:
Which fixes do I apply? "all" (every proposal except DECISION ones),
numbers ("1,3,5-7"), "none", or an amendment ("2 with the alt 'Team photo'").
A DECISION proposal needs its number plus your wording.
On resume, mcp__model-router__route(phase="reflect"). "none" → stop,
proposals stay in the report. An amendment rewrites that proposal in the plan
file before anything else. Accepted set empty → stop.
STEP 8: Apply
- Branch. Not a git repository → stop: fixes need a diff to review.
On
main/develop,bash ~/.claude/lib/gitflow.sh start bugfix a11y-<YYYY-MM-DD>; on a working branch, stay. Neverfinish. - Baseline, before any edit:
python3 -B <scan.py> <root> --json > .claude/audits/.a11y-baseline.json. A derived file: never staged, never committed. - Contract per
$HOME/.claude/lib/contract-interview.md(STEP 4 template,flow: a11y). REQUEST = the user's acceptance verbatim plus the accepted proposals. One criterion per accepted proposal, its oracle the scanner itself:Add one criterion for the project suite when one exists (1. <proposal 1 in one line> CHECK: python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" '<abs root>' --assert-absent 'RULE:path,RULE:path' EXPECT: A11Y-CLEAR EVIDENCE: pendingCHECK: <test command> && echo TESTS-GREEN,EXPECT: TESTS-GREEN). The keyboard walk is a criterion without CHECK: STEP 9 settles it. FILE SCOPE = the files the accepted proposals name. Paths go in single quotes; a path holding a single quote is named to the user, never written into a CHECK. - Positive control. Run each oracle once on the unfixed tree: it must fail. An oracle that passes before the fix proves nothing; drop it, find why, and say so.
- Dispatch the executor, one fresh
bugfixerfor the accepted set (batches of 8 proposals at most, one after the other on the same branch):mcp__model-router__route(phase="orchestrate") # send with the Agent call Agent(subagent_type="bugfixer") prompt: "CONTRACT: <path> DIAGNOSIS: <each accepted finding: rule, file:line, evidence> FIX PLAN: <the accepted proposals verbatim, with the user's wording; the regression check of each is its contract oracle, plus the project test the proposal names> BRANCH: <current branch> Apply to the letter. No commit, no branch ops, no security dispatch. Finish with the BUGFIX-EXEC REPORT."NEED-DECISIONroutes per MID-RUN CLARIFICATION of the contract include: a wording, visible or scope question goes to the user verbatim.BLOCKED→ surface it, stop. - Gates per
$HOME/.claude/lib/verify-secure-loop.md,CONTRACTthe path above,DIFFthe executor's working-tree diff,TESTthe suite. GATE 0 runs every scanner oracle (the per-fix proof), GATE 1 a fresh verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are the include's; loop decisions stay in this main loop.
STEP 9: Re-pass (prove it all)
mcp__model-router__route(phase="reflect"). The gates proved each accepted
fix on its own; this pass proves the whole tree.
- Full scan against the baseline:
Every accepted pair must show
python3 -B <scan.py> <root> --baseline .claude/audits/.a11y-baseline.jsonFIXED, and the run must end onA11Y-NO-NEW(exit 0). ANEWhit is a regression the fix made. - Live: when STEP 4 ran, walk the same flow again once the user has reloaded the dev server and says go. Each stop a proposal named must now pass.
- Add an "after" column to
.claude/audits/A11Y.md: proposal, before, after, evidence.
Anything not fixed, or a NEW hit → one more round from STEP 6, limited to those items. Two rounds at most: after the second, stop with the residuals open and say so plainly. Never report a fix the re-pass did not prove.
STEP 10: Commit and hand over
- Commit gate. Show files,
git diff --statand the message, wait for the user's go:ThenA11Y: READY TO COMMIT FILES : <list> MESSAGE : fix(a11y): <rules fixed, one line>git add <files touched>(never-A, never the baseline file) and commit, project convention else 50 words at most. mcp__model-router__route(phase="apply")for the tail. Reply with: fixed and proven (proposal, rule, file), still open and why, the walk's result, the branch name. Merge waits for the user's explicit signal.- Offer to capitalize a reusable lesson (a false-positive class, a fix pattern), entry pre-filled, written only on approval.