@ponchia/ui 0.4.1 → 0.6.0

package/docs/reference.md

@@ -9,8 +9,11 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 303 classes across 121 component groups
+- 477 classes across 149 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
+- Validate markup as data (no JS/TS): `@ponchia/ui/classes.json` — the same
+  vocabulary as language-neutral JSON (`groups`, `classes`, `states`,
+  `customProperties`), for an external linter or non-JS host
 - Tokens as data: `import { cssVars, tokens, themeColor } from '@ponchia/ui/tokens'`
 
 ## Classes
@@ -66,6 +69,46 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.animateMatrix` | `ui-animate-matrix` | base |
 
+### `.ui-annotation`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.annotation` | `ui-annotation` | base |
+| `cls.annotationBadge` | `ui-annotation__badge` | part |
+| `cls.annotationConnector` | `ui-annotation__connector` | part |
+| `cls.annotationConnectorEnd` | `ui-annotation__connector-end` | part |
+| `cls.annotationLabel` | `ui-annotation__label` | part |
+| `cls.annotationNote` | `ui-annotation__note` | part |
+| `cls.annotationNoteLine` | `ui-annotation__note-line` | part |
+| `cls.annotationSubject` | `ui-annotation__subject` | part |
+| `cls.annotationTitle` | `ui-annotation__title` | part |
+| `cls.annotationAccent` | `ui-annotation--accent` | modifier |
+| `cls.annotationAxis` | `ui-annotation--axis` | modifier |
+| `cls.annotationBadgeVariant` | `ui-annotation--badge` | modifier |
+| `cls.annotationBand` | `ui-annotation--band` | modifier |
+| `cls.annotationBracket` | `ui-annotation--bracket` | modifier |
+| `cls.annotationCallout` | `ui-annotation--callout` | modifier |
+| `cls.annotationCircle` | `ui-annotation--circle` | modifier |
+| `cls.annotationCluster` | `ui-annotation--cluster` | modifier |
+| `cls.annotationCompare` | `ui-annotation--compare` | modifier |
+| `cls.annotationCurve` | `ui-annotation--curve` | modifier |
+| `cls.annotationDanger` | `ui-annotation--danger` | modifier |
+| `cls.annotationDraw` | `ui-annotation--draw` | modifier |
+| `cls.annotationElbow` | `ui-annotation--elbow` | modifier |
+| `cls.annotationEvidence` | `ui-annotation--evidence` | modifier |
+| `cls.annotationFocus` | `ui-annotation--focus` | modifier |
+| `cls.annotationInfo` | `ui-annotation--info` | modifier |
+| `cls.annotationLabelVariant` | `ui-annotation--label` | modifier |
+| `cls.annotationMuted` | `ui-annotation--muted` | modifier |
+| `cls.annotationPulse` | `ui-annotation--pulse` | modifier |
+| `cls.annotationRect` | `ui-annotation--rect` | modifier |
+| `cls.annotationReveal` | `ui-annotation--reveal` | modifier |
+| `cls.annotationSlope` | `ui-annotation--slope` | modifier |
+| `cls.annotationSuccess` | `ui-annotation--success` | modifier |
+| `cls.annotationThreshold` | `ui-annotation--threshold` | modifier |
+| `cls.annotationTimeline` | `ui-annotation--timeline` | modifier |
+| `cls.annotationWarning` | `ui-annotation--warning` | modifier |
+
 ### `.ui-app-content`
 
 | Registry key | Class | Kind |
@@ -122,7 +165,6 @@ each one matches a real selector in the stylesheet.
 | `cls.appRailAccount` | `ui-app-rail__account` | part |
 | `cls.appRailBrand` | `ui-app-rail__brand` | part |
 | `cls.appRailFoot` | `ui-app-rail__foot` | part |
-| `cls.appRailToggle` | `ui-app-rail__toggle` | part |
 
 ### `.ui-app-shell`
 
@@ -172,6 +214,18 @@ each one matches a real selector in the stylesheet.
 | `cls.badgeSuccess` | `ui-badge--success` | modifier |
 | `cls.badgeWarning` | `ui-badge--warning` | modifier |
 
