@ponchia/ui 0.4.1 → 0.6.0

package/docs/d2.md

@@ -0,0 +1,195 @@
+# 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 (paste the
+> object from `d2.json`) 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/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,184 @@
+# 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 any chart — a token-themed inline
+SVG, or an external engine like [Vega-Lite](./vega.md) — 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).
+
+A `ui-legend__symbol` chip is an `.ui-icon` mask — it needs a `--icon-mask`
+(e.g. `style="--icon-mask: var(--glyph-dot)"`) or it paints a solid square, like
+any [icon](./reference.md). And an **interactive** legend entry must be a real
+`<button>` (as in the example below) — a non-button `ui-legend__item` carrying
+`data-series` is not keyboard-reachable.
+
+**Keying the de-emphasised series.** In an accent-rationed chart — one mark
+painted with [`brontoVegaAccent`](./vega.md#spending-the-accent), the rest left
+quiet with `brontoVegaNeutral` — the quiet neutral **is** the last categorical
+series, `--chart-8` (`#4d5358`). So a legend that honestly mirrors that chart
+uses `ui-legend__swatch--1` for the highlighted entry and
+`ui-legend__swatch--8` for the "everything else" entry — both are real palette
+tokens, so the key never drifts from the marks and `check:legend` stays happy.
+Don't hand-roll a grey: `--chart-8` is the neutral by construction.
+
+## 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,93 @@
+# 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).
+
+> **A mark is a behind-text highlight, not a filled chip.** The fill is a
+> low-alpha gradient *behind* the running text, so the text keeps its normal ink
+> and the contrast stays text-on-background — even `ui-mark--accent` is
+> contrast-safe by construction. Don't reach for `--on-accent` here (that ink is
+> for a *solid* accent fill, like a button or a D2 node); a `<mark>` never needs
+> it.
+
+## 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), `--success`, `--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.