ultra11y 4.0.1 → 4.2.0

package/skills/ultra11y/SKILL.md

@@ -4,7 +4,7 @@ description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibili
 when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD backlog, or tickets (GitHub/GitLab/Jira); author accessible markup from scratch; wire the repo gate (init --hook/--ci) or a rendered-DOM capture pipeline. For a review of the code UNDER CHANGE (diff, branch, PR), use the `review-a11y` skill instead."
 license: MIT
 metadata:
-  version: 4.0.1
+  version: 4.2.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup

package/skills/ultra11y/references/ci.md

@@ -262,6 +262,115 @@ Two surfaces come out of it:
 
 A run with no page in scope is not a failure: the report step says so and the job carries on.
 
+## What the artifact looks like when you open it
+
+`audits/` used to hold JSON, SARIF and Markdown: everything a machine needs and nothing that
+opens. `html: 'true'` and `evidence: 'true'` are on by default, so it now has a front door.
+
+```
+audits/
+├── index.html                        ← the entry point: rate, synthesis, page scoreboard, links
+├── ultra11y-<std>-<date>.html        ← the whole audit in ONE file, printable to PDF
+├── <std>-<date>.md                   ← the Markdown report, illustrated by the same crops
+├── audit-latest.json                 ← the machine-readable audit (unchanged)
+├── assets/
+│   ├── <page-id>.png                 ← the page screenshot
+│   └── <page-id>/<hash>.png          ← one annotated crop per distinct defect on that page
+└── pages/
+    ├── index.md + page-<id>.md       ← the per-page dossiers (unchanged)
+    └── index.html + page-<id>.html   ← the same, navigable
+```
+
+Two conventions share `assets/` and that is deliberate: `<page-id>.png` is the whole page,
+`<page-id>/` holds the crops OF that page. Renaming either would break the Markdown sheets
+already published by earlier versions.
+
+**One artifact, not two.** The HTML is written into the same `audits/` the Markdown already
+travels in, and the upload now fires when EITHER producer ran. A separate artifact would mean
+a second name to keep unique, a second 409 to hit, and a reviewer choosing between two
+downloads.
+
+**Everything is self-contained.** No script (an artifact viewer will not run one), no external
+stylesheet or font, and no `src`/`href` that leaves `audits/` — the artifact is read after
+being unzipped somewhere else, so a `../..` climb is a broken image for every reader. `ci.yml`
+asserts this on a real `download-artifact` round trip, because the HTML step itself degrades
+to a `::warning::` and cannot catch its own regression.
+
+### The crops
+
+An occurrence gains a sub-bullet showing the element, ringed:
+
+```md
+- [ ] `.ultra11y/pages/accueil/dom.html:412` (`div.card`) — <img> without an alt attribute…
+  - ![Cropped capture of the img element on the accueil page, outlined](./assets/accueil/c90959b13aa2.png)
+```
+
+**Every document that shows a non-conformity shows its crop**: the Markdown conformance
+report, the per-page sheets, and the single-file composite. They all reference one set of
+files in `assets/`; only the composite pays the base64 tax, because only it has to travel
+alone. `report --evidence` therefore works with or without `--html` — the images are not an
+HTML-only tier. `prd`, `gh` and `jira` deliberately stay text: their output is read on
+github.com, where a path relative to `audits/` resolves to nothing, and a broken image in an
+issue is worse than no image.
+
+Crops are derived AT RENDER TIME from the page snapshot, never stamped on the finding: a
+rectangle in pixels is a property of the image, and a stamped box goes silently wrong the
+moment the audit is re-rendered against a different capture. So `evidence` needs snapshots —
+`snapshot: 'true'` (the default), the E2E plugins, or `ultra11y dev`. Audited from source
+alone, the tier is simply inactive and says nothing: a source finding never had pixels, so it
+is not an occurrence that failed to be illustrated.
+
+The mark is **not monochrome**: a white halo, a red ring and corner brackets whose *shape*
+says "here". A tool that reports 1.4.1 failures cannot ship a deliverable that commits one.
+
+When a crop cannot be drawn, the report says so per page and per criterion, with the reason —
+`no-screenshot`, `below-the-fold`, `unknown-scale`, and nine more. **An occurrence without a
+picture must never read as an occurrence without a defect.**
+
+Two of those reasons look alike and are not:
+
+| Reason | What it means | Costs the reader |
+|---|---|---|
+| `deduplicated` | the same defect on the same element, already shown by another occurrence's picture | nothing |
+| `capped` | a **distinct** defect left undrawn because a limit ran out | a picture — raise `evidence-max` |
+
+`evidence-max` (200 by default) is the run-wide fuse and the only one that is a setting: it
+guards the upload's size. The per-rule (6) and per-page (12) limits are fixed, because they
+are what makes one picture stand for a repeated defect — one design-system failure multiplied
+by 38 routes is one defect, not 472 pictures.
+
+### Printing it
+
+The single file is the deliverable an auditor hands to a client: open
+`ultra11y-<std>-<date>.html`, print, *Save as PDF*. The print sheet keeps each criterion and
+its evidence on one sheet rather than splitting them across a page break.
+
+Its images travel inside it as `data:` URIs, and base64 costs a third more than the bytes it
+encodes — so there is a budget (the `inline-budget` input, `--inline-budget` on the CLI, 12 MB
+by default) and a ladder. Over budget, page screenshots go first, then all but one crop per
+criterion, then the images entirely. Every rung is written **into the document** and onto
+stderr, and the other documents still reference every crop as a file. Images degrade; the
+non-conformities
+never do.
+
+### Publishing it as a page (optional, and it costs something)
+
+An artifact needs a download and a login. If the report should be a URL, GitHub Pages will
+serve `audits/` as-is — it is already self-contained:
+
+```yaml
+- uses: actions/upload-pages-artifact@v3
+  with: { path: audits }
+- uses: actions/deploy-pages@v4
+```
+
+Know the trade before you take it: **a Pages site is public**, and this one names your
+non-conformities, your file paths and your routes, with screenshots. On a private repository
+that is a disclosure, not a convenience. It also needs `pages: write` and `id-token: write`,
+and it overwrites the previous deployment — there is no per-run history the way artifacts have
+one. Left alone, the artifact is the safer default, which is why this is a recipe here and not
+an input on the action.
+
 ## The action is executed in ITS OWN CI, not just parsed
 
 `tests/action.test.ts` reads `action.yml` and gates its shape. That cannot prove the thing

