@ponchia/ui 0.6.0 → 0.6.3

package/docs/sidenote.md

@@ -0,0 +1,64 @@
+# Sidenote
+
+`@ponchia/ui/css/sidenote.css` is an opt-in **margin-note** grammar in the Tufte
+tradition — the channel for evidence, caveats, and provenance asides that belong
+*beside* the prose, not interrupting it. `ui-sidenote` is numbered;
+`ui-marginnote` is the unnumbered variant.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/sidenote.css';
+```
+
+## How it behaves
+
+- **Wide viewports** (≥ 60rem) float the note into the inline-end margin.
+- **Narrow viewports** collapse it to an indented inline block right after its
+  anchor, so nothing is lost on a phone or in a narrow column.
+- **Numbering** is a CSS counter — no host bookkeeping.
+
+## Wiring — two things the host owns
+
+1. **Where numbering restarts.** Put `counter-reset: ui-sidenote` on the article
+   (or a section) so the count starts at 1 there.
+2. **The margin gutter.** At the same breakpoint, give that container
+   `padding-inline-end: calc(var(--sidenote-width) + var(--sidenote-gap))` so the
+   floated note has room. `--sidenote-width` defaults to `12rem`.
+
+```html
+<article style="counter-reset: ui-sidenote">
+  <p>
+    The migration cut p95 latency by 38%<label class="ui-sidenote__ref"></label>.
+    <span class="ui-sidenote">
+      Measured over the first 24h after rollout; see the incident review §4.
+    </span>
+    The error budget held<span class="ui-marginnote">No paging events fired.</span>.
+  </p>
+</article>
+```
+
+The `.ui-sidenote__ref` renders the superscript number and increments the
+counter; place the `.ui-sidenote` immediately after it in the DOM so it reads
+the same number.
+
+## Class reference
+
+| Class | Role |
+| --- | --- |
+| `.ui-sidenote` | A numbered margin note. |
+| `.ui-marginnote` | An unnumbered margin note (no `__ref`). |
+| `.ui-sidenote__ref` | The inline superscript anchor; increments + prints the number. |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--sidenote-width` | `.ui-sidenote` / `.ui-marginnote` | Floated width on wide viewports (default `12rem`). |
+| `--sidenote-gap` | same | Gap between the text column and the note (default `2rem`). |
+
+## Accessibility & robustness
+
+- The note is **real DOM in reading order**, so a screen reader encounters it
+  right after the anchor — no off-screen trickery.
+- On narrow viewports the note is always visible (an indented block with an
+  inline-start rule), so there is no hidden-content trap.
+- Keep the note's meaning in its text; the number is a wayfinding aid, not the
+  content.

package/docs/spark.md

