ultra11y 2.22.0

package/skills/ultra11y/references/audit.md

@@ -0,0 +1,100 @@
+# Audit existing code → WCAG report
+
+Goal: produce a dated, reliable WCAG 2.2 AA compliance report. The engine decides the
+automatable subset; the **AI agent** adjudicates the judgment criteria (`verify --manual`,
+gated) and routes the rendering criteria to `scan`; the gates stop any hallucinated
+non-conformity.
+
+## The loop
+
+1. **Scope it.** Which files / components? HTML, JSX/TSX and Vue/Svelte/Astro components
+   (`.vue`/`.svelte`/`.astro`) are walked by default; add server templates (Twig, ERB,
+   Handlebars…) with `--ext .twig,.erb`. **Test/spec/story markup** (`*.test.*`,
+   `*.spec.*`, `*.stories.*`, `__tests__/`) is excluded by default — it is bad-by-design
+   and never shipped; pass `--no-default-excludes` (or name the file) to audit it anyway.
+   **`.vue`/`.svelte`/`.astro` are audited as SOURCE templates**: slots, snippets and
+   dynamic bindings are invisible, so their findings are flagged `preliminary` and the run
+   carries a `scope.sourceTemplate` caveat — audit the rendered output to confirm (step 3,
+   and `references/rendered.md`).
+2. **Run the engine:**
+   ```
+   node scripts/ultra11y.mjs audit "src/**/*.html" --json > audit.json
+   ```
+   or on a snippet: `node scripts/ultra11y.mjs audit - < page.html --json`.
+   The `AuditResult` classes each success criterion as `C` / `NC` / `NA` (static) or
+   `manual` (rendering / judgment, listed in `residualRisks`). It also records the repo's
+   declared language(s) as `scope.langs` (the primary `<html lang>` subtags seen, most
+   frequent first, e.g. `["fr"]`) — the repo signal `--lang auto` resolves from downstream.
+3. **Triage the results:**
+   - engine `NC` = confirmed candidates (each finding cites `file:line`);
+   - `manual` *needs-rendering* criteria (contrast 1.4.3, focus visible 2.4.7, reflow
+     1.4.10…) → route to `scan`, **never** silently `C`. Note: contrast on
+     **inline literal colours** is now decided statically (1.4.3 turns `NC` for that
+     subset); contrast via external CSS or variables stays residual (→ dynamic tier);
+   - `manual` *judgment* criteria (alt relevance under 1.1.1, link purpose 2.4.4, reading
+     / tab order…) → the AI agent adjudicates them from context via `verify --manual` (gated).
+4. **Decide each applicable criterion**: `C`, `NC` or `NA` (with a justification). For a
+   criterion's detail and grounding: `node scripts/ultra11y.mjs criteria 1.1.1`.
+5. **Render the report:**
+   ```
+   node scripts/ultra11y.mjs report --in audit.json --out audits
+   ```
+   → `audits/wcag-YYYY-MM-DD.md` (5 sections, see `references/methodology.md`); section 2
+   renders one **auditor conformance block** per NC criterion (theme, criterion + official
+   wording, test(s), WCAG mapping + level, finding, expected state, verification,
+   `file:line` occurrences), grouped by severity — the SAME block `prd` and `--gh-issues`
+   emit (see `references/prd.md`), so report and backlog never drift. For a country
+   standard, add `--standard rgaa` (see `references/standards.md`). Pass `--lang` to match
+   your conversation; without it, `auto` resolves the audit's `scope.langs` → the
+   standard's default locale → English. Add `--json` to `report` for a machine summary
+   (`{path, conformancePct, date, standard}`) instead of just the path.
+6. **Check integrity:**
+   ```
+   node scripts/ultra11y.mjs check --report audits/wcag-YYYY-MM-DD.md
+   ```
+   Fails if a section is missing, a cited criterion does not exist, or an `NA` is unjustified.
+7. **High assurance (optional)**: `references/verify.md` — prove every non-conformity is
+   real before you ship.
+
+## The normative page sample (échantillon) — country-standard audits
+
+A file-tree audit answers "is this markup conformant?"; a **country-standard** audit (RGAA,
+Section 508…) is normatively defined over a **representative page sample**, not the whole
+repo. Declare that sample once in `.ultra11yrc.json`:
+
+```json
+{ "standard": "rgaa",
+  "sample": {
+    "pages": [
+      { "id": "accueil", "name": "Page d'accueil", "url": "http://localhost:3000/" },
+      { "id": "contact", "name": "Contact", "url": "http://localhost:3000/contact" },
+      { "id": "compte", "name": "Mon compte", "url": "http://localhost:3000/compte", "auth": true, "storageState": ".auth/user.json", "notes": "connecté" }
+    ],
+    "transverse": ["header", "navigation principale", "pied de page"]
+  } }
+```
+
+- `sample.pages[]` are the audited URLs (each may sit behind `auth` with a per-page
+  `storageState`); `transverse` names the elements audited on **every** page (header, nav,
+  footer, modals…). The `storageState` **path** is used but its content is never read into
+  any output.
+- **Lint the coverage**: `node scripts/ultra11y.mjs sample check` reports which **required
+  page kinds** the active standard's `sampleMethodology` expects but the sample lacks (RGAA:
+  accueil, contact, mentions légales, déclaration d'accessibilité, plan du site, aide,
+  authentification…). Advisory (exit 0) unless the `sample` block is malformed (exit 2).
+- **Scan the sample**: `scan --sample --merge audits/audit-latest.json` iterates every page,
+  keeps each finding's page name + auth flag as provenance, and merges the rendered verdicts
+  in (see `references/dynamic.md`).
+- **Partial-audit honesty**: a `--standard rgaa` report produced **without** a merged sample
+  scan is flagged **partial** — a CLI warning + a report banner naming the needs-rendering
+  criteria that were not tested. Say the audit is partial rather than implying full coverage.
+
+## Golden rules
+
+- **Never invent a non-conformity**: every `NC` must cite a real, resolvable element
+  (`check` verifies it).
+- **Residual is explicit, never silently `C`**: an unproven *needs-rendering* criterion goes to
+  `scan`; a *judgment* criterion the AI agent adjudicates via `verify --manual` (gated). Any
+  criterion still undecided stays in the "to assess manually" section with a recorded reason.
+- The report's **automatic static-check pass rate** covers only the machine-decidable
+  subset; full WCAG conformance requires your manual review (it is not a conformance rate).