package/skills/ultra11y/references/pages.md

@@ -288,6 +288,82 @@ both a CSSOM measurement and a screenshot measurement, and presenting those as o
 be a lie. It is off everywhere else: the backlog, `prd --split criterion` and every tracker issue
 body are byte-identical to what they were.
 
+### Showing the defect, not only citing it (`--evidence`)
+
+`selectorHint` is lossy by construction — first class only, `href` truncated — and every
+rendered-tier finding on a client-rendered page is anchored at `dom.html:2`, the `<html>`
+element. What a non-technical reviewer receives is `` `.ultra11y/pages/accueil/dom.html:412`
+(`div.card`) ``, which locates nothing.
+
+```sh
+node scripts/ultra11y.mjs pages --in audits/audit-latest.json --format report \
+  --split page --evidence --out audits/pages
+```
+
+Each occurrence gains an inert sub-bullet with an annotated crop of the offending element,
+written to `assets/<page-id>/<hash>.png`:
+
+```md
+- [ ] `.ultra11y/pages/accueil/dom.html:412` (`div.card`) — <img> without an alt attribute…
+  - ![Cropped capture of the img element on the accueil page, outlined](./assets/accueil/c90959b13aa2.png)
+```
+
+**Derived at render time, never stamped on the finding.** A rectangle in pixels is a property
+of the image: a box written onto a `Finding` becomes silently wrong the moment the audit is
+re-rendered against another capture. The join goes `sourceStart` → document-order ordinal →
+`boxes.json`, through the same `alignedBoxes` the rendered tier uses — including its refusal
+to align a digest whose tags disagree. `Finding` gains no field.
+
+The mark is not monochrome: a white halo, a red ring, corner brackets whose shape says "here",
+and a dashed inner line that survives a monochrome print. This tool reports 1.4.1 failures; its
+own deliverable cannot commit one.
+
+**Nothing is cut in silence.** Thirteen refusal reasons, each with its own sentence, counted
+per page and per criterion in the sheet itself:
+
+| Reason | What happened |
+|---|---|
+| `no-snapshot` | the capture this finding's own path names is not on this disk |
+| `no-screenshot` | the producer captured no image for that page |
+| `unreadable-image` · `no-boxes` · `truncated` | the capture or the box digest cannot be trusted |
+| `no-offsets` · `unjoinable` | the finding has no byte range, or it resolves to no element |
+| `page-scope` | the finding is about the document, not an element you can frame |
+| `zero-area` · `below-the-fold` | the element is invisible, or outside a viewport-only capture |
+| `unknown-scale` | the device pixel ratio could not be derived — a crop would be off-target |
+| `deduplicated` | the same defect on the same element — another occurrence's picture shows it |
+| `capped` | a **distinct** defect went undrawn: 6 per rule, 12 per page, `--evidence-max` per run |
+
+The last two are counted apart on purpose. `deduplicated` costs the reader nothing — the
+defect is on screen, under another occurrence. `capped` is a real gap, and it is the only one
+a setting can close.
+
+A finding raised on SOURCE is in neither column: it never had pixels, so it is not an
+occurrence that failed to be illustrated, and a repository audited from source alone gets no
+notice at all rather than one line per finding.
+
+An occurrence with no picture must never read as an occurrence with no defect, so the sheet
+says how many were not illustrated and why. So does the combined document, the HTML sheets and
+the composite — every surface that can show a crop can say what it did not show.
+
+Without `--evidence` the Markdown is **byte-identical** to what it was. The crop bullet carries
+no `[ ]`, so `verify` builds the same worklist with or without it — indentation alone would not
+be enough, since `AUDITOR_OCCURRENCE` is anchored `^\s*-\s\[ \]` and tolerates leading space.
+
+### The same, as a page (`--html`)
+
+`--html` writes `index.html` and one `page-<id>.html` beside the Markdown they mirror.
+Self-contained: no script, no external asset, nothing pointing outside the output directory.
+
+**The printable single file comes from `report --html`, not from here.** One composite per
+artifact: emitting one from both commands would put a second copy of every inlined crop into
+the same upload, so `pages --html` deliberately writes none.
+
+```sh
+node scripts/ultra11y.mjs report --in audits/audit-latest.json --html --evidence --out audits
+```
+
+See `references/ci.md` for the artifact layout and the inline-size budget.
+
 ## Holding an external audit against the grid
 
 A human auditor's verdict is evidence, not a measurement this engine can redo. `import` reads one