@@ -0,0 +1,78 @@
+# Spark
+
+`@ponchia/ui/css/spark.css` is an opt-in **inline dataword** — a word-sized
+microchart you drop into a sentence or a dense table cell to show a trend
+in-line. It is the inline counterpart to the scalar `ui-delta` / `ui-num` /
+`ui-stat`, and it fills a gap a block-level chart cannot.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/spark.css';
+```
+
+## Boundary — the host owns the numbers
+
+Bronto paints bars; it does **not** compute scales. The host normalises each
+data point to `0..1` and sets it as `--v` on a `.ui-spark__bar`. Bronto refuses
+raw values and min/max — that is the same boundary that keeps the analytical
+layer from owning chart state.
+
+## Markup
+
+```html
+<!-- "weekly signups, trending up" — the label IS the accessible content -->
+<span class="ui-spark" role="img" aria-label="weekly signups, trending up">
+  <span class="ui-spark__bar" style="--v: 0.2"></span>
+  <span class="ui-spark__bar" style="--v: 0.4"></span>
+  <span class="ui-spark__bar" style="--v: 0.35"></span>
+  <span class="ui-spark__bar" style="--v: 0.7"></span>
+  <span class="ui-spark__bar ui-spark__bar--accent" style="--v: 1"></span>
+</span>
+```
+
+A **win/loss** strip uses fixed-height bars with `--pos` / `--neg` tones:
+
+```html
+<span class="ui-spark" role="img" aria-label="last 5 deploys: 4 passed, 1 failed">
+  <span class="ui-spark__bar ui-spark__bar--pos" style="--v: 1"></span>
+  <span class="ui-spark__bar ui-spark__bar--pos" style="--v: 1"></span>
+  <span class="ui-spark__bar ui-spark__bar--neg" style="--v: 1"></span>
+  <span class="ui-spark__bar ui-spark__bar--pos" style="--v: 1"></span>
+  <span class="ui-spark__bar ui-spark__bar--pos" style="--v: 1"></span>
+</span>
+```
+
+## Class reference
+
+| Class | Role |
+| --- | --- |
+| `.ui-spark` | The inline container (sizes to ~1em tall, `max-content` wide). |
+| `.ui-spark__bar` | One bar — height from `--v` (`0..1`). Defaults to `currentColor`. |
+| `.ui-spark__bar--accent` | Emphasise one bar with the rationed accent. |
+| `.ui-spark__bar--pos` | Success tone (win). |
+| `.ui-spark__bar--neg` | Danger tone (loss). |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--v` | `.ui-spark__bar` | **Required.** Normalised height `0..1`; the host computes it. A bar with no `--v` collapses to a 1px floor. |
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.sparkBar({ tone: 'accent' }); // "ui-spark__bar ui-spark__bar--accent"
+ui.sparkBar({ tone: 'pos' });    // "ui-spark__bar ui-spark__bar--pos"
+ui.sparkBar();                   // "ui-spark__bar"
+```
+
+## Accessibility & robustness
+
+- **A bare spark is opaque.** The `.ui-spark` container **must** carry
+  `role="img"` and an `aria-label` that states the trend in words — colour and
+  shape are never the only channel (WCAG 1.4.1, 1.1.1).
+- **Forced colours:** the bars repaint in the system text colour so the shape
+  survives (the tone distinction lives in the label).
+- **Print:** bars are forced through `print-color-adjust: exact`.
+- No JS, no measurement — it renders identically server-side and in a static
+  report.

package/docs/stability.md

@@ -40,6 +40,7 @@ until `1.0.0` is tagged. This matrix defines what counts as public API.
 | Generated / AI-trust (`css/generated.css`, `.ui-generated*`, `.ui-origin-label*`, `.ui-reasoning*`, `.ui-tool-log`, `.ui-tool-call*`) | Stable additive | The generated-content, origin-label (incl. `--ai`), reasoning-trace and tool-log/tool-call class names and the `ui.originLabel` recipe are public. Opt-in, not in the default bundle. Not a chat kit; no confidence widget. |
 | Workbench (`css/workbench.css`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`) | Stable additive | Inspector, property-row and selection-bar class + BEM part names are public (class-only — no recipe). Opt-in, not in the default bundle. Splitters/drag handles are out of scope. |
 | Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the `useCommand` binding hook. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
+| Controlled-modal focus trap (`initModal`, `useModal`, `data-bronto-modal`) | Stable additive | For the `.ui-modal.is-open` (non-`<dialog>`) path: the `data-bronto-modal` opt-in marker, the `inert`-based focus trap + focus-return, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; the behavior never changes visibility. The native `<dialog>` path (`initDialog`) is the default and gets the trap for free. |
 | Keyboard-shortcut hint (`.ui-shortcut`, `.ui-shortcut__sep`) | Stable additive | Class names for the chord/sequence hint over `.ui-kbd` are public. Ships in the core layer (class-only, no recipe). |
 | Generated docs shipped in npm | Stable paths | `llms.txt` and exported docs paths stay shipped and resolvable within a compatible minor. Markdown/text assets are for reading unless your runtime has a loader. Generated content may change with the source contract. |
 | Demo, examples, tests, scripts | Internal | Useful for learning and verification, but not shipped runtime API unless a path is explicitly exported in `package.json`. |

package/docs/term.md

