@ponchia/ui 0.4.1 → 0.6.0

package/docs/sources.md

@@ -0,0 +1,137 @@
+# Sources, citations & provenance
+
+`@ponchia/ui/css/sources.css` is an opt-in **trust layer** for generated
+reports, AI output, audits, and docs — the grammar that answers _"where did
+this come from?"_. Generic UI kits have tags and footnotes; this is a small,
+explicit vocabulary for sources and their trust state.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/sources.css';
+```
+
+Bronto owns the visual grammar and the trust **states**. The host owns fetching,
+citation numbering, permission checks, and whether a source is actually
+trustworthy. The state is carried by a rationed tone **and** an author-written
+label, so it never relies on colour alone (WCAG 1.4.1). Not in the core bundle.
+
+## Trust states
+
+A cross-cutting trust-state class — `ui-src--verified`, `ui-src--stale`, and the
+rest in the table below — sets the tone on a citation chip, source card, or
+provenance item. Always pair it with a word: the colour is a second channel, not
+the only one.
+
+| State | Class | Tone |
+| --- | --- | --- |
+| Verified | `ui-src--verified` | success |
+| Reviewed (by a human) | `ui-src--reviewed` | accent |
+| Generated | `ui-src--generated` | info |
+| Unverified | `ui-src--unverified` | muted |
+| Stale | `ui-src--stale` | warning |
+| Conflict | `ui-src--conflict` | danger |
+
+A trust-state class **needs a host element** — on its own a tone class
+(`ui-src--verified` and the rest) only sets a `--src-tone`, it does not draw
+anything. The host is one of the elements below, or the standalone `.ui-src`
+pill.
+
+## Standalone trust pill — `.ui-src`
+
+When you just need a bare labelled chip (a row of provenance tags, an inline
+"verified" badge) with no surrounding card or citation, use `.ui-src` as the
+host and add a tone. It draws a small pill with a leading trust dot:
+
+```html
+<span class="ui-src ui-src--verified">Verified</span>
+<span class="ui-src ui-src--generated">AI-generated</span>
+<span class="ui-src ui-src--stale">Stale · 14d</span>
+```
+
+The base `.ui-src` is required — `<span class="ui-src--verified">` alone
+**validates against `classes.json` but renders nothing**, because the tone class
+only carries the colour for a host to consume. The word inside is the channel
+(WCAG 1.4.1); the dot and tint are reinforcement. Reach for `.ui-citation--chip`
+instead when the pill is a real link/button to the source.
+
+## Inline citation — `.ui-citation`
+
+A reference marker on a real `<a>` or `<button>` (the visual index is never the
+only label — give it an accessible name).
+
+```html
+<p>
+  Latency fell 38%<a class="ui-citation" href="#s1" aria-label="Source 1">[1]</a>.
+</p>
+
+<!-- Named-source pill, with a leading trust dot: -->
+<a class="ui-citation ui-citation--chip ui-src--verified" href="#s1">
+  Q3 incident review
+</a>
+```
+
+## Source card — `.ui-source-card`
+
+A single source preview: title, origin, time, excerpt, actions. The
+`border-inline-start` carries the trust tone.
+
+```html
+<article class="ui-source-card ui-src--generated">
+  <h3 class="ui-source-card__title">Model output — pricing summary</h3>
+  <p class="ui-source-card__origin">gpt-x · internal</p>
+  <p class="ui-source-card__time">2026-06-01 09:42</p>
+  <p class="ui-source-card__excerpt">The migration cut p95 latency by 38%…</p>
+  <div class="ui-source-card__actions">
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Open</button>
+  </div>
+</article>
+```
+
+The parts are `__title`, `__origin`, `__time`, `__excerpt` (the body text — not
+`__detail`/`__body`), and `__actions`. A card nests inside a
+`ui-source-list__item` when it sits in a references section (below).
+
+## Source list — `.ui-source-list`
+
+A references section: a reset list of source cards (or rows).
+
+```html
+<ol class="ui-source-list">
+  <li class="ui-source-list__item"><article class="ui-source-card ui-src--verified">…</article></li>
+  <li class="ui-source-list__item"><article class="ui-source-card ui-src--stale">…</article></li>
+</ol>
+```
+
+## Provenance — `.ui-provenance`
+
+A compact metadata row beside generated content — each `__item` carries a trust
+dot and a label.
+
+```html
+<p class="ui-provenance">
+  <span class="ui-provenance__item ui-src--generated">Generated</span>
+  <span class="ui-provenance__item ui-src--verified">3 sources</span>
+  <span class="ui-provenance__item ui-src--reviewed">Human-reviewed</span>
+</p>
+```
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.citation({ chip: true, state: 'verified' });
+// "ui-citation ui-citation--chip ui-src--verified"
+ui.source({ state: 'generated' }); // "ui-source-card ui-src--generated"
+ui.provenance({ state: 'reviewed' }); // "ui-provenance ui-src--reviewed"
+```
+
+## Accessibility & print
+
+- A citation must be a real link or button with a stable accessible name; the
+  bracketed index alone is not enough.
+- The trust state must be readable as text — the tone dot/border is decorative
+  reinforcement. Under `forced-colors`, dots and borders fall back to
+  `CanvasText`, so the label remains the channel.
+- Tone dots and the card's tone border carry `print-color-adjust: exact`, so
+  they survive printing; expand citation URLs in print where it helps the reader.

