@godxjp/ui 18.15.3 → 19.0.0

package/dist/tokens/components/card.css

@@ -73,19 +73,19 @@
    * Tokenised (rule #44) so a service theme can re-tune it without forking CSS.
    * The slot padding compensation in card-layout.css subtracts the same token,
    * so content stays aligned on the shell whatever the rail width. */
-  --card-accent-rail-width: 6px;
+  --card-accent-rail-width: var(--stroke-2xl);
   /* Accent placement `perimeter` (gh#12) — the FULL attention border. Two knobs so a service can
    * tune the edge weight and the outer ring independently; the defaults reproduce the optical
    * weight of `variant="featured"` (1px border + 1px ring) in the card's own semantic accent tone
    * instead of --primary. Structural 1px literals, like the base card hairline. */
-  --card-accent-perimeter-width: 1px;
-  --card-accent-perimeter-ring-width: 1px;
+  --card-accent-perimeter-width: var(--stroke-hairline);
+  --card-accent-perimeter-ring-width: var(--stroke-hairline);
   /* `variant="featured"` edge — role-mirror knob (docs/TOKENS.md). `initial` so the --primary
    * default resolves at the CALL SITE and a scoped [data-tenant]/.dark override of --primary
    * reaches it; a service points it anywhere (e.g. var(--attention)) to retint every featured card
    * at once. Default = hsl(var(--primary)). */
   --card-featured-border-color: initial;
-  --card-featured-ring-width: 1px;
+  --card-featured-ring-width: var(--stroke-hairline);
   --stat-card-label-font-size: var(--font-size-xs);
   --stat-card-label-font-weight: var(--font-weight-medium);
   --stat-card-label-letter-spacing: 0.04em;
@@ -94,8 +94,8 @@
   --stat-card-value-font-weight: var(--font-weight-semibold);
   --stat-card-hint-font-size: var(--font-size-xs);
   --stat-card-gap: var(--space-stack-xs);
-  --stat-card-icon-size: 2.25rem;
-  --stat-card-icon-glyph-size: 1.25rem;
+  --stat-card-icon-size: var(--icon-size-2xl);
+  --stat-card-icon-glyph-size: var(--icon-size-lg);
   --stat-card-icon-radius: var(--radius-md);
   /* Medallion tint — soft brand wash + brand glyph by default; a service retints by overriding
    * --primary or these tokens directly (rule #44/#45). `initial` so the --primary default
@@ -108,10 +108,14 @@
    * Internal rhythm of a launcher tile: one gap knob drives the vertical stack AND the
    * icon↔title↔status row, so a service theme retunes the whole tile density once. */
   --card-service-launcher-space-gap: var(--space-stack-sm);
-  /* Semantic icon surface. `--control-height-lg` is the 36px control tier the hi-fi calls for —
-   * a tier token, never a literal, so the medallion tracks --scaling with its sibling controls. */
-  --card-service-launcher-icon-size: var(--control-height-lg);
-  --card-service-launcher-icon-glyph-size: var(--space-5);
+  /* Semantic icon surface — 36px, the `--icon-size-2xl` step, multiplied by --scaling so the
+   * medallion still breathes with its sibling controls (the gh#328 rule: an icon that wants
+   * density says so itself). It read `var(--control-height-lg)` until gh#324: a CONTROL tier is
+   * the wrong axis for an icon box, and the bug was visible — `@media (pointer: coarse)` lifts
+   * the control ladder to the 44px tap floor, so on every touch device the medallion silently
+   * inflated to 48px while the glyph inside it stayed 20px. */
+  --card-service-launcher-icon-size: calc(var(--icon-size-2xl) * var(--scaling));
+  --card-service-launcher-icon-glyph-size: calc(var(--icon-size-lg) * var(--scaling));
   --card-service-launcher-icon-radius: var(--radius-md);
   /* Available-service medallion tint. `initial` (role-mirror rule, docs/TOKENS.md) so the role
    * defaults resolve at the CALL SITE and a scoped [data-tenant]/.dark override reaches them.

package/dist/tokens/components/chart.css

@@ -25,7 +25,7 @@
   /* Ceiling on a single mark so a 3-point trend does not render slabs. */
   --chart-trend-bar-max-width: 1.5rem;
   /* Floor so a zero/absent value still reads as a plotted category rather than a hole. */
-  --chart-trend-bar-min-height: 2px;
+  --chart-trend-bar-min-height: var(--stroke-md);
   /* Muted mark fill — role-mirror knob, declared `initial` so the role default re-resolves
    * at the CALL SITE under `.dark` / `[data-tenant]` (docs/TOKENS.md · "Role-mirror knobs
    * MUST be `initial`"). Default = hsl(var(--muted-foreground) / 0.75), which clears the

package/dist/tokens/components/control.css

@@ -1,9 +1,9 @@
 /* Control primitive tokens: heights, horizontal padding, adjacent control sizes. */
 
 :root {
-  --control-height-compact: 1.75rem;
-  --control-height-default: 2rem;
-  --control-height-comfortable: 2.75rem;
+  --control-height-compact: var(--band-height-sm);
+  --control-height-default: var(--band-height-md);
+  --control-height-comfortable: var(--band-height-xl);
   --control-padding-x-compact: var(--space-2);
   --control-padding-x-default: var(--space-3);
   --control-padding-x-comfortable: var(--space-4);
@@ -27,12 +27,24 @@
    * once instead of each component hard-coding Tailwind utilities. Defaults preserve
    * the historical look (font-size-base, 1px border, shadow-xs). */
   --control-font-size: var(--font-size-base);
-  --control-border-width: 1px;
+  --control-border-width: var(--stroke-hairline);
   --control-shadow: var(--shadow-xs);
-  --control-icon-size: calc(1rem * var(--scaling));
-  --control-icon-size-sm: calc(0.875rem * var(--scaling));
+  --control-icon-size: calc(var(--icon-size-md) * var(--scaling));
+  --control-icon-size-sm: calc(var(--icon-size-sm) * var(--scaling));
   --control-focus-ring-width: var(--focus-ring-width);
 
+  /* Ring knobs for the two controls that need a softer, heavier mark than the
+   * global default — both are filled surfaces where a hard 2px ring reads as a
+   * second border. Values preserve the look these controls always had; they are
+   * knobs now instead of hand-written box-shadows (styles/focus-ring.css). */
+  --toggle-focus-ring-width: var(--stroke-lg);
+  --toggle-focus-ring-alpha: 0.35;
+  --time-input-focus-ring-width: var(--stroke-lg);
+  --time-input-focus-ring-alpha: 0.3;
+
+  /* Outline-form gaps — marks where a radius-hugging ring would touch the glyph. */
+  --rating-focus-ring-offset: 2px;
+
   --checkbox-size: calc(1rem * var(--scaling));
   --checkbox-size-compact: 0.875rem;
   --checkbox-size-comfortable: 1.125rem;
@@ -94,8 +106,16 @@
   --slider-track-background: initial;
   --slider-range-background: initial;
 
+  /* Switch OFF track fill (gh#315) — `initial`, default hsl(var(--input)). Its own knob so a
+   * service can quieten the off-track without dragging the --input control-boundary role back
+   * below the WCAG SC 1.4.11 floor (rule #45); whatever you set still owes 3:1 against the page
+   * and against the thumb (--background), or "off" stops being a visible state. */
+  --switch-unchecked-background: initial;
+
+  /* ColorPicker — width of the hex text field beside the swatch. */
   --color-picker-input-width: 6.5rem;
 
+  /* Command / CommandPalette — list height, inner paddings and the palette's own box. */
   --command-list-max-height: min(300px, 50vh);
   --command-input-padding-x: var(--space-3);
   --command-group-padding: var(--space-1);
@@ -107,6 +127,9 @@
   --command-palette-hint-padding-y: var(--space-2);
   --command-palette-hint-padding-x: var(--space-4);
   --command-palette-hint-gap: var(--space-4);
+
+  /* SearchInput — the inset the leading/trailing icons sit at, and the field padding derived
+   * from it so the text never runs under an icon. */
   --search-input-edge-inset: var(--space-3);
   --search-input-start-padding: calc(
     var(--search-input-edge-inset) + var(--control-icon-size) + var(--control-gap)
@@ -115,6 +138,8 @@
     var(--search-input-edge-inset) + var(--control-icon-size) + var(--control-gap)
   );
 
+  /* The --font-size-xs tier, spelled once per control that reads it, so a service can retune a
+   * single one of them without moving the whole scale. */
   --choice-description-font-size: var(--font-size-xs);
   --color-picker-hex-font-size: var(--font-size-xs);
   --command-group-heading-font-size: var(--font-size-xs);
@@ -127,9 +152,334 @@
 /* Rule #24 — on touch devices (coarse pointer) interactive controls keep a ≥44px tap target
  * regardless of density; desktop (fine pointer) keeps the compact heights above. --control-height
  * resolves through these via var(), so inputs/buttons/selects/table rows all bump together. */
+/* Control-family tokens added for #319.
+ *
+ * These MUST live in a plain :root, not inside the @media (pointer: coarse) block below —
+ * bare declarations in a conditional group rule are invalid CSS and the parser drops them
+ * silently. They spent this whole refactor dead for exactly that reason: the guards read the
+ * file textually, so check-token-tiers and the geometry ratchet both passed while every one of
+ * these resolved to nothing. */
+:root {
+  /* TRAILING AFFIX — the clear ✕ / chevron overlay a select-family trigger parks at its inline
+   * end. Select, SearchSelect and TagInput each hard-coded the same `end-2 size-6 rounded-sm
+   * opacity-50` stack independently (#319), so a service retuning affix weight had to chase the
+   * literal through several components. One shared set of knobs instead — this is a CONTROL-level
+   * concern, not a per-component one. */
+  --control-affix-inset-inline-end: var(--space-2);
+  --control-affix-action-size: 1.5rem;
+  --control-affix-action-radius: var(--radius-sm);
+  --control-affix-icon-size: var(--icon-size-md);
+  /* Resting weight of an affix glyph — it must read as secondary until hovered/focused. */
+  --control-affix-rest-alpha: 0.5;
+  /* Room a trigger reserves so its label never runs under the affix. */
+  /* 2.25rem — the room a single trailing affix needs. Written as a raw rem because the
+   * literal it replaced (`pe-9`) is a flat Tailwind step, not a density-scaled one. */
+  --control-trigger-space-inline-end: 2.25rem;
+
+  /* INSIDE-FIELD AFFIX — the leading/trailing controls Input and TimePicker render WITHIN the
+   * field box, as opposed to the overlay affix (--control-affix-*) that Select and SearchSelect
+   * park on top of a trigger. Both carried the identical literal stack (#319). Because these sit
+   * on the field's own surface rather than over it, they rest a touch heavier than the overlay
+   * pair — that difference is the reason the two sets stay separate. */
+  --control-inline-affix-size: 1.25rem;
+  --control-inline-affix-icon-size: var(--control-affix-icon-size);
+  --control-inline-affix-space-gap: var(--space-1);
+  --control-inline-affix-inset-inline: var(--space-2);
+  --control-inline-affix-rest-alpha: 0.7;
+  /* Inline room the field reserves so its text never runs under a single affix. */
+  --control-inline-affix-space-inline-end: 2.25rem;
+  /* Input centres its affix on the field's single line; a textarea has no single line to centre
+   * on, so its clear control parks at the top-end corner instead. */
+  --textarea-clear-inset-block-start: var(--space-2);
+  /* MULTILINE BOX — the block padding of `.ui-control-multiline` (Textarea). It was a bare
+   * `--space-2` inside the padding shorthand, which made it unreachable for a service that runs a
+   * denser composer, AND it is the constant the auto-grow row maths has to add back, so the two
+   * had to read the same knob or drift (#45). */
+  --control-multiline-padding-block: var(--space-2);
+  /* TEXTAREA AUTO-GROW (gh#310) — `autoGrow` grows the box with its content between a floor and a
+   * ceiling expressed in TEXT ROWS. Rows, not pixels, because a row count survives a density
+   * change and a `--font-size-base` retheme where a px ceiling would silently stop matching the
+   * visible line count. Defaults reproduce today's geometry when `autoGrow` is absent (#44). */
+  /* The unit a "row" is measured in. `initial` on purpose: the call site reads
+   * `var(--textarea-autogrow-line-height, var(--line-height-normal))`, so a service that retunes
+   * the multiline line-height for CJK legibility retunes the ceiling with it (#46). Unitless —
+   * it is multiplied by `--control-font-size`. */
+  --textarea-autogrow-line-height: initial;
+  /* Floor of the grown box, in text rows. The `minRows` prop overrides per instance — the same
+   * theme-global / prop-local priority as `--form-label-width` vs `labelWidth`. The floor is
+   * additionally clamped up to `--control-height` so a resting one-row composer still lines up
+   * with the Input / Button beside it instead of undercutting the control tier. */
+  --textarea-autogrow-min-height-rows: 1;
+  /* Ceiling of the grown box, in text rows; past it the control scrolls internally instead of
+   * pushing the page. `maxRows={0}` sets this to `infinity` for an unbounded box. */
+  --textarea-autogrow-max-height-rows: 8;
+  /* The non-text part of the box the row maths must add back: block padding + border, both
+   * edges. `.ui-textarea-autogrow--ghost` re-declares it without the border, because the ghost
+   * variant drops its own chrome. */
+  --textarea-autogrow-box-inset: calc(
+    (var(--control-multiline-padding-block) + var(--control-border-width)) * 2
+  );
+  /* A field parking TWO inline affixes (TimePicker's clear+clock, DatePicker's clear+calendar)
+   * reserves a wider end than the single-affix case. */
+  --control-inline-affix-pair-space-inline-end: 3.5rem;
+  /* COMPOSITE FIELD — the bordered box that wraps two inputs plus a separator (date/month
+   * range pickers) or one input plus affixes. Shared so the four range/picker fields cannot
+   * drift into four slightly different boxes. */
+  --control-composite-field-space-gap: var(--space-2);
+  /* The <input type=file> button is a browser-owned box we restyle; it sits one tier below the
+   * field so it reads as a control INSIDE the control. */
+  --input-file-button-height: var(--band-height-sm);
+  --input-file-button-font-size: var(--font-size-sm);
+
+  /* SEARCH-SELECT — the Popover+Command combobox. Its panel geometry was baked onto the
+   * component as arbitrary values (`max-w-[min(32rem,calc(100vw-1.5rem))]`), so a service could
+   * not widen the panel or change the viewport gutter without forking. */
+  --search-select-panel-max-width: 32rem;
+  --search-select-panel-viewport-inset: var(--space-6);
+  --search-select-list-space-inset: var(--space-1);
+  --search-select-footer-space-inset: var(--space-1);
+  --search-select-option-space-gap: var(--space-2);
+  --search-select-option-font-size: var(--font-size-sm);
+  --search-select-option-sublabel-font-size: var(--font-size-xs);
+  --search-select-status-space-inline: var(--space-2);
+  --search-select-status-space-block: var(--space-3);
+  /* Empty/error states sit alone in the panel, so they get a taller, centred block. */
+  --search-select-placeholder-space-block: var(--space-6);
+  --search-select-status-font-size: var(--font-size-sm);
+  --search-select-spinner-size: 1rem;
+
+  /* CASCADER — column browser + flat search list. Its option rows, column widths and panel
+   * paddings were literals on the component (#319), so a service could not widen a column to fit
+   * longer JA labels or tighten the row rhythm without forking. */
+  --cascader-column-min-width: 9rem;
+  --cascader-columns-max-height: min(280px, 50vh);
+  --cascader-list-max-height: min(300px, 50vh);
+  --cascader-panel-space-inset: var(--space-1);
+  --cascader-option-space-inline: var(--space-3);
+  --cascader-option-space-block: var(--space-2);
+  --cascader-option-space-gap: var(--space-1);
+  --cascader-option-font-size: var(--font-size-sm);
+  --cascader-option-icon-size: var(--icon-size-md);
+  /* The flat search result row is denser than a column row — it has no chevron to balance. */
+  --cascader-result-space-inline: var(--space-2);
+  --cascader-result-space-block: 0.375rem;
+  --cascader-result-radius: var(--radius-sm);
+  --cascader-result-icon-space-inline-end: var(--space-2);
+  --cascader-empty-space-block: var(--space-6);
+
+  /* SELECT — the Radix listbox surface. Its popup shares the menu row rhythm (--menu-item-*),
+   * so only what is genuinely its own lives here (#319). */
+  --select-content-max-height: 24rem;
+  --select-scroll-button-space-block: var(--space-1);
+  /* Select rows sit slightly wider than a menu row: a listbox has no leading icon column to
+   * absorb the optical inset, so 2.5 reads level with a menu's 2 + icon. */
+  --select-item-space-inline: 0.625rem;
+
+  /* TIME PICKER — scroll columns of hour/minute/second plus an inline affix pair. All of its
+   * geometry was literal on the component (#319): a service could not shorten the column, widen
+   * the panel for a 12-hour layout, or retune the row rhythm without forking. */
+  --time-picker-column-height: 13rem;
+  --time-picker-panel-width: 9rem;
+  /* 12-hour mode adds an AM/PM column, so the panel is wider. */
+  --time-picker-panel-width-12h: 13rem;
+  --time-picker-heading-space-inline: var(--space-1);
+  --time-picker-heading-space-block: 0.375rem;
+  --time-picker-heading-font-size: var(--font-size-xs);
+  --time-picker-column-space-inset: var(--space-1);
+  --time-picker-option-space-block: 0.375rem;
+  --time-picker-option-radius: var(--radius-md);
+  --time-picker-option-font-size: var(--font-size-sm);
+  --time-picker-footer-space-inset: var(--space-2);
+
+  --time-picker-affix-space-gap: var(--control-inline-affix-space-gap);
+
+  /* TREE SELECT — a Select whose panel holds a tree. Its rows, indent and toggle were literal
+   * on the component, and the depth indent was a magic expression in JSX
+   * (`depth * 1.25 + 0.5` rem) that no theme could reach at all (#319). */
+  --tree-select-list-max-height: min(300px, 50vh);
+  --tree-select-row-space-block: 0.375rem;
+  --tree-select-row-space-inline-end: var(--space-2);
+  --tree-select-row-radius: var(--radius-sm);
+  --tree-select-row-font-size: var(--font-size-sm);
+  /* Indent = base + depth × step. A denser service dials the step down without touching JSX. */
+  --tree-select-depth-space-base: var(--space-2);
+  --tree-select-depth-space-step: 1.25rem;
+  --tree-select-toggle-size: 1.25rem;
+  --tree-select-toggle-space-inline-end: var(--space-1);
+  --tree-select-label-space-gap: var(--space-2);
+  --tree-select-empty-space-block: var(--space-6);
+
+  /* CALENDAR — the react-day-picker grid. Day/weekday cells already size from --control-height
+   * (the system control tier), but the frame around them — root inset, month gaps, nav offset,
+   * grid rhythm — was literal on the component (#319), so a service could not tighten the
+   * calendar to its own density without forking the classNames map. */
+  --calendar-space-inset: var(--space-3);
+  --calendar-month-space-gap: var(--space-4);
+  --calendar-caption-space-inline: var(--space-8);
+  --calendar-caption-font-size: var(--font-size-sm);
+  --calendar-nav-space-block-start: var(--space-3);
+  --calendar-nav-space-inline: var(--space-1);
+  /* Nav chevrons read as secondary until hovered — they frame the month, they are not the point. */
+  --calendar-nav-rest-alpha: 0.7;
+  --calendar-grid-space-block-start: var(--space-4);
+  --calendar-week-space-block-start: var(--space-2);
+  --calendar-weekday-font-size: var(--font-size-xs);
+  --calendar-weekday-radius: var(--radius-md);
+  --calendar-day-font-size: var(--font-size-sm);
+  --calendar-day-radius: var(--radius-md);
+  --calendar-chevron-size: var(--icon-size-md);
+
+  /* TRANSFER — the two-pane list mover. Pane height, header rhythm and row density were literal
+   * on the component (#319), so a service could not fit the panes to its own page grid or
+   * tighten the row for a dense admin table without forking. */
+  --transfer-pane-min-height: 14rem;
+  --transfer-pane-radius: var(--radius-md);
+  --transfer-panes-space-gap: var(--space-3);
+  --transfer-header-space-inline: var(--space-3);
+  --transfer-header-space-block: var(--space-2);
+  --transfer-header-font-size: var(--font-size-sm);
+  --transfer-header-space-gap: var(--space-2);
+  --transfer-search-space-inset: var(--space-2);
+  --transfer-list-space-inset: var(--space-1);
+  --transfer-row-space-inline: var(--space-2);
+  --transfer-row-space-block: var(--space-2);
+  --transfer-row-space-gap: var(--space-2);
+  --transfer-row-radius: var(--radius-sm);
+  --transfer-row-font-size: var(--font-size-sm);
+  /* The checkbox is top-aligned against a two-line row, so it needs a hair of optical offset to
+   * sit level with the first line's cap height rather than its box. */
+  --transfer-row-check-space-block-start: 0.125rem;
+  --transfer-row-description-font-size: var(--font-size-xs);
+  --transfer-empty-space-block: var(--space-8);
+  --transfer-actions-space-gap: var(--space-2);
+  --transfer-action-icon-size: var(--icon-size-md);
+
+  /* MONTH PICKER — shared by MonthPicker and MonthRangePicker, which render the same year-nav +
+   * 3-column month grid. Both carried an identical copy of every literal (#319); one set of knobs
+   * now drives both, so they cannot drift apart the way Select and DropdownMenu once did. */
+  --month-picker-panel-space-inset: var(--space-3);
+  --month-picker-grid-space-block-start: var(--space-3);
+  --month-picker-grid-space-gap: var(--space-1);
+  --month-picker-cell-space-inline: var(--space-4);
+  --month-picker-nav-font-size: var(--font-size-sm);
+  /* Year-nav chevrons read as secondary until hovered — same treatment as the Calendar nav, so
+   * the two panels stay visually consistent when either is retuned. */
+  --month-picker-nav-rest-alpha: var(--calendar-nav-rest-alpha);
+  --month-picker-icon-size: var(--icon-size-md);
+  --month-picker-separator-icon-size: var(--icon-size-sm);
+
+  /* BUTTON size-xs box + the count pill (#319, reconciled in #316).
+   *
+   * `size="xs"` now reads the tier, like every other control in the library. It used to be
+   * `calc(var(--control-height) - 0.75rem)` = 1.25rem, which sat 4px BELOW `--control-height-xs`
+   * (1.5rem) that `size="icon-xs"` already used — the same tier name, two heights, so an xs
+   * Button never lined up with the xs control beside it. It was also the exact shape this repo's
+   * own rule forbids: an ad-hoc `calc(var(--control-height) ± length)` silently re-derives a tier
+   * and drifts from its siblings (the bug that made Pagination's size-changer taller than its
+   * page buttons), and being a raw length rather than a `--scaling`-multiplied step, it did not
+   * move with density while the tier did.
+   *
+   * What settled it was not consistency but MEASUREMENT: an xs Button rendered 20px tall, under
+   * the 24x24 CSS px that WCAG 2.2 SC 2.5.8 (Target Size, Minimum) requires, while icon-xs beside
+   * it rendered 24px and passed. So this is an accessibility fix that happens to also remove an
+   * inconsistency, not a visual preference. It is a real visual change on the most-used component
+   * in the library (20px -> 24px), and it stays a knob: a service that wants the old box sets
+   * --button-xs-height back. */
+  --button-xs-height: var(--control-height-xs);
+  --button-xs-space-inline: var(--space-2);
+  --button-xs-space-gap: var(--space-1);
+  --button-xs-font-size: var(--font-size-xs);
+  --button-xs-icon-size: var(--icon-size-xs);
+  /* Icon-adjacent padding: a button whose only child is an icon needs less inline room than one
+   * carrying a label, or the glyph floats in a too-wide box. One knob per size tier. */
+  --button-icon-space-inline-md: var(--space-3);
+  --button-icon-space-inline-sm: 0.625rem;
+  --button-icon-space-inline-lg: var(--space-4);
+  --button-icon-space-inline-xs: 0.375rem;
+  --button-space-block: var(--space-2);
+  /* Count pill — a borderless counter that reads on the button's own surface. */
+  /* OTP separator glyph. Was a bare 1rem in styles/control.css, so the two-tier contract had no
+   * tier-2 route here at all: a consumer wanting a different separator could only use !important
+   * or fork the stylesheet. Same value, now reachable. */
+  /* The OTP blinking caret. The ratchet catches it because the selector says "caret", but it is a
+   * text CURSOR, not a chevron: a 1px bar as tall as the digit's line box. Its width belongs to
+   * the stroke scale; its height belongs to neither the icon nor the band scale, so it is declared
+   * rather than forced onto one.
+   * scale-exempt: text-caret height, tracks the OTP digit's line box, not an icon or a band */
+  --otp-caret-block-size: 1rem;
+  --otp-caret-inline-size: var(--stroke-hairline);
+  --otp-separator-icon-size: var(--icon-size-md);
+
+  --button-count-min-width: var(--space-4);
+  --button-count-space-inline: var(--space-1);
+  --button-count-font-size: var(--font-size-xs);
+
+  /* Count pill · COLOUR (gh#320). The pill used to tint itself translucently over whatever the
+   * button's surface happened to be (`bg-primary-foreground/15`, `bg-foreground/8`), which means
+   * its contrast was a FUNCTION of that surface — and five of those combinations measured below
+   * the 4.5:1 that WCAG 2.2 SC 1.4.3 requires of small text:
+   *
+   *   default (light)                  3.88   ·  destructive (dark)              4.29
+   *   outline family (light, at rest)  4.32   ·  outline family (light, hover)   3.64
+   *   outline family (dark, hover)     3.68
+   *
+   * The hover rows are the reason a static sweep never caught this: `--accent` only appears under
+   * the cursor, so no screenshot of a resting page contains the failing state. Same shape as
+   * gh#299 and gh#315 — a value that passes on the surface someone happened to check.
+   *
+   * The fix is the one gh#312 already validated on Toggle: OPAQUE role fills, which make the pill's
+   * contrast independent of the button's variant AND of hover. Each filled variant uses its own
+   * label pair SWAPPED, so the pill is exactly as legible as the label beside it and cannot be less
+   * legible under any theme that keeps that button readable at all:
+   *
+   *   default      --primary     on --primary-foreground       5.04 light · 7.07 dark
+   *   destructive  --destructive on --destructive-foreground   6.10 light · 5.53 dark
+   *   secondary    --secondary   on --secondary-foreground    14.25 light · 12.40 dark
+   *   outline family --foreground on --muted                  14.25 light · 12.40 dark
+   *
+   * The outline family's `--muted` fill is 1.09:1 against the button's own ground, so at rest the
+   * counter still reads as quiet text rather than a badge (#44) — it is legibility of the DIGITS
+   * that went up, not loudness of the pill.
+   *
+   * All eight are role-mirror knobs: `initial` at :root with the role default at the CALL SITE, so
+   * a scoped [data-tenant]/.dark override of the role still reaches them (docs/TOKENS.md ·
+   * "Role-mirror knobs MUST be `initial`"). */
+  --button-count-background: initial;
+  --button-count-color: initial;
+  --button-count-default-background: initial;
+  --button-count-default-color: initial;
+  --button-count-destructive-background: initial;
+  --button-count-destructive-color: initial;
+  --button-count-secondary-background: initial;
+  --button-count-secondary-color: initial;
+
+  /* LABEL — the Label primitive's own box and type (#319). Every one of these was a Tailwind
+   * literal baked into label.tsx (`text-sm leading-none flex items-center gap-2`), so a service
+   * whose form grid wanted a smaller/denser label had to hand-write font-size on every call site
+   * (which is exactly why --form-label-font-size had to be invented as a per-instance escape).
+   * They live under the `control` prefix because Label is a control-family primitive and
+   * src/tokens/components/ has no `label` file of its own.
+   *
+   * Defaults reproduce today's rendering exactly:
+   *   font-size   ← `text-sm`      → --text-sm → var(--font-size-sm)
+   *   line-height ← `leading-none` → 1 (leading-none beats text-sm's companion line-height) */
+  --control-label-font-size: var(--font-size-sm);
+  --control-label-line-height: 1;
+  /* Label → addon/required-marker gap. A RAW rem, deliberately NOT var(--space-2): the `gap-2` it
+   * replaces reads Tailwind's own --spacing grid, which this repo does NOT density-scale, so a
+   * --space-* default would silently resize every label row under a compact/comfortable density.
+   * A service that WANTS it to follow density points the knob at var(--space-2) itself. */
+  --control-label-space-gap: 0.5rem;
+  /* Weight of a label whose `peer` control is disabled. Deliberately its OWN knob rather than the
+   * global --disabled-opacity (0.5): a label must stay READABLE next to a disabled control — it is
+   * still the field's accessible name — so it rests one step heavier than the control it names.
+   * Default = the historical `peer-disabled:opacity-70`. */
+  --control-label-disabled-alpha: 0.7;
+}
+
 @media (pointer: coarse) {
   :root {
-    --control-height-compact: 2.75rem;
-    --control-height-default: 2.75rem;
+    --control-height-compact: var(--band-height-xl);
+    --control-height-default: var(--band-height-xl);
   }
 }

package/dist/tokens/components/data-display.css

@@ -1,6 +1,16 @@
 /* Data-display component tokens — small-by-design text knobs (rule #45/#46). */
 
 :root {
+  /* Accordion chevron and Carousel arrow. Both were bare 1rem literals in
+   * data-display-layout.css — glyphs with no tier-2 route, invisible to the icon ratchet because
+   * neither selector contains the word "icon". */
+  --accordion-chevron-size: var(--icon-size-md);
+  --carousel-arrow-icon-size: var(--icon-size-md);
+
+  /* Outline-form ring gaps — a hugging ring would touch these marks
+   * (styles/focus-ring.css). */
+  --accordion-focus-ring-offset: 2px;
+  --carousel-dot-focus-ring-offset: 2px;
   --progress-label-font-size: var(--font-size-xs);
   --tree-item-title-font-size: var(--font-size-xs);
   --tree-item-description-font-size: var(--font-size-xs);
@@ -40,6 +50,46 @@
   --avatar-tinted-foreground: initial;
   --avatar-tinted-glyph-size: var(--control-icon-size);
 
+  /* PRESENCE INDICATOR — `<Avatar presence="online|away|busy|offline">` (gh#309): the realtime
+     reachability dot pinned to the block-end/inline-end corner of the mark. Every constant below is
+     a knob (rule #45) and the separator ring is chrome that reads a token (rule #44), because the
+     hand-rolled workaround this replaces —
+     `bg-green-500 ring-2 ring-background -end-0.5 -bottom-0.5` on a wrapper span — bakes four
+     service-tunable constants and a raw palette colour into a consumer page.
+
+     --avatar-presence-size is a PROPORTION of the mark, not a px step. One value therefore tracks
+     EVERY avatar the system paints — the --control-height default box, a `size-12` call site, the
+     --avatar-square-size entity mark, --org-switcher-avatar-size (1.75rem), --upload-avatar-size
+     (6rem), the 36px ListRow density="compact" leading mark — instead of freezing one diameter that
+     is a boulder on a 24px mark and a speck on a 96px one. --avatar-presence-min-size is the
+     legibility floor for the smallest marks; --avatar-presence-inset lets a service pull the dot
+     further into a round mark than into a square one.
+
+     --avatar-presence-ring-color and the four state colours are ROLE-MIRROR knobs: declared
+     `initial` here so the --background / --success / --warning / --destructive / --muted-foreground
+     defaults resolve at the CALL SITE and a scoped [data-tenant] / .dark override of the ROLE still
+     reaches them (docs/TOKENS.md · "Role-mirror knobs MUST be `initial`"). Binding them to the role
+     here would freeze the ring light-mode-white on a dark avatar.
+
+     Presence is never colour-alone (WCAG 1.4.1): the colour rides with a SHAPE — filled · half
+     filled · barred · hollow — and a localized sr-only string, so --avatar-presence-stroke-width and
+     --avatar-presence-bar-* are part of the accessible encoding, not decoration.
+
+     Defaults = 30% of the mark, floor 0.5rem · flush with the mark's corner · 2px separator ring in
+     --background · 1.5px state stroke · a 56%-wide, 1.5px dnd bar. */
+  --avatar-presence-size: 30%;
+  --avatar-presence-min-size: var(--space-2);
+  --avatar-presence-inset: 0;
+  --avatar-presence-ring-width: var(--stroke-md);
+  --avatar-presence-stroke-width: var(--stroke-sm);
+  --avatar-presence-bar-inline-size: 56%;
+  --avatar-presence-bar-block-size: var(--stroke-sm);
+  --avatar-presence-ring-color: initial;
+  --avatar-presence-online-color: initial;
+  --avatar-presence-away-color: initial;
+  --avatar-presence-busy-color: initial;
+  --avatar-presence-offline-color: initial;
+
   /* Progress track + fill — `initial` so the role defaults re-resolve under a scoped theme.
      Track reads --secondary, fill reads --success; a service re-tones once.
      Defaults = hsl(var(--secondary)) track · hsl(var(--success)) fill. */
@@ -65,4 +115,29 @@
   --qr-code-size-sm: 8rem;
   --qr-code-size-md: 10rem;
   --qr-code-size-lg: 12.5rem;
+
+  /* SCROLL AREA — the custom scrollbar rail. `.ui-scroll-area-*` did not exist at all: the whole
+   * rail shipped as Tailwind literals on the component (`w-2.5 p-px` / `h-2.5 p-px`,
+   * `rounded-full`), so a service could not widen the bar for a touch/coarse-pointer console or
+   * square the thumb to match a sharp-cornered theme without forking ScrollArea (rule #45).
+   * --scroll-area-bar-size is a RAW rem on purpose: it replaces a FLAT Tailwind step (2.5 = 10px),
+   * not a --space-* step, so binding it to the density-scaled scale would silently change today's
+   * rendering under a non-default --scaling. Defaults reproduce the previous rail exactly. */
+  --scroll-area-bar-size: 0.625rem;
+  /* Hairline inset that keeps the thumb off the rail edge — a service running a thicker bar
+   * usually wants a proportionally larger gutter here. */
+  --scroll-area-bar-padding: 1px;
+  --scroll-area-thumb-radius: var(--radius-pill);
+
+  /* PERMISSION MATRIX — the sticky-first-column grid. Nothing here was themeable: the class
+   * `.ui-permission-matrix` existed as a bare hook with no CSS rule at all, so every constant
+   * lived on the component (#319). A JA/VI service whose role names run longer than the English
+   * ones could not widen the label column without forking. */
+  --permission-matrix-label-width: 16rem;
+  --permission-matrix-role-space-gap: var(--space-1);
+  --permission-matrix-name-space-gap: 0.375rem;
+  --permission-matrix-cell-icon-size: var(--control-icon-size);
+  /* Floor for the scrolling body — below this the columns collapse into unreadable slivers, so
+   * the table scrolls instead. Mirrors --table-surface-min-inline-size on DataTable. */
+  --permission-matrix-min-width: 48rem;
 }

package/dist/tokens/components/data-entry.css

@@ -1,6 +1,31 @@
 /* Data-entry component tokens — small-by-design text knobs (rule #45/#46). */
 
 :root {
+
   --password-strength-score-font-size: var(--font-size-xs);
   --password-strength-checklist-font-size: var(--font-size-xs);
+
+  /* BranchScopePicker (gh#319). `.ui-branch-scope-picker` was a bare hook with no rule anywhere:
+   * every measure lived as a Tailwind literal on the component, so a service could only retune
+   * the control by forking it (#45).
+   *
+   * All four are FLAT rems, not `--space-*` aliases, on purpose: the literals they replace read
+   * Tailwind's own `--spacing` grid, which this package never remaps and which does NOT move with
+   * the density axis. Aliasing them to `--space-3`/`--space-2`/`--space-1` would silently start
+   * scaling the control inside a `.ui-density-*` subtree — a visual change, not a refactor. */
+  /* Stack rhythm between the mode radios, the subset box and the error line (was `gap-3`). */
+  --branch-scope-picker-gap: 0.75rem;
+  /* Read-only summary: the wrapped run of branch Badges (was `gap-1.5`). */
+  --branch-scope-picker-badges-gap: 0.375rem;
+  /* The `mode="selected"` subset box — its inner stack rhythm and the inset that clears its
+   * indent rule (was `gap-2` / `ps-4`). */
+  --branch-scope-picker-subset-gap: 0.5rem;
+  --branch-scope-picker-subset-padding-inline: 1rem;
+  /* The indent rule itself is CHROME (#44), so it is a knob: a service that wants the flat
+   * treatment sets it to 0 rather than forking the component. Default = today's `border-s-2`. */
+  --branch-scope-picker-subset-border-width: var(--stroke-md);
+  /* Bounded height of the scrollable branch list (was `max-h-64`). Flat by design: the box is a
+   * keyboard-reachable scroll region whose job is to cap the control's measure, so it must not
+   * grow with density and push the surrounding form off a 390px frame. */
+  --branch-scope-picker-list-max-height: 16rem;
 }

package/dist/tokens/components/descriptions.css

@@ -11,4 +11,26 @@
    * block above an editable field on the same card) retunes this to `var(--space-4)` to match
    * Form's own field-to-field rhythm instead of the two blocks reading as visually unrelated. */
   --descriptions-row-gap: var(--space-3);
+  /* Column-to-column gap of the <dl> grid (#319). Was a hardcoded `gap-x-6`, the one axis of the
+   * grid rhythm a service could NOT reach while --descriptions-row-gap was already a knob — so a
+   * 2/3-column detail block could be retuned vertically but never horizontally.
+   * A RAW rem, deliberately NOT var(--space-6): `gap-x-6` reads Tailwind's own --spacing grid,
+   * which this repo does NOT density-scale, so a --space-* default would silently rescale the
+   * column gap under a compact/comfortable density. Point it at var(--space-6) to opt in. */
+  --descriptions-column-gap: 1.5rem;
+  /* Label → value gap inside ONE item when layout="horizontal" (was `gap-x-3`). Pairs with
+   * --descriptions-label-width: a service that narrows the label column usually wants to close
+   * this gap in the same step. Raw rem for the same --spacing reason as above. */
+  --descriptions-label-gap: 0.75rem;
+  /* VALUE TYPOGRAPHY (gh#294 + #319). `FormField staticText` renders its read-only value with the
+   * SAME typography as a <dd> so a static Form row and a Descriptions value are indistinguishable
+   * when mixed on one card. That contract used to be two copies of the literal `text-sm` plus a
+   * comment asking future editors to keep them in sync; both call sites now read these tokens, so
+   * the mirror is mechanical and a service retunes BOTH from one place. */
+  --descriptions-value-font-size: var(--font-size-sm);
+  /* Companion to --descriptions-value-font-size (the gh#260 bug). The `text-sm` utility this
+   * replaces ALSO set a line-height, via Tailwind's default `--text-sm--line-height`
+   * (= calc(1.25 / 0.875)); the theme remaps --text-sm but never that companion. Without this the
+   * value would silently inherit ambient leading instead of its own 20px line box. */
+  --descriptions-value-line-height: calc(1.25 / 0.875);
 }