●  Agent loops \u00b7 a11y audit until clean \u00b7 copy-paste playbook
EST. 20241 makerBuilt in public
Agent loop \u00b7 Quality loop \u00b7 6 steps

A11y Audit Until Clean
clean for everyone.

For shipping UI that everyone can use. Each pass scans only the routes you touched, fixes real barriers (labels, contrast, keyboard), and repeats until the checker reports zero violations.

Typical run: 15–40 min typical \u00b7 Copy any prompt box and hand it to your agent as-is.

Loops / A11y Audit Until Clean

\u00a7 01

When to use

6 steps15–40 min typical
  • A change touches forms, navigation, modals, or any interactive component users tab through.
  • You want automated signal before a manual screen-reader pass — catch the mechanical issues first.
  • Design handoff included contrast or focus specs and you need proof they hold in the browser.
  • The team keeps a zero-known-violations bar on changed routes.
\u00a7 02

The steps

one prompt per stepcopy \u00b7 paste \u00b7 run
01Name the routes and the rules
List the changed routes (URLs or story paths) and the checker plus ruleset to use. Example: "Audit /signup and /checkout with axe-core, WCAG 2.2 AA. Report the violation count per route with no fixes yet, then stop."
Why: Scanning everything finds everything except what you changed — scope it.
02Run the baseline scan
Run the automated checker on ONLY the listed routes. Save the raw report to a11y-baseline.json. Report each violation with route, rule id, and affected element. Do not fix yet — stop after reporting.
Why: You need a before-list so each fix round is measurable.
03Fix one barrier class at a time
Fix all violations of ONE rule across the scoped routes. Common order: names/labels, keyboard/focus, contrast, structure/landmarks. Re-state the rule, list files changed, then stop without re-scanning.
Why: Grouping by rule (all missing labels, then all contrast) is faster than hopping route to route.
04Re-scan the same routes
Re-run the identical audit command on the same routes. Save to a11y-02.json (then -03, etc.). Report fixed count, remaining count, and any NEW violations. Stop after reporting.
Why: Same routes, same rules, fresh report — that is the only valid comparison.
05Keyboard-walk the happy path
Tab through each scoped route using keyboard only: reach every interactive element, open and close any modal or menu, submit the form. Report any trap, invisible focus, or dead-end found, with the key sequence that triggers it. Then stop.
Why: Automated checks miss focus traps and tab order — five minutes of keys catches them.
06Record the clean report
Save the final zero-violation report as a11y-final.json. Write a 5-line note: routes audited, ruleset, rounds taken, manual keyboard result, and files changed. Keep it under 120 words, then stop.
Why: A clean scan nobody saved will be re-debated next sprint.
\u00a7 03

Stop conditions

exit criteria
  • Automated scan reports zero violations on every scoped route with the agreed ruleset.
  • Keyboard walk completes with no traps, invisible focus, or unreachable controls.
  • Baseline and final reports are saved and the changed files list is recorded.
\u00a7 04

Failure modes

what goes wrong + guardrail

Fixing the checker instead of the barrier

Symptom: rules get disabled to reach zero. Guardrail: any disabled rule needs a written reason plus a follow-up issue — never silent skips.

Only the homepage gets scanned

Symptom: clean report, broken checkout. Guardrail: freeze the route list in step 1; adding a route restarts the count.

Contrast passes in one theme only

Symptom: light mode is fine, dark mode fails. Guardrail: scan each shipped theme (light/dark, high-contrast if offered) before declaring clean.

\u00a7 05

More loops

5 playbooks
\u2190 All loopsmosaic/lab \u00b7 agent loops
Build Until Green → Coverage Until Threshold → A11y Audit Until Clean → CI Failure Watcher → Plan Then Execute →