Architecture & the Loop
a11y-loop is two things working together: an Agent Skill that sets the rules — first while the UI work is being planned, then while the agent writes the code — and a Node CLI that checks the plan and verifies the rendered result in a real browser, feeding failures back to the agent until the report converges. An optional Claude Code plugin adds two gates on top, one at plan approval and one at the end of a session. The same CLI also runs as an MCP server (a11y-loop mcp) and as a GitHub Action.
The skill's phases run in that order. §0 settles the decisions that are cheap now and expensive later (conformance target, per-component criteria, foreclosing decisions, color tokens, structure); §1 governs the code as it is written; §2 is the audit loop below; §3 governs what may be claimed about the result. Only §2 needs a browser — see Planning with Accessibility for the phase that runs before any of this exists.
One audit-fix-reaudit cycle
The flow in words: the skill's §0 puts the accessibility decisions in the plan, where changing them is still a sentence; §1 sets standing rules while the agent writes the UI; a11y-loop audit verifies the rendered result across five passes plus any built interaction states; violations feed back to the agent to fix; a11y-loop diff confirms convergence without new regressions; the JSON report and its manual-review checklist are the artifact of record, with SARIF offered as a secondary format for tools that consume it.
The plan phase has two enforcement points outside the skill itself. a11y-loop plan-check runs in any agent or CI job and exits 1 on a UI plan with no accessibility content. In interactive Claude Code, the optional plugin layer runs the same decision as a hook on ExitPlanMode and declines such a plan once. Both check that the question was asked, not that the answer is any good — the audit loop above and a human reviewer are still what judge the answer. The end of the work has its own gate in the same plugin: a Stop hook declines, once per session, to end a session that wrote UI files and never ran a11y-loop audit afterwards. It checks that the audit ran, not what it found. The equivalents for other clients are in Gates in other agents.
Tech stack
- Runtime: Node.js ≥ 20, ESM
- Browser automation: Playwright (Chromium)
- Accessibility engine: axe-core 4.14.0 via
@axe-core/playwright4.14.0, both pinned exactly - Color math: culori (OKLCh contrast fixes)
- Focus order: tabbable
- SARIF: SARIF 2.1.0 written directly, in the shape axe-sarif-converter produced before 0.3.0
- Agent integration: the open Agent Skills standard
See the overview's Tech Stack section for licensing details (axe-core is MPL-2.0, separate from this project's MIT license).