ultra11y 2.22.0

package/skills/ultra11y/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: ultra11y
+description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibility and produce a dated auditor-conformance report, OR to AUTHOR/REVIEW accessible markup (native-HTML-first, ARIA last). An install-free engine (`node scripts/ultra11y.mjs`, no keys) runs 72 static checks tied to WCAG criteria — alt/lang/title, unlabeled fields, empty links/buttons, tables, headings, ARIA vocabulary, label-in-name, autocomplete — measured against the official W3C ACT corpus. The engine decides 3 of the 55 criteria; the AI agent adjudicates the 38 judgment ones from harvested evidence + a per-criterion decision protocol (`verify --manual`, gated, fannable via `orchestrate`), and the 14 rendering ones go to `scan` — never silently conforming. Library/SFC code is audited as RENDERED captures (`render --setup`); country standards are pluggable packs (`--standard rgaa`, `scan --sample`). check/verify reject invented non-conformities. Triggers: 'audit WCAG/a11y', 'make accessible', 'fix a11y', 'audit RGAA'."
+license: MIT
+metadata:
+  version: 2.22.0
+---
+
+# ultra11y — audit WCAG 2.2 AA and write accessible markup
+
+On accessibility, an automated tool only sees part of the problem. `ultra11y` owns
+that with a **division of labour**: the deterministic, install-free engine
+(`node scripts/ultra11y.mjs <command>` — no `npm install`, no key; the JSX/TSX parser
+is embedded in the bundle) does the *mechanical* work — detect the machine-checkable
+non-conformities and tie each to the right **WCAG success criterion** — and **the AI agent**
+(Claude running this skill) *adjudicates the judgment criteria itself* — alt relevance, link
+purpose in context, reading order — statically, from the evidence the engine harvests
+(`verify --manual`), each verdict gated by `verify`/`check`. Only the truly **rendered-DOM**
+criteria (computed contrast, visible focus, zoom/reflow, content-on-hover) fall to the `scan`
+tier (axe-core in a real browser); a human is at most optional oversight. Gates stop any
+hallucinated non-conformity from surviving, and nothing is ever silently "conforming".
+
+**WCAG 2.2 Level AA is the worldwide core.** Country standards — France's **RGAA**, the
+US **Section 508**, the EU **EN 301 549** — are pluggable *standards packs* that map their
+criteria onto WCAG. Add `--standard rgaa` to re-key reports/criteria; **plug an external
+pack at runtime** with `--pack ./pack.json` (or a `.ultra11yrc.json`), no rebuild; or
+contribute your country (see `references/standards.md`). Packs (and their concrete
+**implementation guidance** — the RGAA SocialGouv/etalab good/bad patterns) can be
+**AI-ingested** and gated by `pack check` so a fabricated mapping never passes — see
+`references/packs.md` and `references/guidance.md`.
+
+**Most of the work is yours.** Of the 55 WCAG 2.2 AA success criteria, the engine can decide
+**3** outright; **14** need a rendered page (`scan`) and **38** are judgment calls the agent
+adjudicates. So the engine's clean run is a starting point, never a verdict — and
+`references/adjudication.md` is the page you actually work from.
+
+> **Core rules:**
+> 1. **Never invent a non-conformity**: every `NC` cites a real, resolvable element (`check` verifies it).
+> 2. **Native HTML first, ARIA last**; never duplicate implicit semantics.
+> 3. **Residual is explicit, never silently conforming**: the AI agent *adjudicates* every
+>    *judgment* criterion itself (`verify --manual`, gated), and the *rendering* criteria go to
+>    `scan`; any criterion still unproven stays "to assess manually" — no status without a
+>    recorded, justified verdict.
+> 4. **The FINAL rendered semantic HTML must be correct.** The engine sees only source; a
+>    component library (DSFR/MUI…) or `.vue`/`.svelte`/`.astro` SFC hides the real markup, so
+>    a green source audit is not proof. Verify the produced semantic HTML — install the
+>    zero-touch **capture** harvester (`render --setup`) so every component your tests render
+>    is serialized to `.ultra11y/captures` and audited, with `audit --require-captures` gating
+>    the blind spots. See `references/automation.md` / `rendered.md`.
+> 5. **Language**: ALWAYS pass `--lang` matching the language of your conversation with
+>    the user; ask the user when ambiguous. Without the flag the CLI auto-detects (repo
+>    `<html lang>` → the active standard's default locale → English) — a scripted/CI
+>    fallback, not a substitute for passing `--lang` yourself.
+> 6. **Technical tokens stay in English, even in French prose.** In any French deliverable
+>    you write (report commentary, PRD, GitHub issues, judgment verdicts), attribute/
+>    element/role names and their values are code, not prose — never translate them:
+>    `aria-live` stays `aria-live` (never « région live »), same for `tabindex`, `alt`,
+>    `role="alert"`, landmark role names. The engine's own fr catalog follows this; match
+>    it. Normative standard vocabulary (RGAA wording such as « lien d'évitement ») keeps
+>    its official French.
+
+## The reference library
+
+Domain knowledge first, then the tooling. Read the one that matches the question in front of you.
+
+| Accessibility knowledge | |
+|---|---|
+| `references/adjudication.md` | How to decide each of the 52 criteria the engine hands you — the decision rule, when NA is legitimate, the questions |
+| `references/naming.md` | Accessible-name computation, 2.5.3 label-in-name, visually-hidden CSS, naming images/SVG/figures |
+| `references/widgets.md` | ARIA APG composite patterns, keyboard contracts, focus management, SPA route changes, live regions |
+| `references/forms-and-errors.md` | Labels and instructions, the `autocomplete` token list, error identification/suggestion/prevention, redundant entry, accessible authentication |
+| `references/structure.md` | Headings, landmarks, lists and `dl`, simple and complex tables, meaningful sequence |
+| `references/media-and-motion.md` | Captions/audio description/transcripts, pointer gestures, target size, orientation, reflow, reduced motion |
+| `references/forbidden-patterns.md` | 15 anti-patterns: bad → why → native fix → criterion |
+| `references/focus-and-logic.md` | The focus/keyboard criteria you own, and how to reason about them |
+| `references/criteria.md` | The 55 criteria: level, automatability class, engine rules, pack mapping (generated) |
+| `references/act.md` | What the engine is measured to catch — and what it demonstrably does not (generated) |
+
+| Running the tool | |
+|---|---|
+| `references/audit.md` | The audit loop end to end, and the normative page sample |
+| `references/judgment.md` | The adjudication + refutation worklists, verdict vocabulary, fail-closed fold |
+| `references/verify.md` | The `check`/`verify` gates |
+| `references/false-positives.md` | Where a finding may still be wrong, and how to refute it |
+| `references/rendered.md` · `references/automation.md` | Auditing produced HTML, captures, hooks and CI |
+| `references/dynamic.md` | The `scan` tier: runtimes, probes, authenticated pages |
+| `references/scale.md` | Focusing an audit on a large repository |
+| `references/fix.md` · `references/correction.md` | Applying fixes, by priority, without regressions |
+| `references/prd.md` | The auditor block as a backlog, and GitHub issues |
+| `references/standards.md` · `references/packs.md` · `references/guidance.md` | Country standards, authoring a pack, implementation guidance |
+| `references/methodology.md` | Statuses, pass rate, severities, report format |
+| `references/cross-file.md` | `--graph`: imports and cross-file rules |
+| `references/orchestration.md` | Fanning the judgment phases out across subagents |
+
+## Choose by situation
+
+- **"Audit / compliance report"** → `node scripts/ultra11y.mjs audit … --json`, then
+  `report` (synthesis table + one **auditor conformance block** per NC criterion — same
+  block `prd`/`--gh-issues` use), then `check`; read **`references/audit.md`**.
+- **"Code rendered by a library (DSFR, MUI…) or a `.vue`/`.svelte`/`.astro` SFC / avoid
+  false negatives"** → audit the **produced HTML**, not the source template. Easiest:
+  install the zero-touch **capture** harvester (`render --setup`) so your tests serialize
+  every rendered component to `.ultra11y/captures` (auto-ingested, findings attributed to the
+  source component; `render --coverage` and `audit --require-captures` track blind spots). Or
+  `render` (build→audit recipe or SSR snapshot `--scaffold`) then `audit` on the output, and
+  `scan` for computed rendering. SFC-source findings are flagged `preliminary` (a
+  `scope.sourceTemplate` caveat); read **`references/rendered.md`**.
+- **"A finding looks wrong / false positive on a component"** → the engine auto-suppresses
+  most component false positives (slot/prop-injected names, component children, dynamic
+  bindings, conditional headings) and marks SFC/library-source findings `preliminary`;
+  confirm or refute the rest with `verify --apply`; read **`references/false-positives.md`**.
+- **"Large repo / audit smartly"** → focus: `--changed` (git diff), template
+  prioritization, dedup, `--max-files`; read **`references/scale.md`**.
+- **"Cross-file analysis (tree + dependencies), JSX/TSX as a real AST"** →
+  `audit --graph` resolves imports and applies cross-file rules (an icon-only component
+  used without a name, an anchor target in another file…), no browser; read
+  **`references/cross-file.md`**.
+- **"Generate the fix markdown / PRDs (→ GitHub issues)"** → `prd` (the SAME auditor
+  conformance block `report`'s NC section renders — theme/criterion/test/WCAG+level/
+  finding/expected/verification in the active standard's vocabulary — as a backlog);
+  `--split criterion`, `--format doc` for a product-requirements doc, `--format remediation`
+  for the legacy dev backlog, `--gh-issues` for one issue per criterion (that block as the
+  body) or `--gh-single` for a single consolidated issue via the `gh` CLI); read
+  **`references/prd.md`**.
+- **"Plug or author a standards pack (RGAA & beyond), AI-ingest external rules"** →
+  `--pack`/`.ultra11yrc.json` to load at runtime, `pack check` to gate it (the
+  anti-hallucination guardrail), `pack scaffold` to start one; concrete before/after
+  implementation guidance attaches to findings/PRD; read **`references/packs.md`** and
+  **`references/guidance.md`**.
+- **"Adjudicate the judgment criteria (judgment phase)"** → `verify --manual --in audit.json`
+  emits an ADJUDICATION worklist (`ADJUDICATE.todo.json` + `ADJUDICATE.md`), one item per
+  residual criterion, pre-loaded with the engine's harvested evidence (every alt, link text +
+  context, literal colour pairs, control labels, heading outline, ARIA state, tabindex,
+  lang-of-parts); the AI agent fills each `verdict` — `C`/`NA` (with a `justification`), `NC`
+  (with a groundable finding), or `manual` (with a `reason`) — then `verify --apply … --in
+  audit.json` folds them back FAIL-CLOSED; read **`references/judgment.md`**.
+- **"Many items to adjudicate/verify (fan the judgment out to subagents)"** →
+  `orchestrate --run <dir>` emits, from the run's CURRENT worklists, one launchable
+  multi-agent workflow per ready phase + the `agents/<role>.md` dispatch contracts +
+  a sequential `RUNBOOK.md` — the default execution path on a subagent-capable harness;
+  see **Orchestration — route by harness** below.
+- **"Focus, keyboard & interaction logic (the interaction-logic part)"** → the engine marks
+  focus order/visible/trap and on-focus/on-input criteria as residual risks; the AI agent reads
+  the full component source and adjudicates the keyboard/focus behaviour (visible-focus and the
+  other rendered criteria go to `scan`); read **`references/focus-and-logic.md`**.
+- **"Put the fixes in place"** → `fix` (dry-run by default, `--write` applies the safe
+  codemods, proposes the rest without inventing anything); read **`references/fix.md`**.
+- **"Fix by priority, no regressions (correction phase)"** → `fix` (`--write`,
+  `--iterate`) + the `prd` backlog, blocking→major→minor; read **`references/correction.md`**.
+- **"Automatic repo gate (hook / CI)"** → `init --hook` writes a git pre-commit gate over
+  the **strict staged snapshot** (audits the exact index blobs, auto-applies safe fixes and
+  re-stages them, blocks only on judgment issues); `init --baseline`/`--ci` is the opt-in
+  "block only NEW non-conformities" variant. For library/SFC code, commit rendered
+  **captures** (`render --setup`) and stage them so the real semantic HTML is what's
+  checked (`audit --require-captures`); read **`references/automation.md`**.
+- **"Make this code accessible / review it"** → audit the snippet
+  (`audit - < component.html`) native-first; read **`references/authoring.md`** and
+  **`references/forbidden-patterns.md`**.
+- **"What does criterion X mean"** → `criteria` (e.g. `criteria 1.4.3`, or
+  `criteria --standard rgaa 8.3`); see **`references/criteria.md`**.
+- **"How trustworthy is a given check / what does the engine NOT catch"** → the engine is
+  scored against the **W3C ACT-Rules test corpus** (~1 100 third-party examples): which
+  checks are consistent, where recall is partial, which deviations are deliberate, and
+  which statically-decidable rules are still missing — read **`references/act.md`**. Use it
+  to calibrate how much of a criterion the engine really settles before you adjudicate.
+- **"Country standard (RGAA, Section 508, EN 301 549)"** → `--standard <pack>` on
+  `report`/`prd`/`criteria`/`check`/`verify`; see **`references/standards.md`** and
+  **`references/methodology.md`**. **For a country-standard audit, PROPOSE the scan by
+  default**: such an audit is normatively defined over a declared page **sample**, and an
+  un-scanned `--standard rgaa` report is marked **partial** — say so rather than implying
+  full coverage. The sample workflow (`sample check`, `scan --sample`, `--merge`) is in
+  **`references/audit.md`**.
+- **"High-assurance audit"** → `verify --report … --semantic`; see **`references/verify.md`**.
+- **"Check contrast / rendering (dynamic tier)"** → `scan <url> --merge …` runs axe-core in a
+  headless browser and, on the local runtime, probes focus visibility, 200% zoom, text
+  spacing and content-on-hover, with bounded stateful interactions and authenticated pages;
+  read **`references/dynamic.md`**.
+
+## Orchestration — route by harness
+
+The judgment phases fan out: `ADJUDICATE.todo.json` (one item per residual criterion) and
+`VERIFY.todo.json` (one entry per NC claim) are independent per-item worklists, and
+`orchestrate --run <dir>` emits a launchable workflow, per-role dispatch contracts and a
+sequential RUNBOOK from whichever worklists currently exist. Fan-out is an optimization,
+never a requirement: the gates are harness-independent, every phase has a sequential
+fallback with identical artifacts, and the fail-closed `verify --apply` fold always stays
+with you. Read **`references/orchestration.md`** for the routing table and the rules.
+
+## Command cheat sheet
+
+The full surface is in `--help`; these are the lines you reach for.
+
+```
+node scripts/ultra11y.mjs audit "src/**/*.tsx" --graph --out audits --json   # the default audit (AST + cross-file, persisted)
+node scripts/ultra11y.mjs audit - < component.html                           # a snippet via stdin
+node scripts/ultra11y.mjs audit --changed --json                             # only the git diff (large repo)
+node scripts/ultra11y.mjs audit --staged --fail-on blocking                  # gate EXACTLY the staged snapshot (pre-commit)
+node scripts/ultra11y.mjs audit "dist/**/*.html"                             # the RENDERED HTML (reliable for DSFR/MUI…)
+node scripts/ultra11y.mjs render --setup                                     # install the capture harvester (tests → .ultra11y/captures)
+node scripts/ultra11y.mjs audit --require-captures                           # gate the components with no rendered capture
+node scripts/ultra11y.mjs scan http://localhost:3000 --runtime local --cwd . --merge audits/audit-latest.json
+node scripts/ultra11y.mjs verify --report audits/wcag-YYYY-MM-DD.md --in audits/audit-latest.json --manual --out audits
+node scripts/ultra11y.mjs verify --apply audits/ADJUDICATE.todo.json --in audits/audit-latest.json --out audits
+node scripts/ultra11y.mjs orchestrate --run audits                           # fan the judgment phases out (--eco for the sequential path)
+node scripts/ultra11y.mjs report --in audits/audit-latest.json --out audits  # → audits/wcag-YYYY-MM-DD.md
+node scripts/ultra11y.mjs prd    --in audits/audit-latest.json --gh-issues   # the same auditor block as a backlog
+node scripts/ultra11y.mjs check  --report audits/wcag-YYYY-MM-DD.md          # integrity gate
+node scripts/ultra11y.mjs criteria 1.4.3                                     # one success criterion (--list for all)
+node scripts/ultra11y.mjs fix "src/**/*.html" --write --iterate               # apply the safe codemods to a fixpoint
+node scripts/ultra11y.mjs init --hook                                        # pre-commit gate (--baseline for the regression variant)
+node scripts/ultra11y.mjs pack check ./packs/section508.json                  # gate an (AI-)authored standards pack
+```
+Add `--standard rgaa` to `report`/`prd`/`criteria`/`check`/`verify` for a country standard,
+`--pack ./pack.json` to load one at runtime, and `--json` anywhere for machine output.
+`--lang` follows the conversation (pass it explicitly — Core rule 5).
+
+## The loop: audit → render → judge → fix → re-audit
+
+To converge on conformance (not a single pass), chain the steps, letting the agent
+drive the judgment and content stages:
+
+1. **Audit** the source (`audit … --graph`) for a first map; on library-rendered code,
+   **audit the render** (`render` → build/SSR → `audit`) for reliable verdicts (otherwise
+   the scope-risk note reminds you).
+2. **Adjudicate & refute** with `verify`, two worklists. (a) `verify --manual --in audit.json`
+   emits `ADJUDICATE.todo.json` — one item per residual *judgment* criterion, pre-loaded with the
+   engine's harvested evidence — which the AI agent rules on (`C`/`NC`/`NA`, or `manual` with a
+   `reason` when it truly `needs-rendered-dom`), each verdict carrying a `justification` or a
+   groundable finding; `verify --apply … --in audit.json` folds them back FAIL-CLOSED (agent NCs
+   become real `agent:<sc>` findings that re-render in §2). (b) `verify --report … [--semantic]`
+   builds `VERIFY.todo.json` to **refute any `preliminary`/SFC/library-source finding** the
+   rendered DOM disproves (verdicts `supported`/`partial`/`refuted`/`unsupported`);
+   `verify --apply` drops the refuted/unsupported ones (the anti-hallucination gate). This
+   includes **focus & interaction logic** (read the full component source: keyboard
+   operability, focus order/visibility, traps, on-focus/on-input changes; see
+   `references/focus-and-logic.md`) and the per-rule traps in `references/false-positives.md`.
+   Both worklists fan out (`orchestrate --run <dir> --phase adjudicate|verify-report` —
+   see **Orchestration — route by harness**); the `--apply` fold always stays with you.
+3. **Fix** by priority: `fix --write --iterate` for the mechanical part (anti-regression
+   gate), then hand-apply the judgment/content fixes (alt, labels, structure) guided by
+   `references/correction.md`.
+4. **Re-audit** (on the render where relevant) and repeat.
+5. **Deliver the auditor block.** `report` (compliance doc: synthesis + one auditor
+   conformance block — theme/criterion/test/WCAG+level/finding/expected/verification —
+   per NC criterion) and `prd` (the same blocks as an actionable backlog, `--gh-issues`
+   filing one GitHub issue per criterion with that identical block) are two views of the
+   ONE building block, in the language of this conversation (pass `--lang` explicitly —
+   Core rule 5).
+
+**Stop** when `check` and `verify --apply` are green again and only explicitly-named
+residual risks remain. (To automate the outer cadence, the harness `/loop` command can
+re-run this cycle.)
+
+## Combining engine, judgment and residual risk
+
+`audit` classes each criterion `C`/`NC`/`NA` for the static subset and `manual` for the rest,
+each carrying an `automatability` class that says WHY it is manual and how to close it:
+**`static`** (the engine decides), **`needs-rendering`** (`scan`), **`judgment`** (you, from
+the harvested evidence and the decision protocol). Engine `NC`s are confirmed candidates
+with a cited `file:line`; a `preliminary: true` finding (SFC/library source) is provisional —
+confirm it against the render or refute it. A criterion is never silently marked conforming:
+the report is complete only when every applicable criterion is a justified `C`/`NC`/`NA` and
+every residual risk is named. See **`references/methodology.md`**.
+
+**Advisory recommendations are a distinct class.** A good-practice signal with NO failing
+normative test renders under a dedicated section and can never flip a criterion to `NC` nor
+enter `conformancePct`. An `NC` needs a `normativeRef`; a recommendation does not. Do not
+promote one to the other — see **`references/false-positives.md`**.
+
+## Do not
+
+- Invent a non-conformity the engine did not find and you cannot see (contrast on
+  **inline literal colours** is decided statically; **computed** contrast — external CSS,
+  variables — goes through `scan` (Docker tier) or is verified at render before being declared).
+- Add ARIA that duplicates native semantics.
+- Mark a rendering/judgment criterion "conforming" without a recorded, gated justification
+  (agent adjudication via `verify --manual`, or `scan` evidence).
+- Hand-edit `references/criteria.md` (generated from the WCAG dataset via `criteria --generate`).
+
+## Scope
+
+Static engine: offline, deterministic, install-free; inputs are HTML + JSX/TSX (real AST,
+cross-file analysis via `--graph`) + stdin. The **rendering** criteria (computed contrast,
+reflow) are covered by the optional `scan` tier (axe-core, Docker **or** `--runtime local`).
+The local runtime additionally **probes** focus visibility (2.4.7), 200% text zoom (1.4.4),
+text spacing (1.4.12) and content-on-hover (1.4.13) — observed in the rendered page, raised
+as NC only when the failure is seen (a clean probe leaves the SC `manual`, never silently
+conforming); reading order and alt relevance are the AI agent's judgment, adjudicated from the
+harvested evidence and gated (`verify --manual`).
+Data: WCAG 2.2 ©
+W3C (W3C Document License); the RGAA pack is RGAA 4.1.2 © DINUM, Licence Ouverte / Etalab
+2.0 (see `NOTICE`).