package/docs/spotlight.md

@@ -0,0 +1,78 @@
+# Spotlight (guided focus)
+
+`@ponchia/ui/css/spotlight.css` is an opt-in **guided-focus overlay** — a
+dimming layer with a cutout over a target element, an optional ring, and a
+callout note. It's the *visual language* of a product tour or onboarding step.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/spotlight.css';
+```
+
+**Bronto is not a tour engine.** It owns the look and (via `initSpotlight`)
+positions the cutout over a target. Step order, advancing, persistence, and
+whether the overlay is shown are the host's job — Bronto deliberately stays out
+of that state machine.
+
+## Markup
+
+```html
+<div
+  class="ui-spotlight ui-spotlight--ring"
+  data-bronto-spotlight
+  data-target="save-button"
+  role="region"
+  aria-label="Tour"
+>
+  <div class="ui-spotlight__hole"></div>
+
+  <div class="ui-tour-note" style="position: absolute; …place near the hole…">
+    <span class="ui-tour-note__step">Step 2 of 4</span>
+    <h2 class="ui-tour-note__title">Save your work</h2>
+    <p class="ui-tour-note__body">Changes autosave, but you can force a save here.</p>
+    <div class="ui-tour-note__actions">
+      <button class="ui-button ui-button--ghost" type="button">Skip</button>
+      <button class="ui-button" type="button">Next</button>
+    </div>
+  </div>
+</div>
+```
+
+```js
+import { initSpotlight } from '@ponchia/ui/behaviors';
+const stop = initSpotlight(); // positions the cutout; re-places on resize/scroll
+// Advance the tour by pointing at the next target — the cutout follows:
+document.querySelector('[data-bronto-spotlight]').dataset.target = 'next-thing';
+// Hide it when the tour ends (host-owned):
+document.querySelector('[data-bronto-spotlight]').hidden = true;
+```
+
+## Pieces
+
+| Class | Role |
+| --- | --- |
+| `ui-spotlight` | The fixed overlay. Non-blocking (`pointer-events: none`) — a visual highlight, not a modal trap. |
+| `ui-spotlight__hole` | The cutout. Dims the page via one box-shadow; positioned by `--spot-x/y/w/h`. |
+| `ui-spotlight--ring` | Adds an accent ring around the cutout. |
+| `ui-tour-note` | The callout card (re-enables pointer events for its controls). |
+| `ui-tour-note__step` / `__title` / `__body` / `__actions` | Callout parts. |
+
+`ui.spotlight({ ring })` builds the overlay class string.
+
+## How positioning works
+
+`initSpotlight` reads each `[data-bronto-spotlight]`'s `data-target` id, measures
+that element with `getBoundingClientRect`, and sets `--spot-x/y/w/h` (viewport
+coordinates) on the overlay. Because the overlay is `position: fixed`, those map
+directly. It re-places on resize, scroll, and whenever `data-target` changes —
+so stepping a tour is just updating `data-target`. `--spot-pad` insets the
+cutout from the target; `--spot-radius` rounds it.
+
+## Accessibility notes
+
+- The overlay is **non-blocking by design** (the dim is a box-shadow, not an
+  interaction trap). If a step must block interaction, that's a host concern —
+  add your own inert/`aria-hidden` handling around it.
+- Put the tour's real content in `.ui-tour-note` (a focusable region with a
+  heading), not in the visual dim, so screen-reader users get the same guidance.
+- Keep the callout's label stable and move focus to it when a step opens (host).

package/docs/stability.md

@@ -1,7 +1,12 @@
 # Public API Stability
 
 `@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
