a11y-loop 0.1.1 → 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "a11y-loop",
+  "displayName": "a11y-loop",
+  "version": "0.2.0",
+  "description": "Hard-gates plan mode: a plan that changes UI has to say what it decided about accessibility before it can be approved. Ships the a11y-loop skill and a /a11y-plan command alongside it.",
+  "author": {
+    "name": "Chan Meng",
+    "email": "chanmeng.dev@gmail.com",
+    "url": "https://github.com/ChanMeng666"
+  },
+  "homepage": "https://github.com/ChanMeng666/a11y-loop#readme",
+  "repository": "https://github.com/ChanMeng666/a11y-loop",
+  "license": "MIT",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "axe-core",
+    "plan-mode",
+    "hooks",
+    "agent-skills"
+  ],
+  "skills": "./skill/",
+  "commands": "./commands/",
+  "hooks": "./hooks/hooks.json"
+}

package/README.md

@@ -8,7 +8,12 @@
 
 <div align="center"><a name="readme-top"></a>
 
-# 🔁 a11y-loop
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./.github/brand/a11y-loop-logo-dark.svg">
+  <img src="./.github/brand/a11y-loop-logo-light.svg" alt="a11y-loop logo" width="88" height="88">
+</picture>
+
+# a11y-loop
 
 ### Write accessible UI by default. Verify it in a real browser. Say exactly what you couldn't check.
 
@@ -16,7 +21,7 @@ a11y-loop makes AI coding agents write accessible UI by default, then proves wha
 with a real browser audit across the states it built — and tells you exactly what it could not
 check.
 
