← All craftbooks

Accessibility Audit

Review and QAevalv1.1.0released 2026-07-19workflow: build-loop

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

1. Scope the auditreviewerentry

   enumerate components + lock a WCAG AA checklist

   Show working prompt

   Step 1: For a whole-project or recurring review, call `map_repo`, `list_file_issues`, and targeted `search_code` queries to enumerate the complete UI surface (routes/views, navigation, forms, dialogs, custom widgets, media, and shared components); for a page-scoped request, inventory only that surface. Record indexed review coverage and do not treat an indexed lead as a confirmed finding. Step 2: Identify the user flows to audit. Step 3: Build a WCAG 2.1 AA acceptance-criteria checklist covering: semantic landmarks and heading order (1.3.1), keyboard operability of all controls with no traps (2.1.1/2.1.2), visible focus indicators and logical focus order (2.4.7/2.4.3), text contrast ≥ 4.5:1 and UI/large text ≥ 3:1 (1.4.3/1.4.11), text alternatives for images/icons (1.1.1), programmatic labels for every form field (1.3.1/4.1.2), correct and minimal ARIA (4.1.2), name/role/value for custom widgets, reflow at 320px and 200% zoom (1.4.10/1.4.4), and no information conveyed by color alone (1.4.1). Step 4: For each item, state the pass condition for THIS UI and the verification method. Write the surface, index coverage, flow list, and WCAG checklist to `write_task_note` AND `notes/scope.md`. No findings yet.

2. Audit each criterionreviewer

   inspect markup, keyboard, contrast, ARIA per SC

   Show working prompt

   Step 1: Open/inspect the UI (use the browser or a11y tooling if available; otherwise read the HTML/CSS/JS and reason about the rendered semantics). Step 2: For EACH checklist criterion, perform the actual check: tab through the page recording focus order and any unreachable/trapped controls; verify each interactive element has an accessible name and correct role; compute contrast ratios for text and UI on their real backgrounds; confirm every image/icon has appropriate alt or is correctly hidden; confirm every input has a programmatic label; validate ARIA usage against the spec (no redundant/invalid roles). Step 3: For each violation capture: the WCAG SC number and level, the selector/element, what is wrong, the user impact (who is blocked and how), severity, and the concrete code fix. Step 4: Record the criteria that PASS so the report shows full coverage. Good looks like: 'SC 1.4.3 FAIL — .btn-primary text #9aa on #fff = 2.1:1, needs ≥4.5:1; darken to #555'. Stage findings to `write_task_note`. Do not write the report yet.

3. Write the a11y reportreviewer

   findings keyed to WCAG SCs with fixes

   Show working prompt

   Step 1: Open `a11y-report.md` and write a top-line verdict (Conformant / Partially-conformant / Non-conformant to WCAG 2.1 AA) with counts by severity. Step 2: Add a '## Findings' section; for each, write `### [SEVERITY] SC <number> (<Level>) — <element>` with what is wrong, the user impact, and the exact code fix. Order critical-first. Step 3: Add a '## Passing criteria' section listing the SCs checked and met, so coverage is auditable. Step 4: Add a '## Manual verification needed' section for items a static check cannot fully settle (e.g. screen-reader announcement quality). Every finding must cite a specific SC and element with a concrete remedy — no generic 'add ARIA'. On a loop-back, fix only the named gaps. `write_task_note` the report path and the severity counts.

4. Evaluatereviewer

   Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

   Show working prompt

   Open `a11y-report.md` and grade it against the scope WCAG checklist. Check EACH criterion and write PASS/FAIL with a one-line reason: (1) every checklist SC was assessed (found-and-reported or marked passing); (2) each finding cites a specific WCAG success-criterion number and level; (3) each finding names the affected element and a concrete code fix; (4) contrast findings include actual computed ratios; (5) keyboard operability and focus order were actually walked; (6) a passing-criteria section makes coverage auditable; (7) the verdict matches the findings. If any criterion fails, name the exact gap and loop back.
   
   Then route — this is the whole point of the loop:
   
   - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
   - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "report" })` to loop back. The builder fixes exactly those gaps.
   
   Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.

5. Finishdeveloper

   All acceptance criteria met. Stamp a short summary and report DONE.

   Show working prompt

   Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

• accessibility audit
• a11y review
• check WCAG compliance
• is this accessible
• screen reader test
• keyboard navigation audit

Toolsets

• [object Object]
• [object Object]

Source

View this craftbook on GitHub · MIT license