-patches are non-breaking. This matrix defines what counts as public API.
+patches are non-breaking. In practical terms: **PATCH releases (`0.5.x`) are
+non-breaking bug-fixes and additive changes — safe to upgrade without review;
+MINOR releases (`0.x.0`) may include breaking changes and consumers should
+review the CHANGELOG before upgrading.** Pin `~0.x` (tilde) to accept only
+patches, or `^0.x` only if you accept minor-level churn. This policy holds
+until `1.0.0` is tagged. This matrix defines what counts as public API.
 
 | Surface | Stability | Contract |
 | --- | --- | --- |
@@ -9,8 +14,11 @@ patches are non-breaking. This matrix defines what counts as public API.
 | JS module format | Stable | JS subpaths are ESM-only. CommonJS consumers use dynamic `import()`. |
 | CSS class names (`.ui-*`) | Stable | Names and documented modifier semantics are public. Internal selector structure and leaf-file boundaries may change. |
 | Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, recipe names, and option unions are public. |
+| Class vocabulary as data (`@ponchia/ui/classes.json`) | Stable additive | The JSON shape (`groups`/`classes`/`states`/`customProperties`) and its entries are public — for validating markup from a non-JS/non-TS host. Generated from `cls` (the `classes` list cannot drift from the CSS); `states`/`customProperties` are gated against the stylesheet. New classes/hooks are additive. |
 | Design tokens | Stable names/roles | Token names and documented roles are public. Exact values and generated colour math outputs may change for visual tuning before 1.0. |
 | `--accent-1..6` | Stable names/roles | A subtle-to-bold accent ramp derived from `--accent`. Exact resolved values are visual tuning; algorithm changes require release-note visibility and resolver/browser checks. |
+| Tokens as data (`tokens.json`, `tokens.dtcg.json`, `tokens/resolved.json`) | Stable additive | The JSON shapes are public for non-CSS/non-JS consumers. `resolved.json` exposes `light`/`dark` (resolved colours) and `scale` (resolved non-colour scales). Token names/roles are stable; exact resolved values are visual tuning (pin `~0.x`). |
+| Theme axes | Mixed | `data-theme` (light/dark) is the **contractual** base. `data-surface="oled"`, `data-density`, and `data-contrast` are **convenience presets** — best-effort visual variants, **not** part of the stability contract; their presence and exact values may change for tuning. (A computed-style smoke test guards the OLED `--bg` flip; the others are unverified.) |
 | Behavior attributes (`data-bronto-*`) | Stable | Attribute names and documented markup relationships are public. Behavior internals are not. |
 | Behavior functions (`@ponchia/ui/behaviors`) | Stable | Exported function names, option names, custom events, SSR no-op behavior, idempotency, and cleanup-returning contract are public. |
 | Glyph registry/renderers (`@ponchia/ui/glyphs`) | Stable additive | Existing glyph names stay valid. New glyphs are additive. Renderer option names and accessibility defaults are public. |
@@ -18,7 +26,21 @@ patches are non-breaking. This matrix defines what counts as public API.
 | React/Solid/Qwik bindings | Stable thin adapters | Hook/primitive names, optional peer behavior, root ref/signal/resolver support, and cleanup lifecycle are public. They remain wrappers over vanilla behaviors, not component APIs. |
 | Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. |
 | Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. Exact palette values may tune if gates and release notes justify it. |
