ultra11y 2.22.0

package/skills/ultra11y/references/dynamic.md

@@ -0,0 +1,152 @@
+# Dynamic tier (axe-core) — optional
+
+The static engine leaves some criteria "to assess" because they need a **render**: computed
+contrast (1.4.3), focus visible (2.4.7), reflow/zoom (1.4.4/1.4.10), text spacing (1.4.12),
+content on hover (1.4.13), target size (2.5.8). The dynamic tier decides them by running
+**axe-core in a real headless browser** (Playwright). Two runtimes, same finding shape:
+
+- **`--runtime local`** (recommended): resolves a host/target Playwright + `@axe-core/playwright`
+  **at runtime** from `--cwd` (no Docker, no global install). Most projects with Playwright
+  e2e tests already have both deps. Adds the residual-criteria **probes** (below).
+- **`--runtime docker`**: runs axe-core in a Docker image auto-built on first use (runner +
+  Dockerfile embedded in the bundle). No host deps beyond Docker. Axe + 320px reflow only.
+- **`--runtime auto`** (default): local if Playwright resolves from `--cwd`, else Docker, else
+  an actionable error.
+
+## Prerequisites
+
+- **local**: a project reachable from `--cwd` with `@playwright/test` + `@axe-core/playwright`
+  installed, and a Chromium browser (`npx playwright install chromium`).
+- **docker**: Docker running.
+
+The rest of the skill (static audit) needs neither.
+
+## Usage
+
+```
+# auto runtime (local if available, else Docker)
+node scripts/ultra11y.mjs scan https://example.com --json
+
+# explicit local runtime, resolving deps + browser from a project (e.g. a monorepo package)
+node scripts/ultra11y.mjs scan http://localhost:3000 --runtime local --cwd packages/app --json
+
+# authenticated pages: pass a Playwright storageState JSON (cookies/localStorage)
+node scripts/ultra11y.mjs scan http://localhost:3000/dashboard --runtime local \
+  --cwd packages/app --storage-state packages/app/test-results/.auth/user.json --json
+
+# several explicit URLs at once (one browser, one context per page)
+node scripts/ultra11y.mjs scan http://localhost:3000/ http://localhost:3000/login --runtime local --cwd packages/app
+
+# merge with a static audit: the "to assess" criteria turn C/NC
+node scripts/ultra11y.mjs audit "src/**/*.tsx" --jsx --out audits --json > /dev/null
+node scripts/ultra11y.mjs scan http://localhost:3000 --runtime local --cwd packages/app --merge audits/audit-latest.json --out audits
+node scripts/ultra11y.mjs report --in audits/audit-latest.json --out audits
+```
+
+`--storage-state` is **local-only**. Combining it with an **explicit** `--runtime docker` (or
+the `--docker` alias) is an unsupported combination and errors out (exit 2) — the Docker tier
+cannot use a Playwright storageState, and scanning unauthenticated would silently defeat the
+flag. Under `--runtime auto` that happens to fall back to Docker (no local Playwright
+resolved), it degrades with a warning instead — you didn't ask for Docker specifically.
+Produce the file with Playwright (e.g. an e2e auth setup that logs in and
+`context.storageState({ path })`).
+
+### Cover many pages (crawl)
+
+```
+# every URL listed in a sitemap.xml
+node scripts/ultra11y.mjs scan --sitemap https://example.com/sitemap.xml --json
+
+# BFS of served same-origin links, from an entry page
+node scripts/ultra11y.mjs scan --crawl https://example.com --depth 2 --max 50 --json
+```
+
+Each finding keeps the **page** it came from (`--merge` reports that URL as `file`). `--crawl`
+follows links in the **served HTML** (SSR/MPA); for a pure SPA, use `--sitemap` or pass the
+URLs explicitly. The crawl fetch is unauthenticated — for authed pages pass explicit URLs +
+`--storage-state` instead.
+
+## What the dynamic tier adds
+
+- **Real contrast (1.4.3)** — axe computes the rendered colours (the main win, both runtimes).
+- **Reflow (1.4.10)** — no horizontal scroll at 320px wide (both runtimes).
+- **Cross-check** — axe re-validates the structural criteria (alt, labels, ARIA, headings…) at
+  render; a render finding is **authoritative** and turns the criterion NC.
+
+axe findings map to WCAG success criteria via a curated table (`axe-rule → SC`), completed by
+axe's **native WCAG tags** (`wcag<abc>`). On merge (`--merge`), a `manual` criterion the tier
+decides leaves the residual risks and becomes `C`/`NC` (ruleId `axe:<rule>` for axe findings).
+
+### Residual-criteria probes (local runtime only)
+
+Beyond axe, the local runtime runs bespoke Playwright probes for the criteria axe alone cannot
+decide. Each raises a **definite NC only when the failure is observed** in the rendered page; a
+clean probe leaves the SC `manual` (never silently conforming). Merged findings get a
+`dyn-<engine>` ruleId.
+
+| Probe | SC | How |
+|---|---|---|
+| focus visibility | 2.4.7 | Tab through focusables; flag any whose computed style (outline/box-shadow/border/background) is unchanged when focused |
+| 200% zoom | 1.4.4 | Enlarge text to 200%; flag page-level horizontal scroll or text clipped in an `overflow:hidden` container |
+| text spacing | 1.4.12 | Inject the WCAG 1.4.12 spacing override; flag clipped/truncated text |
+| content on hover | 1.4.13 | For `aria-describedby` triggers whose target is hidden, hover to reveal then check it is dismissible (Escape) |
+
+Visually-hidden (`clip`/1px sr-only) elements are excluded from these probes. **Target size
+(2.5.8)** is intentionally left to axe-core's own `target-size` rule, which applies the inline
+and 24px-spacing exceptions correctly (a hand-rolled probe was strictly noisier on real pages).
+
+These probes are heuristic (conservative severities: focus + zoom `majeur`, the rest `mineur`)
+and **local-only** — the Docker `RUNNER` is kept byte-identical to `docker/runner.mjs`
+(`docker-sync` test), so mirroring the probes into the Docker path is deferred. Adversarially
+verify probe findings (a `verify` pass) before filing them.
+
+### Stateful interaction probes (local runtime, interactions ON by default)
+
+The read-only probes above measure a page **as served**. Some non-conformities only appear
+once the user has *interacted* — a filled field that overflows its cell, a status message
+that never reaches a live region. The local runtime therefore also runs a **stateful** pass
+that drives the page, then restores it. **Safety contract**: only NON-navigating actions are
+performed — fill text inputs (a long representative value, respecting `maxlength`), toggle
+checkbox/radio, click `button[type="button"]`. **Never** a link, a submit button, or a form
+submit; every interaction records `location.href` first and aborts + restores if it changed;
+every loop is bounded; original state is always restored.
+
+| Stateful probe | SC | What it adds |
+|---|---|---|
+| fill-inputs → re-measure | 1.4.4 / 1.4.10 / 1.4.12 | fills visible text-like inputs with real content, then re-runs the zoom/reflow/spacing stress probes so an overflow that only occurs *when the field holds the value the auditor must type* is caught |
+| live-region | 4.1.3 | triggers safe interactions and checks that a resulting status message lands in an `aria-live`/`role="status"`/`role="alert"` region (status-messages) — the extra SC `localTestedScs` reports only when interactions are on |
+
+- **`--no-interact`** disables the whole stateful pass (fill + live-region), leaving only the
+  read-only probes — use it when even bounded, non-navigating interaction is unwelcome.
+- **Authenticated-scan click policy.** When a `--storage-state` session is loaded, the
+  live-region probe does **not** click buttons by default (even a `type="button"` click can
+  trigger a server mutation the `location.href` assertion cannot see). Fill/toggle still run.
+  **`--interact-clicks`** re-enables the clicks explicitly; unauthenticated scans keep clicks
+  on. Defense-in-depth on top: a button whose accessible name matches a
+  destructive/submitting verb (delete, remove, send, submit, confirm, pay…) is **never**
+  clicked, in either mode.
+
+## Scan a normative page sample (`scan --sample`)
+
+A real country-standard audit runs over a declared **page sample** (échantillon), not one
+URL. Declare it in `.ultra11yrc.json` under `sample.pages` (+ `transverse`), then:
+
+```
+node scripts/ultra11y.mjs sample check                                   # lint the sample's coverage vs the standard's required kinds
+node scripts/ultra11y.mjs scan --sample --runtime local --cwd packages/app --merge audits/audit-latest.json --out audits
+```
+
+`scan --sample` iterates every configured sample page (per-page `--storage-state` supported
+for authenticated pages), keeps each finding's originating **page name + auth flag** as
+provenance (surfaced in the auditor ticket's *Pages / URLs impactées* and *Contexte de
+reproduction*), and `--merge`s them into the audit. `sample check` is an **advisory** lint —
+it reports which required page kinds the sample lacks (a malformed `sample` block is a hard
+error, exit 2; a merely-incomplete one is guidance, exit 0). See `references/audit.md`
+(sample concept) and `references/packs.md` (`sampleMethodology`).
+
+## Limits
+
+Even with the local probes, **reading order**, **alt relevance** and the other judgment criteria
+are the AI agent's to adjudicate (gated, `verify --manual`), not the dynamic tier's. The probes
+reduce — but do not eliminate — the residual on 2.4.7/1.4.4/1.4.12/1.4.13/2.5.8: confirm a sample
+on screen (optional human oversight). pa11y can be added as a second source if needed.

