@ponchia/ui 0.5.0 → 0.6.3

package/docs/annotations.md

@@ -77,7 +77,15 @@ offset, matching d3-annotation's mental model.
 
 The visible note text should also be represented in the figure caption,
 `<desc>`, fallback table, or surrounding prose when the figure is complex.
-Use `aria-hidden="true"` only for decorative annotations.
+
+Match the accessibility treatment to the annotation's job, in both directions:
+a **data** annotation (a peak, a threshold, a watched region — it says something
+the reader needs) must stay readable, so represent its text as above and do
+**not** `aria-hidden` it; a purely **decorative** mark (a cover flourish, a
+margin doodle that carries no data) should be `aria-hidden="true"` and
+`focusable="false"` on the whole SVG so a screen reader skips the decoration.
+The one thing to avoid is the middle: a meaningful callout hidden from assistive
+tech, or decoration announced as if it were data.
 
 ## Variants and motion
 
@@ -132,7 +140,7 @@ selections, DOM nodes, or frameworks.
 | --- | --- |
 | `annotationTransform({ x, y })` | Group transform for the subject anchor. |
 | `noteTransform({ dx, dy, align, valign, width, height })` | Note transform from the subject anchor, with optional alignment. |
-| `notePlacement({ x, y, width, height, bounds, preferred })` | Bounded note offset, alignment and transform for one annotation. |
+| `notePlacement({ x, y, width, height, bounds, preferred, inset })` | Bounded note offset, alignment and transform for one annotation. `inset` reserves an extra margin (e.g. the title stroke-halo, ~3) so a placement that "fits" doesn't clip. |
 | `declutterLabels(items, { gap, min, max })` | Adjusted centres for `items` (`[{ pos, size }]`) so labels don't overlap along one axis (order-preserving). |
 | `directLabels(items, { axis, cross, gap, min, max, shape })` | Decluttered label points **and** a leader path per item: `[{ x, y, anchor, key, d }]`. |
 | `circleSubjectPath({ radius })` | Circle subject path. |
@@ -147,10 +155,10 @@ selections, DOM nodes, or frameworks.
 | `timelineEventPath({ size, direction })` | Event pin marker path. |
 | `evidenceMarkerPath({ x, y, width, height, padding })` | Centered square/rect evidence marker path. |
 | `connectorLine({ dx, dy, subject })` | Straight connector, trimmed against circle/rect subjects. |
-| `connectorElbow({ dx, dy, subject })` | D3-like dogleg connector. |
+| `connectorElbow({ dx, dy, subject, mid })` | Right-angle dogleg connector (H/V/H); `mid` (0..1, default 0.5) sets the turn position along the dominant axis. |
 | `connectorCurve({ dx, dy, subject })` | Deterministic cubic connector. |
 | `connectorEndDot({ x, y, radius })` | Dot marker path. |
-| `connectorEndArrow({ x1, y1, x2, y2, size })` | Arrow marker path. |
+| `connectorEndArrow({ x1, y1, x2, y2, size, spread })` | Arrow marker path. `x1,y1`→`x2,y2` sets the direction (the head sits at `x2,y2`); `spread` is the half-angle (default 0.32 ≈ a crisp 37° head). |
 | `annotationParts(options)` | Convenience object with `transform`, `subject`, `connector`, and `note`. |
 
 `declutterLabels` is a deliberately small, deterministic **1-D** declutter for
@@ -193,6 +201,119 @@ back to another side or a clamped note transform. It is not a collision solver
 for a whole chart. For dense annotation sets, pre-compute positions or author a
 mobile-specific SVG.
 