-| Reports (`css/report.css`, `.ui-report*`, `.ui-chart*`, print utilities) | Stable additive | Report class names, BEM part names, chart helper class names, and print utility names are public. Report CSS is opt-in and not imported by the default bundle. |
+| Reports (`css/report.css`, `.ui-report*`, print utilities) | Stable additive | Report class names, BEM part names, and print utility names are public. Report CSS is opt-in and not imported by the default bundle. The data key now lives in the standalone Legends layer (below), not `css/report.css`; charting is via the Vega theme target (`@ponchia/ui/vega`, see [vega](./vega.md)) or a token-themed inline SVG, not a shipped renderer. |
+| Annotations (`@ponchia/ui/annotations`, `css/annotations.css`, `.ui-annotation*`) | Stable additive | SVG annotation class names, recipe option names, and helper function names are public. Helper internals and exact path-control heuristics may tune before 1.0. |
+| Legends (`css/legend.css`, `.ui-legend*`, `@ponchia/ui/behaviors` `initLegend`) | Stable additive | Legend class names, recipe option names, and the `bronto:legend:toggle` event contract (`aria-pressed="true"` ⇒ shown) are public. Opt-in, not in the default bundle; swatch colours are gated to the `--chart-*` palette. |
+| Marks (`css/marks.css`, `.ui-mark*`, `.ui-bracket-note*`) | Stable additive | Text-mark and bracket-note class names and recipe option names are public. Opt-in, not in the default bundle. Uses semantic tones only. |
+| Connectors (`@ponchia/ui/connectors`, `css/connectors.css`, `.ui-connector*`, `initConnectors`) | Stable additive | Connector class names, the `data-bronto-connector` attribute contract, geometry helper function names, and recipe options are public. Helper internals/heuristics may tune before 1.0. Opt-in, not in the default bundle. |
+| Spotlight (`css/spotlight.css`, `.ui-spotlight*`, `.ui-tour-note*`, `initSpotlight`) | Stable additive | Spotlight/tour-note class names, the `--spot-*` custom-property contract, and the `data-bronto-spotlight`/`data-target` attributes are public. Opt-in, not in the default bundle. Not a tour engine. |
+| Crosshair (`css/crosshair.css`, `.ui-crosshair*`, `.ui-readout`, `initCrosshair`) | Stable additive | Crosshair/readout class names, the `--crosshair-x/y` properties, the `data-bronto-crosshair` attribute, and the `bronto:crosshair:move`/`:leave` event contract are public. Opt-in. Reports pointer position only — no data mapping. |
+| Selection states (`css/selection.css`, `.ui-sel*`) | Stable additive | The `.ui-sel`/`--on`/`--off`/`--maybe` emphasis classes and recipe options are public. Opt-in, cross-cutting. The host owns selection logic; Bronto only styles the states. |
+| Analytical roll-up (`css/analytical.css`) | Stable additive | A convenience `@import` of the seven analytical leaves (annotations, legend, marks, connectors, spotlight, crosshair, selection). The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
+| Sources / provenance (`css/sources.css`, `.ui-citation*`, `.ui-source-card*`, `.ui-source-list*`, `.ui-provenance*`, `.ui-src--*`) | Stable additive | Citation/source/provenance class names, the cross-cutting `.ui-src--*` trust-state modifiers (always paired with an author label), and the `ui.citation`/`ui.source`/`ui.provenance` recipes + `cls.sourceList` are public. Opt-in, not in the default bundle. |
+| Lifecycle state (`css/state.css`, `.ui-state*`, `.ui-syncbar`) | Stable additive | The `.ui-state`/`__label`/`__detail`/`--busy` classes, the canonical lifecycle state modifiers, `.ui-syncbar`, and the `ui.state` recipe are public. Opt-in, not in the default bundle. |
+| 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. |
+| 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/state.md