package/skills/ultra11y/references/false-positives.md

@@ -0,0 +1,81 @@
+# Known false-positive traps — what to scrutinise before trusting a finding
+
+The static engine reads SOURCE, not the rendered DOM. On component-based code that
+creates a few predictable false-positive (FP) classes. The engine now **auto-suppresses**
+most of them; this page tells you (the agent) where it still cannot be sure, so you can
+**confirm or refute** instead of trusting blindly. Run the refutation loop:
+`verify --report <md> [--semantic]` → rule each item against the cited `file:line` →
+`verify --apply <verdicts.json>` (refuted/unsupported entries fail the gate).
+
+## How the engine already protects you
+
+- **Components are skipped.** A PascalCase tag (`<Button>`, `<HistoryEntry>`) keeps its
+  case in JSX **and** in `.vue/.svelte/.astro` (parsed with case preserved). Single-file
+  rules only fire on intrinsic HTML tags, so a component child of `<ul>`, a `<Select>`,
+  or a `role` prop on `<UChatMessage>` is no longer mis-flagged.
+- **Injected content is not "empty".** A `<slot>`, `{@render children()}`, `{children}`,
+  or a child component means the name/content/options may be supplied at runtime —
+  `empty-heading`, `button-empty-name`, `link-empty-name`, `select-has-option`,
+  `list-structure`, `data-table-no-headers` and `h1-missing` all bail instead of asserting.
+- **Dynamic bindings/values count as present, never invalid.** `:aria-label`,
+  `v-bind:aria-label`, `bind:value`, `:alt`, `:scope` (Vue/Svelte/Alpine) are read as
+  "present, value unknown"; a dynamic `role={…}` is skipped (not parsed as a bogus role);
+  a `v-bind="…"` / `{...rest}` / `{shorthand}` spread suppresses missing-name/label/alt.
+- **Cross-file references resolve under `--graph`.** An `aria-controls`/`for`/heading
+  target defined in another file (including a `const X = "id"; id={X}`) is proven to exist
+  and the finding is suppressed; an icon-only component whose definition supplies its own
+  `aria-label` is not flagged "unnamed". **Always run component code with `--graph`.**
+- **Conditional branches & interleaved components aren't crossed.** Headings in different
+  arms of `{cond ? … : …}` are mutually exclusive, and a child component between two
+  headings may inject an intermediate one — so `heading-order-skip` won't compare across them.
+- **Framework shell templates are recognized.** A SPA mount shell (`<div id="app"></div>`)
+  or a build placeholder (`%sveltekit.body%`/`%sveltekit.head%`, `{{ }}`, `<%= %>`) means
+  the real content/title is injected later — `h1-missing`/`title-missing-empty` don't fire.
+- **Slot-projected required content is not "missing".** A `<slot>`/`{@render children()}`
+  passthrough suppresses `fieldset-legend-missing` and `aria-required-children`; `<th>` in a
+  `<thead>` carries implicit column scope.
+- **Test/story markup is out of scope by default.** `*.test.*`, `*.spec.*`, `*.stories.*`
+  and `__tests__/` are excluded (bad-by-design fixtures). Re-include with
+  `--no-default-excludes` or by naming the file.
+
+## Where the AI agent must still adjudicate
+
+A finding's `preliminary: true` (in `--json`) and a `scope.sourceTemplate` / `scope.rendered`
+caveat in the report mean **the verdict is provisional** — the AI agent confirms it against the
+rendered output (rendering criteria go to `scan`), recording a verdict either way.
+
+| Rule / situation | Why it may still be wrong | How to confirm or refute |
+|---|---|---|
+| Any finding on `.vue/.svelte/.astro` SOURCE | Slots, snippets, `{#if}`, `v-for`, scoped logic and provide/inject are invisible to the template parser | Audit the **rendered** HTML (Storybook/build output) or `scan` a live page; refute the source finding if the rendered DOM is conformant |
+| Any finding on library-rendered JSX (DSFR/MUI…) | The component's produced HTML lives in `node_modules` | `render` → build/SSR → `audit` the output, or `scan` |
+| `control-label-missing` in an SFC | The label may be wired via provide/inject or a sibling `<Label>` component the parser can't link | Read the form component + its field wrapper; refute if a programmatic label exists at render |
+| `heading-order-skip` via `{#if}`/`v-if` in SFCs (no AST) | SFC conditionals are opaque text, so arms can't be separated like in JSX | Reason about each render path; flag only a skip that occurs in a single path |
+| `contrast` (1.4.3), focus, zoom, reflow | Needs computed styles | `scan` (Docker tier) — never decide from source |
+| `aria-*` referencing a runtime-built id (`id={`\`x-${i}\``}`) | The id is dynamic; cross-file resolution only handles `const` string ids | Read the component; refute if the id is generated and wired correctly |
+
+## Normativity false positives — a "problem" with no failing normative test
+
+A finding can cite a real element yet still not be a **non-conformity**, because no test of
+the active standard actually fails. These were the professional-auditor + official-Ara
+corrections against ultra11y's own RGAA audit of egapro; each is now handled as a
+**recommendation (non-normative)** or suppressed outright — never a normative NC.
+
+| Case | Why it is NOT an NC | Current handling |
+|---|---|---|
+| An **empty `<th>`** (layout/spacer header cell) | No RGAA/WCAG test says every `<th>` must have content; a best-practice-only axe `empty-table-header` violation carries no `wcag*` tag | merges as **advisory**, attaches to no criterion as NC |
+| A **download link** (`…report.pdf`) whose text doesn't name the format/weight | Good practice (DSFR), but no failing normative test under 6.1/2.4.4 | the RGAA `download-link-format` pack rule is **`advisory: true`** → « Recommandation (non normative) », never flips 6.1 |
+| **Two `<h1>`** on a page / a page **starting at `<h2>`** | "one `<h1>` per page" is not a rule in HTML, a11y, or SEO; no heading-order skip occurs | `h1-multiple` / `h1-missing` are **advisory** (no normative NC) |
+| A **lorem-ipsum tooltip** | Content-quality (UX), not accessibility | emits **no finding** |
+
+The distinction is the same one you apply in the judgment phase (`references/judgment.md`):
+an **NC needs a `normativeRef`** citing the precise failed test of the active standard; a
+good practice without one is a `recommendations[]` entry, and a pure UX concern is neither.
+When you adjudicate, don't "promote" a recommendation to an NC to look thorough.
+
+## The rule of thumb
+
+The engine raises **confirmed candidates**, never silent conformance. When a finding is
+`preliminary`, or sits on SFC/library source, treat it as "verify, don't trust": open the
+`file:line`, check whether the missing thing is injected/rendered elsewhere, and record a
+`supported`/`refuted` verdict via `verify --apply`. A refuted finding is dropped — that is
+the anti-hallucination contract working as intended.

package/skills/ultra11y/references/fix.md

@@ -0,0 +1,46 @@
+# Put the fixes in place — `fix` (hybrid, native-first)
+
+`fix` applies what is **mechanically safe**, prepares what needs a word filled in, and
+**proposes** what is judgment — without ever inventing content (anti-hallucination doctrine).
+By default it is a **dry-run** (diff); `--write` applies.
+
+```
+node scripts/ultra11y.mjs fix "src/**/*.html"            # dry-run: diff + list
+node scripts/ultra11y.mjs fix "src/**/*.html" --write     # apply the safe fixes
+node scripts/ultra11y.mjs fix --changed --write           # only the git diff
+node scripts/ultra11y.mjs fix page.html --only positive-tabindex --write
+```
+
+## Three classes of fix
+
+- **auto** — deterministic, no judgment, written as-is:
+  `positive-tabindex` (→ `tabindex="0"`), `redundant-aria` (drop the redundant `role`),
+  `meta-viewport-zoom-block` (drop blocking `user-scalable=no` / `maximum-scale`).
+- **fill-in (placeholder)** — inserts a **valid** attribute with a `TODO` sentinel that **you**
+  replace with a relevant, in-context value: `html-lang-missing` (`lang="TODO"`),
+  `iframe-title-missing` (`title="TODO"`), `img-alt-missing` (`alt="TODO"` or
+  `aria-label="TODO"`), `control-label-missing` (`aria-label="TODO"`).
+- **judgment (proposal)** — the engine never fixes on its own: alt relevance (1.1.1), link/
+  button purpose (2.4.4/4.1.2), contrast, table/fieldset structure… the AI agent writes the
+  content and adjudicates the criterion (`verify --manual`, gated).
+
+## Guarantees
+
+- **Edit by source range**: codemods re-read the opening tag locally (attribute offsets are not
+  provided by the parser) and apply edits **back-to-front**; edits that overlap on one element
+  are dropped, never misapplied.
+- **Anti-regression gate**: after `--write`, the file is re-audited; if a fix **introduced** a
+  new non-conformity, it is **not** written.
+- **JSX/TSX: safe codemods only.** `.jsx`/`.tsx` parse to a real AST whose offsets index the
+  original file, so `fix --write` applies the codemods marked **jsxSafe** (attribute removal /
+  insertion of React-valid props) — it never rewrites an attribute name (`tabIndex={5}` is
+  never turned into `tabindex="0"`). Only the rare **lossy** fallback (a file the AST parser
+  could not parse at all) stays proposal-only.
+
+## Fix order (native-first)
+
+native semantics → accessible names / labels → keyboard access → visible focus → meaning not
+carried by colour alone → media. See `references/authoring.md` and
+`references/forbidden-patterns.md`. After fixing, re-audit; the AI agent adjudicates the judgment
+criteria (`verify --manual`, gated) and the rendering criteria go to `scan` — never marked
+conforming without a recorded, gated justification.

package/skills/ultra11y/references/focus-and-logic.md

@@ -0,0 +1,64 @@
+# Focus & interaction logic — the agent reads the source and adjudicates the interaction logic
+
+A static engine sees *structure*. It cannot see what happens when a user **tabs, types, or
+opens a dialog** — focus visibility, focus order, focus traps, what changes on focus/input,
+whether a mouse interaction has a keyboard equivalent. ultra11y therefore marks every such
+criterion **`manual` / residual risk** (never silently "conforming") and hands it to **the AI
+agent**, which adjudicates it via `verify --manual` (gated). This is the interaction-logic half
+of the division of labour, and it is where reading the *actual source* matters most.
+
+> **Read the whole component, not just the report.** The audit parses every element in scope
+> (`audit --graph` resolves imports across files), but a focus/logic verdict requires reading
+> the real source of each interactive component — the JSX, the event handlers, the effects,
+> the state — and reasoning about what a keyboard/screen-reader user experiences.
+
+## The criteria you own (surfaced as residual risks)
+
+| SC | What to reason about, reading the source |
+|---|---|
+| **2.1.1 Keyboard** | Every action reachable by mouse is reachable by keyboard. Mouse-only handlers (`onMouseEnter`/`onMouseLeave`/`onClick` on a non-interactive element) need a focus/key equivalent (`onFocus`/`onKeyDown`) or a native interactive element. |
+| **2.1.2 No keyboard trap** | Focus can leave every widget (modals, menus, date pickers, embeds). Trace the trap logic and the Escape/return path. |
+| **2.4.3 Focus order** | Tab order follows meaning. Watch DOM order vs visual order, portals/modals, and `tabIndex` (positive is already flagged; reason about roving `tabIndex` in menus/tabs/grids). |
+| **2.4.7 Focus visible** | A visible focus indicator on every focusable element — check CSS (`:focus`/`:focus-visible`, never a bare `outline: none`) at render. |
+| **2.4.11 Focus not obscured** | The focused element isn't hidden behind sticky headers/footers/overlays. |
+| **3.2.1 On focus / 3.2.2 On input** | Focusing or changing a control doesn't trigger an unexpected context change (auto-submit, navigation, surprise modal). Trace `onFocus`/`onChange` handlers. |
+| **2.5.3 Label in name** | The visible label text is contained in the accessible name (so voice control works). |
+
+## Component patterns to trace (where focus logic lives)
+
+- **Dialog / modal**: focus moves into it on open, is trapped while open, returns to the
+  trigger on close, Escape closes it, `aria-modal`/`role="dialog"` + a label.
+- **Menu / dropdown / combobox / listbox**: roving `tabIndex` (one tab stop), arrow-key
+  navigation, Escape, `aria-expanded`/`aria-activedescendant`, focus returned to the trigger.
+- **Tabs / accordion**: arrow keys move between tabs, focus follows selection appropriately.
+- **Toast / live region**: announced without stealing focus.
+- **Custom controls built on `<div>`/`<span>`**: prefer a native element; if not, they need
+  `role`, `tabindex="0"`, key handlers (Enter/Space), and state in ARIA — the engine flags
+  the clickable non-interactive element (2.1.1), but YOU verify the full keyboard contract.
+
+## Workflow
+
+1. **Audit the full scope** with `audit --graph` so every component/import is captured.
+2. **Build the worklists**. `verify --manual --in audit.json` lists each residual (manual)
+   focus/logic criterion, pre-loaded with harvested evidence (ARIA state, `tabindex`, control
+   labels), for the AI agent to adjudicate; `verify --report … --semantic` lists the engine's
+   detected candidates (e.g. a clickable non-interactive element flagged under 2.1.1) to confirm
+   or refute — both grounded in the W3C Understanding reference (see `references/verify.md` /
+   `references/judgment.md`).
+3. **For each focus/logic item, open the real source** of the relevant components and reason
+   about the keyboard/focus/interaction behaviour above. Adjudicate a residual criterion in
+   `ADJUDICATE.todo.json`: `C` (justified) / `NC` (with a groundable `file:line` finding: what
+   the keyboard user experiences) / `NA` (justified) / `manual` (with a `reason`). Confirm or
+   refute an engine candidate in `VERIFY.todo.json`: `supported` / `partial` / `refuted` /
+   `unsupported`, with a concrete cited reason. What needs a rendered DOM (focus *visible*, *not
+   obscured*) is marked `needs-rendered-dom` and goes through the `scan` dynamic tier
+   (`references/dynamic.md`). The local runtime (`scan --runtime local`) now **probes focus
+   visibility (2.4.7)** directly — tabbing through focusables and flagging any whose computed
+   style does not change on focus — alongside 200% zoom (1.4.4), text spacing (1.4.12) and
+   content-on-hover (1.4.13). A probe finding is a real NC; a clean probe still leaves the SC
+   `manual` — never marked conforming on a guess.
+4. **`verify --apply`** to gate FAIL-CLOSED: an unadjudicated, refuted or unsupported focus/logic
+   claim — or an agent verdict missing its justification/finding/reason — fails.
+
+The rule that never bends: a focus/interaction criterion the AI agent could not decide by reading
+the source (or rendering) is an **explicit residual risk** with a recorded reason, not a silent pass.

package/skills/ultra11y/references/forbidden-patterns.md

@@ -0,0 +1,61 @@
+# Forbidden anti-patterns (accessible HTML/CSS)
+
+15 common traps. Format: ❌ bad → why → ✅ native fix → WCAG success criterion (engine
+rule when statically detected).
+
+### 1. Clickable `<div>`/`<span>`
+❌ `<div onClick={…}>` → not focusable, not keyboard-operable, no role.
+✅ native `<button type="button">`. WCAG 2.1.1 / 4.1.2 (`clickable-noninteractive`).
+
+### 2. `<html>` without `lang`
+❌ default language undeclared → wrong screen-reader pronunciation.
+✅ `<html lang="en">`. WCAG 3.1.1 (`html-lang-missing`).
+
+### 3. Page without `<title>` (or empty)
+❌ missing tab/history title. ✅ a relevant `<title>`. WCAG 2.4.2 (`title-missing-empty`).
+
+### 4. Empty link or button
+❌ `<a href="/"></a>`, `<button></button>` → no accessible name.
+✅ visible text, or `aria-label`. WCAG 2.4.4 / 4.1.2 (`link-empty-name`, `button-empty-name`).
+
+### 5. Unnamed icon-only control
+❌ `<button><svg/></button>` with no name. ✅ `aria-label` or visually-hidden text.
+WCAG 2.4.4 / 4.1.2 (`icon-only-control-unnamed`).
+
+### 6. `<label>` not associated with the field
+❌ a visual label with no `for`/wrapping. ✅ `<label for="id">` or a wrapping label.
+WCAG 4.1.2 (`control-label-missing`).
+
+### 7. `placeholder` used as a label
+❌ placeholder alone → disappears on input, not a label. ✅ a real `<label>`.
+WCAG 4.1.2 (`placeholder-as-label`).
+
+### 8. `outline: none` / `outline: 0` on a focusable element
+❌ removes the keyboard focus indicator. ✅ keep/style a visible focus.
+WCAG 2.4.7 (needs-rendering — verify manually).
+
+### 9. Positive `tabindex`
+❌ `tabindex="1"` breaks the logical DOM order. ✅ `tabindex="0"` or nothing.
+WCAG 2.4.3 (`positive-tabindex`).
+
+### 10. Informative text baked into an image
+❌ text-as-image with no alternative. ✅ real text styled with CSS. WCAG 1.4.5 (judgment).
+
+### 11. Meaning carried by CSS alone (`::before`/`::after`)
+❌ information injected by styles only. ✅ text in the HTML. WCAG 1.3.1 (judgment/rendering).
+
+### 12. Skip link hidden with `display:none`
+❌ missing target or non-focusable skip link. ✅ a real target + visible on focus.
+WCAG 2.4.1 (`skip-link-target-missing` for the target).
+
+### 13. Navigation not structured as a list
+❌ a run of links with no `<ul>`. ✅ `<nav><ul><li>…`. WCAG 1.3.1 (judgment).
+
+### 14. Data table without headers
+❌ `<table>` without `<th>`/`scope`/`<caption>`. ✅ headers + `scope` + caption.
+WCAG 1.3.1 (`data-table-no-headers`, `table-caption-missing`).
+
+### 15. Redundant or broken ARIA
+❌ `<button role="button">`, `aria-labelledby="nonexistent-id"`, an invented role.
+✅ native semantics; valid ARIA references. WCAG 4.1.2 (`redundant-aria`,
+`aria-ref-missing-id`, `invalid-aria-role`).

package/skills/ultra11y/references/forms-and-errors.md

@@ -0,0 +1,147 @@
+# Forms, errors and authentication
+
+Forms are where accessibility failures cost the most: a broken image is an annoyance, an
+unusable form is a transaction the user cannot complete. This page covers 1.3.5, 3.2.2,
+3.3.1–3.3.4 and WCAG 2.2's 3.3.7/3.3.8.
+
+## Labels and instructions (3.3.2, 4.1.2)
+
+```html
+<!-- ✓ the association is programmatic, and clicking the text focuses the field -->
+<label for="email">Email address</label>
+<input id="email" type="email" name="email" autocomplete="email"
+       aria-describedby="email-hint" required>
+<p id="email-hint">We use it only to send your receipt.</p>
+```
+
+- A `placeholder` is **not** a label: it disappears on input, is often too low-contrast, and
+  is announced inconsistently. Keep it for an example (`e.g. name@example.com`), never for
+  the label. Engine rule: `placeholder-as-label`.
+- State the format **before** the error, not only in it: `aria-describedby` on the field.
+- `required` on the control is what assistive tech announces. A red asterisk alone is a
+  1.4.1 failure too — pair it with text ("Required fields are marked *", or a real word).
+- Group related controls: radios and checkboxes in `<fieldset><legend>`, a date split across
+  three inputs likewise. Engine rules: `fieldset-legend-missing`,
+  `radio-checkbox-group-ungrouped`, `date-fields-ungrouped`.
+
+## 1.3.5 Identify Input Purpose — the token list
+
+A field collecting information **about the user** must declare its purpose. The token has to
+come from the HTML autofill vocabulary; an invented one reads as compliant and fills nothing
+(engine rule: `autocomplete-token-invalid`).
+
+| Group | Tokens |
+|---|---|
+| Identity | `name` `honorific-prefix` `given-name` `additional-name` `family-name` `honorific-suffix` `nickname` `organization-title` `organization` `sex` `bday` `bday-day` `bday-month` `bday-year` `photo` `language` |
+| Credentials | `username` `new-password` `current-password` `one-time-code` |
+| Address | `street-address` `address-line1` `address-line2` `address-line3` `address-level1`…`address-level4` `country` `country-name` `postal-code` |
+| Payment | `cc-name` `cc-given-name` `cc-additional-name` `cc-family-name` `cc-number` `cc-exp` `cc-exp-month` `cc-exp-year` `cc-csc` `cc-type` `transaction-currency` `transaction-amount` |
+| Contact | `tel` `tel-country-code` `tel-national` `tel-area-code` `tel-local` `tel-local-prefix` `tel-local-suffix` `tel-extension` `email` `impp` `url` |
+
+Qualifiers may precede the token: `section-*` (to separate two addresses on one form), then
+`shipping`/`billing`, then `home`/`work`/`mobile`/`fax`/`pager` (contact fields only).
+
+```html
+<input autocomplete="shipping postal-code">      <!-- ✓ -->
+<input autocomplete="section-work work email">   <!-- ✓ -->
+<input autocomplete="postcode">                  <!-- ✗ not a token -->
+```
+
+**Applicability:** the criterion covers the USER's own data. An order number, a search term
+or a quantity is not in scope — that is a legitimate `NA` on the field.
+
+## 3.3.1 / 3.3.3 — identifying and fixing errors
+
+```html
+<label for="dob">Date of birth</label>
+<input id="dob" name="dob" aria-invalid="true"
+       aria-describedby="dob-err" aria-errormessage="dob-err">
+<p id="dob-err">Enter the date as DD/MM/YYYY — for example 04/03/1990.</p>
+```
+
+- The error must be **in text**, not only a red border (1.4.1 + 3.3.1).
+- It must be **associated** with its field. Engine rules: `error-not-associated`,
+  `aria-invalid-no-description`.
+- 3.3.3 asks for the **correction** when it is knowable: "Enter DD/MM/YYYY" beats "Invalid
+  date". Withhold only where suggesting it would compromise security.
+
+**Error summary pattern** — for a form with several errors, put a summary at the top, move
+focus to it on submit, and link each entry to its field:
+
+```html
+<div role="alert" tabindex="-1" id="errors">
+  <h2>There are 2 problems with this form</h2>
+  <ul>
+    <li><a href="#dob">Date of birth: enter the date as DD/MM/YYYY</a></li>
+    <li><a href="#email">Email address: enter an address with an @</a></li>
+  </ul>
+</div>
+```
+
+Focus the summary (not the first field): the user hears how many problems there are before
+being dropped into one of them.
+
+## 3.2.2 On Input / 3.2.1 On Focus
+
+Changing a value, or merely receiving focus, must not by itself change the context.
+
+```html
+<!-- ✗ selecting an option navigates; keyboard users trigger it while browsing the list -->
+<select onchange="location = this.value">…</select>
+
+<!-- ✓ the change is explicit, and announced beforehand -->
+<label for="lang">Language</label>
+<select id="lang">…</select>
+<button type="submit">Change language</button>
+```
+
+Engine rule: `on-input-context-change`. Auto-advancing between one-character code fields is
+the same failure in a friendlier costume — allow it, but keep the form usable without it.
+
+## 3.3.4 Error Prevention (legal, financial, data)
+
+For submissions that are legally binding, financial, or that modify/delete user data, one of
+these must hold: **reversible**, **checked** (errors detected and a chance to correct), or
+**confirmed** (a review step before the final commit). A one-click irreversible delete fails.
+
+## 3.3.7 Redundant Entry (WCAG 2.2)
+
+Information already entered in the same process must not be asked for again — auto-populate
+it, or offer it for selection. Exceptions: re-entry is essential (confirming a password),
+the earlier information is no longer valid, or it would compromise security.
+
+```html
+<!-- ✓ the shipping address is offered rather than retyped -->
+<label><input type="checkbox" name="same" checked> Billing address is the same as shipping</label>
+```
+
+## 3.3.8 Accessible Authentication (WCAG 2.2)
+
+No step of an authentication process may require a **cognitive function test** — memorising,
+transcribing, or solving a puzzle — unless an alternative, a mechanism to help, object
+recognition, or user-provided content is available.
+
+```html
+<!-- ✗ blocking paste turns login into a memory test and breaks password managers -->
+<input type="password" onpaste="return false">
+<!-- ✗ autofill switched off on a credential field -->
+<input type="password" autocomplete="off">
+
+<!-- ✓ declare the real purpose; let the manager fill and the user paste -->
+<input type="password" autocomplete="current-password">
+<input type="text" inputmode="numeric" autocomplete="one-time-code">
+```
+
+Engine rule: `credential-entry-blocked`. Also in scope: a transcription CAPTCHA with no
+alternative, and a code the user must retype from another screen with no way to paste.
+
+## What the engine settles, and what stays yours
+
+| Decided by the engine | Yours to adjudicate |
+|---|---|
+| Missing/duplicate labels, placeholder-as-label, ungrouped radios and date parts | Whether a label is **descriptive** (2.4.6) and an instruction sufficient (3.3.2) |
+| `autocomplete` token outside the vocabulary | Whether the field collects **user** data at all (1.3.5 applicability) |
+| Error text not associated, `aria-invalid` with no description | Whether the message says **how to fix it** (3.3.3) |
+| Paste/autofill blocked on a credential field | Whether the whole auth flow imposes a cognitive test (3.3.8) |
+| `onchange` that submits or navigates | Whether a context change was **announced beforehand** (3.2.2) |
+| — | Redundant entry across a multi-step flow (3.3.7) |

package/skills/ultra11y/references/guidance.md

@@ -0,0 +1,55 @@
+# Implementation guidance — concrete before/after rules attached to criteria
+
+A standards pack says *what* a criterion requires; **guidance** says *how to implement
+it*. It is the layer of concrete, how-to-implement rules — the RGAA SocialGouv/etalab
+good/bad code patterns — keyed to a pack criterion and the WCAG success criteria it maps
+onto. It enriches output without ever changing the verdict.
+
+## Where it shows up
+
+Guidance is looked up at **render time** by criterion / WCAG SC, so the canonical
+`audit` JSON stays untouched (no schema change, no new finding). It surfaces in:
+
+- **`prd`** — each backlog item gains a before/after example and an effort estimate; the
+  `--format doc` PRD weaves it into the user stories and acceptance criteria.
+- **`criteria`** lookups for a pack criterion.
+
+Because attachment is presentation-only, guidance never marks anything conforming and
+never invents a non-conformity — it is illustration, not detection.
+
+## Dataset shape
+
+A guidance dataset is JSON: `{ pack, source, license, attribution, entries[] }`, where
+each entry is `{ id, criterionId, wcag[], title, summary, impact?, examples[], reference }`
+and an example is `{ lang: "html"|"jsx"|"css", bad?, good?, note? }`. The built-in RGAA
+guidance ships at `src/data/guidance/rgaa.json` (its entry ids mirror the SocialGouv rule
+files). Load external guidance with `--pack <dir>` (a `guidance.json` beside `pack.json`)
+or a `.ultra11yrc.json` `guidance` list. `pack check --guidance` validates that every
+entry resolves to a real criterion, maps to recognized WCAG SCs, and that every example
+parses.
+
+## Honesty rule — guidance is NOT a free detector
+
+A pattern earns a **WCAG-core detector** only when it is both statically decidable **and**
+maps to a success criterion present in the WCAG 2.2 **AA** core. Everything else lives
+here as guidance (and, where the country standard covers it, in the pack), never as a
+silent "conforming".
+
+The headline example: **opening a new window** (`target="_blank"` without warning). Its
+only clean WCAG home is **3.2.5 Change on Request — which is AAA, absent from the AA
+core** (the dataset jumps 3.2.4 → 3.2.6). So ultra11y does **not** ship a WCAG-core
+detector for it — no static rule flags `target="_blank"` under any standard. It ships as
+RGAA guidance (criterion 13.2 → WCAG 3.2.1): look it up with `criteria --standard rgaa 13.2`,
+and it attaches to the relevant `prd`/`report` entry — it is never raised as an audit
+non-conformity, and never force-mapped onto a wrong AA criterion. (`--standard` is a
+`report`/`prd`/`criteria` flag, not an `audit` one.) Judgment- and
+rendering-dependent rules (alt relevance, computed contrast, reading order) stay guidance
++ residual risk for the same reason.
+
+## Attribution
+
+RGAA 4.1.2 © DINUM — Licence Ouverte / Etalab 2.0. The before/after implementation
+patterns are adapted from SocialGouv/skills (`rgaa-html-css`) and the official RGAA
+méthode; the dataset stores short derived summaries + minimal examples, not verbatim prose
+(see `NOTICE`). When ingesting another source, record its license and attribution in the
+dataset header and `NOTICE` before redistributing any text.