+### Using the helpers in a static, no-JS report
+
+The [report layer](./reporting.md) is static and ships no behavior JS, but these
+helpers are JS — so in a hand- or LLM-authored report you can't call them at
+render time. Bridge the gap by running them **once, at author/build time**, and
+pasting the returned strings straight into the SVG. The output is deterministic
+(path numbers are rounded to three decimals), so the strings are stable and
+diff-friendly.
+
+```js
+// author-time only — copy the logged strings into the static HTML
+import { circleSubjectPath, connectorLine } from '@ponchia/ui/annotations';
+
+circleSubjectPath({ radius: 15 });
+// "M0,-15A15,15 0 1 1 0,15A15,15 0 1 1 0,-15Z"
+connectorLine({ dx: 78, dy: -38, subject: { type: 'circle', radius: 15, radiusPadding: 0 } });
+// "M13.485,-6.57L78,-38"
+```
+
+The static markup then carries only the resolved strings — no runtime, no
+import:
+
+```html
+<g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(34, 58)">
+  <path class="ui-annotation__subject" d="M0,-15A15,15 0 1 1 0,15A15,15 0 1 1 0,-15Z" />
+  <path class="ui-annotation__connector" d="M13.485,-6.57L78,-38" />
+  <g class="ui-annotation__note" transform="translate(78, -38)">…</g>
+</g>
+```
+
+The same author-time-copy idea covers foreign-renderer theme literals: a
+`file://` report can't `import` the Vega/Mermaid/D2 theme helpers either, so
+`npm run emit:theme <vega|mermaid|d2> <light|dark>` prints the resolved object to
+paste inline, and `npm run emit:theme:check <file>` re-checks a pasted block
+against current tokens. See [vega.md](./vega.md#from-a-cdn-no-bundler).
+
+## Using annotations off-chart
+
+Annotations are not only for charts. Two report uses worth calling out:
+
+- **A decorative margin mark.** A small `ui-annotation` group — a circled point
+  with a short note — adds a hand-annotated feel to a report cover or section
+  opener. It carries no data, so mark the whole SVG `aria-hidden="true"` and
+  `focusable="false"`: a screen reader should not read decoration.
+
+```html
+<svg width="440" height="92" viewBox="0 0 440 92" aria-hidden="true" focusable="false">
+  <g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(34, 58)">
+    <path class="ui-annotation__subject" d="M0,-15A15,15 0 1 1 0,15A15,15 0 1 1 0,-15Z" />
+    <circle r="3.5" fill="var(--accent)" />
+    <path class="ui-annotation__connector" d="M13.485,-6.57L78,-38" />
+    <g class="ui-annotation__note" transform="translate(78, -38)">
+      <path class="ui-annotation__note-line" d="M0,0H188" />
+      <text class="ui-annotation__title" y="-8">You are here</text>
+      <text class="ui-annotation__label" y="12">a short, terse label</text>
+    </g>
+  </g>
+</svg>
+```
+
+- **A data note that sits off the plot area, statically (no JS).** When the
+  callout carries a *finding* — a threshold, a labelled event — rather than
+  decoration, it must **not** be `aria-hidden`; instead mirror its text in the
+  figure's `<desc>` and the fallback table so the data reaches every reader. The
+  JS `notePlacement()` helper computes this offset for you, but for a frozen
+  `file://`/print-bound report you place it by hand: reserve a band at the top of
+  the `viewBox` for the note (don't draw bars into it), keep the subject (the
+  rule/point) on the plot, and translate the `__note` group **up, above the
+  plot**, so the connector points off the plotting area. Author the `viewBox` near
+  the rendered pixel size to keep text near 1× (see the user-unit trap below):
+
+```html
+<svg viewBox="0 0 360 180" role="img" aria-labelledby="fig-t fig-d" style="max-inline-size: 540px; width: 100%">
+  <title id="fig-t">Write success rate over the incident day</title>
+  <!-- The note text is repeated here so it is not JS- or sight-only. -->
+  <desc id="fig-d">…dashed line marks the 99.9% SLO floor; the off-plot callout reads "SLO floor 99.9% — below floor 41 min".</desc>
+
+  <line x1="36" y1="150" x2="336" y2="150" stroke="var(--line)" /><!-- axis -->
+  <!-- bars drawn only below y≈40, leaving the top band free for the note -->
+
+  <!-- subject rule ON the plot; note translated UP, off the plotting area -->
+  <g class="ui-annotation ui-annotation--threshold ui-annotation--danger" transform="translate(0, 44)">
+    <path class="ui-annotation__subject" d="M36,0L336,0" stroke-dasharray="4 4" />
+    <path class="ui-annotation__connector" d="M180,0L150,-30" />
+    <g class="ui-annotation__note" transform="translate(40, -34)">
+      <path class="ui-annotation__note-line" d="M0,0H150" />
+      <text class="ui-annotation__title" y="-8">SLO floor 99.9%</text>
+      <text class="ui-annotation__label" y="12">Below floor 41 min</text>
+    </g>
+  </g>
+</svg>
+```
+
+- **Bracketing a passage of prose belongs to marks, not here.** To bracket a
+  sentence or paragraph in running text, use `.ui-bracket-note` from the
+  [marks layer](./marks.md) — it is the prose analogue of
+  `ui-annotation--bracket`. SVG annotations are for SVG figures.
+
+## Sizing: the user-unit trap
+
+Annotation text (`__title`, `__label`) is sized in **SVG user units**, so it
+scales with the figure. A 360-unit-wide chart stretched across a full report
+column is scaled roughly 2.5–3×, and the callout text scales with it — long
+notes turn huge and overflow the `viewBox` (SVG text is clipped, not wrapped).
+Two rules keep callouts readable:
+
+- **Keep note text terse** — a title and a few words, like the recipe examples
+  (`Peak`, `Limit`, `80 kB cap`). Push the full sentence into the figure caption,
+  the `<desc>`, or the fallback table.
+- **Constrain the figure width** so the user-unit → pixel scale stays near
+  1–1.5×: set a `max-inline-size` on the SVG instead of letting it stretch to the
+  whole column, or author the `viewBox` at roughly the rendered pixel size.
+
 ## Density and responsive rules
 
 Annotations are strongest when they explain the few things a reader would miss.
@@ -294,8 +415,8 @@ stable references, threshold annotations for limits, circle/rect subjects for
 specific data, and badge markers for compact index points.
 
 ```html
-<figure class="ui-report__figure ui-chart ui-print-exact" role="group" aria-labelledby="annotated-chart">
-  <figcaption id="annotated-chart" class="ui-chart__caption">
+<figure class="ui-report__figure ui-print-exact" role="group" aria-labelledby="annotated-chart">
+  <figcaption id="annotated-chart" class="ui-report__caption">
     Fig 2 - Weekly throughput, annotated at the peak
   </figcaption>
   <svg viewBox="0 0 360 160" role="img" aria-labelledby="throughput-title throughput-desc">
@@ -328,14 +449,12 @@ specific data, and badge markers for compact index points.
       </g>
     </g>
   </svg>
-  <div class="ui-chart__fallback">
-    <div class="ui-table-wrap">
-      <table class="ui-table ui-table--dense">
-        <caption>Annotated chart source data</caption>
-        <thead><tr><th>Week</th><th class="is-num">Hours</th></tr></thead>
-        <tbody><tr><td>Week 4</td><td class="is-num">18</td></tr></tbody>
-      </table>
-    </div>
+  <div class="ui-table-wrap">
+    <table class="ui-table ui-table--dense">
+      <caption>Annotated chart source data</caption>
+      <thead><tr><th>Week</th><th class="is-num">Hours</th></tr></thead>
+      <tbody><tr><td>Week 4</td><td class="is-num">18</td></tr></tbody>
+    </table>
   </div>
 </figure>
 ```

package/docs/architecture.md

@@ -61,7 +61,7 @@ on top of the CSS, none of which require a framework commitment**:
   not in three places (the two CSS dark blocks are now identical by
   construction), resolving the duplication ADR-0003 flagged. The CSS-only
   presets (density / contrast / OLED) stay hand-authored below a marker and are
-  preserved across regeneration. `scripts/check-tokens.mjs` fails CI if
+  preserved across regeneration. `scripts/check-fresh.mjs` fails CI if
   `css/tokens.css` drifts from the model.
 - **classes/** — `cls` is the flat registry; recipes only emit from it;
   `scripts/check-classes.mjs` enforces a bidirectional match with the
@@ -79,6 +79,51 @@ on top of the CSS, none of which require a framework commitment**:
 - **react/** / **solid/** / **qwik/** — optional lifecycle adapters over `behaviors/`.
   They do not define markup, own state, or fork behavior logic; they only run
   the vanilla initializers on mount and cleanup on unmount/dispose.
+- **`css/analytical.css` — the analytical roll-up.** This convenience file
+  `@import`s exactly **seven** analytical-figure leaves: `annotations`,
+  `legend`, `marks`, `connectors`, `spotlight`, `crosshair`, and `selection`.
+  The adjacent opt-in leaves — `sources`, `state`, `generated`, `workbench`,
+  and `command` — are report/tooling/trust surfaces that are intentionally
+  **not** part of the analytical roll-up and must be imported individually.
+  Importing `analytical.css` does not pull in any of those five.
+- **Root export (`.`) is CSS-only.** `exports["."]` resolves to the CSS
+  bundle (`dist/bronto.css`). It is a CSS side-effect import for CSS-aware
+  bundlers (`@import '@ponchia/ui'` in CSS, or a side-effect
+  `import '@ponchia/ui'` in Vite/Astro/SvelteKit). There is no runtime JS at
+  the package root — Node/runtime JS imports of `.` are not supported. All JS
+  entrypoints are explicit subpaths (`/behaviors`, `/classes`, `/tokens`,
+  `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, `/charts`). This is a
+  permanent, intentional contract.
+
+## Repository layout
+
+The repo root mixes five kinds of directory that look alike but follow very
+different rules. Two distinctions matter most: several are **path-frozen
+published subpaths** — the directory name _is_ the public import specifier
+(`@ponchia/ui/react` resolves to `./react/`), so they cannot be moved or
+renamed — and several are **generated** and must never be hand-edited (a
+generator overwrites them and a drift gate fails CI).
+
+| Path | Kind | Edit here? | Notes |
+| --- | --- | --- | --- |
+| `css/` | source | yes | The framework. Hand-authored `@layer bronto` CSS. (`css/tokens.css` palette blocks and `css/generated.css` are generated — see below.) |
+| `tokens/index.js` | source | yes | The single source of truth for token **values** (`cssVars`). |
+| `classes/index.js`, `behaviors/`, `annotations/`, `connectors/`, `react/`, `solid/`, `qwik/`, `glyphs/`, `shiki/` | source · published-subpath (path-frozen) | yes — but **do not move** | Authored ESM shipped as-is; the dir name is the public import path. The `.d.ts` beside them are generated/drift-checked: `connectors`/`annotations`/`react`/`solid`/`qwik`/`behaviors` are emitted from JSDoc by `tsc` (`npm run dts:emit`), `classes`/`tokens`/`glyphs` from the runtime. No leaf `.d.ts` is hand-maintained. |
+| `dist/` | generated | no | Build of `css/` (`npm run dist:build`); byte-checked by `check:dist`. |
+| `tokens/index.json`, `tokens/resolved.json`, `tokens/tokens.dtcg.json`, `tokens/charts.json`, `classes/index.d.ts`, `tokens/index.d.ts`, `tokens/{skins,charts}.d.ts`, `glyphs/glyphs.d.ts`, `classes/vscode.css-custom-data.json`, `docs/reference.md` | generated | no | Committed build artifacts; regenerate with `npm run prepack`, never hand-edit. Drift-checked in `npm run check`. |
+| `fonts/` | vendored | — | The Doto webfont (woff2) + its OFL license. |
+| `scripts/` | tooling | yes | `gen-*` regenerate artifacts, `check-*` are the drift/contract gates wired into `npm run check`, plus `build-dist`, `serve`, `size-report`. |
+| `docs/` | source (mostly) | yes | Hand-authored docs + ADRs; the curated subset in `package.json` `files` ships in the tarball. `docs/reference.md` is generated. |
+| `demo/`, `test/`, `examples/` | fixtures | yes | The self-driving demo/showcase, the unit + Playwright e2e suite, and consumer example apps built against the packed tarball. |
+| `.github/`, `*.config.mjs`, `.prettierrc`, `.stylelintrc.json`, `tsconfig.json`, `.editorconfig` | config | yes | CI workflows and tool config. |
+| `package.json`, `llms.txt`, `CHANGELOG.md`, `MIGRATIONS.json`, `README.md`, `CONTRIBUTING.md`, `ROADMAP.md`, `LICENSE` | meta | yes | Manifest, the agent entrypoint, the curated changelog, the rename map, and project docs. |
+
+The **path-frozen** dirs are the cost of zero-build, path-stable publishing:
+`files` map 1:1 to published paths and the consumer's own bundler tree-shakes
+the ESM, so there is no `src/` indirection (and no JS bundler — see the
+distribution decision below). **Generated** files are regenerated from their
+source and policed by a drift gate — edit the source, run the generator, commit
+the result.
 
 ## Drift control
 
@@ -89,12 +134,10 @@ gating" below), so a version that fails any invariant never reaches npm.
 | Invariant                                       | Enforced by         |
 | ----------------------------------------------- | ------------------- |
 | exports / import graph / `files` consistent     | `check-exports.mjs` |
-| `tokens.css` ⇄ `tokens/index.js` ⇄ `.json`      | `check-tokens.mjs`  |
+| pure generated mirrors fresh — `tokens.css`/`index.json`, `dtcg.json`, `resolved.json`, `classes`/`tokens` `.d.ts`, `reference.md`, vscode data — each byte-equal to its generator (registry: `scripts/lib/artifacts.mjs`) | `check-fresh.mjs` |
 | `classes` `cls` ⇄ `.ui-*` selectors             | `check-classes.mjs` |
-| `classes`/`tokens` `.d.ts` ⇄ JS runtime (exact) | `check-dts.mjs`     |
-| `annotations`/`connectors` hand-written `.d.ts` ⇄ exports | `check-helpers-dts.mjs` |
+| `connectors`/`annotations`/`react`/`solid`/`qwik`/`behaviors` `.d.ts` (+ maps) == fresh `tsc` emit of their JSDoc | `check-dts-emit.mjs` |
 | legend swatch colours ⊆ `charts.js` · opt-in   | `check-legend.mjs`  |
-| `tokens.dtcg.json` ⇄ token model                | `check-dtcg.mjs`    |
 | color tokens tiered · no raw chromatic color in components | `check-color-policy.mjs` |
 | `css/skins.css` ⇄ `tokens/skins.js` · colorways opt-in | `check-skins.mjs` |
 | every shipped colorway accent meets its WCAG floor | `check-contrast.mjs` |
@@ -116,7 +159,7 @@ payload contract, raised only intentionally with a CHANGELOG note.
 `test/types.test-d.ts`, whose `@ts-expect-error`s would fail to compile
 if the generated literal `cls`/token types stopped rejecting typos —
 so the *value* of the generated `.d.ts` is itself gated, not just their
-freshness (`check-dts`).
+freshness (`check-fresh`).
 
 ## Release gating
 

package/docs/bullet.md

@@ -0,0 +1,78 @@
+# Bullet
+
+`@ponchia/ui/css/bullet.css` is an opt-in **bullet graph** — Stephen Few's
+compact "is this measure inside its qualitative budget, and how does it compare
+to target?" figure. A thin measure bar sits over 2–3 grayscale qualitative range
+bands, with a perpendicular target tick. It is the canonical SLO / error-budget
+figure that `ui-meter` (a single label|bar|value reading) structurally cannot
+encode — a bullet carries the bands and the target too. Few designed it grayscale
+on purpose, which is exactly the Nothing palette.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/bullet.css';
+```
+
+## How it behaves
+
+- **Bands** are a grayscale gradient with hard stops at `--band-lo` and
+  `--band-hi` — the qualitative ranges (e.g. poor / ok / good).
+- **The measure** is a thin dark bar whose length is the normalised reading `--v`.
+- **The target** is a full-height tick at `--t`; shape (not colour) distinguishes
+  it from the measure, per Few's grayscale rule.
+
+## Wiring — the host normalises every value to 0..1
+
+Identical contract to `ui-spark`: Bronto paints geometry, the host does the
+arithmetic. Set the normalised values as custom properties; the figure refuses
+raw values and scale computation.
+
+```html
+<figure>
+  <div
+    class="ui-bullet"
+    style="--band-lo: 0.6; --band-hi: 0.85"
+    role="img"
+    aria-label="uptime 99.62%, below the 99.9% target, in the warning band"
+  >
+    <div class="ui-bullet__measure ui-bullet__measure--neg" style="--v: 0.62"></div>
+    <div class="ui-bullet__target" style="--t: 0.9"></div>
+  </div>
+  <figcaption class="ui-bullet__label"><span>Uptime</span><span>99.62%</span></figcaption>
+</figure>
+```
+
+The `.ui-bullet__label` row is optional — use it, a `<figcaption>`, or your own
+caption. Either way the **reading lives in text**, never in colour alone.
+
+## Class reference
+
+| Class                        | Role                                                          |
+| ---------------------------- | ------------------------------------------------------------ |
+| `.ui-bullet`                 | The track + qualitative range bands (`--b1` / `--b2`).       |
+| `.ui-bullet__measure`        | The measure bar; length is `--v` (0..1).                     |
+| `.ui-bullet__measure--accent`| Paint the measure in the rationed accent (emphasis).         |
+| `.ui-bullet__measure--pos`   | Paint the measure in the success tone.                       |
+| `.ui-bullet__measure--neg`   | Paint the measure in the danger tone.                        |
+| `.ui-bullet__target`         | The full-height target tick at `--t` (0..1).                 |
+| `.ui-bullet__label`          | Optional caption row (label + reading, in mono).             |
+
+| Custom property | On                    | Meaning                                                  |
+| --------------- | --------------------- | -------------------------------------------------------- |
+| `--v`           | `.ui-bullet__measure` | **Required.** Normalised measure (0..1).                 |
+| `--t`           | `.ui-bullet__target`  | Normalised target position (0..1); omit to drop the tick.|
+| `--band-lo`     | `.ui-bullet`          | Lower band boundary (0..1, default `0.5`).               |
+| `--band-hi`     | `.ui-bullet`          | Upper band boundary (0..1, default `0.8`, ≥ `--band-lo`).|
+
+## Accessibility & robustness
+
+- A bare bullet is **opaque to assistive tech**, so `.ui-bullet` MUST carry a
+  host-written `role="img"` + `aria-label` that states the reading, the target,
+  and the band — colour is never the only channel (WCAG 1.4.1).
+- Under `forced-colors` the band gradient flattens, so the track gains a border
+  and the marks repaint in the system text colour; the band meaning is carried by
+  the required label.
+- Bands + marks are `print-color-adjust: exact`, so the figure survives the print
+  economy.
+- Relationship to `ui-meter` (report.css): a meter is a labelled progress reading;
+  reach for a bullet when you also need a target and qualitative bands.

package/docs/code.md

@@ -0,0 +1,76 @@
+# Code
+
+`@ponchia/ui/css/code.css` is an opt-in chrome for **fenced code** — the surface
+for code-as-evidence in changelogs, version history, config snippets, and
+generated reports. It paints the frame, an optional line-number gutter, and
+add / remove / highlight line states. Its sibling is [diff.css](diff.md)
+(multi-column line/row diffs); the two share one change vocabulary —
+`--add` / `--remove` (`ui-code__line--remove` ↔ `ui-diff__row--remove`).
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/code.css';
+```
+
+## Boundary — it never parses
+
+Bronto owns the chrome; it does **not** tokenize or highlight syntax. The host
+supplies the coloured token spans — hand-written, or from a real highlighter.
+The shipped [`shiki/nothing.json`](../shiki/nothing.json) theme makes Shiki emit
+spans with bronto token colours, so Shiki output drops straight in. A bronto
+class that tried to parse source would cross the same line that removed the
+chart renderer in 0.6.0.
+
+## Markup
+
+```html
+<figure class="ui-code ui-code--numbered">
+  <figcaption class="ui-code__head">theme.css</figcaption>
+  <pre class="ui-code__body"><code><span class="ui-code__line">.ui-diff {</span>
+<span class="ui-code__line ui-code__line--remove">  font-size: var(--text-sm);</span>
+<span class="ui-code__line ui-code__line--add">  font-size: var(--text-xs);</span>
+<span class="ui-code__line ui-code__line--hl">  line-height: 1.6;</span>
+<span class="ui-code__line">}</span></code></pre>
+</figure>
+```
+
+- `ui-code--numbered` turns on the gutter; it numbers each `.ui-code__line` with
+  a CSS counter (no host bookkeeping).
+- Each token span the host emits lives **inside** `.ui-code__line`; Bronto never
+  touches it.
+- Plain text inside `.ui-code__body` (no `.ui-code__line` wrappers) renders as an
+  unnumbered code block — the line grammar is opt-in.
+
+## Class reference
+
+| Class | Role |
+| --- | --- |
+| `.ui-code` | The `<figure>` frame. |
+| `.ui-code--numbered` | Show the line-number gutter. |
+| `.ui-code__head` | A filename / language bar (use on `<figcaption>`). |
+| `.ui-code__body` | The `<pre>` scroll/wrap region. |
+| `.ui-code__line` | One line — the unit numbered + state-tinted. |
+| `.ui-code__line--add` | Added line (green wash). |
+| `.ui-code__line--remove` | Removed line (red wash). |
+| `.ui-code__line--hl` | Neutral highlight / call-out (accent wash, not a change). |
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.code({ numbered: true });     // "ui-code ui-code--numbered"
+ui.codeLine({ change: 'add' });  // "ui-code__line ui-code__line--add"
+ui.codeLine({ change: 'hl' });   // "ui-code__line ui-code__line--hl"
+ui.codeLine();                   // "ui-code__line"
+```
+
+## Accessibility & robustness
+
+- **Line states never rely on colour.** In forced-colors mode each
+  add/remove/hl line gains an inline-start border, and the tints are forced through
+  `print-color-adjust: exact`.
+- **Long lines wrap** rather than scroll, so the block prints cleanly.
+- **Line numbers** are generated content (`user-select: none`), so copying the
+  block yields clean code with no line numbers.
+- Keep real text in the `<code>`; don't encode meaning only in a tint.