package/skills/ultra11y/references/authoring.md

@@ -0,0 +1,37 @@
+# Write / review accessible HTML/CSS (without regressions)
+
+Doctrine: **semantic native HTML first, ARIA last** (native-first, ARIA last). Add ARIA
+only when no native element fits, and never duplicate implicit semantics (see
+`references/forbidden-patterns.md`).
+
+## Review loop
+
+1. **Structure & landmarks** — a single `<main>`, `<header>/<nav>/<footer>`, `h1…h6`
+   headings without level skips, real lists (`ul/ol/dl`).
+2. **Accessible names** — every link/button has a label; every field has an associated
+   `<label>` (not just a `placeholder`).
+3. **Images & icons** — relevant `alt` if informative, `alt=""` if decorative, a name on
+   icon-only controls.
+4. **Tables** — `<caption>`, `<th scope>`, cell↔header association.
+5. **Keyboard** — everything reachable and operable by keyboard; no positive `tabindex`;
+   visible focus (verify at render); a working skip link.
+6. **Language & title** — `<html lang>`, a relevant `<title>`, language changes marked.
+
+## Catch regressions early
+
+Before shipping the code, audit the snippet:
+```
+node scripts/ultra11y.mjs audit - < component.html
+node scripts/ultra11y.mjs audit "src/components/**/*.tsx" --jsx
+```
+Fix by priority: native semantics → names/labels → keyboard → focus → meaning not carried
+by colour/shape alone → media.
+
+## Definition of Done
+
+A change is "done" when: native semantics are correct, accessible names are present,
+keyboard access is preserved, no regression is introduced, and the points not statically
+verifiable (contrast, visible focus, zoom) are **flagged as residual risks** rather than
+assumed OK.
+
+For the exact meaning of a criterion: `node scripts/ultra11y.mjs criteria <sc>`.