+### `.ui-bracket-note`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.bracketNote` | `ui-bracket-note` | base |
+| `cls.bracketNoteLabel` | `ui-bracket-note__label` | part |
+| `cls.bracketNoteAccent` | `ui-bracket-note--accent` | modifier |
+| `cls.bracketNoteDanger` | `ui-bracket-note--danger` | modifier |
+| `cls.bracketNoteInfo` | `ui-bracket-note--info` | modifier |
+| `cls.bracketNoteSuccess` | `ui-bracket-note--success` | modifier |
+| `cls.bracketNoteWarning` | `ui-bracket-note--warning` | modifier |
+
 ### `.ui-breadcrumb`
 
 | Registry key | Class | Kind |
@@ -238,21 +292,6 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.center` | `ui-center` | base |
 
-### `.ui-chart`
-
-| Registry key | Class | Kind |
-| --- | --- | --- |
-| `cls.chart` | `ui-chart` | base |
-| `cls.chartBar` | `ui-chart__bar` | part |
-| `cls.chartCaption` | `ui-chart__caption` | part |
-| `cls.chartFallback` | `ui-chart__fallback` | part |
-| `cls.chartFill` | `ui-chart__fill` | part |
-| `cls.chartLabel` | `ui-chart__label` | part |
-| `cls.chartLegend` | `ui-chart__legend` | part |
-| `cls.chartPlot` | `ui-chart__plot` | part |
-| `cls.chartSwatch` | `ui-chart__swatch` | part |
-| `cls.chartTrack` | `ui-chart__track` | part |
-
 ### `.ui-check`
 
 | Registry key | Class | Kind |
@@ -266,6 +305,13 @@ each one matches a real selector in the stylesheet.
 | `cls.chip` | `ui-chip` | base |
 | `cls.chipAccent` | `ui-chip--accent` | modifier |
 
+### `.ui-citation`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.citation` | `ui-citation` | base |
+| `cls.citationChip` | `ui-citation--chip` | modifier |
+
 ### `.ui-cluster`
 
 | Registry key | Class | Kind |
@@ -283,6 +329,44 @@ each one matches a real selector in the stylesheet.
 | `cls.comboboxList` | `ui-combobox__list` | part |
 | `cls.comboboxOption` | `ui-combobox__option` | part |
 
+### `.ui-command`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.command` | `ui-command` | base |
+| `cls.commandEmpty` | `ui-command__empty` | part |
+| `cls.commandGroup` | `ui-command__group` | part |
+| `cls.commandInput` | `ui-command__input` | part |
+| `cls.commandItem` | `ui-command__item` | part |
+| `cls.commandList` | `ui-command__list` | part |
+| `cls.commandMeta` | `ui-command__meta` | part |
+| `cls.commandShortcut` | `ui-command__shortcut` | part |
+
+### `.ui-compare`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.compare` | `ui-compare` | base |
+| `cls.compareCol` | `ui-compare__col` | part |
+| `cls.compareHead` | `ui-compare__head` | part |
+| `cls.compare2up` | `ui-compare--2up` | modifier |
+
+### `.ui-connector`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.connector` | `ui-connector` | base |
+| `cls.connectorEnd` | `ui-connector__end` | part |
+| `cls.connectorPath` | `ui-connector__path` | part |
+| `cls.connectorAccent` | `ui-connector--accent` | modifier |
+| `cls.connectorDanger` | `ui-connector--danger` | modifier |
+| `cls.connectorDashed` | `ui-connector--dashed` | modifier |
+| `cls.connectorDraw` | `ui-connector--draw` | modifier |
+| `cls.connectorInfo` | `ui-connector--info` | modifier |
+| `cls.connectorMuted` | `ui-connector--muted` | modifier |
+| `cls.connectorSuccess` | `ui-connector--success` | modifier |
+| `cls.connectorWarning` | `ui-connector--warning` | modifier |
+
 ### `.ui-container`
 
 | Registry key | Class | Kind |