@@ -0,0 +1,85 @@
+# Lifecycle & system state
+
+`@ponchia/ui/css/state.css` is an opt-in vocabulary for the states real apps
+spend their time in — saving, saved, queued, offline, stale, conflicted, locked,
+reviewed. These are usually improvised per product, so even good apps feel
+inconsistent. This is the canonical set: a labelled state object with a rationed
+tone, plus a page/document sync bar.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/state.css';
+```
+
+Bronto ships the visual states and the canonical wording. The host owns the
+state machine, retry policy, persistence, and announcements. **Persistent state
+deserves persistent UI** — a toast is secondary, not the answer. The tone is a
+second channel; the **label is the state**, so it survives forced-colors and
+screen readers (WCAG 1.4.1).
+
+## `.ui-state`
+
+A leading tone dot, a `__label`, and an optional `__detail`. Add `--busy` to
+pulse the indicator for an in-progress state (reduced-motion-safe).
+
+```html
+<span class="ui-state ui-state--saving ui-state--busy">
+  <span class="ui-state__label">Saving…</span>
+</span>
+
+<span class="ui-state ui-state--saved">
+  <span class="ui-state__label">Saved</span>
+  <span class="ui-state__detail">2m ago</span>
+</span>
+```
+
+## State matrix
+
+Use the canonical label; the modifier bakes in the tone.
+
+| State | Class | Canonical label | Tone | Busy? |
+| --- | --- | --- | --- | --- |
+| Saving | `ui-state--saving` | "Saving…" | accent | yes |
+| Saved | `ui-state--saved` | "Saved" / "All changes saved" | success | — |
+| Queued | `ui-state--queued` | "Queued" / "Pending" | muted | — |
+| Offline | `ui-state--offline` | "Offline" | warning | — |
+| Stale | `ui-state--stale` | "Out of date" | warning | — |
+| Conflict | `ui-state--conflict` | "Conflict" | danger | — |
+| Error | `ui-state--error` | "Failed" / "Couldn't save" | danger | — |
+| Locked | `ui-state--locked` | "Locked" / "Read-only" | muted | — |
+| Reviewed | `ui-state--reviewed` | "Reviewed" | success | — |
+| Needs review | `ui-state--needs-review` | "Needs review" | warning | — |
+
+"Syncing" and "Retrying" are the saving tone with their own label — use
+`ui-state--saving ui-state--busy` and write the word.
+
+## `.ui-syncbar`
+
+A page- or document-level status strip: a state on one side, optional actions on
+the other.
+
+```html
+<div class="ui-syncbar">
+  <span class="ui-state ui-state--saved">
+    <span class="ui-state__label">All changes saved</span>
+    <span class="ui-state__detail">just now</span>
+  </span>
+  <button class="ui-button ui-button--subtle ui-button--sm" type="button">View history</button>
+</div>
+```
+
+## Recipe
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.state({ state: 'saving', busy: true }); // "ui-state ui-state--saving ui-state--busy"
+ui.state({ state: 'conflict' }); // "ui-state ui-state--conflict"
+```
+
+## Scope
+
+CSS only — there is no JS yet. Auto-updating elapsed time ("2m ago") or live
+progress text is the host's job; a small optional behavior may come later if a
+real consumer needs it. Background-job progress and conflict-resolution
+affordances are deliberately deferred until then.

package/docs/usage.md

@@ -39,6 +39,14 @@ All three are small. They are **not** interchangeable:
 Rule of thumb: state → dot, classification → badge, user-controlled value
 → chip.
 
+**Tone vocabulary varies by family — by design.** Colour is rationed, so not
+every component carries every tone: `--info`/`--muted` exist on some families
+(badge, dot, state) and not others (alert/toast/meter lead with
+`--success`/`--warning`/`--danger`). The authoritative per-component tone list is
+each base's `modifiers` array in
+[`@ponchia/ui/classes.json`](../classes/classes.json) — read it rather than
+extrapolating a tone you saw on one component onto another.
+
 ## Numbers: `ui-num` vs the table state classes
 
 - Inside `.ui-table`, a numeric cell is `.is-num` (+ `.is-pos` /
@@ -70,10 +78,11 @@ for narrative body content you do not fully control.
 
 Do not turn every report block into a card. Use `ui-report__summary`,
 `ui-report__finding`, and `ui-report__evidence` for document structure; use
-`ui-card` only when the block is genuinely a repeated card item. Charts use
-the report `ui-chart*` wrappers plus the opt-in data-viz tokens; simple static
-bar charts can use `ui-chart__plot`, `ui-chart__bar`, and `ui-chart__fill`.
-Always include a caption and fallback data. Full LLM/static report cookbook:
+`ui-card` only when the block is genuinely a repeated card item. bronto ships
+**no chart component**: for a chart, theme Vega-Lite (`@ponchia/ui/vega`, see
+[vega.md](vega.md)) or hand-author a token-themed inline SVG painted from the
+data-viz palette tokens. Always wrap it in a `ui-report__figure` with a caption,
+a `.ui-legend` key, and fallback data. Full LLM/static report cookbook:
 [reporting.md](reporting.md).
 
 ## Buttons: variant and size
@@ -102,6 +111,13 @@ destructive action).
 | toast    | transient, out-of-flow, system-initiated. Danger toasts route to an assertive live region; everything else polite. |
 | tooltip  | supplemental, hover/focus, never essential info (it's not announced reliably; don't hide required content in it). |
 
