@ponchia/ui 0.4.0 → 0.5.0

package/docs/connectors.md

@@ -0,0 +1,91 @@
+# Connectors (leader lines)
+
+`@ponchia/ui/css/connectors.css` + `@ponchia/ui/connectors` draw a **leader line
+between two DOM elements** — connect a note to a card, a card to a chart point,
+or two related regions. This is the page-coordinate, element-to-element cousin
+of the figure-coordinate [annotations](./annotations.md) layer.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/connectors.css';
+```
+
+Bronto computes the **geometry** (pure functions) and styles the line; the
+optional `initConnectors` behavior draws and keeps it in sync. It owns no
+layout, no scales — just the path between two rects.
+
+## Markup
+
+An `.ui-connector` is an SVG that overlays a **positioned** container. Give it
+the ids of the two elements to connect; `initConnectors` fills in the path.
+
+```html
+<div style="position: relative">
+  <div id="card-a" class="ui-card">…</div>
+  <div id="note-b" class="ui-card">…</div>
+
+  <svg
+    class="ui-connector ui-connector--accent"
+    data-bronto-connector
+    data-from="card-a"
+    data-to="note-b"
+    data-shape="elbow"
+    data-end="arrow"
+    aria-hidden="true"
+  ></svg>
+</div>
+```
+
+```js
+import { initConnectors } from '@ponchia/ui/behaviors';
+const stop = initConnectors(); // redraws on resize/scroll; returns a cleanup
+```
+
+A connector is decorative — mark it `aria-hidden="true"` and make sure the
+relationship it depicts is also clear from the content/DOM order.
+
+| Attribute | Values |
+| --- | --- |
+| `data-from` / `data-to` | ids of the elements to connect (required). |
+| `data-shape` | `straight` (default), `elbow`, `curve`. |
+| `data-from-side` / `data-to-side` | `top`/`right`/`bottom`/`left`/`center`. Omit a side to auto-pick it (set neither for fully automatic facing edges). |
+| `data-end` | `arrow` (default), `dot`, `none`. |
+
+Tones: `ui-connector--accent` / `--muted` / `--success` / `--warning` /
+`--danger` / `--info` (monochrome by default). `ui-connector--dashed` for a
+dashed line; `ui-connector--draw` strokes it in once (reduced-motion-safe).
+`ui.connector({ tone, dashed, motion })` builds the class string.
+
+## Geometry helpers (no DOM)
+
+For SSR, canvas, or your own renderer, the pure helpers return SVG strings /
+coordinates and never touch the DOM:
+
+```js
+import { connectRects, arrowHead } from '@ponchia/ui/connectors';
+
+const { d, to, angle } = connectRects({
+  fromRect: { x: 0, y: 0, width: 80, height: 32 },
+  toRect: { x: 220, y: 120, width: 80, height: 32 },
+  shape: 'curve',
+});
+const head = arrowHead(to, angle); // place at the endpoint
+```
+
+- `anchorPoint(rect, side)` — a point on a rect's edge.
+- `connectorPath({ from, to, shape, curvature, mid })` — path between two points.
+- `straightPath` / `elbowPath` / `curvePath` — the individual shapes.
+- `connectRects(opts)` → `{ d, from, to, angle }`.
+- `arrowHead(point, angle, size)` / `dotMark(point, radius)` — end markers.
+- `autoSides(fromRect, toRect)` / `angleBetween(from, to)`.
+- `endTangentAngle(from, to, shape)` — the angle the path *arrives* at `to`
+  (chord for `straight`, axis-aligned for `elbow`/`curve`); rotate an end marker
+  by this so it points along the path. `connectRects().angle` already uses it.
+
+## Coordinate model
+
+`initConnectors` measures the from/to elements relative to the connector SVG's
+own box (via `getBoundingClientRect`), so place the SVG as an overlay
+(`position: absolute; inset: 0`, which `.ui-connector` sets) inside a
+`position: relative` container that holds both endpoints. The SVG has no
+`viewBox`, so its user units are CSS pixels.

package/docs/contrast.md

@@ -65,26 +65,26 @@ Overall: **all contractual pairings meet their floor ✅**.
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 18.76:1 | Lc 99 | ✅ pass |
-| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 17.47:1 | Lc 99 | ✅ pass |
-| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 15.55:1 | Lc 98 | ✅ pass |
-| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 12.04:1 | Lc 71 | ✅ pass |
-| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 11.22:1 | Lc 71 | ✅ pass |
-| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 9.98:1 | Lc 70 | ✅ pass |
-| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 5.69:1 | Lc 37 | ✅ pass |
-| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 5.30:1 | Lc 37 | ✅ pass |
-| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.72:1 | Lc 36 | ✅ pass |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.88:1 | Lc 45 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.41:1 | Lc 45 | ✅ pass |
+| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 15.01:1 | Lc 91 | ✅ pass |
+| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 13.65:1 | Lc 90 | ✅ pass |
+| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 12.44:1 | Lc 89 | ✅ pass |
+| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 11.20:1 | Lc 73 | ✅ pass |
+| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 10.19:1 | Lc 72 | ✅ pass |
+| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 9.28:1 | Lc 71 | ✅ pass |
+| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 7.16:1 | Lc 50 | ✅ pass |
+| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 6.52:1 | Lc 49 | ✅ pass |
+| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 5.94:1 | Lc 48 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.14:1 | Lc 45 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 5.58:1 | Lc 44 | ✅ pass |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.95:1 | Lc 43 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.95:1 | Lc 41 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.55:1 | Lc 40 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.95:1 | Lc 41 | ✅ pass |
-| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 8.70:1 | Lc 58 | ✅ pass |
-| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 10.66:1 | Lc 68 | ✅ pass |
-| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 6.00:1 | Lc 43 | ✅ pass |
-| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 8.41:1 | Lc 56 | ✅ pass |
-| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.01:1 | Lc 10 | ℹ️ not gated |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.31:1 | Lc 40 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 4.83:1 | Lc 39 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.31:1 | Lc 40 | ✅ pass |
+| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 7.58:1 | Lc 57 | ✅ pass |
+| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 9.29:1 | Lc 67 | ✅ pass |
+| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 5.23:1 | Lc 42 | ✅ pass |
+| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 7.33:1 | Lc 55 | ✅ pass |
+| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.29:1 | Lc 15 | ℹ️ not gated |
 
 ## Display colorways (skins)
 
@@ -112,12 +112,12 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.97:1 | Lc 75 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 12.08:1 | Lc 75 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 11.57:1 | Lc 75 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 10.52:1 | Lc 74 | ✅ pass |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.88:1 | Lc 72 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 11.88:1 | Lc 70 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.07:1 | Lc 70 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 11.88:1 | Lc 70 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.60:1 | Lc 70 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 9.64:1 | Lc 69 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 10.60:1 | Lc 70 | ✅ pass |
 
 ### E-ink — light
 
@@ -134,12 +134,12 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 13.98:1 | Lc 80 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.02:1 | Lc 79 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.47:1 | Lc 79 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.35:1 | Lc 78 | ✅ pass |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 12.86:1 | Lc 76 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 12.86:1 | Lc 75 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.98:1 | Lc 74 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 12.86:1 | Lc 75 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 11.48:1 | Lc 74 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 10.44:1 | Lc 73 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 11.48:1 | Lc 74 | ✅ pass |
 
 ### Phosphor Green — light
 
@@ -156,12 +156,12 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 14.54:1 | Lc 82 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.55:1 | Lc 82 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.97:1 | Lc 82 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.80:1 | Lc 81 | ✅ pass |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 13.75:1 | Lc 80 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 13.75:1 | Lc 79 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 12.81:1 | Lc 79 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 13.75:1 | Lc 79 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 12.27:1 | Lc 79 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.16:1 | Lc 78 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 12.27:1 | Lc 79 | ✅ pass |
 
 ## Data-viz palette (advisory)
 
@@ -191,14 +191,14 @@ the brand accent.
 
 | Series | Colour | Ratio _(advisory)_ | APCA _(advisory)_ |
 | --- | --- | --- | --- |
-| 1 _(accent)_ | `#ff3b41` | 5.95:1 | Lc 41 |
-| 2 | `#e69f00` | 9.32:1 | Lc 58 |
-| 3 | `#56b4e9` | 9.10:1 | Lc 57 |
-| 4 | `#009e73` | 6.14:1 | Lc 41 |
-| 5 | `#f0e442` | 15.88:1 | Lc 88 |
-| 6 | `#0072b2` | 4.05:1 | Lc 27 |
-| 7 | `#cc79a7` | 6.86:1 | Lc 45 |
-| 8 | `#4d5358` | 2.69:1 | Lc 15 |
+| 1 _(accent)_ | `#ff3b41` | 5.31:1 | Lc 40 |
+| 2 | `#e69f00` | 8.32:1 | Lc 58 |
+| 3 | `#56b4e9` | 8.12:1 | Lc 56 |
+| 4 | `#009e73` | 5.48:1 | Lc 40 |
+| 5 | `#f0e442` | 14.17:1 | Lc 87 |
+| 6 | `#0072b2` | 3.61:1 | Lc 26 |
+| 7 | `#cc79a7` | 6.12:1 | Lc 44 |
+| 8 | `#4d5358` | 2.40:1 | Lc 14 |
 
 ## Scope & caveats
 