@@ -297,6 +381,27 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.cq` | `ui-cq` | base |
 
+### `.ui-crosshair`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.crosshair` | `ui-crosshair` | base |
+| `cls.crosshairBadge` | `ui-crosshair__badge` | part |
+| `cls.crosshairLine` | `ui-crosshair__line` | part |
+| `cls.crosshairLineX` | `ui-crosshair__line--x` | modifier |
+| `cls.crosshairLineY` | `ui-crosshair__line--y` | modifier |
+| `cls.crosshairMuted` | `ui-crosshair--muted` | modifier |
+
+### `.ui-delta`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.delta` | `ui-delta` | base |
+| `cls.deltaDown` | `ui-delta--down` | modifier |
+| `cls.deltaFlat` | `ui-delta--flat` | modifier |
+| `cls.deltaInvert` | `ui-delta--invert` | modifier |
+| `cls.deltaUp` | `ui-delta--up` | modifier |
+
 ### `.ui-display`
 
 | Registry key | Class | Kind |
@@ -407,6 +512,13 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.file` | `ui-file` | base |
 
+### `.ui-generated`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.generated` | `ui-generated` | base |
+| `cls.generatedLabel` | `ui-generated__label` | part |
+
 ### `.ui-grid`
 
 | Registry key | Class | Kind |
@@ -447,6 +559,14 @@ each one matches a real selector in the stylesheet.
 | `cls.inputIconSlot` | `ui-input-icon__icon` | part |
 | `cls.inputIconEnd` | `ui-input-icon--end` | modifier |
 
+### `.ui-inspector`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.inspector` | `ui-inspector` | base |
+| `cls.inspectorBody` | `ui-inspector__body` | part |
+| `cls.inspectorHead` | `ui-inspector__head` | part |
+
 ### `.ui-kbd`
 
 | Registry key | Class | Kind |
@@ -471,6 +591,39 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.label` | `ui-label` | base |
 
+### `.ui-legend`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.legend` | `ui-legend` | base |
+| `cls.legendCaption` | `ui-legend__caption` | part |
+| `cls.legendItem` | `ui-legend__item` | part |
+| `cls.legendLabel` | `ui-legend__label` | part |
+| `cls.legendSwatch` | `ui-legend__swatch` | part |
+| `cls.legendSwatch1` | `ui-legend__swatch--1` | modifier |
+| `cls.legendSwatch2` | `ui-legend__swatch--2` | modifier |
+| `cls.legendSwatch3` | `ui-legend__swatch--3` | modifier |
+| `cls.legendSwatch4` | `ui-legend__swatch--4` | modifier |
+| `cls.legendSwatch5` | `ui-legend__swatch--5` | modifier |
+| `cls.legendSwatch6` | `ui-legend__swatch--6` | modifier |
+| `cls.legendSwatch7` | `ui-legend__swatch--7` | modifier |
+| `cls.legendSwatch8` | `ui-legend__swatch--8` | modifier |
+| `cls.legendSwatchCircle` | `ui-legend__swatch--circle` | modifier |
+| `cls.legendSwatchLine` | `ui-legend__swatch--line` | modifier |
+| `cls.legendSymbol` | `ui-legend__symbol` | part |
+| `cls.legendTick` | `ui-legend__tick` | part |
+| `cls.legendTicks` | `ui-legend__ticks` | part |
+| `cls.legendTitle` | `ui-legend__title` | part |
+| `cls.legendTrack` | `ui-legend__track` | part |
+| `cls.legendValue` | `ui-legend__value` | part |
+| `cls.legendCompact` | `ui-legend--compact` | modifier |
+| `cls.legendDiverging` | `ui-legend--diverging` | modifier |
+| `cls.legendGradient` | `ui-legend--gradient` | modifier |
+| `cls.legendInteractive` | `ui-legend--interactive` | modifier |
+| `cls.legendThreshold` | `ui-legend--threshold` | modifier |
+| `cls.legendVertical` | `ui-legend--vertical` | modifier |
+| `cls.legendWithValues` | `ui-legend--with-values` | modifier |
+
 ### `.ui-lightbox`
 
 | Registry key | Class | Kind |
