@ponchia/ui 0.4.1 → 0.6.0

package/docs/command.md

@@ -0,0 +1,95 @@
+# Command palette
+
+`@ponchia/ui/css/command.css` + `initCommand` are an opt-in **command palette**:
+a filter input over a grouped listbox of commands with shortcut hints. Command
+palettes turn a product from a page collection into a tool. Existing libraries
+(cmdk, kbar) are good — Bronto owns the *design-system contract* (the shell,
+shortcuts, groups, meta) and a small navigation behavior, not the action registry.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/command.css';
+```
+
+```js
+import { initCommand, initDialog } from '@ponchia/ui/behaviors';
+initDialog(); // open/close the dialog the palette lives in
+initCommand(); // filter + keyboard-navigate the list
+```
+
+**Bronto** filters and keyboard-navigates a DOM-authored list. **The host** owns
+the action registry, permission checks, routing, async effects, and execution —
+it listens for `bronto:command:select` and runs the command. There is **no global
+Cmd/Ctrl+K**; you open the palette yourself (e.g. a `<dialog>` opened by a button
+or your own shortcut). Pairs with the [`ui-shortcut`](./reference.md) hint. Not in
+the core bundle.
+
+## Markup
+
+```html
+<dialog class="ui-modal" id="cmdk" data-bronto-dialog-light aria-label="Command palette">
+  <div class="ui-command" data-bronto-command>
+    <input class="ui-command__input" aria-label="Command" placeholder="Type a command…" />
+    <ul class="ui-command__list">
+      <li class="ui-command__group">Navigation</li>
+      <li class="ui-command__item" data-value="dashboard">
+        <span>Go to dashboard</span>
+        <span class="ui-command__shortcut"><kbd class="ui-kbd">G</kbd> <kbd class="ui-kbd">D</kbd></span>
+      </li>
+      <li class="ui-command__group">Actions</li>
+      <li class="ui-command__item" data-value="invoice">
+        <span>New invoice</span>
+        <span class="ui-command__meta">Create</span>
+      </li>
+    </ul>
+    <p class="ui-command__empty" hidden>No commands</p>
+  </div>
+</dialog>
+<button class="ui-button" data-bronto-open="cmdk" type="button">Commands</button>
+```
+
+| Class | Role |
+| --- | --- |
+| `ui-command` | The palette shell (input + list + empty). |
+| `ui-command__input` | The filter input (becomes `role="combobox"`). |
+| `ui-command__list` | The listbox of commands. |
+| `ui-command__group` | A non-selectable group label; auto-hidden when its items all filter out. |
+| `ui-command__item` | A command row (`role="option"`); optional `data-value`. |
+| `ui-command__shortcut` | A trailing shortcut hint (use `ui-kbd`). |
+| `ui-command__meta` | Trailing secondary text (category, hint). |
+| `ui-command__empty` | Shown when nothing matches. |
+
+## Behavior & events
+
+`initCommand()` owns ids, `role`/`aria-activedescendant`, a roving active item,
+substring filtering, the full keyboard (Down/Up/Home/End/Enter/Escape), and
+pointer select. It emits:
+
+- `bronto:command:select` — `{ value, label }`. The host executes and closes.
+- `bronto:command:close` — on Escape. The host closes the dialog.
+
+> **Permission boundary:** `initCommand()` owns the `hidden` attribute on items
+> (that is how it filters), so it will reveal any item you pre-hid the moment the
+> query changes. To gate a command by permission, **omit it from the DOM** —
+> don't render it hidden.
+
+```js
+const dialog = document.getElementById('cmdk');
+document.querySelector('[data-bronto-command]').addEventListener('bronto:command:select', (e) => {
+  run(e.detail.value); // YOUR action registry
+  dialog.close();
+});
+document.querySelector('[data-bronto-command]').addEventListener('bronto:command:close', () =>
+  dialog.close(),
+);
+```
+
+Framework hook: `useCommand()` in `@ponchia/ui/react` · `/solid` · `/qwik`.
+
+## Accessibility
+
+- The input is a `combobox`, the list a `listbox`, items `option`s, with
+  `aria-activedescendant` tracking the active row — standard APG listbox semantics.
+- Focus stays in the input while arrows move the active item; Enter selects it.
+- Open the palette in a focus-trapping `<dialog>` (Bronto's `initDialog`) so focus
+  returns to the trigger on close.

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

@@ -40,51 +40,57 @@ 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) | 17.98:1 | Lc 99 | ✅ pass |
-| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 19.80:1 | Lc 106 | ✅ pass |
-| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 16.74:1 | Lc 94 | ✅ pass |
-| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 11.16:1 | Lc 91 | ✅ pass |
-| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 12.29:1 | Lc 98 | ✅ pass |
-| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 10.39:1 | Lc 87 | ✅ pass |
-| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 5.09:1 | Lc 71 | ✅ pass |
-| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 5.60:1 | Lc 78 | ✅ pass |
-| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.74:1 | Lc 67 | ✅ pass |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.32:1 | Lc 75 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.96:1 | Lc 82 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.18:1 | Lc 79 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 67 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.18:1 | Lc 73 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 4.71:1 | Lc 67 | ✅ pass |
-| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 5.04:1 | Lc 75 | ✅ pass |
-| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 5.60:1 | Lc 78 | ✅ pass |
-| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 6.21:1 | Lc 79 | ✅ pass |
-| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 5.77:1 | Lc 78 | ✅ pass |
-| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.39:1 | Lc 47 | ℹ️ not gated |
+| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 17.98:1 | Lc 99.2 | ✅ pass |
+| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 19.80:1 | Lc 105.8 | ✅ pass |
+| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 16.74:1 | Lc 94.5 | ✅ pass |
+| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 11.16:1 | Lc 91.4 | ✅ pass |
+| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 12.29:1 | Lc 98.1 | ✅ pass |
+| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 10.39:1 | Lc 86.7 | ✅ pass |
+| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 5.09:1 | Lc 71.4 | ✅ pass |
+| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 5.60:1 | Lc 78.0 | ✅ pass |
+| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.74:1 | Lc 66.7 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.32:1 | Lc 75.4 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.96:1 | Lc 82.1 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.91:1 | Lc 71.0 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.31:1 | Lc 75.3 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.18:1 | Lc 78.9 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.18:1 | Lc 78.9 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 66.8 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.18:1 | Lc 73.5 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 4.71:1 | Lc 66.8 | ✅ pass |
+| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 5.04:1 | Lc 74.6 | ✅ pass |
+| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 5.60:1 | Lc 77.8 | ✅ pass |
+| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 6.21:1 | Lc 78.9 | ✅ pass |
+| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 5.77:1 | Lc 78.3 | ✅ pass |
+| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.39:1 | Lc 47.1 | ℹ️ not gated |
 
 ## Dark theme
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--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.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 |
+| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 15.01:1 | Lc 91.1 | ✅ pass |
+| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 13.65:1 | Lc 90.1 | ✅ pass |
+| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 12.44:1 | Lc 88.9 | ✅ pass |
+| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 11.20:1 | Lc 72.7 | ✅ pass |
+| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 10.19:1 | Lc 71.7 | ✅ pass |
+| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 9.28:1 | Lc 70.6 | ✅ pass |
+| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 7.16:1 | Lc 50.3 | ✅ pass |
+| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 6.52:1 | Lc 49.3 | ✅ pass |
+| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 5.94:1 | Lc 48.1 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.14:1 | Lc 44.9 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 5.58:1 | Lc 43.9 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 2.53:1 | Lc 43.8 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 2.75:1 | Lc 49.1 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.95:1 | Lc 42.9 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.95:1 | Lc 42.9 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.31:1 | Lc 40.0 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 4.83:1 | Lc 39.0 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.31:1 | Lc 40.0 | ✅ pass |
+| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 7.58:1 | Lc 56.6 | ✅ pass |
+| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 9.29:1 | Lc 66.6 | ✅ pass |
+| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 5.23:1 | Lc 41.5 | ✅ pass |
+| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 7.33:1 | Lc 54.8 | ✅ pass |
+| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.29:1 | Lc 14.5 | ℹ️ not gated |
 
 ## Display colorways (skins)
 
@@ -101,67 +107,85 @@ 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) | 6.75:1 | Lc 79 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 7.44:1 | Lc 86 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.66:1 | Lc 83 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.14:1 | Lc 71 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.66:1 | Lc 78 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.14:1 | Lc 71 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.75:1 | Lc 78.9 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 7.44:1 | Lc 85.6 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 6.31:1 | Lc 74.5 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.74:1 | Lc 78.8 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.66:1 | Lc 83.3 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.66:1 | Lc 83.3 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.14:1 | Lc 71.4 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.66:1 | Lc 78.0 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.14:1 | Lc 71.4 | ✅ pass |
 
 ### Amber CRT — dark
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--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) | 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 |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 11.57:1 | Lc 74.8 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 10.52:1 | Lc 73.8 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.34:1 | Lc 15.1 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.46:1 | Lc 20.3 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.88:1 | Lc 71.6 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 11.88:1 | Lc 71.6 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.60:1 | Lc 69.9 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 9.64:1 | Lc 68.9 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 10.60:1 | Lc 69.9 | ✅ pass |
 
 ### E-ink — light
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.23:1 | Lc 93 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.47:1 | Lc 100 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.74:1 | Lc 101 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.66:1 | Lc 90 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.74:1 | Lc 97 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 10.66:1 | Lc 90 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.23:1 | Lc 93.3 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.47:1 | Lc 99.9 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 11.43:1 | Lc 88.8 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 12.22:1 | Lc 93.2 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.74:1 | Lc 100.6 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 11.74:1 | Lc 100.6 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.66:1 | Lc 90.4 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.74:1 | Lc 97.0 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 10.66:1 | Lc 90.4 | ✅ pass |
 
 ### E-ink — dark
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--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) | 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 |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.47:1 | Lc 79.1 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.35:1 | Lc 78.1 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.25:1 | Lc 11.0 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.35:1 | Lc 16.3 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 12.86:1 | Lc 75.6 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 12.86:1 | Lc 75.6 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 11.48:1 | Lc 74.1 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 10.44:1 | Lc 73.1 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 11.48:1 | Lc 74.1 | ✅ pass |
 
 ### Phosphor Green — light
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.22:1 | Lc 77 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.85:1 | Lc 83 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.19:1 | Lc 81 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 69 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.19:1 | Lc 75 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 4.71:1 | Lc 69 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.22:1 | Lc 76.6 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.85:1 | Lc 83.3 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.81:1 | Lc 72.2 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.21:1 | Lc 76.5 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.19:1 | Lc 80.7 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.19:1 | Lc 80.7 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 68.6 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.19:1 | Lc 75.3 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 4.71:1 | Lc 68.6 | ✅ pass |
 
 ### Phosphor Green — dark
 
 | 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 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) | 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 |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.97:1 | Lc 81.8 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.80:1 | Lc 80.8 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.20:1 | Lc 8.4 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.30:1 | Lc 13.7 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 13.75:1 | Lc 79.7 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 13.75:1 | Lc 79.7 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 12.27:1 | Lc 78.5 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.16:1 | Lc 77.5 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 12.27:1 | Lc 78.5 | ✅ pass |
 
 ## Data-viz palette (advisory)
 
@@ -178,27 +202,27 @@ the brand accent.
 
 | Series | Colour | Ratio _(advisory)_ | APCA _(advisory)_ |
 | --- | --- | --- | --- |
-| 1 _(accent)_ | `#d71921` | 4.71:1 | Lc 67 |
-| 2 | `#e69f00` | 2.05:1 | Lc 37 |
-| 3 | `#56b4e9` | 2.10:1 | Lc 39 |
-| 4 | `#009e73` | 3.11:1 | Lc 54 |
-| 5 | `#f0e442` | 1.20:1 | Lc 9 |
-| 6 | `#0072b2` | 4.71:1 | Lc 68 |
-| 7 | `#cc79a7` | 2.78:1 | Lc 51 |
-| 8 | `#4d5358` | 7.08:1 | Lc 80 |
+| 1 _(accent)_ | `#d71921` | 4.71:1 | Lc 66.8 |
+| 2 | `#e69f00` | 2.05:1 | Lc 37.4 |
+| 3 | `#56b4e9` | 2.10:1 | Lc 38.6 |
+| 4 | `#009e73` | 3.11:1 | Lc 54.4 |
+| 5 | `#f0e442` | 1.20:1 | Lc 9.1 |
+| 6 | `#0072b2` | 4.71:1 | Lc 68.4 |
+| 7 | `#cc79a7` | 2.78:1 | Lc 50.6 |
+| 8 | `#4d5358` | 7.08:1 | Lc 80.4 |
 
 ### Dark theme — categorical vs `--bg`
 
 | Series | Colour | Ratio _(advisory)_ | APCA _(advisory)_ |
 | --- | --- | --- | --- |
-| 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 |
+| 1 _(accent)_ | `#ff3b41` | 5.31:1 | Lc 40.0 |
+| 2 | `#e69f00` | 8.32:1 | Lc 57.5 |
+| 3 | `#56b4e9` | 8.12:1 | Lc 56.3 |
+| 4 | `#009e73` | 5.48:1 | Lc 40.0 |
+| 5 | `#f0e442` | 14.17:1 | Lc 87.4 |
+| 6 | `#0072b2` | 3.61:1 | Lc 26.1 |
+| 7 | `#cc79a7` | 6.12:1 | Lc 43.9 |
+| 8 | `#4d5358` | 2.40:1 | Lc 14.4 |
 
 ## 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.