a11y-loop 0.1.0

package/skill/a11y-loop/references/manual-testing.md

@@ -0,0 +1,224 @@
+# What automation cannot check, and how to hand off
+
+A clean audit means "no automatically detectable failures in the states that
+were driven". It is the starting point for human review, not a substitute for
+it. This file is the material for that hand-off.
+
+---
+
+## Coverage, with denominators
+
+The honest figures disagree because they count different things. Always quote a
+figure **with its denominator**; a bare percentage is how coverage gets
+overstated.
+
+| Figure | What it actually measures | Source |
+|---|---|---|
+| **57%** | Volume of individual issue *instances* that automated testing found, across 2,000+ audits / 13,000+ pages / ~300,000 issues | Deque study, quoted in axe-core's README |
+| **31%** (17 of 55) | WCAG 2.2 A/AA success criteria that have *any* ACT-approved automated rule — and, in his words, "it's not full coverage of that 31%" | Adrian Roselli, March 2026 |
+| **13%** (7 of 55) | WCAG 2.2 A/AA criteria that automation flags *reliably*; 45% partially detectable, 42% not detectable | accessible.org |
+
+The seven criteria accessible.org counts as reliably automatable: 1.3.5 Identify
+Input Purpose, 1.4.3 Contrast (Minimum), 1.4.11 Non-text Contrast, 2.4.1 Bypass
+Blocks, 2.4.2 Page Titled, 2.5.8 Target Size (Minimum), 3.1.1 Language of Page.
+
+Karl Groves' breakdown of the rest: **9 Level A/AA criteria cannot be
+meaningfully tested by any tool**, and **13 more** can be tested automatically
+but need a human to confirm the result.
+
+Engine scope, for the provenance section of a report: axe-core ships 105 rules,
+of which **89 run by default** (60 WCAG 2.0 A/AA + 2 WCAG 2.1 A/AA + 27
+best-practice). WCAG 2.2 coverage is a single rule, `target-size`, and it is
+disabled by default upstream. **58 of the 105 rules can return an
+`incomplete` result** — a place the engine knows it could not decide.
+`a11y-loop` surfaces those as `needsReview` rather than folding them into
+passes.
+
+---
+
+## Requires human judgment — the full list
+
+Automation can tell you an attribute exists. It cannot tell you whether the
+content is any good.
+
+**Text alternatives and names**
+- Whether `alt` text conveys what the image conveys. `alt="decorative image"`,
+  `alt="image"`, and `alt="hero-2.jpg"` all pass every automated check and are
+  worse than `alt=""`.
+- Whether an accessible name is *useful*, not merely present.
+- Whether a decorative image was correctly judged decorative.
+- Whether link text makes sense out of context, as a screen reader user hears it
+  in a list of links ("read more", "here", "learn more").
+- Whether the visible label and the accessible name say the same thing in a way
+  a voice-control user would guess (SC 2.5.3 checks containment, not sense).
+
+**Structure and order**
+- Whether the heading outline reflects the actual information hierarchy.
+- Whether tab order is *logical* — a tool can only report that it diverges from
+  DOM order, not which order is right.
+- Whether landmarks segment the page usefully.
+- Whether reflow at 320px preserves meaning, or merely avoids a scrollbar.
+- Whether a table's header associations describe the real data relationships.
+
+**Forms and errors**
+- Whether an error message tells the user how to fix the problem (SC 3.3.3).
+- Whether required formats are explained before submission, not after.
+- Whether a multi-step process re-asks for information already given (SC 3.3.7).
+- Whether an authentication alternative is genuinely usable (SC 3.3.8).
+
+**Visual and motion judgment**
+- Whether a focus indicator is *visually* adequate: occluded by a sticky header
+  (SC 2.4.11), lost against a busy background image, or 1px on a dense table.
+- Whether reduced motion still communicates state change.
+- Whether contrast holds over gradients, images, video, and translucent
+  overlays — exactly the cases the engine returns as `incomplete`.
+
+**Media**
+- Caption accuracy, speaker identification, and timing.
+- Audio description completeness.
+- Transcript quality.
+
+**Consistency and cognition**
+- Consistent navigation and identification across pages (SC 3.2.3, 3.2.4) —
+  needs a multi-page view no single-page scan has.
+- Consistent placement of help (SC 3.2.6).
+- Reading level, plain language, and cognitive load (COGA). Barely covered by
+  any automated tool, and named as an open gap in the 2026 literature review.
+- Whether ARIA is used *appropriately* rather than merely *validly*. A page can
+  be free of ARIA syntax errors and still misrepresent itself completely.
+
+**Real assistive technology behavior**
+- NVDA, JAWS, VoiceOver, and TalkBack diverge from each other and from the
+  specification. Nothing predicts their actual output except running them.
+
+---
+
+## Known engine limitations to state in a report
+
+- `color-contrast` gives up — and returns `incomplete` — on background images,
+  gradients, pseudo-element backgrounds, and foreground opacity or occlusion. A
+  computed ratio of exactly 1:1 is usually the tell that it could not resolve
+  the background.
+- Hover and focus state contrast is never checked unless the state is driven and
+  the page re-scanned.
+- `target-size` has a documented false-positive history with overlapping and
+  translucent targets (axe-core issues #4805, #4350, #4295), which is why it is
+  reported as needs-review.
+- Cross-origin iframes may go untested — look for the `frame-tested` result.
+- Anything requiring interaction, timing, or state across multiple pages is out
+  of scope for a load-time scan. This is what `--interact` states exist for, and
+  it only covers the states someone thought to write.
+- axe-core returns zero false positives by design intent ("bugs
+  notwithstanding"), which means it stays silent wherever it is unsure. Silence
+  is not a pass.
+
+---
+
+## A five-minute keyboard test anyone can run
+
+No tools, no training. Hand this to whoever owns the feature.
+
+1. **Put the mouse away.** Click once in the page background, then use only the
+   keyboard.
+2. **Press `Tab` repeatedly through the whole page.** At every stop, ask: can I
+   *see* where I am? If the focus indicator vanishes anywhere, that is SC 2.4.7.
+3. **Watch the order.** Does focus move in the order things are laid out? Does
+   it ever jump backwards, or into something invisible?
+4. **Check for hidden stops.** If focus disappears for a press or two, it is
+   probably landing on an `aria-hidden` or off-screen element.
+5. **Check the sticky header.** Tab down the page — does the focused element ever
+   slide under a sticky header, footer, or cookie bar? That is SC 2.4.11.
+6. **Operate every control.** `Enter` on links and buttons, `Space` on buttons
+   and checkboxes, arrow keys in tabs, menus, radio groups, and selects. Anything
+   that only responds to a click is SC 2.1.1.
+7. **Open a dialog.** Does focus move into it? Does `Tab` stay inside it? Does
+   `Escape` close it? Does focus come back to the button that opened it? All four
+   must be yes.
+8. **Submit a form with mistakes.** Is the error announced or at least reachable?
+   Does it tell you how to fix it? Does focus go somewhere useful?
+9. **Zoom the browser to 400%** (`Ctrl`/`Cmd` and `+`). Any horizontal
+   scrolling, overlapping, or clipped text is SC 1.4.10 / 1.4.4.
+10. **Turn on OS dark mode and high contrast.** Does anything disappear?
+
+Any "no" is a real defect regardless of what an automated report said.
+
+---
+
+## Assistive technology: where to start
+
+- **NVDA** — free, open source, Windows. The most practical starting point, and
+  roughly the most-used screen reader worldwide.
+  [nvaccess.org](https://www.nvaccess.org/) · learn `Insert+Down` (read all),
+  `H` (next heading), `Tab`, `F` (next form field), `D` (next landmark),
+  `Insert+F7` (elements list — the fastest way to see how your page is really
+  structured).
+- **VoiceOver** — built into macOS and iOS, nothing to install. `Cmd+F5` to
+  toggle; `Ctrl+Option+U` opens the rotor. Test iOS separately: mobile
+  VoiceOver plus touch gestures behaves differently from macOS.
+- **JAWS** — Windows, commercial, still dominant in enterprise and government.
+  Worth testing if your users are in those settings; behavior differs from NVDA
+  often enough to matter.
+- **TalkBack** — Android, built in. The mobile counterpart to the above.
+- **Windows High Contrast / forced colors** and **OS text scaling** — fast, no
+  learning curve, and they surface hard-coded colors and fixed-height text boxes
+  immediately.
+
+Do not run one screen reader and generalise. They diverge from each other and
+from the specification, which is why the APG says outright that testing with
+real assistive technology is essential and that its own examples target spec
+compliance rather than AT bug workarounds.
+
+---
+
+## Involving disabled users
+
+The 2026 systematic literature review of LLMs for web accessibility found that
+few studies involve users with disabilities at all. Automated checks and expert
+review both answer "does this conform?"; only disabled users answer "is this
+usable?", and those are different questions with different answers.
+
+Practical, in rough order of cost:
+
+- Ask your organisation whether any employees use assistive technology daily and
+  would review a build.
+- Contact a local disability organisation or a Disabled People's Organisation —
+  many run paid user-testing panels.
+- Pay for a session with a screen reader user before a launch, not after. One
+  hour typically finds problems no scanner and no checklist surfaced.
+- Provide a real accessibility feedback route in the product and route it to
+  someone who can act.
+- Record who tested, with which assistive technology, on which version. An
+  honest, specific statement of who tested with what is more credible than any
+  score — and almost nobody publishes one.
+
+---
+
+## Wording for the hand-off
+
+Say this:
+
+> `a11y-loop audit` found no automatically detectable failures across the five
+> rendering passes (default, dark mode, forced colors, reduced motion, 320px
+> reflow) in the states driven: *default, settings-dialog-open,
+> signup-form-error*. Automated testing covers a minority of WCAG failures — on
+> Deque's measure, 57% of issue instances by volume; by criterion count, 17 of
+> the 55 WCAG 2.2 A/AA criteria have any automated rule at all. The following
+> still need human review: *[the manualChecklist from the report]*. Two
+> `needsReview` findings remain, both contrast over the hero gradient. Alt text
+> for three images is DRAFT and needs your confirmation. Please run a keyboard
+> pass and a screen reader pass before this ships.
+
+Not this:
+
+> The page is now fully accessible and WCAG 2.2 AA compliant.
+
+That second sentence is the claim shape that drew a $1,000,000 FTC penalty
+against an overlay vendor in 2025, and the 800+ signatories of the
+[Overlay Fact Sheet](https://overlayfactsheet.com/) exist to refute it. It is
+also just untrue: what was checked is what was checked.
+
+## Related
+
+- [wcag22-quick-ref.md](wcag22-quick-ref.md) — the 55 criteria and contrast thresholds
+- [apg-patterns.md](apg-patterns.md) — keyboard contracts to verify by hand
+- [ai-failure-modes.md](ai-failure-modes.md) — what to look for in generated code

package/skill/a11y-loop/references/wcag22-quick-ref.md

@@ -0,0 +1,224 @@
+# WCAG 2.2 Level AA — developer quick reference
+
+Normative text: [WCAG 2.2](https://www.w3.org/TR/WCAG22/) (W3C Recommendation
+5 Oct 2023, updated 12 Dec 2024; ratified as ISO/IEC 40500:2025).
+Filterable per-criterion index with techniques:
+[How to Meet WCAG](https://www.w3.org/WAI/WCAG22/quickref/).
+
+**Counting.** WCAG 2.2 has **86 success criteria** (31 A / 24 AA / 31 AAA), of
+which the **55 A + AA criteria** below must all be met for Level AA
+conformance. Sources claiming 87 have added the 9 new criteria without
+subtracting the one that was removed — **do not repeat the 87 figure**.
+
+**4.1.1 Parsing was removed** in WCAG 2.2, declared obsolete because assistive
+technology no longer parses HTML directly. Duplicate IDs and invalid nesting
+are still bugs worth fixing (they break `aria-labelledby`, label association,
+and `getElementById`), but they are no longer a WCAG failure. Never cite 4.1.1.
+
+**Target Level AA.** Every major regulation references AA: New Zealand Web
+Accessibility Standard 1.2 and UK public sector at WCAG 2.2 AA, US ADA Title II
+and EU EN 301 549 v3.2.1 at 2.1 AA (EU moves to 2.2 AA with v4.1.1), US Section
+508 at 2.0 AA. WCAG 2.2 is backward compatible, so hitting 2.2 AA satisfies all
+of them at once. W3C states explicitly that AAA is not a realistic
+whole-site target; treat individual AAA criteria as opt-in advisories.
+
+---
+
+## The 55 criteria (Level A and AA)
+
+`2.2` marks a criterion new in WCAG 2.2.
+
+### 1. Perceivable
+
+| SC | Name | Lvl | | What it means when you are writing code |
+|---|---|---|---|---|
+| 1.1.1 | Non-text Content | A | | Every image, icon, chart, and control has a text alternative; purely decorative images get `alt=""` |
+| 1.2.1 | Audio-only and Video-only (Prerecorded) | A | | Transcript for audio-only; transcript or audio track for video-only |
+| 1.2.2 | Captions (Prerecorded) | A | | Captions on all prerecorded video with sound |
+| 1.2.3 | Audio Description or Media Alternative | A | | Visual information in video is available in audio or text |
+| 1.2.4 | Captions (Live) | AA | | Live captions on live audio content |
+| 1.2.5 | Audio Description (Prerecorded) | AA | | An audio description track for prerecorded video |
+| 1.3.1 | Info and Relationships | A | | Structure you convey visually exists in markup: headings, lists, `<th>`, `<fieldset>`, label association |
+| 1.3.2 | Meaningful Sequence | A | | DOM order matches reading order; CSS reordering must not break it |
+| 1.3.3 | Sensory Characteristics | A | | No instructions that rely only on shape, size, position, or sound ("the round button on the right") |
+| 1.3.4 | Orientation | AA | | Do not lock to portrait or landscape unless essential |
+| 1.3.5 | Identify Input Purpose | AA | | `autocomplete` tokens on common fields (`name`, `email`, `tel`, address parts) |
+| 1.4.1 | Use of Color | A | | Color is never the only carrier of meaning; body-text links need a non-color cue |
+| 1.4.2 | Audio Control | A | | Audio over 3s has a pause/stop control or independent volume |
+| 1.4.3 | Contrast (Minimum) | AA | | 4.5:1 text, 3:1 large text — in light **and** dark mode |
+| 1.4.4 | Resize Text | AA | | Text scales to 200% without loss; relative units, no fixed-height text boxes |
+| 1.4.5 | Images of Text | AA | | Real text, not pictures of text (logos excepted) |
+| 1.4.10 | Reflow | AA | | No horizontal scroll at 320 CSS px wide (= 400% zoom of a 1280px viewport) |
+| 1.4.11 | Non-text Contrast | AA | | 3:1 for control boundaries, focus rings, icons, meaningful graphics |
+| 1.4.12 | Text Spacing | AA | | No loss when users override line-height 1.5, paragraph 2em, letter 0.12em, word 0.16em |
+| 1.4.13 | Content on Hover or Focus | AA | | Hover/focus popups are dismissible, hoverable, and persistent |
+
+### 2. Operable
+
+| SC | Name | Lvl | | What it means when you are writing code |
+|---|---|---|---|---|
+| 2.1.1 | Keyboard | A | | Every function works from the keyboard alone |
+| 2.1.2 | No Keyboard Trap | A | | Focus can always leave a component by keyboard |
+| 2.1.4 | Character Key Shortcuts | A | | Single-key shortcuts can be disabled, remapped, or fire only when the control has focus |
+| 2.2.1 | Timing Adjustable | A | | Time limits can be turned off, adjusted, or extended |
+| 2.2.2 | Pause, Stop, Hide | A | | Motion or auto-updating content over 5s can be paused, stopped, or hidden |
+| 2.3.1 | Three Flashes or Below Threshold | A | | Nothing flashes more than three times per second |
+| 2.4.1 | Bypass Blocks | A | | A skip link, or landmarks plus headings, to jump past repeated navigation |
+| 2.4.2 | Page Titled | A | | Every page and route has a unique, descriptive `<title>` |
+| 2.4.3 | Focus Order | A | | Tab order is meaningful; dialogs and inserted content receive focus where expected |
+| 2.4.4 | Link Purpose (In Context) | A | | Link text says where it goes; "read more" needs context or a fuller accessible name |
+| 2.4.5 | Multiple Ways | AA | | More than one route to a page: nav, search, sitemap |
+| 2.4.6 | Headings and Labels | AA | | Headings and labels actually describe what follows |
+| 2.4.7 | Focus Visible | AA | | A visible focus indicator on every keyboard-focusable element |
+| 2.4.11 | Focus Not Obscured (Minimum) | AA | `2.2` | Sticky headers, footers, and cookie bars must not entirely hide the focused element |
+| 2.5.1 | Pointer Gestures | A | | Pinch/swipe/path gestures have a single-pointer alternative |
+| 2.5.2 | Pointer Cancellation | A | | Act on pointer-up, not pointer-down; allow abort by moving away |
+| 2.5.3 | Label in Name | A | | The visible label text is contained in the accessible name |
+| 2.5.4 | Motion Actuation | A | | Shake/tilt triggers have a UI equivalent and can be disabled |
+| 2.5.7 | Dragging Movements | AA | `2.2` | Every drag interaction has a single-pointer alternative |
+| 2.5.8 | Target Size (Minimum) | AA | `2.2` | Targets >= 24x24 CSS px, or spaced so a 24px circle does not overlap a neighbour |
+
+### 3. Understandable
+
+| SC | Name | Lvl | | What it means when you are writing code |
+|---|---|---|---|---|
+| 3.1.1 | Language of Page | A | | `<html lang="en">` — trivially emitted, still missing on 13.5% of pages |
+| 3.1.2 | Language of Parts | AA | | Mark inline language changes with `lang` |
+| 3.2.1 | On Focus | A | | Focusing something never changes context (no auto-submit, no popup on focus) |
+| 3.2.2 | On Input | A | | Changing a value never changes context unless the user was warned first |
+| 3.2.3 | Consistent Navigation | AA | | Repeated navigation keeps the same relative order across pages |
+| 3.2.4 | Consistent Identification | AA | | The same function gets the same name and icon everywhere |
+| 3.2.6 | Consistent Help | A | `2.2` | Help mechanisms appear in the same relative order on every page that has them |
+| 3.3.1 | Error Identification | A | | Errors are described in text and name the field — not just a red border |
+| 3.3.2 | Labels or Instructions | A | | Inputs have labels; required formats stated up front, not only after failure |
+| 3.3.3 | Error Suggestion | AA | | Suggest a correction when you can determine one |
+| 3.3.4 | Error Prevention (Legal, Financial, Data) | AA | | Consequential submissions are reversible, checked, or confirmed |
+| 3.3.7 | Redundant Entry | A | `2.2` | Do not ask for the same information twice in one process — auto-fill or offer it for selection |
+| 3.3.8 | Accessible Authentication (Minimum) | AA | `2.2` | No cognitive-function test in login without an alternative; allow paste and password managers |
+
+### 4. Robust
+
+| SC | Name | Lvl | | What it means when you are writing code |
+|---|---|---|---|---|
+| 4.1.2 | Name, Role, Value | A | | Every control exposes an accessible name, the correct role, and its current state |
+| 4.1.3 | Status Messages | AA | | Status changes that do not move focus are announced via `role="status"` / `role="alert"` |
+
+Understanding documents live at
+`https://www.w3.org/WAI/WCAG22/Understanding/<slug>`, where the slug is the
+criterion name lowercased and hyphenated — `non-text-content`,
+`contrast-minimum`, `name-role-value`, `status-messages`. When unsure, start
+from the [Understanding index](https://www.w3.org/WAI/WCAG22/Understanding/).
+
+---
+
+## The 9 criteria new in WCAG 2.2
+
+Six are at A/AA and therefore obligations; three are AAA. These are the ones
+generated code misses most reliably, because most training data predates them.
+
+**2.4.11 Focus Not Obscured (Minimum) — AA.** When an element receives keyboard
+focus, no author-created content may hide it entirely. The usual culprits are
+sticky headers, sticky footers, cookie banners, and chat widgets. Fix with
+`scroll-margin-top` matching the sticky header height on focusable elements, and
+by giving overlays a real close control.
+[Understanding](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html)
+
+**2.4.12 Focus Not Obscured (Enhanced) — AAA.** As above, but *no part* of the
+focused element may be obscured.
+[Understanding](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html)
+
+**2.4.13 Focus Appearance — AAA.** The focus indicator must be at least as large
+as a 2px-thick perimeter of the component and have at least 3:1 contrast between
+focused and unfocused states. Useful as a design target even though it is AAA;
+AA still requires a visible indicator via 2.4.7 and 3:1 via 1.4.11.
+[Understanding](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html)
+
+**2.5.7 Dragging Movements — AA.** Any functionality that uses a dragging
+movement must also be operable with a single pointer without dragging. Sortable
+lists need move-up/move-down buttons; sliders need clickable track and arrow
+keys; kanban cards need a "move to" menu; drag-to-upload needs a file input.
+[Understanding](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html)
+
+**2.5.8 Target Size (Minimum) — AA.** Pointer targets are at least 24x24 CSS px.
+Exceptions: spacing (a 24px-diameter circle centred on the target overlaps no
+other target's circle), inline targets inside a sentence, targets whose size is
+browser-determined, and where a conforming equivalent exists elsewhere on the
+page. Icon buttons at 16px and dense table-row action links are the common
+failures. Note that axe-core's `target-size` rule is **disabled by default** and
+has a documented false-positive history with overlapping and translucent
+elements — `a11y-loop` enables it but reports it as needs-review, never as a
+hard failure.
+[Understanding](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)
+
+**3.2.6 Consistent Help — A.** If a help mechanism (contact details, human
+contact, a self-help link, an automated chat) repeats across pages, it must
+appear in the same relative order in the page. It does not require that you
+*provide* help — only that existing help is placed consistently.
+[Understanding](https://www.w3.org/WAI/WCAG22/Understanding/consistent-help.html)
+
+**3.3.7 Redundant Entry — A.** Information the user already supplied in the same
+process is either auto-populated or available to select — no retyping an address
+at step 4 that was entered at step 2. Exceptions: re-entry that is essential
+(confirming a password), where the earlier information is no longer valid, or
+for security. Multi-step checkout and signup wizards are the common failures.
+[Understanding](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html)
+
+**3.3.8 Accessible Authentication (Minimum) — AA.** No step in an
+authentication process may require a cognitive function test (remembering a
+password, transcribing characters, solving a puzzle, identifying objects in
+images) unless there is an alternative, or a mechanism to assist. In practice:
+never block paste into password or one-time-code fields, never disable password
+managers, use `autocomplete="current-password"` / `one-time-code`, and offer a
+non-puzzle option alongside any CAPTCHA. Object-recognition CAPTCHAs are
+explicitly permitted only as the *alternative*, not as the sole path.
+[Understanding](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html)
+
+**3.3.9 Accessible Authentication (Enhanced) — AAA.** As above with the
+object-recognition and personal-content exceptions removed.
+[Understanding](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-enhanced.html)
+
+---
+
+## Contrast thresholds
+
+| | Normal text | Large text | Non-text / UI |
+|---|---|---|---|
+| **AA** | **4.5:1** (SC 1.4.3) | **3:1** (SC 1.4.3) | **3:1** (SC 1.4.11) |
+| AAA | 7:1 (SC 1.4.6) | 4.5:1 (SC 1.4.6) | — |
+
+**Large text is 18pt regular or 14pt bold.** At the CSS default of 1pt =
+1.333px that is **>= 24px regular, or >= 18.5px bold**. Get this boundary right:
+it is the most common source of disagreement between contrast tools. A 20px
+heading is *not* large text and needs 4.5:1.
+
+SC 1.4.11 applies to the visual boundary of controls (input borders, button
+edges, checkbox outlines), focus indicators, and graphics required to understand
+content (chart lines, meaningful icons) — not to decorative graphics or to
+inactive controls.
+
+Reference math, matching browsers, axe-core, and the
+[WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/):
+
+```
+c_srgb = c_8bit / 255
+c      = c_srgb <= 0.04045 ? c_srgb / 12.92 : ((c_srgb + 0.055) / 1.055) ** 2.4
+L      = 0.2126*R + 0.7152*G + 0.0722*B
+ratio  = (L_lighter + 0.05) / (L_darker + 0.05)
+```
+
+Composite translucent foregrounds over their background in non-linear sRGB
+*before* linearizing. Run `a11y-loop contrast <fg> <bg> [--large] [--ui] --fix`
+rather than doing this by hand; `--fix` returns both a lighter and a darker
+passing candidate with hue and chroma preserved.
+
+**APCA is not a WCAG algorithm.** It was removed from the WCAG 3 draft in July
+2023, and the April 2026 WCAG 3 editor's draft states the contrast algorithm is
+"yet to be determined". APCA's technical critique of WCAG 2 is legitimate —
+WCAG 2 overstates contrast for near-black pairs — but Lc values have no
+normative or legal standing. Never let an APCA pass excuse a WCAG 2 failure.
+
+## Related
+
+- ARIA and widget behavior: [apg-patterns.md](apg-patterns.md)
+- What generated code gets wrong: [ai-failure-modes.md](ai-failure-modes.md)
+- What none of this can check: [manual-testing.md](manual-testing.md)

package/src/cli.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * a11y-loop CLI.
+ *
+ * Exit codes are the loop's contract:
+ *   0 — no violations (audit) / threshold met (contrast) / no regression (diff)
+ *   1 — violations found / threshold missed / regression introduced
+ *   2 — tool error (bad arguments, missing browser, unreadable report)
+ */
+
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { readFile } from 'node:fs/promises';
+
+import { runAuditCommand } from './commands/audit.js';
+import { runContrastCommand } from './commands/contrast.js';
+import { runDiffCommand } from './commands/diff.js';
+import { ToolError } from './lib/axe-runner.js';
+
+export const EXIT = { OK: 0, FINDINGS: 1, ERROR: 2 };
+
+const OPTIONS = {
+  json: { type: 'boolean', default: false },
+  out: { type: 'string' },
+  sarif: { type: 'string' },
+  headed: { type: 'boolean', default: false },
+  // parseArgs has no --no-* negation, so the negative form is its own option.
+  'no-best-practice': { type: 'boolean', default: false },
+  interact: { type: 'string' },
+  quiet: { type: 'boolean', default: false },
+  file: { type: 'string' },
+  html: { type: 'string' },
+  large: { type: 'boolean', default: false },
+  ui: { type: 'boolean', default: false },
+  fix: { type: 'boolean', default: false },
+  before: { type: 'string' },
+  after: { type: 'string' },
+  help: { type: 'boolean', default: false, short: 'h' },
+  version: { type: 'boolean', default: false },
+};
+
+const USAGE = `a11y-loop — accessibility verification for AI coding agents
+
+USAGE
+  a11y-loop audit <url>              audit a running page
+  a11y-loop audit --file <path>      audit an HTML file (served over http, never file://)
+  a11y-loop audit --html "<button>"  audit a fragment (the usual entry point for an agent)
+  a11y-loop contrast <fg> <bg>       check a colour pair against WCAG 2.x
+  a11y-loop diff --before a.json --after b.json    compare two audits
+
+AUDIT OPTIONS
+  --json                 machine-readable report on stdout
+  --out <path>           write the JSON report to a file
+  --sarif <path>         also write SARIF v2.1 (see notes in the report)
+  --interact <path.mjs>  audit interaction states: export const states = { name: async (page) => {} }
+  --headed               run a visible browser (debugging)
+  --no-best-practice     omit axe best-practice rules (they are never blocking either way)
+  --quiet                one-line summary only
+
+CONTRAST OPTIONS
+  --large                large-scale text thresholds (>=24px, or >=18.5px bold)
+  --ui                   non-text / UI component threshold (3:1, SC 1.4.11)
+  --fix                  suggest passing colours, lighter and darker, in OKLCh
+  --json                 machine-readable result
+
+EXIT CODES
+  0  no violations / threshold met / no regression
+  1  violations found / threshold missed / new violations introduced
+  2  tool error
+
+Five rendering passes run per audit: default, dark, forced-colors, reduced-motion,
+and a 320x256 viewport (the WCAG-sanctioned 400% zoom equivalent for SC 1.4.10).
+
+Automated checks cover a subset of WCAG (Deque: ~57% of issues by volume; ~31% of AA
+criteria have any automated rule). This is not an audit or conformance claim.
+`;
+
+/**
+ * Turn argv into a command plus normalised flags.
+ * @param {string[]} argv
+ */
+export function parseCli(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: OPTIONS,
+    allowPositionals: true,
+    strict: true,
+  });
+
+  const flags = {
+    ...values,
+    bestPractice: !values['no-best-practice'],
+  };
+  delete flags['no-best-practice'];
+
+  return { command: positionals[0] ?? null, positionals: positionals.slice(1), flags };
+}
+
+/**
+ * Work out what `audit` should audit.
+ * @returns {{type:'url'|'file'|'html', value:string}}
+ */
+export function resolveAuditTarget(positionals, flags) {
+  const given = [
+    positionals[0] ? { type: 'url', value: positionals[0] } : null,
+    flags.file ? { type: 'file', value: flags.file } : null,
+    flags.html !== undefined ? { type: 'html', value: flags.html } : null,
+  ].filter(Boolean);
+
+  if (given.length === 0) {
+    throw new ToolError('audit needs a target.', {
+      hint: 'Use one of:\n  a11y-loop audit http://localhost:3000\n  a11y-loop audit --file page.html\n  a11y-loop audit --html "<button></button>"',
+    });
+  }
+  if (given.length > 1) {
+    throw new ToolError(
+      `audit takes exactly one target, but got ${given.map((g) => g.type).join(' and ')}.`,
+    );
+  }
+
+  const target = given[0];
+  if (target.type === 'url' && !/^https?:\/\//i.test(target.value)) {
+    if (/^file:\/\//i.test(target.value)) {
+      throw new ToolError('file:// URLs are not supported.', {
+        hint:
+          'A null origin breaks axe frame injection, ES modules and fetch. Use --file <path> ' +
+          'instead — a11y-loop serves it over http on 127.0.0.1.',
+      });
+    }
+    throw new ToolError(`"${target.value}" is not an http(s) URL.`, {
+      hint: 'Did you mean --file or --html?',
+    });
+  }
+  return target;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{write:Function, writeError:Function}} [io]
+ * @returns {Promise<number>} exit code
+ */
+export async function main(argv, io) {
+  const out = io ?? {
+    write: (text) => process.stdout.write(text),
+    writeError: (text) => process.stderr.write(text),
+  };
+
+  let parsed;
+  try {
+    parsed = parseCli(argv);
+  } catch (error) {
+    out.writeError(`a11y-loop: ${error.message}\n\n${USAGE}`);
+    return EXIT.ERROR;
+  }
+
+  const { command, positionals, flags } = parsed;
+
+  if (flags.version) {
+    const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    out.write(`${pkg.version}\n`);
+    return EXIT.OK;
+  }
+
+  if (flags.help || command === 'help' || command === null) {
+    out.write(USAGE);
+    return command === null && !flags.help ? EXIT.ERROR : EXIT.OK;
+  }
+
+  try {
+    if (command === 'audit') {
+      const target = resolveAuditTarget(positionals, flags);
+      return await runAuditCommand({ target, flags }, out);
+    }
+
+    if (command === 'contrast') {
+      const [fg, bg] = positionals;
+      if (!fg || !bg) {
+        throw new ToolError('contrast needs two colours.', {
+          hint: 'a11y-loop contrast "#777777" "#ffffff" [--large] [--ui] [--fix]',
+        });
+      }
+      return await runContrastCommand({ fg, bg, flags }, out);
+    }
+
+    if (command === 'diff') {
+      return await runDiffCommand({ flags }, out);
+    }
+
+    out.writeError(`a11y-loop: unknown command "${command}"\n\n${USAGE}`);
+    return EXIT.ERROR;
+  } catch (error) {
+    if (error instanceof ToolError) {
+      out.writeError(`a11y-loop: ${error.message}\n`);
+      if (error.hint) out.writeError(`\n${error.hint}\n`);
+      return EXIT.ERROR;
+    }
+    out.writeError(`a11y-loop: unexpected error: ${error?.message ?? error}\n`);
+    if (process.env.A11Y_LOOP_DEBUG) out.writeError(`${error?.stack ?? ''}\n`);
+    else out.writeError('Set A11Y_LOOP_DEBUG=1 for a stack trace.\n');
+    return EXIT.ERROR;
+  }
+}
+
+// Only run when invoked as a program, so tests can import `main` freely.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await main(process.argv.slice(2));
+}