@@ -486,6 +639,22 @@ each one matches a real selector in the stylesheet.
 | `cls.linkArrow` | `ui-link--arrow` | modifier |
 | `cls.linkCta` | `ui-link--cta` | modifier |
 
+### `.ui-mark`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.mark` | `ui-mark` | base |
+| `cls.markAccent` | `ui-mark--accent` | modifier |
+| `cls.markBox` | `ui-mark--box` | modifier |
+| `cls.markDanger` | `ui-mark--danger` | modifier |
+| `cls.markDraw` | `ui-mark--draw` | modifier |
+| `cls.markInfo` | `ui-mark--info` | modifier |
+| `cls.markMuted` | `ui-mark--muted` | modifier |
+| `cls.markStrike` | `ui-mark--strike` | modifier |
+| `cls.markSuccess` | `ui-mark--success` | modifier |
+| `cls.markUnderline` | `ui-mark--underline` | modifier |
+| `cls.markWarning` | `ui-mark--warning` | modifier |
+
 ### `.ui-matrix`
 
 | Registry key | Class | Kind |
@@ -522,6 +691,7 @@ each one matches a real selector in the stylesheet.
 | `cls.meterFill` | `ui-meter__fill` | part |
 | `cls.meterAccent` | `ui-meter--accent` | modifier |
 | `cls.meterDanger` | `ui-meter--danger` | modifier |
+| `cls.meterInfo` | `ui-meter--info` | modifier |
 | `cls.meterSuccess` | `ui-meter--success` | modifier |
 | `cls.meterWarning` | `ui-meter--warning` | modifier |
 
@@ -558,6 +728,13 @@ each one matches a real selector in the stylesheet.
 | `cls.numNeg` | `ui-num--neg` | modifier |
 | `cls.numPos` | `ui-num--pos` | modifier |
 
+### `.ui-origin-label`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.originLabel` | `ui-origin-label` | base |
+| `cls.originLabelAi` | `ui-origin-label--ai` | modifier |
+
 ### `.ui-pagehead`
 
 | Registry key | Class | Kind |
@@ -606,6 +783,14 @@ each one matches a real selector in the stylesheet.
 | `cls.progressBar` | `ui-progress__bar` | part |
 | `cls.progressIndeterminate` | `ui-progress--indeterminate` | modifier |
 
+### `.ui-property`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.property` | `ui-property` | base |
+| `cls.propertyLabel` | `ui-property__label` | part |
+| `cls.propertyValue` | `ui-property__value` | part |
+
 ### `.ui-prose`
 
 | Registry key | Class | Kind |
@@ -613,6 +798,13 @@ each one matches a real selector in the stylesheet.
 | `cls.prose` | `ui-prose` | base |
 | `cls.proseCompact` | `ui-prose--compact` | modifier |
 
+### `.ui-provenance`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.provenance` | `ui-provenance` | base |
+| `cls.provenanceItem` | `ui-provenance__item` | part |
+
 ### `.ui-quote`
 
 | Registry key | Class | Kind |
@@ -632,6 +824,19 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.ratio` | `ui-ratio` | base |
 
+### `.ui-readout`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.readout` | `ui-readout` | base |
+
+### `.ui-reasoning`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.reasoning` | `ui-reasoning` | base |
+| `cls.reasoningBody` | `ui-reasoning__body` | part |
+
 ### `.ui-report`
 
 | Registry key | Class | Kind |
@@ -645,7 +850,7 @@ each one matches a real selector in the stylesheet.
 | `cls.reportFigure` | `ui-report__figure` | part |
 | `cls.reportFinding` | `ui-report__finding` | part |
 | `cls.reportFootnotes` | `ui-report__footnotes` | part |
-| `cls.reportHeader` | `ui-report__header` | part |
+| `cls.reportHead` | `ui-report__head` | part |
 | `cls.reportMeta` | `ui-report__meta` | part |
 | `cls.reportSection` | `ui-report__section` | part |
 | `cls.reportSectionUnnumbered` | `ui-report__section--unnumbered` | modifier |