package/skills/ultra11y/references/act.md

@@ -0,0 +1,163 @@
+<!-- GENERATED from the vendored W3C ACT corpus by `pnpm run build:act` — do not edit by hand. -->
+
+# ACT conformance — how this engine scores against a corpus it did not write
+
+The recall matrix in this repository proves that each rule fires on the defect written FOR it.
+That is circular. The [W3C ACT-Rules Community Group](https://act-rules.github.io) publishes rules
+with `passed` / `failed` / `inapplicable` examples authored independently of this project, so running
+the engine over them measures something a self-authored fixture cannot.
+
+**How to read this.** An ACT example asserts something about ITS OWN rule and nothing else, so each
+case is judged only with the engine rules mapped to that ACT rule — never with the whole engine.
+Only normative findings count (an `advisory` recommendation never flips a criterion, so it cannot
+fail a case either). Rules needing a rendered page or a human call are declared, not scored — saying
+so beats quietly scoring zero.
+
+## Summary
+
+| | |
+|---|---|
+| Corpus | 1134 examples across 91 ACT rules |
+| Source | https://act-rules.github.io/testcases.json |
+| Rules scored | **32** |
+| Failed examples caught | **103 / 149** |
+| Clean examples left alone | **291 / 291** — no unexplained false positive |
+| Consistent | 5 |
+| Divergent (documented, 9 cases) | 3 |
+| Partially consistent | 24 |
+| **Inconsistent** | **0** |
+| Declared gaps (static, not implemented) | 13 |
+
+*Partially consistent* is the ACT Rules Format's own term for a tool that never reports a false
+positive but does not catch everything — it is a coverage statement, not an error. *Divergent* means
+every deviation on that rule is listed below with the argument for it.
+
+## Scored rules
+
+| ACT rule | WCAG | Engine rules | Verdict | Caught |
+|---|---|---|---|---|
+| [Image has non-empty accessible name](https://act-rules.github.io/rules/23a2a8) | 1.1.1 | `img-alt-missing` | 🟨 partially consistent | 4/5 |
+| [HTML page has non-empty title](https://act-rules.github.io/rules/2779a5) | 2.4.2 | `title-missing-empty` | 🟨 partially consistent | 4/5 |
+| [Visible label is part of accessible name](https://act-rules.github.io/rules/2ee8b8) | 2.5.3 | `label-in-name-mismatch` | 🟦 divergent (documented) | 3/3 |
+| [Id attribute value is unique](https://act-rules.github.io/rules/3ea0c8) | 4.1.1 | `duplicate-id` | ✅ consistent | 3/3 |
+| [Audio or video element that plays automatically has a control mechanism](https://act-rules.github.io/rules/4c31df) | — | `autoplay-media` | 🟦 divergent (documented) | 5/5 |
+| [Element with role attribute has required states and properties](https://act-rules.github.io/rules/4e8ab6) | 4.1.2 | `aria-required-attr` | 🟨 partially consistent | 1/2 |
+| [Image button has non-empty accessible name](https://act-rules.github.io/rules/59796f) | 1.1.1, 4.1.2 | `input-image-alt-missing` | 🟨 partially consistent | 2/3 |
+| [ARIA state or property is permitted](https://act-rules.github.io/rules/5c01ea) | — | `aria-prohibited-attr` | 🟨 partially consistent | 0/2 |
+| [ARIA attribute is defined in WAI-ARIA](https://act-rules.github.io/rules/5f99a7) | — | `invalid-aria-attr` | ✅ consistent | 2/2 |
+| [Role attribute has valid value](https://act-rules.github.io/rules/674b10) | 1.3.1 | `invalid-aria-role` | ✅ consistent | 2/2 |
+| [ARIA state or property has valid value](https://act-rules.github.io/rules/6a7281) | — | `invalid-aria-value`, `live-region-conflict` | 🟨 partially consistent | 9/10 |
+| [Element with aria-hidden has no content in sequential focus navigation](https://act-rules.github.io/rules/6cfa84) | 4.1.2 | `aria-hidden-focusable` | 🟨 partially consistent | 5/6 |
+| [Autocomplete attribute has valid value](https://act-rules.github.io/rules/73f2c2) | 1.3.5 | `autocomplete-token-invalid` | ✅ consistent | 5/5 |
+| [SVG element with explicit role has non-empty accessible name](https://act-rules.github.io/rules/7d6734) | 1.1.1 | `img-alt-missing` | 🟨 partially consistent | 2/4 |
+| [Audio or video element avoids automatically playing audio](https://act-rules.github.io/rules/80f0bf) | 1.4.2 | `autoplay-media` | 🟦 divergent (documented) | 2/2 |
+| [Object element rendering non-text content has non-empty accessible name](https://act-rules.github.io/rules/8fc3b6) | 1.1.1 | `object-embed-no-name` | 🟨 partially consistent | 2/4 |
+| [Button has non-empty accessible name](https://act-rules.github.io/rules/97a4e1) | 4.1.2 | `button-empty-name`, `icon-only-control-unnamed` | 🟨 partially consistent | 4/5 |
+| [Headers attribute specified on a cell refers to cells in the same table element](https://act-rules.github.io/rules/a25f45) | 1.3.1 | `headers-attr-dangling` | ✅ consistent | 4/4 |
+| [Meta viewport allows for zoom](https://act-rules.github.io/rules/b4f0c3) | 1.4.4 | `meta-viewport-zoom-block` | 🟨 partially consistent | 3/4 |
+| [HTML page has lang attribute](https://act-rules.github.io/rules/b5c3f8) | 3.1.1 | `html-lang-missing` | 🟨 partially consistent | 3/4 |
+| [ARIA required owned elements](https://act-rules.github.io/rules/bc4a75) | 1.3.1 | `aria-required-children` | 🟨 partially consistent | 3/7 |
+| [Meta element has no refresh delay](https://act-rules.github.io/rules/bc659a) | 2.2.1, 2.2.4, 3.2.5 | `meta-refresh-redirect` | 🟨 partially consistent | 3/4 |
+| [HTML page lang attribute has valid language tag](https://act-rules.github.io/rules/bf051a) | 3.1.1 | `lang-invalid` | 🟨 partially consistent | 1/4 |
+| [Meta element has no refresh delay (no exception)](https://act-rules.github.io/rules/bisz58) | 2.2.4, 3.2.5 | `meta-refresh-redirect` | 🟨 partially consistent | 2/4 |
+| [Link has non-empty accessible name](https://act-rules.github.io/rules/c487ae) | 2.4.4, 2.4.9, 4.1.2 | `link-empty-name`, `icon-only-control-unnamed` | 🟨 partially consistent | 7/11 |
+| [Iframe element has non-empty accessible name](https://act-rules.github.io/rules/cae760) | 4.1.2 | `iframe-title-missing` | 🟨 partially consistent | 3/4 |
+| [Table header cell has assigned cells](https://act-rules.github.io/rules/d0f69e) | 1.3.1 | `th-no-data-cells` | 🟨 partially consistent | 0/3 |
+| [Element with lang attribute has valid language tag](https://act-rules.github.io/rules/de46e4) | 3.1.2 | `lang-invalid`, `inline-lang-change-missing` | 🟨 partially consistent | 6/9 |
+| [Form field has non-empty accessible name](https://act-rules.github.io/rules/e086e5) | 4.1.2 | `control-label-missing` | 🟨 partially consistent | 4/7 |
+| [Video element auditory content has captions](https://act-rules.github.io/rules/f51b46) | — | `media-no-track` | 🟨 partially consistent | 0/4 |
+| [ARIA required context role](https://act-rules.github.io/rules/ff89c9) | 1.3.1 | `aria-required-parent` | 🟨 partially consistent | 2/4 |
+| [Heading has non-empty accessible name](https://act-rules.github.io/rules/ffd0e9) | 1.3.1 | `empty-heading` | 🟨 partially consistent | 7/8 |
+
+### Notes and documented divergences
+
+- **Visible label is part of accessible name** · reports on *Passed Example 6*: an icon FONT renders the text 'search' as a glyph, so the visible label is not the text in the DOM — a fact only the rendered page carries
+- **Audio or video element that plays automatically has a control mechanism** · reports on *Inapplicable Example 2*: the source cannot tell that the referenced media has no audio track
+- **Audio or video element that plays automatically has a control mechanism** · reports on *Passed Example 3*: the pause mechanism is a custom button wired in JavaScript, not a native `controls` attribute
+- **ARIA state or property is permitted** — covers the name-prohibited roles; the full per-role permitted-attribute matrix is not encoded
+- **Element with aria-hidden has no content in sequential focus navigation** · reports on *Passed Example 4*: a focus-sentinel link inside an aria-hidden wrapper: it IS reachable by Tab, and only a runtime focus handler bounces it back — the same call axe-core makes
+- **SVG element with explicit role has non-empty accessible name** — role=img on <svg> is handled by the same rule
+- **Audio or video element avoids automatically playing audio** · reports on *Inapplicable Example 2*: the source cannot tell that the referenced media file is silent
+- **Audio or video element avoids automatically playing audio** · reports on *Passed Example 3*: the pause mechanism is a custom button wired in JavaScript, not a native `controls` attribute
+- **Audio or video element avoids automatically playing audio** · reports on *Passed Example 2*: a #t= media fragment shortening playback below 3s is not resolvable from source
+- **Meta element has no refresh delay (no exception)** — this variant drops the >20h exception the engine honours, so long delays are knowingly not reported
+- **Iframe element has non-empty accessible name** · reports on *Inapplicable Example 3*: a tabindex=-1 iframe is still exposed to assistive tech and still needs a title (RGAA 2.1 requires one unconditionally)
+- **Table header cell has assigned cells** — only the explicit `headers`-wired shape is decided; scope-based assignment needs a full table model
+- **Element with lang attribute has valid language tag** · reports on *Inapplicable Example 2*: lang="" on an element carrying text declares no language for that text; ACT deems the rule inapplicable, this engine reports it under 3.1.2
+- **Form field has non-empty accessible name** — `placeholder-as-label` is deliberately NOT mapped: a placeholder does contribute to the accessible name, so ACT passes it — ultra11y still reports it, as a stricter house rule under 3.3.2.
+- **Video element auditory content has captions** — presence of a caption track; whether the captions are accurate is a judgment call
+
+## Declared gaps — statically decidable, not implemented yet
+
+| ACT rule | WCAG | Why it is not covered |
+|---|---|---|
+| [Document has heading for non-repeated content](https://act-rules.github.io/rules/047fe0) | — | a heading for the non-repeated content (h1-missing is advisory, so it does not count) |
+| [Letter spacing in style attributes is not !important](https://act-rules.github.io/rules/24afc2) | 1.4.12 | letter-spacing:!important in a style attribute |
+| [Element with presentational children has no focusable content](https://act-rules.github.io/rules/307n5z) | 4.1.2 | presentational-children conflict |
+| [Element marked as decorative is not exposed](https://act-rules.github.io/rules/46ca7f) | — | an element marked decorative that is still exposed (focusable, or with a name) |
+| [HTML page lang and xml:lang attributes have matching values](https://act-rules.github.io/rules/5b7ae0) | 3.1.1 | lang vs xml:lang mismatch |
+| [Line height in style attributes is not !important](https://act-rules.github.io/rules/78fd32) | 1.4.12 | line-height:!important in a style attribute |
+| [Word spacing in style attributes is not !important](https://act-rules.github.io/rules/9e45ec) | 1.4.12 | word-spacing:!important in a style attribute |
+| [Document has a landmark with non-repeated content](https://act-rules.github.io/rules/b40fd1) | — | ACT asks that the non-repeated content sit in SOME landmark — a weaker claim than `missing-main-landmark`, which requires a <main>, so the two are not equivalent |
+| [Bypass Blocks of Repeated Content](https://act-rules.github.io/rules/cf77f2) | 2.4.1 | presence of a bypass mechanism (landmark or skip link) |
+| [Attribute is not duplicated](https://act-rules.github.io/rules/e6952f) | 4.1.1 | duplicate attributes are collapsed by the parser; needs a raw-source scan |
+| [No keyboard shortcut uses only printable characters](https://act-rules.github.io/rules/ffbc54) | 2.1.4 | 2.1.4 single-character keyboard shortcuts |
+| [Menuitem has non-empty accessible name](https://act-rules.github.io/rules/m6b1q3) | 4.1.2 | role-specific accessible name (menuitem) |
+| [Document has an instrument to move focus to non-repeated content](https://act-rules.github.io/rules/ye5d6e) | — | presence of a bypass instrument |
+
+## Out of the static engine's reach — routed, not ignored
+
+| ACT rule | WCAG | Decided by |
+|---|---|---|
+| [Text has enhanced contrast](https://act-rules.github.io/rules/09o5cg) | 1.4.6 | rendered (`scan`) — AAA enhanced contrast — outside the AA core |
+| [Scrollable element is keyboard accessible](https://act-rules.github.io/rules/0ssw9k) | 2.1.1, 2.1.3 | rendered (`scan`) |
+| [HTML graphics contain no text](https://act-rules.github.io/rules/0va7u6) | 1.4.5, 1.4.9 | rendered (`scan`) — text baked into a graphic |
+| [Audio and visuals of video element have transcript](https://act-rules.github.io/rules/1a02b0) | 1.2.8 | judgment (agent) |
+| [Video element visual content has audio description](https://act-rules.github.io/rules/1ea59c) | — | judgment (agent) |
+| [Video element visual content has strict accessible alternative](https://act-rules.github.io/rules/1ec09b) | 1.2.5 | judgment (agent) |
+| [Audio element content has transcript](https://act-rules.github.io/rules/2eb176) | — | judgment (agent) |
+| [Error message describes invalid form field value](https://act-rules.github.io/rules/36b590) | 3.3.1 | judgment (agent) |
+| [Block of repeated content is collapsible](https://act-rules.github.io/rules/3e12e1) | — | rendered (`scan`) |
+| [Iframe elements with identical accessible names have equivalent purpose](https://act-rules.github.io/rules/4b1c6c) | 4.1.2 | judgment (agent) |
+| [Zoomed text node is not clipped with CSS overflow](https://act-rules.github.io/rules/59br37) | 1.4.4 | rendered (`scan`) — clipping under zoom — probed by scan --runtime local |
+| [Link in context is descriptive](https://act-rules.github.io/rules/5effbb) | 2.4.4, 2.4.9 | judgment (agent) — link purpose in context (2.4.4) |
+| [Device motion based changes to the content can also be created from the user interface](https://act-rules.github.io/rules/7677a9) | 2.5.4 | judgment (agent) |
+| [Focusable element has no keyboard trap](https://act-rules.github.io/rules/80af7b) | 2.1.2 | rendered (`scan`) |
+| [Content has alternative for visual reference](https://act-rules.github.io/rules/9bd38c) | 1.3.3 | judgment (agent) — sensory characteristics (1.3.3) |
+| [DEPRECATED — Image filename is accessible name for image](https://act-rules.github.io/rules/9eb3f6) | 1.1.1 | withdrawn upstream |
+| [Focusable element has no keyboard trap via standard navigation](https://act-rules.github.io/rules/a1b64e) | — | rendered (`scan`) |
+| [Audio or video element that plays automatically has no audio that lasts more than 3 seconds](https://act-rules.github.io/rules/aaa1bf) | — | rendered (`scan`) — needs the media's duration |
+| [Video element content is media alternative for text](https://act-rules.github.io/rules/ab4d13) | — | judgment (agent) |
+| [DEPRECATED — Video element visual-only content has description track](https://act-rules.github.io/rules/ac7dc6) | — | withdrawn upstream |
+| [Audio element content is media alternative for text](https://act-rules.github.io/rules/afb423) | — | judgment (agent) |
+| [Text has minimum contrast](https://act-rules.github.io/rules/afw4f7) | 1.4.3, 1.4.6 | rendered (`scan`) — computed contrast; only inline literal colour pairs are decided statically (contrast-literal) |
+| [Link is descriptive](https://act-rules.github.io/rules/aizyf1) | 2.4.9 | judgment (agent) |
+| [Iframe with negative tabindex has no interactive elements](https://act-rules.github.io/rules/akn7bn) | 2.1.1 | rendered (`scan`) — needs the iframe's own document |
+| [Links with identical accessible names have equivalent purpose](https://act-rules.github.io/rules/b20e66) | 2.4.9 | judgment (agent) |
+| [Orientation of the page is not restricted using CSS transform property](https://act-rules.github.io/rules/b33eff) | 1.3.4 | rendered (`scan`) — orientation lock via CSS transform |
+| [Heading is descriptive](https://act-rules.github.io/rules/b49b2e) | 2.4.6 | judgment (agent) — is the heading descriptive (2.4.6) |
+| [Device motion based changes to the content can be disabled](https://act-rules.github.io/rules/c249d5) | 2.5.4 | judgment (agent) |
+| [Video element visual-only content has accessible alternative](https://act-rules.github.io/rules/c3232f) | 1.2.1 | judgment (agent) |
+| [HTML page title is descriptive](https://act-rules.github.io/rules/c4a8a4) | 2.4.2 | judgment (agent) |
+| [Video element visual content has accessible alternative](https://act-rules.github.io/rules/c5a4ea) | 1.2.3, 1.2.5, 1.2.8 | judgment (agent) |
+| [Form field label is descriptive](https://act-rules.github.io/rules/cc0f0a) | 2.4.6 | judgment (agent) |
+| [Video element visual-only content has audio track alternative](https://act-rules.github.io/rules/d7ba54) | — | judgment (agent) |
+| [Audio element content has text alternative](https://act-rules.github.io/rules/e7aa44) | 1.2.1 | judgment (agent) |
+| [Image not in the accessibility tree is decorative](https://act-rules.github.io/rules/e88epe) | 1.1.1 | judgment (agent) — is the image genuinely decorative |
+| [Video element auditory content has accessible alternative](https://act-rules.github.io/rules/eac66b) | 1.2.2 | judgment (agent) |
+| [Focusable element has no keyboard trap via non-standard navigation](https://act-rules.github.io/rules/ebe86a) | — | rendered (`scan`) |
+| [Video element visual-only content has transcript](https://act-rules.github.io/rules/ee13b5) | — | judgment (agent) |
+| [Text content that changes automatically can be paused, stopped or hidden](https://act-rules.github.io/rules/efbfc7) | 2.2.2 | rendered (`scan`) |
+| [DEPRECATED — Video element visual content has description track](https://act-rules.github.io/rules/f196ce) | — | withdrawn upstream |
+| [Video element visual-only content is media alternative for text](https://act-rules.github.io/rules/fd26cf) | — | judgment (agent) |
+| [Links with identical accessible names and same context serve equivalent purpose](https://act-rules.github.io/rules/fd3a94) | 2.4.4, 2.4.9 | judgment (agent) |
+| [HTML element language subtag matches language](https://act-rules.github.io/rules/off6ek) | 3.1.2 | judgment (agent) — does the subtag match the actual text language |
+| [Element in sequential focus order has visible focus](https://act-rules.github.io/rules/oj04fd) | 2.4.7 | rendered (`scan`) — visible focus (2.4.7) — probed by scan --runtime local |
+| [Image accessible name is descriptive](https://act-rules.github.io/rules/qt1vmo) | 1.1.1 | judgment (agent) — is the alt relevant (1.1.1) |
+| [HTML page language subtag matches default language](https://act-rules.github.io/rules/ucwvc8) | 3.1.1 | judgment (agent) |
+
+The corpus is vendored at `scripts/vendor/act-testcases.json` (refreshed by
+`pnpm run build:act:refresh`, and daily by the act-refresh workflow) so the suite stays
+offline and deterministic.
+ACT-Rules Community Group test cases are © their contributors under the W3C Software and
+Document License — see `NOTICE`.