@@ -0,0 +1,81 @@
+# Term & Glossary
+
+`@ponchia/ui/css/term.css` is an opt-in **inline glossary** — the accessible
+upgrade of the famously touch/keyboard-broken `abbr[title]`. A dotted-underline
+term whose definition lives in real, reachable DOM via the native `[popover]` +
+`popovertarget` pairing, plus a `ui-glossary` `<dl>` that collects every term at
+the end of a document. Jargon that explains itself inline and gathers into a
+reference.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/term.css';
+```
+
+## How it behaves
+
+- The term is a real `<button>`, so it is keyboard- and touch-reachable — the
+  exact failure of `abbr[title]`, which only reveals on desktop hover.
+- The definition is a native popover: `popovertarget` gives open/close, Esc, and
+  light-dismiss for free, with no JavaScript.
+- Where CSS anchor positioning exists the definition opens beside the word and
+  flips at the viewport edge; otherwise it falls back to a centred top-layer card.
+
+## Wiring — native popover pairing
+
+The host owns the `popovertarget` ↔ `id` wiring. No Bronto kernel is involved.
+
+```html
+<p>
+  We held the
+  <button class="ui-term" popovertarget="def-eb">error budget</button>
+  through the change.
+  <span class="ui-def" popover id="def-eb">
+    The amount of unreliability a service is allowed before its SLO is breached.
+  </span>
+</p>
+```
+
+To anchor the definition to its term where supported, set a matching
+`anchor-name` on the button and `position-anchor` on the `.ui-def` (a
+progressive enhancement; the centred fallback works everywhere):
+
+```css
+#def-eb {
+  position-anchor: --eb;
+}
+.ui-term[popovertarget='def-eb'] {
+  anchor-name: --eb;
+}
+```
+
+The end-of-document glossary is a plain `<dl>`:
+
+```html
+<dl class="ui-glossary">
+  <dt class="ui-glossary__term">Error budget</dt>
+  <dd class="ui-glossary__def">The unreliability a service may spend before its SLO breaches.</dd>
+  <dt class="ui-glossary__term">p95</dt>
+  <dd class="ui-glossary__def">The 95th-percentile value of a latency distribution.</dd>
+</dl>
+```
+
+## Class reference
+
+| Class                 | Role                                                              |
+| --------------------- | ---------------------------------------------------------------- |
+| `.ui-term`            | The inline term `<button>` (dotted underline "has a definition"). |
+| `.ui-def`             | The definition body — a native `[popover]` styled as a raised card. |
+| `.ui-glossary`        | The end-of-document `<dl>` two-column glossary block.            |
+| `.ui-glossary__term`  | A glossary `<dt>` (mono, the term).                              |
+| `.ui-glossary__def`   | A glossary `<dd>` (the definition).                              |
+
+## Accessibility & robustness
+
+- Because the term is a `<button popovertarget>`, the definition is reachable by
+  **keyboard and touch**, not just hover — the whole point versus `abbr[title]`.
+- The definition is real DOM in reading order, so a screen reader encounters it
+  right after the term.
+- Popovers don't print; the **printed document leans on the `ui-glossary` block**,
+  so include it at the end of any report that uses inline terms.
+- On narrow viewports the glossary stacks each term over its definition.

package/docs/textref.md

@@ -0,0 +1,78 @@
+# Textref
+
+`@ponchia/ui/css/textref.css` is an opt-in **deep-link-to-the-cited-sentence**
+provenance primitive. A citation whose `href` is a URL [Text
+Fragment](https://developer.mozilla.org/en-US/docs/Web/Text_fragments)
+(`#…:~:text=`): the browser scrolls to the exact quoted text and highlights it,
+and Bronto owns the on-brand `::target-text` paint. It is the inline counterpart
+to the static `ui-src` / `ui-citation` trust layer (`sources.css`), which can
+label a source but cannot point *inside* it.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/textref.css';
+```
+
+## How it behaves
+
+- The link navigates to the document and the browser scrolls to + highlights the
+  first match of the quoted text — no script, no anchors to pre-place.
+- Bronto repaints that browser highlight (`::target-text`) in the rationed
+  accent wash so it matches the rest of the trust layer.
+- On engines without Text Fragments the link still navigates to the page (or its
+  `#section` anchor); the highlight is purely additive, so nothing breaks.
+
+## Wiring — the host builds the fragment URL
+
+`::target-text` highlighting is driven entirely by the URL; Bronto ships no
+runtime for it. Build the `href` with a three-line pure helper and drop it on the
+`.ui-textref` link:
+
+```js
+// Encode a quote as a URL Text Fragment directive.
+// encodeTextFragment('p95 latency fell 38%') -> '#:~:text=p95%20latency%20fell%2038%25'
+export function encodeTextFragment(quote, { prefix } = {}) {
+  const enc = (s) => encodeURIComponent(s).replace(/-/g, '%2D');
+  const text = prefix ? `${enc(prefix)}-,${enc(quote)}` : enc(quote);
+  return `#:~:text=${text}`;
+}
+```
+
+```html
+<p>
+  The migration cut p95 latency by 38%
+  <a
+    class="ui-textref"
+    href="https://example.com/incident-review#:~:text=p95%20latency%20fell%2038%25"
+    >jump to the source</a
+  >.
+</p>
+```
+
+Notes for an autonomous author:
+
+- Text Fragment navigation requires a **user activation** (a real click) on most
+  engines — it will not fire from a programmatic `location.assign`.
+- Keep the quote short and verbatim; a fuzzy or paraphrased quote won't match.
+- Use the optional `prefix` (a `prefix-,` directive) to disambiguate a quote that
+  appears more than once on the target page.
+
+## Class reference
+
+| Class         | Role                                                                |
+| ------------- | ------------------------------------------------------------------- |
+| `.ui-textref` | A citation link whose `href` is a `#:~:text=` fragment; dotted underline + quote-jump cue. |
+
+| Custom property        | On            | Meaning                                                                   |
+| ---------------------- | ------------- | ------------------------------------------------------------------------- |
+| `--textref-highlight`  | `.ui-textref` | The `::target-text` wash for the matched sentence (default `var(--accent-soft)`). |
+
+## Accessibility & robustness
+
+- The link is a real `<a href>` — keyboard- and screen-reader-reachable, and it
+  degrades to ordinary navigation everywhere.
+- `::target-text` is repainted with the system highlight colours under
+  `forced-colors`, so the landed-on sentence stays visible in high-contrast mode.
+- The highlight is **global** once this leaf is imported: any text-fragment
+  landing on the page gets the brand wash, which keeps provenance highlighting
+  consistent across a report.