@@ -695,12 +900,36 @@ each one matches a real selector in the stylesheet.
 | `cls.segmented` | `ui-segmented` | base |
 | `cls.segmentedOption` | `ui-segmented__option` | part |
 
+### `.ui-sel`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.sel` | `ui-sel` | base |
+| `cls.selMaybe` | `ui-sel--maybe` | modifier |
+| `cls.selOff` | `ui-sel--off` | modifier |
+| `cls.selOn` | `ui-sel--on` | modifier |
+
 ### `.ui-select`
 
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.select` | `ui-select` | base |
 
+### `.ui-selectionbar`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.selectionbar` | `ui-selectionbar` | base |
+| `cls.selectionbarActions` | `ui-selectionbar__actions` | part |
+| `cls.selectionbarCount` | `ui-selectionbar__count` | part |
+
+### `.ui-shortcut`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.shortcut` | `ui-shortcut` | base |
+| `cls.shortcutSep` | `ui-shortcut__sep` | part |
+
 ### `.ui-sidebar`
 
 | Registry key | Class | Kind |
@@ -748,12 +977,50 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.skiplink` | `ui-skiplink` | base |
 
+### `.ui-source-card`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.sourceCard` | `ui-source-card` | base |
+| `cls.sourceCardActions` | `ui-source-card__actions` | part |
+| `cls.sourceCardExcerpt` | `ui-source-card__excerpt` | part |
+| `cls.sourceCardOrigin` | `ui-source-card__origin` | part |
+| `cls.sourceCardTime` | `ui-source-card__time` | part |
+| `cls.sourceCardTitle` | `ui-source-card__title` | part |
+
+### `.ui-source-list`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.sourceList` | `ui-source-list` | base |
+| `cls.sourceListItem` | `ui-source-list__item` | part |
+
 ### `.ui-spinner`
 
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.spinner` | `ui-spinner` | base |
 
+### `.ui-spotlight`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.spotlight` | `ui-spotlight` | base |
+| `cls.spotlightHole` | `ui-spotlight__hole` | part |
+| `cls.spotlightRing` | `ui-spotlight--ring` | modifier |
+
+### `.ui-src`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.src` | `ui-src` | base |
+| `cls.srcConflict` | `ui-src--conflict` | modifier |
+| `cls.srcGenerated` | `ui-src--generated` | modifier |
+| `cls.srcReviewed` | `ui-src--reviewed` | modifier |
+| `cls.srcStale` | `ui-src--stale` | modifier |
+| `cls.srcUnverified` | `ui-src--unverified` | modifier |
+| `cls.srcVerified` | `ui-src--verified` | modifier |
+
 ### `.ui-stack`
 
 | Registry key | Class | Kind |
@@ -776,6 +1043,25 @@ each one matches a real selector in the stylesheet.
 | `cls.statLabel` | `ui-stat__label` | part |
 | `cls.statValue` | `ui-stat__value` | part |
 
+### `.ui-state`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.state` | `ui-state` | base |
+| `cls.stateDetail` | `ui-state__detail` | part |
+| `cls.stateLabel` | `ui-state__label` | part |
+| `cls.stateBusy` | `ui-state--busy` | modifier |
+| `cls.stateConflict` | `ui-state--conflict` | modifier |
+| `cls.stateError` | `ui-state--error` | modifier |
+| `cls.stateLocked` | `ui-state--locked` | modifier |
+| `cls.stateNeedsReview` | `ui-state--needs-review` | modifier |
+| `cls.stateOffline` | `ui-state--offline` | modifier |
+| `cls.stateQueued` | `ui-state--queued` | modifier |
+| `cls.stateReviewed` | `ui-state--reviewed` | modifier |
+| `cls.stateSaved` | `ui-state--saved` | modifier |
+| `cls.stateSaving` | `ui-state--saving` | modifier |
+| `cls.stateStale` | `ui-state--stale` | modifier |
+
 ### `.ui-statgrid`
 
 | Registry key | Class | Kind |