package/docs/crosshair.md

@@ -0,0 +1,63 @@
+# Crosshair & readout
+
+`@ponchia/ui/css/crosshair.css` is an opt-in **ruler + readout** for reading a
+value off a plot: pointer-tracking crosshair rules, axis value badges, and a
+pinned readout chip.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/crosshair.css';
+```
+
+Bronto draws the rules and (via `initCrosshair`) tracks the pointer — it reports
+**where** the pointer is, as pixels and 0–1 fractions. It does **not** find the
+nearest data point or map pixels to data values; that needs your scales. So this
+is the *visual + pointer* layer, not a chart engine.
+
+## Markup
+
+The plot is `[data-bronto-crosshair]` (a `position: relative` box); it contains a
+`.ui-crosshair` overlay with the rule(s) you want.
+
+```html
+<figure data-bronto-crosshair style="position: relative">
+  <!-- your chart / image / canvas -->
+  <div class="ui-crosshair" aria-hidden="true">
+    <div class="ui-crosshair__line ui-crosshair__line--x"></div>
+    <div class="ui-crosshair__line ui-crosshair__line--y"></div>
+    <div class="ui-readout" id="readout"></div>
+  </div>
+</figure>
+```
+
+```js
+import { initCrosshair } from '@ponchia/ui/behaviors';
+const stop = initCrosshair(); // returns a cleanup
+document.querySelector('[data-bronto-crosshair]').addEventListener(
+  'bronto:crosshair:move',
+  (e) => {
+    const { x, y, fx, fy } = e.detail; // px + 0..1 fractions
+    // YOU map the fraction to a data value with your scale:
+    readout.textContent = `${(fx * 100).toFixed(0)}%`;
+  },
+);
+```
+
+| Class | Role |
+| --- | --- |
+| `ui-crosshair` | The overlay. Hidden until `.is-active` (set on the first pointer move over the plot). |
+| `ui-crosshair__line` + `--x` / `--y` | Vertical / horizontal rule, positioned by `--crosshair-x` / `--crosshair-y`. |
+| `ui-crosshair__badge` | An axis value chip (you set its text + edge). |
+| `ui-readout` | A pinned readout chip; follows the crosshair point. |
+
+`ui-crosshair--muted` is a subtler neutral crosshair. `ui.crosshair({ muted })`
+builds the class string. Include only the lines you need (just `--x` for a
+vertical scrubber, etc.).
+
+## Events
+
+- `bronto:crosshair:move` — `{ x, y, fx, fy }` (px within the plot + fractions).
+- `bronto:crosshair:leave` — pointer left the plot.
+
+The crosshair is decorative (`aria-hidden`); expose the underlying values to
+assistive tech through a data table or text, not the rules.

package/docs/generated.md

@@ -0,0 +1,91 @@
+# Generated content & AI trust
+
+`@ponchia/ui/css/generated.css` is an opt-in layer of **trust surfaces for AI /
+system-generated content**. Bronto is not a chat framework — it does not ship
+chat bubbles. It ships the surfaces that make generated content legible and
+accountable: a marked region, an origin label, and quiet collapsible reasoning
+and tool-call logs. It pairs with the [source & provenance layer](./sources.md).
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/generated.css';
+```
+
+Bronto styles the disclosure, origin, and trace surfaces. The host owns model
+metadata, reasoning-visibility policy, tool execution, redaction, and safety.
+Prefer evidence and source links over decorative "AI sparkle" styling. Not in
+the core bundle.
+
+## Generated region — `.ui-generated`
+
+Wraps a block of machine-authored content with a quiet accent edge and an
+optional origin `__label`.
+
+```html
+<section class="ui-generated">
+  <p class="ui-generated__label">Model output</p>
+  <p>The migration cut p95 latency by 38% in the first hour.</p>
+</section>
+```
+
+## Origin label — `.ui-origin-label`
+
+A small tag for "AI assisted", "model output", "tool output", or "human
+reviewed". `--ai` accent-tints it for model-generated origin; the default is a
+neutral tag. The words carry the meaning — the tint is reinforcement.
+
+```html
+<span class="ui-origin-label ui-origin-label--ai">AI generated</span>
+<span class="ui-origin-label">Human reviewed</span>
+```
+
+## Reasoning — `.ui-reasoning`
+
+A quiet, collapsible "how this was produced" block on a native `<details>` (zero
+JS). Keep it closed by default; the host decides what reasoning is safe to show.
+
+```html
+<details class="ui-reasoning">
+  <summary>Reasoning</summary>
+  <p class="ui-reasoning__body">Compared the Q2 and Q3 latency tables, then…</p>
+</details>
+```
+
+## Tool log — `.ui-tool-log` / `.ui-tool-call`
+
+A document-grade record of tool invocations. Each `.ui-tool-call` is a
+collapsible `<details>`: a `__name`, an optional `__status` (put a `.ui-dot` or
+text), and a `__body` with the arguments or output.
+
+```html
+<div class="ui-tool-log">
+  <details class="ui-tool-call">
+    <summary>
+      <span class="ui-tool-call__name">search_docs(query)</span>
+      <span class="ui-tool-call__status"><span class="ui-dot ui-dot--live"></span> ok</span>
+    </summary>
+    <pre class="ui-tool-call__body">{ "query": "p95 latency", "hits": 3 }</pre>
+  </details>
+</div>
+```
+
+## Recipe
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.originLabel({ ai: true }); // "ui-origin-label ui-origin-label--ai"
+```
+
+The other parts are class-only (`cls.generated`, `cls.toolCall`, …) — they have
+no options, so apply the class directly.
+
+## Accessibility
+
+- The reasoning and tool-call disclosures are native `<details>` — keyboard- and
+  screen-reader-accessible with no JS.
+- An origin label must read as text ("AI generated"); the accent tint is not the
+  only signal.
+- A confidence / verdict widget is intentionally **not** shipped: don't
+  fabricate precision. Add a confidence surface only when the product has a real
+  signal to show.

package/docs/legends.md

@@ -0,0 +1,168 @@
+# Legends & data keys
+
+`@ponchia/ui/css/legend.css` is an opt-in layer of **data keys** for charts,
+reports, and analytical figures. A legend maps a visual encoding (colour, a
+pattern, a shape, a gradient) to its meaning. It reads the same Tier-4
+`--chart-*` tokens the [data-viz palette](./reference.md) ships, so a key never
+drifts from the series it describes.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/dataviz.css';
+@import '@ponchia/ui/css/legend.css';
+```
+
+Bronto **paints and positions** the key; it owns no scales, no data→pixel
+mapping, and no series state. Pair it with Bronto's own `.ui-chart` bars, an
+SVG/canvas figure, or any external chart engine — the host owns the chart.
+
+## What it is not
+
+- Not a chart engine. It does not compute tick positions, "nice" numbers,
+  bin thresholds, or bubble radii — you supply the tick/range **text**; the
+  CSS positions the slots you give it.
+- Not a colour source. Swatch colour always comes from a `--chart-*` token
+  (enforced by `check:legend`), never a hand-rolled hex.
+
+## Accessibility: colour is never the only channel
+
+A legend that distinguishes series by **colour alone** fails
+[WCAG 1.4.1 Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html).
+In a legend, the **text label** is the required non-colour channel — every
+entry carries its name, so the meaning survives even if colour is lost
+(`forced-colors`, monochrome print, colour-vision deficiency). Where the chart
+*mark itself* is colour-only (a bare area or line), also pair the swatch with
+its `--chart-pattern-*` so the figure — not just the legend — stays readable.
+
+Recommended structure: wrap the figure and its key in a `<figure>` with a
+`<figcaption>`, and give the legend its own group label.
+
+```html
+<figure role="group" aria-labelledby="fig-1-title">
+  <figcaption id="fig-1-title">Fig 1 — Weekly focus split</figcaption>
+
+  <!-- … the chart … -->
+
+  <ul class="ui-legend" aria-label="Series">
+    <li class="ui-legend__item">
+      <span
+        class="ui-legend__swatch"
+        style="--chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
+        aria-hidden="true"
+      ></span>
+      <span class="ui-legend__label">Research</span>
+    </li>
+    <li class="ui-legend__item">
+      <span class="ui-legend__swatch ui-legend__swatch--2" aria-hidden="true"></span>
+      <span class="ui-legend__label">Delivery</span>
+    </li>
+  </ul>
+</figure>
+```
+
+The swatch is decorative (`aria-hidden="true"`) — the meaning is the label
+text. Set its colour either inline (`--chart-color`) to mirror exactly what the
+chart mark uses, or with a `--N` index helper for the categorical palette.
+
+## Parts
+
+| Class | Role |
+| --- | --- |
+| `ui-legend` | The container (a wrapping inline row by default). |
+| `ui-legend__title` | Optional heading for the key. |
+| `ui-legend__item` | One entry — swatch + label (+ value). |
+| `ui-legend__swatch` | The colour/pattern chip. |
+| `ui-legend__symbol` | A glyph/shape chip (fill an `.ui-icon` mask). |
+| `ui-legend__label` | The series name (the non-colour channel). |
+| `ui-legend__value` | Optional trailing value/range. |
+| `ui-legend__caption` | Optional footnote (units, source). |
+| `ui-legend__track` | The gradient bar (continuous keys). |
+| `ui-legend__ticks` / `ui-legend__tick` | Tick labels under the track. |
+
+### Swatch colour
+
+| Approach | Use |
+| --- | --- |
+| `style="--chart-color: var(--chart-3)"` | Mirror any token, any order; add `--chart-pattern` to match a patterned mark. |
+| `class="… ui-legend__swatch--3"` | Categorical palette series 1–8 — sets `--chart-3` for you. |
+
+`ui-legend__swatch--circle` and `ui-legend__swatch--line` change the chip shape
+(dot series, line series).
+
+## Variants
+
+| Modifier | Effect |
+| --- | --- |
+| `ui-legend--vertical` | Stack entries instead of the wrapping row. |
+| `ui-legend--compact` | Denser type and gaps. |
+| `ui-legend--with-values` | Align a trailing `__value` column across rows. |
+| `ui-legend--gradient` | Continuous colour ramp (`__track` + `__ticks`). |
+| `ui-legend--diverging` | Use the 7-stop diverging ramp (with `--gradient`). |
+| `ui-legend--threshold` | Binned `swatch │ range-label` grid. |
+| `ui-legend--interactive` | Entries are toggle controls (see below). |
+
+The recipe mirrors this surface:
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.legend({ type: 'gradient', diverging: true });
+// "ui-legend ui-legend--gradient ui-legend--diverging"
+ui.legendSwatch({ series: 3, shape: 'circle' });
+// "ui-legend__swatch ui-legend__swatch--3 ui-legend__swatch--circle"
+```
+
+### Continuous ramp
+
+Supply the min/mid/max tick **text**; the track interpolates the sequential
+ramp in OKLCH (`--diverging` swaps in the diverging ramp around its neutral
+centre).
+
+```html
+<div class="ui-legend ui-legend--gradient" role="group" aria-label="Density">
+  <span class="ui-legend__track" aria-hidden="true"></span>
+  <span class="ui-legend__ticks">
+    <span class="ui-legend__tick">0</span>
+    <span class="ui-legend__tick">50</span>
+    <span class="ui-legend__tick">100</span>
+  </span>
+</div>
+```
+
+## Interactive legends (optional)
+
+An interactive legend toggles a series on or off. Bronto ships the **control
+surface** only; the **host owns the data**. The split is deliberate (it keeps
+the legend out of chart-engine territory):
+
+- **Bronto:** each entry is a `<button aria-pressed>`. The optional
+  `initLegend` behavior flips `aria-pressed`, toggles `.is-inactive`, and
+  dispatches `bronto:legend:toggle` with `{ detail: { series, active } }`.
+- **You:** listen for the event, hide/show your own series, and announce the
+  change through an `aria-live` region you own.
+
+```html
+<ul class="ui-legend ui-legend--interactive" data-bronto-legend aria-label="Series">
+  <li>
+    <button type="button" class="ui-legend__item" aria-pressed="true" data-series="research">
+      <span class="ui-legend__swatch ui-legend__swatch--1" aria-hidden="true"></span>
+      <span class="ui-legend__label">Research</span>
+    </button>
+  </li>
+</ul>
+```
+
+```js
+import { initLegend } from '@ponchia/ui/behaviors';
+const stop = initLegend(); // returns a cleanup fn
+document.addEventListener('bronto:legend:toggle', (e) => {
+  const { series, active } = e.detail;
+  // hide/show your series, then announce it in your own aria-live region
+});
+```
+
+Convention: `aria-pressed="true"` means the series is **shown** (the default).
+The entry's label never changes on toggle — only `aria-pressed` and
+`.is-inactive` flip, so a screen reader reads a stable name with a clear
+pressed state. React/Solid/Qwik consumers can use `useLegend()` instead of
+calling `initLegend` directly.

package/docs/marks.md

@@ -0,0 +1,86 @@
+# Text marks & evidence
+
+`@ponchia/ui/css/marks.css` is an opt-in layer of **evidence and emphasis marks
+for running text** — the prose counterpart to the [SVG annotations](./annotations.md)
+layer. Annotations call out a figure; marks call out a sentence. The look is
+sober and report-grade (good for docs, audits, and generated/LLM reports), not
+a hand-drawn highlighter.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/marks.css';
+```
+
+Monochrome by default — the rationed accent is opt-in via `--accent`, and the
+status tones are only for status-bearing emphasis.
+
+## Inline marks — `.ui-mark`
+
+Put `.ui-mark` on a `<mark>` so the emphasis is semantic, not just visual.
+
+```html
+<p>
+  The migration <mark class="ui-mark ui-mark--accent">cut p95 latency by 38%</mark>,
+  but <mark class="ui-mark ui-mark--danger ui-mark--underline">error rate doubled</mark>
+  in the first hour.
+</p>
+```
+
+| Style | Effect |
+| --- | --- |
+| _(default)_ | Highlighter fill. |
+| `ui-mark--underline` | Coloured underline (no fill). |
+| `ui-mark--box` | Outlined box. |
+| `ui-mark--strike` | Strikethrough (removed/superseded text). |
+
+| Tone | Use |
+| --- | --- |
+| _(default)_ | Neutral ink emphasis (monochrome). |
+| `ui-mark--accent` | The rationed accent — "this is the proof". |
+| `ui-mark--success` / `--warning` / `--danger` / `--info` | Status-bearing emphasis only. |
+| `ui-mark--muted` | De-emphasis. |
+
+`ui-mark--draw` sweeps the highlight in once on load; it respects
+`prefers-reduced-motion` (reduced motion shows the resting full highlight). It
+applies to the highlight fill, so pair it with the default (no style modifier).
+
+## Passage bracket — `.ui-bracket-note`
+
+Brackets a whole block and optionally labels it — the prose analogue of
+`ui-annotation--bracket`. Useful for "this paragraph is the evidence/caveat".
+
+```html
+<blockquote class="ui-bracket-note ui-bracket-note--accent">
+  <span class="ui-bracket-note__label">Source</span>
+  Q3 incident review, §4 — sustained for 47 minutes before rollback.
+</blockquote>
+```
+
+Tones: `--accent` (the rationed accent), `--warning`, `--danger`, `--info`. The
+default is a neutral bracket.
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.mark({ tone: 'accent', motion: 'draw' });
+// "ui-mark ui-mark--accent ui-mark--draw"
+ui.mark({ style: 'underline', tone: 'danger' });
+// "ui-mark ui-mark--underline ui-mark--danger"
+ui.bracketNote({ tone: 'warning' });
+// "ui-bracket-note ui-bracket-note--warning"
+```
+
+## Accessibility
+
+- A `.ui-mark` is **visual emphasis**; it does not announce itself to screen
+  readers. When the emphasis carries meaning that the surrounding words don't,
+  state it in the text (a screen-reader user can't see the highlight) — the same
+  rule as colour (WCAG 1.4.1). Use a native `<mark>` so the relationship is at
+  least semantic.
+- In `forced-colors` mode a highlight `background` is dropped, so marks add an
+  underline to keep the emphasis visible; the `--box`/`--underline`/`--strike`
+  styles already survive as a system colour.
+- `.ui-bracket-note` is a plain block; wrap a quotation in `<blockquote>` (or a
+  region with its own heading/label) so its role is conveyed without the border.