package/docs/theming.md

@@ -19,17 +19,40 @@ theme-owned neutral ramp endpoint:
 | `--field-dot-accent`  | `--accent` at 78% / 82%                       | form dot indicators |
 | `--focus-ring`        | `var(--accent)` (solid)                       | **every focus outline** — override to tune the ring alone |
 
-So a full re-brand is one declaration — globally or on any subtree:
+So a full re-brand is one declaration **at `:root` (or a theme root)**:
 
 ```css
 :root      { --accent: #2f6df6; }   /* brand the whole app blue   */
-.promo     { --accent: #16a34a; }   /* …or just this section green */
 :root[data-theme='dark'] { --accent: #6ea8ff; } /* per-theme tuning */
 ```
 
 Everything — buttons, focus rings, dot motifs, accent borders, soft
 fills — follows automatically, in both light and dark.
 
+> **Re-branding a subtree (not `:root`) is only a *partial* re-brand.**
+> The derived family (`--accent-soft`, `--accent-strong`, `--accent-text`,
+> `--bg-accent`, the `--accent-1…6` ramp) is computed from `--accent` via
+> `color-mix()` **at `:root`**, where it resolves once. A custom property's
+> value is substituted where it's declared, so overriding only `--accent`
+> on a `.promo` subtree re-brands the surfaces that read raw `var(--accent)`
+> (focus rings, dot motifs, some borders) but leaves every *derived* surface
+> (soft fills, accent-as-text, the ramp) at the root hue — a visibly broken
+> half-rebrand. To re-brand a subtree fully, set the derived tokens you use
+> too, e.g.:
+>
+> ```css
+> .promo {
+>   --accent: #16a34a;
+>   --accent-strong: color-mix(in srgb, var(--accent) 83%, #000);
+>   --accent-text: var(--accent-strong);
+>   --accent-soft: color-mix(in srgb, var(--accent) 10%, transparent);
+>   --bg-accent: color-mix(in srgb, var(--accent) 6%, transparent);
+> }
+> ```
+>
+> When in doubt, re-brand at `:root`/`[data-theme]` — that path re-derives
+> the whole family for you.
+
 > **Two contrast obligations when you change `--accent`:**
 >
 > 1. **Buttons** — pick an `--accent` with ≥ 4.5:1 against `--button-text`