+The CSS `ui-tooltip` is hover/focus-only and CSS can't wire it to assistive
+tech for you — associate the bubble with its trigger yourself, or it conveys
+nothing to a screen reader: give `.ui-tooltip__bubble` an `id`, point the
+trigger's `aria-describedby` at it, and keep the bubble `role="tooltip"`. For a
+tooltip that must stay visible near a viewport edge or inside a scroll
+container, use `initPopover` (a real focus-managed panel) instead.
+
 ## Meter vs progress
 
 Both are a thin horizontal bar; they mean different things.
@@ -135,6 +151,37 @@ this much* → meter.
   (`aria-hidden`) and the input keeps its full width. Don't hand-roll an
   absolute overlay.
 
+## Navigation: the landmarks and names the classes don't carry
+
+The navigation classes are styling only — the ARIA scaffolding is yours, and
+without it these widgets are unlabelled or unannounced:
+
+- **`ui-breadcrumb`** — wrap it in `<nav aria-label="Breadcrumb">` and mark the
+  last (current) crumb with `aria-current="page"`.
+- **`ui-pagination`** — wrap it in `<nav aria-label="Pagination">`; give the
+  current page `aria-current="page"`; label icon-only prev/next controls
+  (`aria-label="Previous page"`). Disable a control with native `disabled`
+  (a `<button>`) **or** `aria-disabled="true"` — both now render disabled and
+  are non-interactive; don't ship an `aria-disabled` control that still acts.
+- **`ui-tabs`** — `initTabs` adds the full APG wiring (roles, roving tabindex,
+  `aria-selected`, panel `hidden`, focusable panel). If you wire tabs yourself,
+  name the `ui-tabs__list` (`role="tablist"` + an `aria-label`) and pair each
+  tab with its panel via `aria-controls`/`aria-labelledby`.
+- **`ui-sitenav` / `ui-app-nav`** — signal the current link with
+  `aria-current="page"` (both honour it; `ui-app-nav` also accepts the
+  visual-only `.is-active`, but prefer `aria-current`).
+- **`ui-skiplink`** — keep it the first focusable element and point its `href`
+  at the `id` of your main landmark.
+
+## Avatar: it's an unlabelled blob until you name it
+
+`ui-avatar` is a presentation box. Give it an accessible name yourself: an
+image avatar needs real `alt` text (`alt=""` only if it's purely decorative
+beside a visible name); an initials avatar needs an accessible name on the
+element (e.g. `aria-label="Ada Lovelace"`) because the initials alone don't
+convey identity to AT. Keep initials to ~2 characters — the box is
+`overflow: hidden` and silently clips a third.
+
 ## Modal: native `<dialog>` vs `is-open`
 
 Prefer the **native `<dialog>`** path — you get top-layer, backdrop and
@@ -181,6 +228,13 @@ that fuses the cells into a square, gapless pixel glyph that stays crisp and
 legible down to **~16px** — so the same set doubles as real inline UI icons,
 not just decoration. (Below the dot fragments into dot-soup; solid does not.)
 
+One caveat on ink: `solid` cells inherit the dot palette (`--field-dot-hot`,
+~40% alpha), so at small sizes a solid glyph reads as a soft grey, not full
+ink. When you want a crisp, full-strength small icon (toolbar, button affordance),
+use the one-node mask renderer instead — `renderGlyph(name, { render: 'mask' })`
+paints the glyph in `currentColor` on a `.ui-icon`, so it tracks text colour at
+any size.
+
 `renderGlyph(name, { label })` returns an SSR-safe string: decorative
 (`aria-hidden`) by default, or `role="img"` + `aria-label` when you pass a
 `label` — which is how it conveys meaning to assistive tech. Prefer the