-[Demo GIF][demo-link] · [SKILL.md][docs-link] · [Benchmark](evals/benchmark-results.md) · [Changelog](CHANGELOG.md) · [Report Bug](https://github.com/ChanMeng666/a11y-loop/issues) · [Request Feature](https://github.com/ChanMeng666/a11y-loop/issues)
+[Demo GIF][demo-link] · [Documentation][docs-site-link] · [SKILL.md][docs-link] · [Benchmark](evals/benchmark-results.md) · [Changelog](CHANGELOG.md) · [Report Bug](https://github.com/ChanMeng666/a11y-loop/issues) · [Request Feature](https://github.com/ChanMeng666/a11y-loop/issues)
 
 <!-- SHIELD GROUP -->
 
@@ -41,6 +46,7 @@ check.
 
 - [🌟 Introduction](#-introduction)
 - [🎬 Demo](#-demo)
+- [🎥 Promo Video](#-promo-video)
 - [✨ Key Features](#-key-features)
 - [📊 Honest Coverage](#-honest-coverage)
 - [📈 Benchmark](#-benchmark)
@@ -66,7 +72,9 @@ accessibility-agnostic ones (W4A'25, 17.32% vs. 15.93%). Instructions alone are
 
 a11y-loop is two things working together:
 
-1. **An Agent Skill** — standing generation rules (semantic HTML first, ARIA discipline, APG
+1. **An Agent Skill** — plan rules that apply while the work is still being scoped (conformance
+   target, per-component criteria, the product decisions that foreclose accessibility, color tokens
+   before components), then standing generation rules (semantic HTML first, ARIA discipline, APG
    keyboard contracts, labels, focus visibility, AA contrast in light and dark, reduced motion,
    24×24 targets) that apply while the agent is writing UI code.
 2. **A Node CLI** (`a11y-loop audit` / `contrast --fix` / `diff`) that verifies the result in a
@@ -77,18 +85,29 @@ same `SKILL.md` is portable across 40+ clients — Claude Code, Cursor, GitHub C
 Gemini CLI, and more — not just one vendor's agent. The CLI runs the same checks standalone in CI
 or any other pipeline.
 
-It was built for the **My Life My Voice** accessibility challenge, run by a disability
-organization in Aotearoa New Zealand, where the NZ Government Web Accessibility Standard 1.2 has
-mandated WCAG 2.2 AA since 17 March 2025. The idea: give AI coding agents a way to build
-accessibility in from the start, instead of treating it as a compliance afterthought bolted on
-after the fact. a11y-loop has no affiliation with My Life My Voice or the NZ government beyond
-having been built for that challenge.
+a11y-loop is a personal open-source project. It exists because the same handful of failures — low
+contrast, missing alt text, empty links and buttons, unlabelled form inputs — have topped the
+WebAIM Million every year for a decade, and the reason is not that they are hard to fix. It is
+that accessibility usually arrives as an after-the-fact compliance check, once the UI is already
+built and nobody wants to touch it. The goal here is to move it earlier: make accessibility a
+default of the development workflow rather than an audit at the end — which matters more now that
+so much UI code is written by AI agents in the first place.
+
+"Earlier" now reaches back past the first line of code. Some of the decisions that settle whether
+an interface can be made accessible — reordering that only works by dragging, a menu that only opens
+on hover, data that only exists as canvas pixels — are made while the work is being scoped, and they
+are nearly free to change there and a rewrite afterwards. §0 of the skill puts those decisions in
+the plan, where they are still cheap.
 
 **What this is not.** a11y-loop does not claim compliance, does not guarantee accessibility, and
 does not replace manual testing or testing with assistive technology. A clean report means "no
 automatically detectable failures" — see [Honest Coverage](#-honest-coverage) below for exactly
 what that does and doesn't cover.
 
+## 🎥 Promo Video
+
+https://github.com/user-attachments/assets/33ff8672-7690-4581-9ceb-d95476883c54
+
 ## 🎬 Demo
 
 ![a11y-loop fixing a seeded-violation demo page across five audit passes until it converges on zero violations](docs/demo.gif)
@@ -116,6 +135,20 @@ reduced-motion, and a 320×256 reflow viewport (the WCAG-sanctioned 400% zoom eq
 SC 1.4.10) — because most real failures only show up under a specific rendering condition, not on
 a single default-viewport load.
 
+<details>
+<summary><kbd>Diagram: the five passes feeding one report</kbd></summary>
+
+```mermaid
+graph LR
+    P1["Default<br/>1280×720"] --> R["One JSON report<br/>per audited page/state"]
+    P2["Dark mode"] --> R
+    P3["Forced-colors mode"] --> R
+    P4["Reduced motion"] --> R
+    P5["320×256 reflow<br/>(400% zoom equiv., SC 1.4.10)"] --> R
+```
+
+</details>
+
 `2` **Checks axe-core can't run** — tab order, focus visibility (including focus-ring contrast),
 dialog focus trap / Escape / focus-return, target size (24×24 CSS px, SC 2.5.8), reduced-motion
 effectiveness, ambiguous link text, div-as-button, and positive `tabindex`. These sit alongside
@@ -147,6 +180,16 @@ instead of jumping to black or white.
 `8` **Portable as an Agent Skill** — plain `SKILL.md` + `references/`, no proprietary format, works
 in any client implementing the open Agent Skills standard, not only Claude Code.
 
+`9` **Accessibility enters at the plan, not the pull request** — §0 gives the agent the decisions to
+settle while the work is still being scoped: the conformance target for the relevant jurisdiction,
+per-component acceptance criteria, the color tokens (verified with `contrast --fix`, which needs no
+browser and no code), the structure, and the interaction states that will need auditing. It also
+names the product choices that foreclose accessibility — drag-only reordering (SC 2.5.7), hover-only
+menus (SC 1.4.13), canvas-rendered data (SC 1.1.1), time limits (SC 2.2.1), CAPTCHA (SC 3.3.8) —
+each with the alternative, while changing them is still a sentence rather than a rewrite. In Claude
+Code, the [optional plugin layer](#optional-the-claude-code-plugin-layer) enforces it at plan
+approval.
+
 ## 📊 Honest Coverage
 
 Automated accessibility testing has a real, bounded scope, and a11y-loop says so in every report
@@ -155,6 +198,22 @@ rather than implying otherwise:
 - Deque's own research puts automated coverage at **~57% of accessibility issues by volume**
   across a 13,000+ page / ~300,000 issue study — but only **~31% of WCAG 2.2 AA success criteria**
   have *any* automated rule at all, and only **~13% are reliably automatable** end-to-end.
+
+<details>
+<summary><kbd>Diagram: WCAG 2.2 AA success criteria, by automation reach</kbd></summary>
+
+```mermaid
+pie showData title WCAG 2.2 AA success criteria — automation reach (Deque research)
+    "Reliably automatable end-to-end (~13%)" : 13
+    "Have some automated rule, not fully reliable (~18%)" : 18
+    "No automated rule — needs manual/AT review (~69%)" : 69
+```
+
+Illustrates the same figures cited above, not a new metric — a clean report never implies coverage
+of the other ~87%.
+
+</details>
+
 - **A clean a11y-loop report means "no automatically detectable failures were found" — it is
   never a conformance or compliance claim**, and the tool will not tell you your app is
   accessible, compliant, or free of legal risk. No single score is ever produced.
@@ -215,7 +274,10 @@ illustration of the effect's shape, not a controlled study or a precise effect s
 
 ```mermaid
 graph TD
-    A["Agent Skill<br/>skill/a11y-loop/SKILL.md + references/"] -->|standing generation rules| B["Agent writes UI code<br/>HTML / JSX / Vue / Svelte / Astro / CSS"]
+    A["Agent Skill<br/>skill/a11y-loop/SKILL.md + references/"] -->|"§0 plan rules"| P["Agent plans the UI work<br/>conformance target, per-component criteria,<br/>foreclosing decisions, color tokens, structure"]
+    P -->|"contrast --fix, no browser needed"| E
+    P --> B
+    A -->|"§1 standing generation rules"| B["Agent writes UI code<br/>HTML / JSX / Vue / Svelte / Astro / CSS"]
     B --> C["a11y-loop CLI"]
     C --> D["audit<br/>5 passes: default, dark,<br/>forced-colors, reduced-motion, 320px reflow"]
     C --> E["contrast --fix<br/>WCAG 2.x + OKLCh suggestions"]
@@ -235,6 +297,31 @@ graph TD
 
 </details>
 
+<details>
+<summary><kbd>Sequence: one audit-fix-reaudit cycle</kbd></summary>
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant CLI as a11y-loop CLI
+    participant Browser as Playwright + Chromium
+    participant Axe as axe-core + a11y-loop's own checks
+    Agent->>CLI: a11y-loop audit (after writing UI code)
+    CLI->>Browser: render page across 5 passes<br/>(+ --interact states, if any)
+    Browser->>Axe: run checks against each rendered pass
+    Axe-->>CLI: findings (WCAG SC, ACT ID, provenance)
+    CLI-->>Agent: JSON report + manual-review checklist
+    alt violations found
+        Agent->>Agent: fix code
+        Agent->>CLI: a11y-loop audit (re-run)
+    else no violations
+        Agent->>CLI: a11y-loop diff --before --after
+        CLI-->>Agent: Converged — FIXED/NEW/REMAINING summary
+    end
+```
+
+</details>
+
 The loop, in words: the skill sets standing rules while the agent writes 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
@@ -250,22 +337,26 @@ secondary format for tools that consume it.
 
 ### Installation
 
-**Not yet published to npm and this repo has no GitHub remote yet** — install from a local clone
-for now:
+```bash
+# Run it directly, no install
+npx a11y-loop <command>
+
+# Or install the CLI globally
+npm i -g a11y-loop
+
+# Either way, install the Chromium build Playwright needs for audits
+npx playwright install chromium
+```
+
+Prefer working from source (e.g. to contribute)? Clone and install instead:
 
 ```bash
-# Clone and install
 git clone https://github.com/ChanMeng666/a11y-loop.git
 cd a11y-loop
 npm install
-
-# Install the Chromium build Playwright needs for audits
 npx playwright install chromium
 ```
 
-Once published, the intended install is `npx a11y-loop <command>` with no local setup at all —
-that comes after the first npm publish.
-
 If you keep browser binaries off the system drive, set `PLAYWRIGHT_BROWSERS_PATH` before running
 `npx playwright install chromium` (and before running the test suite, which launches the same
 browser) — e.g. `PLAYWRIGHT_BROWSERS_PATH=D:\playwright-browsers`.
@@ -285,6 +376,38 @@ cp -r skill/a11y-loop .claude/skills/a11y-loop
 Any client implementing the [Agent Skills specification](https://agentskills.io/specification)
 can load it the same way — Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, and more.
 
+### Optional: the Claude Code plugin layer
+
+The skill above is the whole product and it is portable. This repository also ships a thin
+Claude-Code-only layer that adds one thing the portable skill cannot do — enforcement during
+plan mode:
+
+```bash
+# From a checkout, in Claude Code
+/plugin install .
+```
+
+It contributes:
+
+- a `PreToolUse` hook matched to `ExitPlanMode`. When a plan changes UI work and says nothing about
+  accessibility, the plan is declined once and the `### Accessibility` section is handed back to fill
+  in. It names any decision already in the plan that is hard to walk back later — drag-only
+  reordering, hover-only menus, infinite scroll, canvas-rendered data, time limits, CAPTCHA, autoplay.
+- `/a11y-plan`, to ask for that section directly.
+
+Deliberate limits: it **defers** rather than allows on every non-deny path, so it never suppresses
+your own plan approval; it declines a given plan **at most once**, so it cannot loop; a plan with no
+UI in it is passed silently; and `A11Y_LOOP_PLAN_GATE=off` disables it. The gate checks that the
+question was asked — it cannot check that the answer is any good. That is still `a11y-loop audit`
+and a human.
+
+| | Portable skill | Plugin layer |
+|---|---|---|
+| Install | copy `skill/a11y-loop` | `/plugin install .` |
+| Works in | 40+ Agent Skills clients | Claude Code only |
+| Gives you | §0 planning, §1 generation, §2 the loop, §3 honest reporting | plan-mode enforcement, `/a11y-plan` |
+| Required? | yes | no |
+
 ## ⚙️ Using it in CI
 
 ```bash
@@ -354,8 +477,17 @@ npm run test:unit       # unit tests only
 npm run test:integration  # integration tests only (drives real Chromium)
 ```
 
+The optional plugin layer is plain Node with no dependencies. Exercise the plan gate directly:
+
+```bash
+echo '{"session_id":"s1","tool_name":"ExitPlanMode","tool_input":{"plan":"Build a React modal with Tailwind CSS."}}' \
+  | node hooks/plan-gate.mjs
+claude plugin validate . --strict
+```
+
 See [`AGENTS.md`](AGENTS.md) for AI-agent-oriented project conventions, the fixture-manifest
-testing pattern, and the loop discipline expected when touching `demo/` or other UI.
+testing pattern, the loop discipline expected when touching `demo/` or other UI, and the rule that
+keeps `skill/` free of any Claude-Code-specific mechanism.
 
 ## 🤝 Contributing
 
@@ -393,6 +525,7 @@ uses to run its checks, is separately licensed under MPL-2.0 — see
 
 [demo-link]: docs/demo.gif
 [docs-link]: skill/a11y-loop/SKILL.md
+[docs-site-link]: https://ChanMeng666.github.io/a11y-loop/
 
 ---
 

package/commands/a11y-plan.md

@@ -0,0 +1,47 @@
+---
+name: a11y-plan
+description: Produce the plan-phase Accessibility section for a feature — conformance target, per-component criteria, decisions that foreclose accessibility, color tokens, structure, verification, manual budget.
+argument-hint: "[feature description, or nothing to use the current plan]"
+disable-model-invocation: true
+allowed-tools: Read Glob Grep Bash(a11y-loop contrast *) Bash(npx a11y-loop contrast *)
+---
+
+Write the **Accessibility** section for this plan-phase work:
+
+$ARGUMENTS
+
+If that is empty, use the plan currently under discussion in this conversation. If there is no plan
+either, ask what is being built before writing anything — a section written against a guess is worse
+than no section.
+
+## How
+
+Load the `a11y-loop` skill and follow its plan rules (§0) and
+`references/plan-phase.md`. Everything about which criteria apply, which product decisions foreclose
+accessibility, and how to pick color tokens lives there. Do not restate WCAG from memory here; read
+`references/wcag22-quick-ref.md` for exact SC numbers and thresholds, and
+`references/apg-patterns.md` for the keyboard contract of any widget the plan names.
+
+Where the plan names concrete colors, verify the pairs with `a11y-loop contrast --fix` in both light
+and dark rather than asserting a ratio.
+
+## Output
+
+One section, in this shape, every line answered from what is actually being built — no placeholders
+left in:
+
+```markdown
+### Accessibility
+- **Target:** WCAG 2.2 Level AA — <rationale / jurisdiction>
+- **Per-component criteria:** <component> → <SC list> + <keyboard contract source>
+- **Foreclosing decisions:** <none reviewed | list + alternatives>
+- **Color tokens:** <pairs verified with contrast --fix, light + dark>
+- **Structure:** <heading outline / landmarks / focus order>
+- **Verification:** <states needing --interact | where the audit gate sits>
+- **Manual budget:** <what automation cannot judge here>
+```
+
+Then say, in one line, which components in this plan you could not write criteria for and why.
+
+The skill's honesty rules (§3) apply to this section as much as to audit output: it is a set of
+decisions and acceptance criteria, not a claim that the result will be accessible or conformant.

package/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/plan-gate.mjs"],
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}