@@ -816,6 +1102,12 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.switcher` | `ui-switcher` | base |
 
+### `.ui-syncbar`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.syncbar` | `ui-syncbar` | base |
+
 ### `.ui-tab`
 
 | Registry key | Class | Kind |
@@ -908,6 +1200,21 @@ each one matches a real selector in the stylesheet.
 | `cls.toastStack` | `ui-toast-stack` | base |
 | `cls.toastStackAssertive` | `ui-toast-stack--assertive` | modifier |
 
+### `.ui-tool-call`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.toolCall` | `ui-tool-call` | base |
+| `cls.toolCallBody` | `ui-tool-call__body` | part |
+| `cls.toolCallName` | `ui-tool-call__name` | part |
+| `cls.toolCallStatus` | `ui-tool-call__status` | part |
+
+### `.ui-tool-log`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.toolLog` | `ui-tool-log` | base |
+
 ### `.ui-tooltip`
 
 | Registry key | Class | Kind |
@@ -915,6 +1222,16 @@ each one matches a real selector in the stylesheet.
 | `cls.tooltip` | `ui-tooltip` | base |
 | `cls.tooltipBubble` | `ui-tooltip__bubble` | part |
 
+### `.ui-tour-note`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.tourNote` | `ui-tour-note` | base |
+| `cls.tourNoteActions` | `ui-tour-note__actions` | part |
+| `cls.tourNoteBody` | `ui-tour-note__body` | part |
+| `cls.tourNoteStep` | `ui-tour-note__step` | part |
+| `cls.tourNoteTitle` | `ui-tour-note__title` | part |
+
 ### `.ui-visually-hidden`
 
 | Registry key | Class | Kind |
@@ -938,11 +1255,19 @@ registry consumer should reach for these instead of re-implementing
 | Class | Where | Effect |
 | --- | --- | --- |
 | `.ui-table .is-num` | numeric `<td>`/`<th>` | tabular figures + end-aligned (the canonical numeric cell) |
-| `.ui-table .is-pos` | numeric `<td>` | positive-delta tone |
-| `.ui-table .is-neg` | numeric `<td>` | negative-delta tone |
+| `.ui-table .is-pos` | numeric `<td>`, `.ui-stat__delta` | positive-delta tone |
+| `.ui-table .is-neg` | numeric `<td>`, `.ui-stat__delta` | negative-delta tone |
+| `.ui-table .is-key` | `<td>`/`<th>` | emphasised key column |
 
 For numeric text *outside* a table, use the `ui-num` primitive
-(`ui.num({ tone })`), which carries the same tabular/aligned/tone intent.
+(`ui.num({ tone })`), which carries the same tabular/aligned/tone intent; for
+a trend figure use `ui-delta` (`ui.delta({ dir, invert })`). The full,
+machine-readable list of these `is-*` state hooks — and the author-set inline
+custom properties (`--chart-color`, `--chart-pattern`, `--value`, and the
+**required** `--icon-mask` on `.ui-icon` and `--ui-vt-name` on `.ui-vt` —
+without which those classes render a solid square / do nothing) — is in
+[`@ponchia/ui/classes.json`](../classes/classes.json)
+(`states` / `customProperties`).
 
 ## Composition & state (read before re-implementing glue)
 
@@ -964,12 +1289,45 @@ works in any framework without a binding layer:
 - **Modal** — native `<dialog>` gets backdrop + top-layer + focus-trap
   free. For a controlled/portal modal, add `is-open`
   (`ui.modal({ open: true })`) for the same skin/layout; the