@@ -263,6 +317,71 @@ dashboards: `--chart-1..8` (categorical), `--chart-seq-*` (sequential),
   Cap a chart at ~8 series. Full detail in [theming.md](theming.md) →
   "Data-viz palette".
 
+## SVG annotations: subject, connector, note
+
+`@ponchia/ui/css/annotations.css` (opt-in) adds Bronto-styled SVG annotations
+for reports and chart figures. It is a visual grammar, not a charting or
+authoring engine.
+
+- Compose each callout from `ui-annotation` plus a subject
+  (`ui-annotation__subject`), connector (`ui-annotation__connector`), and note
+  (`ui-annotation__note`, `ui-annotation__title`, `ui-annotation__label`).
+- Use `ui.annotation({ variant, tone, motion })` when building class strings in
+  JS. The default is a callout in the accent tone; motion is always opt-in.
+- Use `@ponchia/ui/annotations` when you want deterministic SVG path strings
+  for circle, rect, threshold, bracket, band, slope, comparison, cluster, axis,
+  timeline, line, elbow, or curve annotations. Use `notePlacement()` for a
+  single bounded note when you need a conservative first placement pass.
+- Status tones are only for status-bearing callouts; otherwise use `accent` for
+  the main insight and `muted` for secondary labels.
+- Keep annotated charts sparse. Dense figures need a scrollable SVG, a
+  simplified mobile SVG, or complete caption/fallback text.
+- Annotation text must be visible or represented in the figure caption, SVG
+  `<desc>`, or fallback table. Full detail in [annotations.md](annotations.md).
+
+## Forms: the contracts the markup alone won't tell you
+
+- **Disabled — pick one mechanism.** Use the native `disabled` attribute for a
+  genuinely inert control (`ui-input`, `ui-select`, `ui-textarea`, `ui-switch`
+  /`ui-check`/`ui-segmented` wrapping a native input, `ui-range`, `ui-file`,
+  `ui-button`): the browser greys it, blocks activation, and skips it in tab
+  order, and bronto styles the disabled cue. Use `aria-disabled="true"` **only**
+  when the control must stay focusable/announced — bronto then adds
+  `pointer-events: none` to `ui-button`/`ui-link` so it can't be activated, but
+  you still own removing it from the submit logic.
+- **Combobox** (`data-bronto-combobox`) reads its options from the DOM at
+  `initCombobox()` time — re-run it after you replace the option list. The
+  `<input>` owns the value; the listbox is a view.
+- **Validation** is opt-in via `data-bronto-validate` on the form plus
+  `initFormValidation()`; it surfaces messages into a `ui-error-summary` you
+  provide. The summary's title is the legible sans, not the display face — it's
+  meant to be read.
+
+## Reveal: `ui-reveal` needs JS, `ui-scroll-reveal` doesn't
+
+`ui-scroll-reveal` is scroll-driven and **zero-JS** — reach for it in a static
+or LLM-authored report. `ui-reveal` is the JS variant: it starts hidden and you
+toggle `is-visible` (e.g. from an `IntersectionObserver` you own) to play it in.
+With scripting disabled it degrades to fully visible, but if scripting is *on*
+and nothing toggles `is-visible`, the content stays hidden — so only use
+`ui-reveal` when you are wiring that toggle.
+
+## Loading affordances need a role you supply
+
+`ui-spinner`, `ui-dotspinner`, `ui-skeleton`, and an indeterminate `ui-progress`
+are decorative animations — bronto can't know their semantics. Give the busy
+region `aria-busy="true"` (or `role="status"` with an `aria-live` text label like
+"Loading…"), and mark a purely decorative spinner `aria-hidden="true"`. Without
+one of these a screen reader announces nothing while the user waits.
+
+## Popover: prefer the native top layer
+
+`initPopover()` shows a `.ui-popover` in the browser **top layer** when the panel
+carries the native `popover` attribute (never clipped by `overflow`/stacking);
+without it, it falls back to an `is-open` class that a clipping ancestor can cut
+off. Add `popover` to the panel for the robust path — the `is-open` form is a
+fallback, not the default to copy.
+
 ## When to add a behavior
 
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*