package/skills/ultra11y/references/automation.md

@@ -0,0 +1,113 @@
+# Automate in the repo — `init` (hook / CI)
+
+ultra11y can stay an **on-demand** skill, or become a **gate** that runs on its own.
+`init` wires it (zero-dependency, no husky):
+
+```
+node scripts/ultra11y.mjs init --hook          # .git/hooks/pre-commit — strict STAGED gate (default)
+node scripts/ultra11y.mjs init                 # same as --hook
+node scripts/ultra11y.mjs init --ci            # .github/workflows/a11y.yml (PR diff vs base)
+node scripts/ultra11y.mjs init --baseline …    # opt into the legacy regression gate (below)
+```
+
+## Default: strict staged snapshot + safe auto-fix
+
+The default pre-commit hook operates on **exactly what is about to be committed** — the
+**staged index blobs**, read with `git show :./<path>`, *not* the working-tree copy.
+It runs (fix first, then gate — so safe fixes are always applied, and only the judgment
+issues that remain can block):
+
+```
+node scripts/ultra11y.mjs fix   --staged --write --safe            # auto-apply SAFE fixes to the staged snapshot, re-stage
+node scripts/ultra11y.mjs audit --staged --fail-on blocking        # gate: block only if issues remain (need judgment)
+```
+
+Why fix-first: every auto-fixable rule (positive `tabindex`, redundant `role`,
+zoom-blocking viewport) is `major`/`minor`, while the `blocking` findings (missing `alt`,
+missing label) are exactly the ones a codemod must **not** guess. So the safe pass cleans
+up and re-stages what it can, and the gate blocks only on the judgment remainder for the AI
+agent to adjudicate.
+
+- **`--staged`** scopes to staged adds/mods only (not untracked, not unstaged-only edits)
+  and audits the exact bytes a commit would record — including `.gitattributes` clean
+  filters. `--staged` wins over `--changed`/`--since`.
+- **`--safe`** applies only genuinely-**automatic** codemods. Placeholder inserts
+  (`alt="TODO"`, `lang="und"`, `title="TODO"`) are **not** applied: a stub would clear the
+  finding mechanically while still needing a real value, so those (and judgment proposals)
+  are left in place and keep the gate blocking.
+- **Auto-fix + re-stage** happens only for **fully-staged** files (working tree == index).
+  A **partially-staged** file (unstaged edits present) is left untouched — writing
+  index-derived output over it and `git add`-ing would silently stage those edits — so its
+  findings keep the gate blocking with a message to stage/fix it manually.
+- The commit proceeds only when no blocking issue remains after the safe pass. One-off
+  bypass: `SKIP_A11Y=1 git commit …`. Engine path override: `ULTRA11Y=/path/to/ultra11y.mjs`.
+
+**When the hook blocks on judgment issues** (alt relevance, link purpose, labels,
+heading structure) the agent should: open the cited **staged** code, apply the *real*
+fix (not a placeholder), `git add` the file, and re-commit — or run `fix --staged
+--write` to lay down placeholders and then fill them in.
+
+## MUST: the FINAL, rendered semantic HTML has to be correct
+
+The static engine only sees **source**. When markup comes from a **component library**
+(DSFR, MUI, Chakra…) or a `.vue`/`.svelte`/`.astro` SFC, the real **semantic HTML** only
+exists **after rendering** — the source `<Button/>` tells you nothing about the `<button>`
+(or `<div role>`) it emits. A green staged gate on opaque component source is **not**
+proof of an accessible result.
+
+**So make the produced semantic HTML the thing you gate — with rendered CAPTURES.** A
+capture is the *rendered* DOM serialized to `.html` and committed, so the gate audits the
+true markup, not the component call. Zero-touch setup (your tests do the rendering):
+
+```
+node scripts/ultra11y.mjs render --setup             # install the capture harvester into your test runner
+npm test                                              # every rendered component → .ultra11y/captures/*.html (provenance-tagged)
+node scripts/ultra11y.mjs audit --require-captures    # gate: every opaque/control component must have a capture
+```
+
+- **Attribution + coverage.** A finding on a capture is reported against the SOURCE
+  component (via its `<!-- ultra11y:capture … -->` provenance), not the capture file.
+  `render --coverage` shows covered vs blind-spot components; `--require-captures` turns any
+  remaining blind spot into a failure. `.vue`/`.svelte`/`.astro` components now count in this
+  coverage too, so a previously-green gate can newly report blind spots on an SFC-heavy repo —
+  intended (a named blind spot beats invisibility); capture those components or scope the gate.
+- **The gate sees the captures for the diffed components automatically.** In
+  `--changed`/`--staged`/`--since` mode the audit pulls in the committed captures whose
+  provenance points at a diffed source file (a capture is rarely itself part of the diff —
+  the SOURCE changed, its capture usually didn't), so the pre-commit gate audits the real
+  `<button>`/`<nav>`/heading structure/labels for every touched component, catching
+  regressions the opaque source hides. After a component change, re-run your tests so its
+  capture refreshes, and stage the refreshed capture with the source. `fix` never rewrites
+  captures (generated output). Storybook/build HTML and manual Testing-Library dumps also
+  work — anything under `.ultra11y/captures`, or point `--captures <dir>` (`--no-captures`
+  opts out entirely).
+- In CI, audit the **built** output (`audit "dist/**/*.html"`), and use `scan` for the
+  computed rendering criteria (contrast, focus, zoom). See `references/rendered.md`.
+
+Treat this as a hard rule: **do not sign off on a component/SFC change from the source
+audit alone — verify the rendered semantic HTML, and prefer committed captures so the
+gate keeps verifying it.**
+
+## Opt-in: baseline regression gate (legacy)
+
+For large existing backlogs, keep the original "only block NEW regressions" gate. It is
+opt-in via `--baseline` (or an explicit `--fail-on`), and is what `--ci` uses:
+
+```
+node scripts/ultra11y.mjs init --baseline      # writes audits/baseline.json (commit it)
+node scripts/ultra11y.mjs init --hook --baseline
+node scripts/ultra11y.mjs init --ci            # audit --since <base> --baseline … in Actions
+```
+
+The hook/CI then run `audit --changed --baseline audits/baseline.json --fail-on blocking`:
+the audit is restricted to the **diff**, and only **NEW** non-conformities at/above the
+threshold fail — the existing backlog never blocks. Finding identity `(rule, criterion,
+file, source range)` is robust to line drift. **Commit `audits/baseline.json`** (add a
+`!audits/baseline.json` negation if `audits/` is git-ignored) and refresh it as you burn
+down backlog. `--fail-on blocking|major|minor` sets the threshold (French aliases
+`bloquant|majeur|mineur` accepted).
+
+> Either gate relies on the **static** engine. The **rendering** (contrast, focus, zoom) criteria
+> go to `scan` and the **judgment** criteria are adjudicated by the AI agent (`verify --manual`,
+> gated) in the full audit — the gate stops mechanical regressions, it is not the full audit
+> (a human is at most optional oversight).

package/skills/ultra11y/references/correction.md

@@ -0,0 +1,41 @@
+# Correction phase (put the fixes in place, by priority)
+
+Fix without breaking or inventing anything. Doctrine (native HTML first, smallest possible
+change, no regressions) applied in priority order.
+
+## Processing order
+
+1. **🔴 Blocking first**, then 🟠 major, then 🟡 minor — the order of the `prd` backlog and the
+   report. On a large repo, handle the shared templates first (layouts, design system): a fix
+   there covers the whole site.
+2. **Three classes of fix** (`fix`):
+   - **auto** — deterministic codemods (positive tabindex, redundant ARIA, blocked zoom); safe
+     to apply unsupervised.
+   - **placeholder** — inserts a valid attribute with a `TODO` (alt/lang/title/aria-label) that
+     you replace with a real, in-context value.
+   - **proposal** — judgment only; the engine never invents content (alt text, link purpose,
+     table structure) — the AI agent writes it and adjudicates the criterion (`verify --manual`,
+     gated).
+3. **Conforming / non-conforming examples**: for each pattern, start from the smallest change
+   that makes the **rendered** HTML conforming (not just the source). If a library component
+   does not instantiate correctly (e.g. an icon-only DSFR button with no `title`), fix at the
+   usage site and re-verify on the render.
+
+## Commands
+
+```
+node scripts/ultra11y.mjs fix "src/**/*.html"            # dry-run: proposed diff
+node scripts/ultra11y.mjs fix "src/**/*.html" --write     # apply (auto+placeholder)
+node scripts/ultra11y.mjs fix "src/**/*.tsx"  --write     # real JSX: jsxSafe codemods only
+node scripts/ultra11y.mjs fix "src/**" --write --iterate   # re-audit + re-apply to a fixpoint
+node scripts/ultra11y.mjs fix "src/**" --only img-alt-missing,positive-tabindex
+node scripts/ultra11y.mjs prd  --in audits/audit-latest.json   # prioritized backlog of remaining fixes
+```
+
+- **Anti-regression gate**: `--write` applies only if a re-audit proves no new non-conformity
+  is introduced (including no new finding type). An invalid placeholder is thus blocked.
+- **JSX/TSX**: `fix --write` applies only the safe codemods (remove ARIA, insert valid React
+  attributes); it never rewrites an attribute name (no `tabIndex={5}` → `tabindex="0"`). The
+  rest stays a proposal.
+- After fixing, **loop**: re-audit, re-judge the `proposal`s, until `check`/`verify` are green
+  again (see the SKILL's "loop" section).

package/skills/ultra11y/references/criteria.md

@@ -0,0 +1,129 @@
+<!-- GENERATED from src/data/wcag.json by `ultra11y criteria --generate` — do not edit by hand. -->
+
+# WCAG 2.2 Level AA — success-criteria reference
+
+The 55 Level A + AA success criteria across the 4 principles / 13 guidelines, with each
+SC's level, the ultra11y automatability class (automatable / needs rendering / judgment),
+the engine rules that cover it, and — one column per registered standards pack — the pack
+criteria that map to it. SC ids, titles and levels are derived from the W3C source
+(https://github.com/w3c/wcag); WCAG 2.2 © W3C.
+
+## 1.1 Text Alternatives
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 1.1.1 | Non-text Content | A | judgment | img-alt-missing, canvas-fallback-missing, decorative-alt-misuse, input-image-alt-missing, object-embed-no-name, chart-no-accessible-name | 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.9, 4.7, 4.8, 4.9, 6.1, 6.2, 7.2, 10.2, 13.3, 13.4, 13.5, 13.6 |
+
+## 1.2 Time-based Media
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 1.2.1 | Audio-only and Video-only (Prerecorded) | A | judgment | — | 4.1, 4.2 |
+| 1.2.2 | Captions (Prerecorded) | A | judgment | media-no-track | 4.3, 4.4 |
+| 1.2.3 | Audio Description or Media Alternative (Prerecorded) | A | judgment | — | 4.1, 4.2 |
+| 1.2.4 | Captions (Live) | AA | judgment | — | — |
+| 1.2.5 | Audio Description (Prerecorded) | AA | judgment | — | 4.5, 4.6 |
+
+## 1.3 Adaptable
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 1.3.1 | Info and Relationships | A | judgment | fieldset-legend-missing, data-table-no-headers, table-caption-missing, layout-table-data-markup, heading-order-skip, h1-missing, h1-multiple, list-structure, dl-structure, empty-heading, label-for-dangling, missing-main-landmark, multiple-main-landmark, sortable-header-no-aria-sort, nav-landmark-missing, nav-landmark-unnamed, aria-required-parent, headers-attr-dangling, th-no-data-cells, radio-checkbox-group-ungrouped, table-empty-data-cell, css-generated-content-informative | 3.1, 5.1, 5.2, 5.4, 5.5, 5.6, 5.7, 5.8, 7.3, 8.9, 9.1, 9.2, 9.3, 9.4, 10.1, 10.2, 11.1, 11.5, 11.6, 11.7, 11.8, 12.6, 13.3, 13.4 |
+| 1.3.2 | Meaningful Sequence | A | judgment | — | 5.3, 8.10, 10.1, 10.3, 10.8, 13.3, 13.4 |
+| 1.3.3 | Sensory Characteristics | A | judgment | — | 10.9, 10.10 |
+| 1.3.4 | Orientation | AA | needs-rendering | — | 13.9 |
+| 1.3.5 | Identify Input Purpose | AA | judgment | field-purpose-incomplete, autocomplete-token-invalid | 11.13 |
+
+## 1.4 Distinguishable
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 1.4.1 | Use of Color | A | needs-rendering | — | 3.1, 10.6, 10.7, 10.9, 10.10 |
+| 1.4.2 | Audio Control | A | static | autoplay-media | 4.10 |
+| 1.4.3 | Contrast (Minimum) | AA | needs-rendering | contrast-literal | 3.2, 10.5 |
+| 1.4.4 | Resize Text | AA | needs-rendering | meta-viewport-zoom-block | 10.4 |
+| 1.4.5 | Images of Text | AA | needs-rendering | — | 1.8 |
+| 1.4.10 | Reflow | AA | needs-rendering | — | 10.11 |
+| 1.4.11 | Non-text Contrast | AA | needs-rendering | — | 3.3 |
+| 1.4.12 | Text Spacing | AA | needs-rendering | — | 10.12 |
+| 1.4.13 | Content on Hover or Focus | AA | needs-rendering | — | 10.13 |
+
+## 2.1 Keyboard Accessible
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 2.1.1 | Keyboard | A | judgment | clickable-noninteractive | 4.11, 4.12, 7.3, 10.14, 12.9, 12.11 |
+| 2.1.2 | No Keyboard Trap | A | needs-rendering | — | 4.11, 4.12, 12.9 |
+| 2.1.4 | Character Key Shortcuts | A | judgment | — | 12.10 |
+
+## 2.2 Enough Time
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 2.2.1 | Timing Adjustable | A | judgment | meta-refresh-redirect | 13.1, 13.8 |
+| 2.2.2 | Pause, Stop, Hide | A | judgment | autoplay-media, blink-marquee | 13.1, 13.8 |
+
+## 2.3 Seizures and Physical Reactions
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 2.3.1 | Three Flashes or Below Threshold | A | needs-rendering | — | 13.7 |
+
+## 2.4 Navigable
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 2.4.1 | Bypass Blocks | A | judgment | skip-link-target-missing | 9.1, 12.6, 12.7, 13.3, 13.4 |
+| 2.4.2 | Page Titled | A | static | title-missing-empty | 8.5, 8.6 |
+| 2.4.3 | Focus Order | A | judgment | positive-tabindex | 10.3, 12.7, 12.8, 13.3, 13.4 |
+| 2.4.4 | Link Purpose (In Context) | A | judgment | link-empty-name, icon-only-control-unnamed | 6.1, 6.2 |
+| 2.4.5 | Multiple Ways | AA | judgment | — | 12.1, 12.3, 12.4 |
+| 2.4.6 | Headings and Labels | AA | judgment | — | 9.1, 11.1, 11.2 |
+| 2.4.7 | Focus Visible | AA | needs-rendering | — | 7.3, 10.7 |
+| 2.4.11 | Focus Not Obscured (Minimum) | AA | needs-rendering | — | — |
+
+## 2.5 Input Modalities
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 2.5.1 | Pointer Gestures | A | judgment | — | 13.10 |
+| 2.5.2 | Pointer Cancellation | A | judgment | — | 13.11 |
+| 2.5.3 | Label in Name | A | judgment | label-in-name-mismatch | 6.1, 7.1, 11.2, 11.9 |
+| 2.5.4 | Motion Actuation | A | judgment | — | 13.12 |
+| 2.5.7 | Dragging Movements | AA | judgment | — | — |
+| 2.5.8 | Target Size (Minimum) | AA | needs-rendering | — | — |
+
+## 3.1 Readable
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 3.1.1 | Language of Page | A | static | html-lang-missing, lang-invalid | 8.3, 8.4, 13.3, 13.4 |
+| 3.1.2 | Language of Parts | AA | judgment | inline-lang-change-missing, lang-invalid | 8.7, 8.8 |
+
+## 3.2 Predictable
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 3.2.1 | On Focus | A | judgment | — | 7.4, 13.2 |
+| 3.2.2 | On Input | A | judgment | on-input-context-change | 7.4 |
+| 3.2.3 | Consistent Navigation | AA | judgment | — | 12.2, 12.4, 12.5, 12.7 |
+| 3.2.4 | Consistent Identification | AA | judgment | — | 11.3 |
+| 3.2.6 | Consistent Help | A | judgment | — | — |
+
+## 3.3 Input Assistance
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 3.3.1 | Error Identification | A | judgment | aria-invalid-no-description, error-not-associated | 11.10 |
+| 3.3.2 | Labels or Instructions | A | judgment | radio-checkbox-group-ungrouped, date-fields-ungrouped | 11.1, 11.2, 11.4, 11.5, 11.6, 11.7, 11.10 |
+| 3.3.3 | Error Suggestion | AA | judgment | — | 11.11 |
+| 3.3.4 | Error Prevention (Legal, Financial, Data) | AA | judgment | — | 11.12 |
+| 3.3.7 | Redundant Entry | A | judgment | — | — |
+| 3.3.8 | Accessible Authentication (Minimum) | AA | judgment | credential-entry-blocked | — |
+
+## 4.1 Compatible
+
+| SC | Title | Level | Automatability | Rules | RGAA |
+|---|---|---|---|---|---|
+| 4.1.2 | Name, Role, Value | A | judgment | iframe-title-missing, invalid-aria-role, aria-ref-missing-id, redundant-aria, clickable-noninteractive, aria-required-children, aria-hidden-focusable, nested-interactive, invalid-aria-attr, invalid-aria-value, aria-required-attr, aria-prohibited-attr, duplicate-id, control-label-missing, placeholder-as-label, form-field-multiple-labels, select-has-option, button-empty-name, icon-only-control-unnamed, control-name-title-only, field-purpose-incomplete, disabled-context-content | 1.2, 1.3, 1.9, 2.1, 2.2, 4.13, 5.3, 7.1, 7.2, 8.2, 9.1, 10.8, 11.1, 11.9, 12.6, 13.3, 13.4 |
+| 4.1.3 | Status Messages | AA | judgment | live-region-conflict, status-message-not-assertive | 7.5 |

package/skills/ultra11y/references/cross-file.md

@@ -0,0 +1,82 @@
+# Cross-file analysis (`audit --graph`)
+
+By default the engine audits **each file in isolation**. `--graph` (alias `--cross-file`)
+adds a pass that **resolves imports between files**, builds a dependency + component graph,
+and applies rules only the cross-file context makes visible — **without a browser** (no
+Playwright). It complements the per-file static engine and the optional dynamic tier
+(`scan`): all three feed the **same** `AuditResult`.
+
+```
+node scripts/ultra11y.mjs audit "src/**/*.tsx" --graph --json > audit.json
+node scripts/ultra11y.mjs audit --changed --graph     # git diff, graph over the whole scope
+```
+
+## How it works (and why it scales)
+
+- **Real AST**: `.jsx/.tsx` are parsed by a real JS/TS/JSX parser (`@babel/parser`, embedded
+  in the bundle — still "no install"), not regex normalization. `PascalCase` components keep
+  their case (per-file rules ignore them; only cross-file rules resolve them); native
+  elements stay lowercase.
+- **Two passes, bounded memory**: pass 1 — read each file, extract a small *graph node*
+  (imports, components + render-control signals, ids, `<html lang>`), then **drop** the
+  AST/Doc. Pass 2 — the usual audit loop, which also runs the cross-file rules with the graph
+  in hand. The whole repo is never held in memory: O(number of files) small nodes.
+- **`--changed --graph`**: the graph indexes the **whole** scope (to resolve a reference into
+  an unchanged definition), but only the diffed files are audited.
+- **Plain `.ts`/`.js` modules are graphed, never audited.** The graph's own discovery widens
+  to `.ts`/`.js`/`.mjs`/`.cjs` on top of the markup allowlist: a **barrel**
+  (`components/index.ts` re-exporting `Button.tsx`) or a plain-JS component definition is
+  real cross-file structure that imports resolve through — chained re-exports
+  (`export { Button } from "./Button"`, barrels of barrels) are followed to the real
+  definition. Those files feed imports/re-exports/definitions/ids into the graph but never
+  enter the audit loop (no markup rule ever runs on them).
+- **`.vue`/`.svelte`/`.astro` SFCs are first-class graph nodes.** Parsed with component case
+  preserved (same as the audit); the file's own `<script>` block — or an `.astro` file's
+  `---…---` **frontmatter** — is parsed separately as a script AST for its imports; and each
+  SFC synthesizes a self component definition (PascalCase basename), so a `.tsx` importing
+  `./Widget.vue` resolves cross-file and the SFC counts in capture coverage. Astro
+  frontmatter is also stripped (offset-preserving) before the template parse, so frontmatter
+  TypeScript (`Array<string>`) never produces phantom elements or findings.
+- **Import resolution**: relative specifiers (`./IconButton`), **tsconfig-paths aliases**
+  (`@/components/Icon`, read from the nearest `tsconfig.json`'s `baseUrl`/`paths`), and
+  **namespace members** (`<UI.Button/>` from `import * as UI`) all resolve to a discovered
+  file. *Bounds (documented, never a silent false "conforming"):* bare `node_modules`
+  specifiers (`react`) are out of scope; alias bases are resolved relative to the working
+  dir (run the audit from the project root); React **context** value flow and dynamic
+  `import()` are not traced.
+
+## The cross-file rules
+
+- **`cross-icon-only-unnamed`** (WCAG 2.4.4/4.1.2, *flag*): a component that renders an
+  **icon-only** control and *can* receive a name (`{...props}` / `aria-label={…}` /
+  `{children}`) is used **without a name**. The flag is placed **at the usage site**, with the
+  component **definition** in `related`.
+- **`cross-prop-drilled-name-lost`** (WCAG 4.1.2, *flag*): a usage passes an accessible-name
+  prop (`aria-label`/`label`/…) to a component that renders a control but **neither spreads
+  `{...props}` nor forwards a name** to it → the name is silently dropped. Flagged at the
+  usage, with the control **definition** in `related`.
+- **`cross-aria-ref-cross-file`** (WCAG 4.1.2, *suppression*): an `aria-labelledby`/
+  `aria-describedby`/`aria-controls` whose target id lives in **another** file →
+  suppresses the false `aria-ref-missing-id`. Suppressed only when **every** in-page-missing
+  id resolves elsewhere, so a genuinely-dangling reference is never hidden.
+- **`cross-aria-forwarding`** (WCAG 4.1.2, *suppression*): a native control that forwards
+  `{...props}` is nameable by its parent → it **suppresses** the false
+  `button-empty-name`/`icon-only-control-unnamed` on the **definition**.
+- **`cross-skip-link-target`** (WCAG 2.4.1, *suppression*): an `href="#id"` anchor whose
+  target lives in **another** file (imported layout/component) → suppresses the false "broken
+  anchor". A target missing everywhere stays a true positive.
+- **`cross-page-lang`** (WCAG 3.1.1, *suppression*): an `<html>` without `lang` whose imported
+  layout/wrapper declares the language → suppresses the false positive.
+- **`cross-name-ref-cross-file`** (WCAG 1.3.1, *suppression*): a `<label for="id">` or a
+  heading/`aria-labelledby` whose target id is **defined in another** file → suppresses the
+  false `label-for-dangling` / empty-heading. Suppressed only when the id resolves elsewhere.
+
+## Benefit for `fix`
+
+Because the AST indexes the **real file** (exact offsets, non-*lossy* `Doc`), `fix` can apply
+its *safe* codemods on JSX/TSX (remove redundant ARIA, insert `alt`/`lang`/`title`/
+`aria-label`), always behind the anti-regression gate. Codemods that **rewrite** an attribute
+name stay disabled on JSX (so `tabIndex={5}` is never turned into `tabindex="0"`).
+
+> Cross-file flags merge into the same `AuditResult`: `report`, `prd`, `check` and `verify`
+> consume them unchanged.