@ponchia/ui 0.5.0 → 0.6.3

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/d2.md

@@ -0,0 +1,196 @@
+# D2
+
+[D2](https://d2lang.com) compiles a diagram script to **SVG** (Go CLI or the
+`@terrastruct/d2` WASM build). Like the [Mermaid integration](./mermaid.md),
+`@ponchia/ui` doesn't render diagrams — it **themes** them from your tokens and
+lets you **annotate** the result. Two things ship:
+
+- `@ponchia/ui/d2` — helpers that produce on-brand D2 theme overrides.
+- `@ponchia/ui/d2.json` — the resolved slot → hex maps, for any consumer.
+
+D2 stays the consumer's renderer; this is config only, and D2 is **not** a
+dependency.
+
+## Theme a diagram
+
+D2's theme is a compact set of named colour slots. Override them with the bronto
+palette by prepending a `vars` block to your diagram source — `brontoD2Vars()`
+returns exactly that block (both light and dark):
+
+```js
+import { brontoD2Vars } from '@ponchia/ui/d2';
+
+const source = brontoD2Vars() + `
+  api -> db: query
+  db: Store { shape: cylinder }
+`;
+// → render `source` with the D2 CLI or @terrastruct/d2
+```
+
+If you render through D2's Go or WASM API instead of source, pass the slot map to
+its `themeOverrides` / `darkThemeOverrides`:
+
+```js
+import { brontoD2Overrides } from '@ponchia/ui/d2';
+brontoD2Overrides('dark'); // { N1: '#e6e6e6', B1: '#555555', … }
+```
+
+For a build step or non-JS host, read `@ponchia/ui/d2.json` directly.
+
+> **file:// portability.** A report opened from disk (`file://`) cannot
+> `import` the `@ponchia/ui/d2` module **nor** `fetch('…/d2.json')` — the browser
+> blocks both across the `null`/file origin (CORS), exactly as with
+> [Vega](./vega.md#from-a-cdn-no-bundler) and [Mermaid](./mermaid.md#theme-a-diagram).
+> This is rarely an issue for D2, whose native path is **build-time
+> pre-rendering** to a frozen SVG (no client runtime — see below), but if you do
+> theme D2 in the browser over `file://`, **inline** the slot map (generate the
+> paste-ready literal with `npm run emit:theme d2 light` / `dark`, and guard it
+> against token drift with `npm run emit:theme:check <file>`) rather than
+> importing it. Over `http(s)` the `import`/`fetch` forms both work.
+
+### Why resolved colours, not `var(--x)`
+
+D2 compiles to a **frozen SVG** in Go/WASM — there is no client CSS cascade, so a
+`var(--accent)` could never resolve. The maps therefore ship **resolved hex per
+theme**, projected from the same token source as
+[`tokens/resolved.json`](./architecture.md) / `charts.json`. Each slot is set
+explicitly (D2 does not derive a ramp from one seed). Because the output is a
+static SVG, **build-time pre-rendering is D2's native path** — ideal for the
+[report layer](./reporting.md).
+
+### What the slots paint
+
+The mapping keeps a diagram **monochrome by default** — the rationed accent is
+not spent on borders, edges, or shapes the author never marked:
+
+| Slots | Paint | bronto mapping |
+| --- | --- | --- |
+| `N1`–`N3` | Text · muted · subtle | `--text` · `--text-soft` · `--text-dim` |
+| `N4`–`N5` | Strong / regular lines | `--line-strong` · `--line` |
+| `N6`–`N7` | Subtle background · canvas | `--panel-soft` · `--bg` |
+| `B1` | Shape borders **and** connections (edges) | `--line-strong` |
+| `B2`–`B3` | Muted borders | `--line` |
+| `B4`–`B6` | Container fills (outer → leaf) | `--panel-soft` · `--bg-elevated` · `--panel` |
+| `AA*` / `AB*` | Alternative-accent ramps (special-shape fills, class/sql headers) | kept **neutral** |
+
+The alt-accent ramps are deliberately neutral: D2 spends them on special shapes
+(cylinders, class/sql-table headers) by default, so mapping them to the accent
+would colour shapes you never marked. Keeping them neutral is what holds the
+monochrome default.
+
+### Spending the accent
+
+To emphasise a node, opt it into a class that sets the accent explicitly — the
+accent appears only where you ask for it:
+
+```d2
+classes: {
+  accent: {
+    style: { fill: "#d71921"; font-color: "#ffffff"; stroke: "#b2151b" }
+  }
+}
+
+alert: Alert { class: accent }
+```
+
+Use the resolved `--accent` / `--accent-strong` hex (from
+[`tokens/resolved.json`](./architecture.md), per theme) for the `fill` / `stroke`
+so the emphasis matches the rest of the surface. Reserve it for the one thing a
+reader must not miss.
+
+> **The label on an accent fill uses `--on-accent`, not `--accent-text`.** A
+> filled-accent node needs **on-accent ink** for its `font-color` — the resolved
+> `--on-accent` token (white on the light accent, black on the dark accent;
+> ≥ 4.5:1, gated in [contrast.md](./contrast.md)). Do **not** reach for
+> `--accent-text` by name: that is the inverse token — _accent-coloured text for
+> a neutral background_ (it resolves to `--accent-strong`, ~1.3:1 on the accent
+> fill, an unreadable label). The literal `#ffffff` above is `--on-accent` for
+> the light theme; pull the per-theme hex from `tokens/resolved.json`.
+
+### Frozen inline SVG (no D2 runtime)
+
+A static, PDF-first report often has no D2 binary in its pipeline. When you only
+need a few boxes and arrows, **hand-author a token-themed inline `<svg>`** instead
+of running D2 — the same frozen-figure route the [report chart
+recipe](./reporting.md#chart-figure-recipe) uses. Paint each element from the
+token that the live theme map would have resolved, so the frozen diagram still
+re-skins (drive fills from `var(--token)` in the inline `style`/attributes, or
+paste the resolved hex from [`tokens/resolved.json`](./architecture.md) for a
+`file://` PDF):
+
+| Diagram element | bronto token | (live D2 slot it mirrors) |
+| --- | --- | --- |
+| Node fill | `--panel` | `B4`–`B6` container fills |
+| Node border | `--line-strong` | `B1` |
+| Node label | `--text` | `N1` |
+| Edge / connector + arrowhead | `--line-strong` | `B1` |
+| Edge label | `--text-soft` | `N2` |
+| Cluster / container fill | `--panel-soft` | `B4` |
+| Accent (emphasised) node fill · its label | `--accent` · `--on-accent` | the `accent` class above |
+
+```html
+<svg viewBox="0 0 320 120" role="img" aria-labelledby="flow-title">
+  <title id="flow-title">Ingest → Queue → Worker</title>
+  <!-- edge -->
+  <line x1="92" y1="40" x2="128" y2="40" stroke="var(--line-strong)" marker-end="url(#arrow)" />
+  <line x1="220" y1="40" x2="256" y2="40" stroke="var(--line-strong)" marker-end="url(#arrow)" />
+  <defs>
+    <marker id="arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="6" markerHeight="6" orient="auto">
+      <path d="M0,0 L8,4 L0,8 z" fill="var(--line-strong)" />
+    </marker>
+  </defs>
+  <!-- neutral node -->
+  <rect x="16" y="22" width="76" height="36" rx="6" fill="var(--panel)" stroke="var(--line-strong)" />
+  <text x="54" y="44" text-anchor="middle" fill="var(--text)" font-size="12">Ingest</text>
+  <!-- accent (emphasised) node: on-accent ink on the accent fill -->
+  <rect x="128" y="22" width="92" height="36" rx="6" fill="var(--accent)" stroke="var(--accent-strong)" />
+  <text x="174" y="44" text-anchor="middle" fill="var(--on-accent)" font-size="12">Queue</text>
+  <rect x="256" y="22" width="64" height="36" rx="6" fill="var(--panel)" stroke="var(--line-strong)" />
+  <text x="288" y="44" text-anchor="middle" fill="var(--text)" font-size="12">Worker</text>
+</svg>
+```
+
+For anything larger or graph-laid-out, run D2 with the theme map and freeze its
+output — don't hand-lay a complex graph.
+
+### Fit to small screens
+
+D2 emits an SVG with explicit `width`/`height` from its layout, so on a narrow
+screen it overflows unless you make it fluid. Two build-time options:
+
+- **Scale to fit** — drop the fixed `width`/`height` attributes (keep the
+  `viewBox`) so the SVG shrinks to its container. Best for diagrams that stay
+  legible at smaller sizes.
+- **Scroll a wide diagram** — wrap it in `overflow-x: auto` so a large diagram
+  scrolls inside its box instead of pushing the page wide, the same pattern the
+  report layer uses for wide figures.
+
+```css
+.diagram-scroll {
+  overflow-x: auto;
+}
+.diagram-scroll svg {
+  max-inline-size: 100%;
+  block-size: auto;
+}
+```
+
+Render **non-sketch** at a fixed `scale` for predictable boxes.
+
+## Annotate a diagram
+
+D2 output is SVG, so the [annotation layer](./annotations.md) composes onto it
+exactly as in the [Mermaid recipe](./mermaid.md#annotate-a-diagram): render to a
+frozen SVG (the D2 CLI `d2 in.d2 out.svg`, or `@terrastruct/d2` in a build
+script), read the target shape's box, and paste a `<g class="ui-annotation">`
+computed with `@ponchia/ui/annotations`. The same caveats apply — D2's internal
+SVG (element ids, the root transform) is not a public contract, so pin your D2
+version, render **non-sketch**, account for `pad` / `scale`, and avoid
+`animate-interval` (a multi-board animated SVG would not track a single overlay).
+
+## Scope
+
+bronto owns the theme map (gated: every slot resolves to a colour, both themes,
+no `var()` leaks) and the annotation geometry. It does not own D2's rendering,
+its internal SVG, or its CLI — those stay D2's, and the overlay is a documented
+composition, not a shipped runtime binding.

package/docs/diff.md

@@ -0,0 +1,146 @@
+# Diff
+
+`@ponchia/ui/css/diff.css` is an opt-in change-review grammar — the surface for
+showing what **changed**: code review, changelogs, version history, config
+diffs, and generated reports. Marks call out a sentence; diff calls out a line.
+Its sibling is [code.css](code.md) (single-file fenced code); the two share one
+change vocabulary — `--add` / `--remove` (`ui-diff__row--remove` ↔
+`ui-code__line--remove`).
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/diff.css';
+```
+
+```html
+<!-- node_modules / CDN: source css/ → built dist/css/ -->
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/diff.css" />
+```
+
+## Boundary — what Bronto owns vs. what you own
+
+Bronto paints the gutter grammar. **You** pre-classify each row (`add` /
+`remove` / `context`), compute the hunks, and align the two sides in split
+view. Bronto never parses or diffs source — that needs your tokenizer and your
+alignment, the same line that removed the local chart renderer in `0.6.0`. Feed
+it rows that are already classified by your diff engine (`jsdiff`, `git`, a
+language server, …).
+
+## Unified view — `.ui-diff`
+
+Rows are direct children of `.ui-diff` (optionally grouped in a
+`.ui-diff__hunk`). Columns are `[old-ln] [new-ln] [code]`. Mark each changed row
+`--add` / `--remove`, and leave unchanged rows `--context`. Line numbers are
+decorative — keep them `aria-hidden`; the `__code` cell carries the content.
+
+```html
+<div class="ui-diff">
+  <div class="ui-diff__hunk">
+    <div class="ui-diff__head">@@ -12,6 +12,6 @@ .ui-diff</div>
+
+    <div class="ui-diff__row ui-diff__row--context">
+      <span class="ui-diff__ln" aria-hidden="true">12</span>
+      <span class="ui-diff__ln" aria-hidden="true">12</span>
+      <code class="ui-diff__code">  border: 1px solid var(--line);</code>
+    </div>
+
+    <div class="ui-diff__row ui-diff__row--remove">
+      <span class="ui-diff__ln" aria-hidden="true">13</span>
+      <span class="ui-diff__ln" aria-hidden="true"></span>
+      <code class="ui-diff__code">  font-size: var(--text-sm);</code>
+    </div>
+
+    <div class="ui-diff__row ui-diff__row--add">
+      <span class="ui-diff__ln" aria-hidden="true"></span>
+      <span class="ui-diff__ln" aria-hidden="true">13</span>
+      <code class="ui-diff__code">  font-size: var(--text-xs);</code>
+    </div>
+  </div>
+</div>
+```
+
+A removed row leaves the **new** line-number cell empty; an added row leaves the
+**old** one empty. The `+` / `−` gutter glyph is painted for you from the row
+modifier.
+
+## Split view — `.ui-diff--split`
+
+`.ui-diff--split` lays two `.ui-diff__pane` columns side by side (old | new),
+each its own `[ln] [code]` grid. Put `--remove` / `--context` rows in the left
+pane and `--add` / `--context` rows in the right. You align the panes by
+emitting matching row counts (filler `--context` rows where one side is empty).
+
+```html
+<div class="ui-diff ui-diff--split">
+  <div class="ui-diff__pane">
+    <div class="ui-diff__row ui-diff__row--context">
+      <span class="ui-diff__ln" aria-hidden="true">1</span>
+      <code class="ui-diff__code">retries: 3</code>
+    </div>
+    <div class="ui-diff__row ui-diff__row--remove">
+      <span class="ui-diff__ln" aria-hidden="true">2</span>
+      <code class="ui-diff__code">timeout: 30</code>
+    </div>
+  </div>
+  <div class="ui-diff__pane">
+    <div class="ui-diff__row ui-diff__row--context">
+      <span class="ui-diff__ln" aria-hidden="true">1</span>
+      <code class="ui-diff__code">retries: 3</code>
+    </div>
+    <div class="ui-diff__row ui-diff__row--add">
+      <span class="ui-diff__ln" aria-hidden="true">2</span>
+      <code class="ui-diff__code">timeout: 10</code>
+    </div>
+  </div>
+</div>
+```
+
+For a hard before/after of two whole files, you can also drop two plain
+`.ui-diff` blocks into a [`.ui-compare--2up`](./reporting.md) layout.
+
+## Class reference
+
+| Class | Role |
+| --- | --- |
+| `.ui-diff` | The grid container (unified view). |
+| `.ui-diff--split` | Two-pane (old \| new) layout modifier. |
+| `.ui-diff__pane` | One column in split view; its own `[ln] [code]` grid. |
+| `.ui-diff__hunk` | Optional `role="rowgroup"` wrapper for a hunk (layout-transparent). |
+| `.ui-diff__head` | A hunk / file header row, spanning all columns. |
+| `.ui-diff__row` | A line row (layout-transparent; the cells are the grid items). |
+| `.ui-diff__row--add` | Added line — green tint + `+` gutter glyph. |
+| `.ui-diff__row--remove` | Removed line — red tint + `−` gutter glyph. |
+| `.ui-diff__row--context` | Unchanged line — no tint, blank gutter. |
+| `.ui-diff__ln` | A line-number gutter cell (`tabular-nums`, `user-select:none`; keep it `aria-hidden`). |
+| `.ui-diff__code` | A code cell. Long lines wrap (no horizontal scroll), so it prints cleanly. |
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.diff();                       // "ui-diff"
+ui.diff({ split: true });        // "ui-diff ui-diff--split"
+ui.diffRow({ change: 'add' });   // "ui-diff__row ui-diff__row--add"
+ui.diffRow({ change: 'remove' }); // "ui-diff__row ui-diff__row--remove"
+ui.diffRow();                    // "ui-diff__row"  (use --context for an explicit unchanged row)
+```
+
+## Accessibility & robustness
+
+- **Redundant channel (WCAG 1.4.1).** Add/remove is never colour-only: the
+  `+` / `−` gutter glyph is generated content, so it survives **forced colours**
+  and **print**, where the tone tint is dropped. In forced-colors mode the
+  changed code cell also gains an inline-start border.
+- **Print.** Tints are forced through with `print-color-adjust: exact`, and long
+  lines wrap rather than clip — the diff survives the PDF pipeline.
+- **Line numbers** are decorative: `aria-hidden` them and they stay out of a
+  copy selection (`user-select: none`), so copying the diff yields clean code.
+- **Semantics** live in your markup. By default the surface is role-free: with
+  the line numbers `aria-hidden`, a screen reader reads the `__code` lines in
+  DOM order, which is a faithful reading of the diff. If you want grid/table
+  semantics, use a real `<table>` or add the full ARIA chain
+  (`role="table" > rowgroup > row > cell`) — a bare `role="row"` without
+  `role="cell"` children is an ARIA violation. If the change kind itself must be
+  announced, add an off-screen label per changed row; do not rely on the glyph
+  alone.