@@ -46,6 +69,13 @@ fills — follows automatically, in both light and dark.
 > ring is solid `--accent` (≥ 3:1 non-text) — re-brand to a near-`--bg`
 > hue and you must also raise `--focus-ring` (it's an independent knob).
 
+> **Re-inking accent fills: use `--button-text`, not `--on-accent`.** In-DOM
+> components (buttons, chips, accent fills) paint their on-accent ink from
+> `--button-text`. `--on-accent` is a **read-only export** of that resolved ink
+> for *foreign renderers* (charts, canvas, a non-DOM target reading the token) —
+> overriding it in CSS validates but does **not** change any in-DOM component. To
+> change the ink on a re-brand, set `--button-text`.
+
 ## Other supported knobs
 
 - **Spacing** — override the `--space-2xs … --space-2xl` scale, or use a
@@ -182,9 +212,12 @@ you have, so the one-accent discipline holds.
   skin on a subtree would leave that family stale, so the selectors are
   `:root`-anchored and a subtree skin simply no-ops.
 - **Phosphor bloom.** The `amber-crt` / `phosphor-green` skins set
-  `--dotmatrix-glow` (a Tier-3 display knob, default `0`) in dark, so the
-  dot-matrix gains a CRT-style glow. Set it yourself on any `.ui-dotmatrix`
-  to tune the bloom.
+  `--dotmatrix-glow` in dark, so the dot-matrix gains a CRT-style glow. It is a
+  Tier-3 *display knob* — a `--dotmatrix-*` CSS custom property with an inline
+  default of `0` (off), like `--dotmatrix-dot`/`--dotmatrix-gap`, **not** a token
+  in the palette export (Tier-3 display expression lives as `--dotmatrix-*` knobs
+  in `css/dots.css`, by ADR-0001). Set it yourself on any `.ui-dotmatrix` to tune
+  the bloom.
 - **Contrast-gated.** Every shipped skin accent meets the same WCAG AA / 3:1
   floors as the core palette — see [contrast.md](contrast.md) → "Display
   colorways". (Your _own_ `--accent` re-brand is still your obligation; the
@@ -210,6 +243,12 @@ const series = charts.dark.categorical; // ['#ff3b41', '#e69f00', …] — serie
   `var(--accent)` (your brand leads), series 2–8 are the Okabe-Ito
   colourblind-safe set. The set is **gated for mutual distinguishability under
   normal + simulated protanopia/deuteranopia/tritanopia** (OKLab ΔE).
+  **Caveat — the CVD gate measures the SHIPPED default accent.** Series 1 is
+  `var(--accent)`, so if you re-skin `--accent` you change series 1 but not the
+  Okabe-Ito 2–8, and the gate never re-checks your custom hue: a brand close to
+  series 3's orange can collide for a deuteranope. If a re-brand drives data-viz,
+  re-verify your accent against the set, or pin `--chart-1` to a fixed Okabe-Ito
+  value (`--chart-1: #0072b2`) and let your brand lead the UI only.
 - **Sequential `--chart-seq-1..6`** — single-hue light→dark, for
   heatmaps/intensity. **Diverging `--chart-div-1..7`** — blue↔neutral↔orange,
   for ±/gains-losses.

package/docs/toc.md

@@ -0,0 +1,83 @@
+# Table of contents (scrollspy)
+
+`@ponchia/ui/css/toc.css` is an opt-in **sticky contents rail** for long
+generated reports. The entry for the section currently in view is highlighted, so
+a reader always knows where they are. It degrades to a plain anchored list with
+zero JavaScript.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/toc.css';
+```
+
+## How it behaves
+
+- The rail sticks within its scroll container (`--toc-top` sets the inset).
+- The active entry keys on the standard `aria-current="true"` hook — the same
+  rule every other nav surface here uses.
+- Nested lists indent for sub-sections.
+
+## Wiring — the host mirrors the in-view section
+
+CSS alone cannot know which section is on screen, so the host sets
+`aria-current="true"` on the link for the current section. Two ways:
+
+1. **Static** — server-render `aria-current` on the section you're rendering a
+   "current page" for. No script at all.
+2. **Live scrollspy** — a tiny `IntersectionObserver` (~15 lines, copy-paste
+   below) mirrors the in-view section onto its link. No Bronto kernel ships for
+   this; the rail is fully useful as a static sticky list without it.
+
+```html
+<nav class="ui-toc" aria-label="Contents">
+  <p class="ui-toc__title">Contents</p>
+  <ul class="ui-toc__list">
+    <li><a class="ui-toc__link" href="#intro" aria-current="true">Introduction</a></li>
+    <li><a class="ui-toc__link" href="#method">Method</a></li>
+    <li><a class="ui-toc__link" href="#results">Results</a></li>
+  </ul>
+</nav>
+```
+
+```js
+// Optional live scrollspy — mirror the in-view section onto its TOC link.
+const links = new Map(
+  [...document.querySelectorAll('.ui-toc__link')].map((a) => [a.hash.slice(1), a]),
+);
+const spy = new IntersectionObserver(
+  (entries) => {
+    for (const e of entries) {
+      if (!e.isIntersecting) continue;
+      for (const a of links.values()) a.removeAttribute('aria-current');
+      links.get(e.target.id)?.setAttribute('aria-current', 'true');
+    }
+  },
+  { rootMargin: '0px 0px -70% 0px' },
+);
+for (const id of links.keys()) {
+  const section = document.getElementById(id);
+  if (section) spy.observe(section);
+}
+```
+
+## Class reference
+
+| Class            | Role                                                       |
+| ---------------- | ---------------------------------------------------------- |
+| `.ui-toc`        | The sticky contents rail (`<nav>`).                        |
+| `.ui-toc__title` | Optional eyebrow heading for the rail.                     |
+| `.ui-toc__list`  | The list of entries (`<ul>`/`<ol>`; nests for sub-sections). |
+| `.ui-toc__link`  | An entry link; `aria-current="true"` marks the active one. |
+
+| Custom property | On        | Meaning                                                       |
+| --------------- | --------- | ------------------------------------------------------------- |
+| `--toc-top`     | `.ui-toc` | Sticky inset from the top of the scroll container (default `var(--space-md)`). |
+
+## Accessibility & robustness
+
+- The active cue is repainted with the system highlight under `forced-colors`,
+  so it survives high-contrast mode.
+- Wrap the rail in a `<nav aria-label="Contents">` so it is announced as a
+  navigation landmark.
+- Without the optional observer the rail is a normal anchored list — every link
+  still jumps to its section.

package/docs/tree.md

@@ -0,0 +1,74 @@
+# Tree (hierarchy outline)
+
+`@ponchia/ui/css/tree.css` is an opt-in **hierarchy outline** — a depth-indented
+view of nested structure (file trees, report contents, nested generated-content
+provenance, object graphs). It is built on nested native `<details>` (optionally
+`name` exclusive-accordion groups), so open/close, keyboard toggling and the
+open/close animation come from the platform. This leaf is the hierarchy *layer*
+(rails, indent, chevron); it does **not** reinvent the disclosure grammar
+`ui-accordion` already owns.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/tree.css';
+```
+
+## How it behaves
+
+- A **branch** is a `<details class="ui-tree__branch">`; a **leaf** is a plain
+  `.ui-tree__leaf` row with no disclosure.
+- Nested rows indent and carry a hairline guide rail back to their parent.
+- The summary's chevron rotates open; auto-height open/close is gated exactly like
+  `ui-accordion` (Chrome 131+/Safari 18.4+; Firefox snaps).
+
+## Wiring
+
+```html
+<div class="ui-tree">
+  <details class="ui-tree__branch" open>
+    <summary class="ui-tree__summary"><span class="ui-tree__label">src</span></summary>
+    <details class="ui-tree__branch">
+      <summary class="ui-tree__summary"><span class="ui-tree__label">components</span></summary>
+      <div class="ui-tree__leaf"><span class="ui-tree__label">button.css</span></div>
+      <div class="ui-tree__leaf"><span class="ui-tree__label">card.css</span></div>
+    </details>
+    <div class="ui-tree__leaf"><span class="ui-tree__label">index.js</span></div>
+  </details>
+</div>
+```
+
+Add `name="…"` to sibling `<details class="ui-tree__branch">` to make them an
+exclusive-accordion group (only one open at a time) — a platform behaviour, no
+script.
+
+## A11y honesty — disclosure group, not an ARIA tree
+
+A native `<details>` group is a **disclosure group**, not an ARIA `tree`. Do not
+bolt `role="tree"` / `role="treeitem"` / `aria-level` onto this markup: those
+roles imply a roving-focus keyboard model (Up/Down to move, Left/Right to
+collapse/expand, typeahead) that native `<details>` does not provide, so the
+result would announce a contract the keyboard can't honour.
+
+That roving-focus kernel is intentionally **not shipped** with this leaf. It
+lands behind a real consumer that needs the full APG tree interaction (e.g. a
+workbench file pane). Until then, the disclosure semantics are correct and
+honest as-is.
+
+## Class reference
+
+| Class                | Role                                                       |
+| -------------------- | ---------------------------------------------------------- |
+| `.ui-tree`           | The outline container.                                     |
+| `.ui-tree__branch`   | A `<details>` node with children (twist chevron).          |
+| `.ui-tree__leaf`     | A leaf row with no disclosure (chevron-aligned spacer).    |
+| `.ui-tree__summary`  | The branch's `<summary>` toggle row.                       |
+| `.ui-tree__label`    | The row label (truncates with ellipsis).                   |
+
+## Accessibility & robustness
+
+- Open/close, keyboard toggling (Enter/Space on the summary) and the exclusive
+  `name` grouping are all native `<details>` behaviour.
+- The chevron is `currentColor` geometry, so it survives `forced-colors`; the
+  open-branch accent cue is re-asserted with the system highlight.
+- The chevron spin and the auto-height animation both respect
+  `prefers-reduced-motion`.