-  backdrop and focus-trap are then yours.
+  backdrop, top-layer stacking AND focus-trap are then yours (`.is-open`
+  is a bare grid — it does not float or stack on its own).
+- **Current page** — mark the active link with `aria-current="page"`; it is
+  the programmatic cue the navs honour (`ui-sitenav`, `ui-app-nav`). The
+  `.is-active` class is the visual-only equivalent on `ui-app-nav`/`ui-tab`;
+  prefer `aria-current` so assistive tech announces the current page.
+- **Form validation wiring** — `initFormValidation` (`@ponchia/ui/behaviors`)
+  reads these attributes; they ARE the contract, not styling. Markup that omits
+  them renders but the behavior silently no-ops: `data-bronto-validate` on the
+  `<form>`; an optional empty `[data-bronto-error]` node per field (it falls
+  back to the field's `.ui-hint`, restoring the help text when valid again); a
+  `[data-bronto-error-summary]` (`.ui-error-summary`) block. The combobox
+  reads `[data-bronto-combobox]` + per-option `data-value` and emits
+  `bronto:change` (`{ detail: { value } }`) on selection; the interactive
+  legend emits `bronto:legend:toggle` (`{ detail: { series, active } }`).
+- **Status indicator** — `ui-status` carries no dot of its own: compose it with
+  a `.ui-dot` child + a text label, e.g.
+  `<span class="ui-status"><span class="ui-dot ui-dot--success"></span> Live</span>`.
+  (`ui-state` instead bakes in its own dot + the full tone vocabulary — pick
+  one.) A semantic `ui-dot--success|warning|danger|info` is colour-only outside
+  forced-colors, so it ALWAYS needs an adjacent text/aria label — never ship a
+  bare coloured dot as the sole signal.
+- **Opt-in component CSS** — a few classes are not in the core bundle and need
+  their leaf imported, or they render unstyled: `ui-property`/`ui-readout` →
+  `@ponchia/ui/css/workbench.css`; `ui-mark`/`ui-bracket-note` →
+  `@ponchia/ui/css/marks.css`; the analytical leaves (`ui-annotations`,
+  `ui-crosshair`, `ui-spotlight`, …) → their matching leaf.
+- **Loaders need their children** — `ui-dotspinner` requires exactly eight
+  `<i>` children, `ui-dotloader` three `<span>`, and a static `ui-dotbar`
+  lights a segment with `<i class="is-on">`. A childless
+  `<span class="ui-dotspinner">` renders nothing.
+- **`ui-caret` is a typing cursor**, not a dropdown chevron — a blinking block
+  caret (driven by `initDotGlyph`/`uiBlink`). For a disclosure/affordance
+  arrow use `ui-link--arrow` (`ui.link({ arrow: true })`).
 
 ## Tokens
 
 Exact mirror of the `:root` blocks in `css/tokens.css`
-(`check-tokens` enforces parity). DTCG export:
+(`check-fresh` enforces parity). DTCG export:
 [`@ponchia/ui/tokens.dtcg.json`](../tokens/tokens.dtcg.json).
 
 ### Global (scales — shared by both themes)
@@ -992,6 +1350,8 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--sans` | `'Inter', 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif` |
 | `--dot-font` | `'Doto', var(--mono)` |
 | `--display` | `var(--dot-font)` |
+| `--display-weight` | `700` |
+| `--display-weight-strong` | `800` |
 | `--text-2xs` | `0.68rem` |
 | `--text-xs` | `0.76rem` |
 | `--text-sm` | `0.86rem` |
@@ -1065,6 +1425,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--accent-ramp-end` | `#ffffff` |
 | `--accent-strong` | `color-mix(in srgb, var(--accent) 83%, #000)` |
 | `--accent-text` | `var(--accent-strong)` |
+| `--on-accent` | `var(--button-text)` |
 | `--accent-soft` | `color-mix(in srgb, var(--accent) 10%, transparent)` |
 | `--success` | `#2f7d4f` |
 | `--success-soft` | `rgb(47, 125, 79, 0.12)` |
@@ -1102,6 +1463,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--accent-ramp-end` | `#000000` |
 | `--accent-strong` | `color-mix(in srgb, var(--accent) 84%, #fff)` |
 | `--accent-text` | `var(--accent-strong)` |
+| `--on-accent` | `var(--button-text)` |
 | `--accent-soft` | `color-mix(in srgb, var(--accent) 14%, transparent)` |
 | `--success` | `#4ec27e` |
 | `--success-soft` | `rgb(78, 194, 126, 0.14)` |