@mkbabb/glass-ui 3.12.0 → 4.0.0

package/dist/styles/tokens/offsets-sizing.css

@@ -0,0 +1,562 @@
+/* tokens/offsets-sizing.css
+   §9 animation offsets · §10 sizing (control heights, dropdown, carousel, stack-overlap, touch-target floor).
+   Carved from the tokens.css cascade root; @import-ed by tokens.css in
+   cascade order. Same :root cascade context as its siblings. */
+:root {
+    /* ═══════════════════════════════════════════════
+       §9  ANIMATION OFFSETS
+       ═══════════════════════════════════════════════ */
+    /* Hover lift offsets */
+    --lift-sm: -1px;
+    --lift-md: -2px;
+    --lift-lg: -4px;
+
+    /* Layout tokens */
+    /* BA.W-FADING-SCROLL — `--fade-scroll-width` is the public edge-fade ramp
+       width knob for `<FadingScroll>` (inheriting, retunable on any ancestor;
+       SegmentedTabs' `overflow="scroll"` strip overrides it to 0.5rem). It
+       SUPERSEDES `--mask-fade-width` (the scroll-BLIND `.scroll-fade-*` static
+       masks' knob). `--mask-fade-width` is RETIRE-COORDINATED: it survives this
+       wave because the static `.scroll-fade-*` utility blocks survive (so
+       W-CONFIG-CHASSIS's C2/C3 configurator columns still render mid-batch); it
+       retires in a CLEAN BREAK (no alias) at the orchestrator's Batch-2-close
+       commit alongside the static utilities, once C2/C3 have migrated onto the
+       primitive. */
+    --fade-scroll-width: 1rem;
+    --mask-fade-width: 1rem;
+    /* J.W3.C — dock content overflow caps. When dock content exceeds
+       these dimensions, the inner `.dock-layers` (horizontal) /
+       `.glass-dock.vertical` (rail) container scrolls with a
+       `.scroll-fade-{x,y}` mask-fade so the boundary feathers rather
+       than cliffs. Defaults clamp to 80vw / 80vh capped at sensible
+       desktop widths; consumers override per-dock by setting either
+       token directly on a `.glass-dock` instance. User findings 1 + 5a. */
+    /* AX.W04 — `--dock-max-inline-size` is the canonical inline cap EVERY overflow
+       strategy reads: `overflow="scroll"` scrolls past it, and `overflow="wrap"`
+       wraps to N rows on the over-cap crossing (the dock shrink-wraps to content,
+       `max-inline-size` caps that intrinsic width at this token). The prior
+       `--dock-overflow-bp: 640px` viewport-breakpoint token (the magic-640
+       snap-back) is DELETED — the wrap is content-driven, not viewport-coupled, so
+       there is no breakpoint threshold to name. */
+    --dock-max-inline-size: min(80vw, 64rem);
+    --dock-max-block-size: min(80vh, 48rem);
+
+    /* AB.W1.T1 — chassis max-block-size guardrail.
+       Maximum block size a centred consumer-app card may consume while
+       preserving the inline dock footprint. The recipe subtracts the
+       consumer-owned `--dock-footer-space` (dock height + dock inset +
+       card-edge inset) and `--page-padding-top` from the dynamic viewport,
+       then takes one further rem of breathing room so the card never
+       butts the dock — the user mandate is `≥ 1rem visible gap above
+       dock`. Both consumer tokens carry safe fallbacks for callers that
+       have not declared them.
+
+       Consumers should shrink internal regions (meter, readout, timeline)
+       before falling back to scroll. This token is a guardrail against
+       chassis overflow, NOT a license to make the card scroll as the
+       default solution; clamp-first / no-scroll-first is the canon.
+       See DESIGN.md `## Chassis sizing — dock-adjusted viewport`. */
+    --chassis-max-block-size: calc(
+        100dvh
+        - var(--dock-footer-space, 5.75rem)
+        - var(--page-padding-top, 0rem)
+        - 1rem
+    );
+    /* R0G-2 (AO.W3/W4) — chassis mobile dial-reserve canon. instrument-
+       chassis.css's mobile breakpoint reserves the dial's final box from
+       frame 0 via these vars (with the same values as inline fallbacks, the
+       safety net). Token-first home so the vars resolve canonically. */
+    --instrument-dial-min-height-mobile: 24rem;
+    --instrument-dial-meter-reserve-mobile: minmax(0, 1fr);
+
+    --max-width-input: 24rem;
+    --input-min-width-sm: 5rem;
+    --min-width-input-sm: var(--input-min-width-sm);
+    /* AU.W8b.4 — canonical popover width (Combobox list + anchor). Lifts the
+       `w-[200px]` arbitrary-value wrap to the `w-popover` @theme utility. */
+    --popover-width: 200px;
+    /* AZ.R5-4 — the ONE panel inner-padding rung (the consumer-verified "the
+       popover/dropdown content reads TIGHT" finding). The floating-panel +
+       DropdownMenuContent recipes read THIS token for their inner pad instead of
+       the prior hand-set `p-1`/literal, so a consumer retunes every teleported
+       menu/panel surface from one override. The comfortable default is `0.375rem`
+       (a half-rung over the prior 0.25rem tight floor — comfortable both modes
+       without over-padding a dense menu list). PopoverContent keeps its own
+       `--panel-padding-roomy` (1rem) for the prose-popover register. */
+    --panel-padding:       0.375rem;
+    --panel-padding-roomy: 1rem;
+    --chart-height-compact: 15rem;
+    --chart-height-default: 22.5rem;
+    --chart-height-large: 25rem;
+    --chart-margin: 1.25rem;
+    --paper-texture-size: 200px 200px;
+
+    /* Border opacity scale */
+    --border-opacity-light:  0.15;
+    --border-opacity-medium: 0.25;
+    --border-opacity-strong: 0.6;
+
+    /* ═══════════════════════════════════════════════
+       §10 SIZING
+       ═══════════════════════════════════════════════ */
+    /* ── The ONE comfortable-sizing scale doctrine (AX.W51 D18) ──────────────
+       `--ui-scale` is the MASTER comfortable-sizing scalar — ONE unitless knob
+       (registered @property <number>, inherits:true, default the identity 1)
+       every interactive-control magnitude derives through `calc(<base> *
+       var(--ui-scale))`, so a single override grows control HEIGHT + PADDING +
+       GAP + FONT-SIZE + GLYPH in LOCKSTEP, proportion preserved, no per-component
+       hack. The cohorts below (`--control-h-*` heights, `--control-text*` control
+       fonts, `--ui-glyph*` glyphs) are its reading surfaces; the CVA bases + the
+       `.btn-pill`/`.input-pill` pills consume them.
+
+       ONE scale system, not three. The dock (`--dock-scale`) and the dropdown
+       family (`--dropdown-text`, W50) are SPECIALIZATIONS that read this axis:
+       `--dock-scale: calc(var(--ui-scale) * var(--dock-local-scale, 1))` — the
+       dock multiplies ON TOP of the global comfort axis (its existing geometry
+       `calc` cascade inherits the global axis for free, zero edit). A consumer
+       re-tints the whole library's comfort from ONE `:root { --ui-scale: … }`
+       override (or a scoped region — a dense data-table sets it lower) — the
+       token-first axis.
+
+       EXCLUDED — the φ-DISPLAY ladder (`--type-display-*` / `--type-title` /
+       `--type-heading` / `--type-subheading`): a hero/title is a TYPOGRAPHIC
+       identity, NOT a touch target, so it does NOT grow on the comfort/coarse
+       axis. Only interactive-CONTROL text rides `--ui-scale`. Containers (card /
+       panel radii + paddings) are separate `--radius-*` / `--space-*` axes.
+
+       The desktop default is the IDENTITY (1) — byte-exact preservation, no
+       reflow of shipped consumers. The comfort GROWTH lives at the coarse-pointer
+       default (`--ui-coarse-scale`, §below) + the consumer override. The
+       WCAG-2.5.5 44px touch floor survives as a `max(…, --control-floor)` clamp
+       inside the scaled control-size (the coarse block lifts `--control-floor` to
+       `--touch-target`, so a sub-1 scale cannot drop a control under the target).
+       Coordinates with W54's `--glass-level` + W55's `--glass-tint-*` — SEPARATE
+       axes (size vs material vs legibility); a control is comfortably-sized AND
+       glass AND legible, three orthogonal knobs. */
+    --ui-scale: 1;
+    /* The global coarse-pointer comfort default — the WHOLE library grows ~1.5×
+       on touch from ONE place (the @media (pointer: coarse) block at §below lifts
+       :root --ui-scale to this). The dock's prior parallel 1.5× becomes the global
+       default it now shares. Public library-default identity — a consumer sets
+       1.3 / 1.75 on :root or a scope. */
+    --ui-coarse-scale: 1.5;
+    /* The control-height cohort — the h-7/h-9/h-10/h-11 register (28/36/40/44px)
+       the CVA size rungs encode, each scaled by the master axis. The CVA rungs
+       read these via `h-[var(--control-h-*)]` instead of the raw `h-N` literal.
+       `--control-floor` is the WCAG-2.5.5 clamp seam (0 at desktop, lifted to
+       --touch-target under coarse-pointer); each height is `max(scaled, floor)`. */
+    --control-floor: 0px;
+    --control-h-xs: max(calc(1.75rem * var(--ui-scale)), var(--control-floor));
+    --control-h-sm: max(calc(2.25rem * var(--ui-scale)), var(--control-floor));
+    --control-h-md: max(calc(2.5rem  * var(--ui-scale)), var(--control-floor));
+    --control-h-lg: max(calc(2.75rem * var(--ui-scale)), var(--control-floor));
+    /* The control-FONT register (RED 3 — the user's "font too small"). A comfort
+       multiplier BETWEEN the static φ-ladder rung and the painted control font,
+       so interactive-control text grows on the comfort axis while the φ-DISPLAY
+       ladder stays a pure typographic scale (display headings do NOT grow on
+       touch). `--control-text` is the workhorse (the `text-sm` register the
+       buttons/inputs/triggers carried); `--control-text-sm` is the quieter rung
+       (the `text-xs` badge/caption register). W50's `--dropdown-text` IS the
+       picker-family specialization of this register.
+
+       AY.W-SCALE1 — the no-double-vw reconcile: the desktop-fluid viewport base
+       lives ONCE in `--type-small` / `--type-caption` (typography.css §scale — a
+       gentle `clamp(…vw…)` so the control font grows on a wide display); the
+       `--ui-scale` comfort scalar multiplies that FLUID base exactly ONCE HERE. The
+       vw term is applied once (in the rung), the comfort factor once (here) — under
+       the coarse 1.5× the font grows by the comfort factor ONCE, NOT vw×1.5
+       over-scaled. Do NOT inline a second clamp() here, and do NOT multiply the rung
+       by --ui-scale at the rung. */
+    --control-text:    calc(var(--type-small) * var(--ui-scale));
+    --control-text-sm: calc(var(--type-caption) * var(--ui-scale));
+    /* The control-GLYPH cohort (RED 4 — the glyph grows WITH the box). The
+       1rem/0.875rem control-glyph register the `size-4`/`size-3.5` literals
+       encode; the un-sized-<svg> CVA rule reads these via
+       `size-[var(--ui-glyph)]`, KEEPING the `:not([class*=size-])` host-sized-icon
+       escape intact (an explicit `size-9` still wins). */
+    --ui-glyph:    calc(1rem     * var(--ui-scale));
+    --ui-glyph-sm: calc(0.875rem * var(--ui-scale));
+
+    /* ── The picker-family type-scale (AX.W50 D17) ───────────────────────────
+       ONE governed two-rung scale the WHOLE shadcn picker family (Select /
+       DropdownMenu / Combobox / ContextMenu / Command / MultiSelect) reads, so the
+       family paints at ONE uniform scale instead of the scattered raw
+       `text-sm`/`text-xs` Tailwind-literal lottery (item rows at `text-sm`,
+       headings/shortcuts at `text-xs`, the two filter inputs at mismatched heights).
+       A consumer re-tints the whole family from ONE override.
+
+       It is a SPECIALIZATION of W51's control-font register (one scale system, not
+       three): `--dropdown-text` reads `--control-text` (the comfort-scaled `text-sm`)
+       and `--dropdown-text-secondary` reads `--control-text-sm` (the comfort-scaled
+       `text-xs`), so the picker family rides the SAME `--ui-scale` comfort axis as
+       every other control — a `--ui-scale` bump grows the dropdowns too. A consumer
+       wanting the family LARGER than the rest overrides `--dropdown-text` directly
+       (e.g. `var(--type-body)`); the override re-resolves every family surface.
+
+       Scale-contract (which surface reads which rung):
+         • PRIMARY (`--dropdown-text`)   → item rows, triggers, filter inputs, empties.
+         • SECONDARY (`--dropdown-text-secondary`) → section labels, group-headings,
+           keyboard shortcuts (the quieter-than-item caption register; resolves the
+           witness-2 contradiction — the Select/DropdownMenu/ContextMenu labels
+           collapse DOWN to the secondary rung to match the Combobox/Command headings,
+           ONE rung for the section-label role family-wide).
+       `--dropdown-input-height` unifies the two filter-input heights (Combobox was
+       h-10, Command was h-11) onto ONE register — a specialization of W51's
+       `--control-h-md` so the picker input scales on the comfort axis with the font. */
+    --dropdown-text:           var(--control-text);
+    --dropdown-text-secondary: var(--control-text-sm);
+    --dropdown-input-height:   var(--control-h-md);
+
+    --size-icon-btn: 2.5rem;
+    --icon-xs: 0.75rem;
+    --icon-sm: 0.875rem;
+    --icon-md: 1rem;
+    --icon-lg: 1.25rem;
+    --icon-xl: 1.5rem;
+    /* V.W2 T9 — 32px rung; spinner glyphs (Loader2) + dense table-row buttons.
+       Naming follows the radius ladder + Tailwind convention (2xl > xl > xxl) —
+       see B6 §2.4 for the naming rationale. */
+    --icon-2xl: 2rem;
+    /* V.W2 T10 — 40px rung; empty-state hero glyph (DashboardMap MapIcon).
+       AI.W5-ζ — rebound from `2.5rem` literal to `var(--size-icon-btn)` so
+       the alignment is contractual single-source-of-truth rather than the
+       coincidental numerical match noted prior. */
+    --icon-3xl: var(--size-icon-btn);
+    /* V.W2 T11 — 56px rung; FlowSelector school/home survey-flow picker.
+       Largest rung in the icon ladder; reserved for hero-class glyphs. */
+    --icon-hero: 3.5rem;
+
+    /* Golden-ratio spacing rungs — φ² and φ³. Preemptive substrate; W4 hero
+       chassis + W5 StoryChassis migration land the consumers. R3 §A row 1.
+       The 0..4 rungs are not currently named (consumers reach via
+       Tailwind's spacing scale); 5/6 land here because their values fall
+       outside the default ladder and the audacious chassis pattern wants
+       a named handle. */
+    --space-phi-5: 2.618rem; /* φ² */
+    --space-phi-6: 4.236rem; /* φ³ */
+
+    /* Dock geometry — consumers may override locally */
+    --dock-h: calc(var(--size-icon-btn) + 0.75rem + 3px);
+    --dock-margin: 0.5rem;
+    --dock-menubar-reserve: 4rem;
+
+    /* AX.W45 — the dock geometry multiplier. `--dock-scale` threads the WHOLE
+       `.glass-dock[data-density]` geometry cascade (box, padding, gap, tab,
+       tile-min, glyph) via `calc(<base> * --dock-scale)`, so a single knob grows
+       every dock axis in lockstep. The WCAG 2.5.5 44px floor survives as a `max(…,
+       44px)` clamp INSIDE the scaled control-size.
+
+       AX.W51 RECONCILE (D18) — `--dock-scale` is RE-HOMED as a SPECIALIZATION of
+       the global `--ui-scale` comfort axis: `calc(var(--ui-scale) *
+       var(--dock-local-scale, 1))`. The dock now MULTIPLIES on top of the global
+       comfort scalar — its whole existing geometry `calc` chain inherits the global
+       axis for FREE (zero edit to the density cascade; the reconcile is at this ONE
+       definition line). At the desktop identity (`--ui-scale: 1`,
+       `--dock-local-scale: 1`) the dock is byte-identical to HEAD. On coarse-pointer
+       the GLOBAL `:root { --ui-scale: var(--ui-coarse-scale, 1.5) }` block grows the
+       dock WITH the rest of the library — ONE consistent touch scale, not a parallel
+       dock-only 1.5×. `--dock-local-scale` is the dock-local EXTRA multiplier
+       (default 1): a consumer who wants the dock LARGER than the global comfort sets
+       it, and the coarse block lifts it to `--dock-mobile-scale` (default 1, the
+       stack-extra) so the dock can grow an extra notch ON TOP of the global coarse
+       default. `--dock-mobile-scale` is the public library-default identity
+       (presets-in-consumers: a consumer sets 1.3/1.75 on `:root` or a dock scope). */
+    --dock-scale: calc(var(--ui-scale) * var(--dock-local-scale, 1));
+    --dock-local-scale: 1;
+    /* --dock-mobile-scale is the CONSUMER coarse knob — UNSET at :root so the
+       dock-layer coarse default (--dock-coarse-scale, below) is the fallback the
+       coarse block reads; a consumer setting --dock-mobile-scale on ANY ancestor
+       wins the fallback (R5-1 — the knob must reach the geometry cascade, not be
+       shadowed by a hard-pin on .glass-dock[data-density]). The coarse block in
+       dock/overflow.css RE-DECLARES --dock-scale so the descendant --dock-local-scale
+       lift re-flows into it (the substitution-vs-inheritance trap). */
+    --dock-mobile-scale: initial;
+    /* R5-2 — the dock-layer coarse-register default. The dock is a DENSE chrome strip
+       (not a body control), so on touch it floors at a TIGHTER multiplier than the
+       global --ui-coarse-scale 1.5 (which painted an ~80px collapsed pill, ~22% too
+       big — the slides-consumer R5-2 finding). 0.78 × the 1.5 global ≈ 1.17 effective
+       → a ~60px collapsed pill, the WCAG-2.5.5 44px floor held by the
+       `max(…, --dock-control-floor)` clamp. The consumer knob --dock-mobile-scale
+       overrides this; a consumer who wants the dock to MATCH the global comfort sets
+       --dock-mobile-scale: 1. */
+    --dock-coarse-scale: 0.78;
+    /* Library glyph ownership — `.dock-icon-button > svg` reads this so the dock
+       icon glyph scales WITH the box (mirroring `.dark-mode-toggle-button > svg`).
+       A consumer-passed explicit lucide size class still WINS (utility layer >
+       component layer); this is a DEFAULT, not a ceiling. */
+    --dock-icon-glyph: calc(1.25rem * var(--dock-scale));
+
+    /* AX.W45-TUNE Q1 — the COLLAPSED-pill floor tokens. The collapsed summary
+       used to fall to `--dock-layer-height` (the FULL control height, ~2.5rem) for
+       its `min-width` with NO block floor, so the shrunken pill read as an
+       un-collapsed control row, not a tight proportioned squircle. These two floor
+       tokens (referenced by dock.css's `.collapsed .dock-layer--summary` min-size +
+       the `--dock-pad-collapsed` morph floor) mint a TIGHT proportioned pill: the
+       summary min-size is ≈70% of the full control height (a proportioned dot, not a
+       full-row stub — the ratified default), and the collapsed padding is a step
+       BELOW the expanded `--dock-padding-block` so the collapsed chrome hugs the
+       glyph. The summary carries a SYMMETRIC `min-block-size` (dock.css) keyed to the
+       same token so the pill floors on BOTH axes — a squircle, not a stub. Consumers
+       retune the pill geometry per-instance via these two handles. */
+    /* AY.W-DOCK-NAV B4 — the collapsed pill is a PERFECT CIRCLE (the user's
+       "circle, not oval" bar). The diameter is the collapsed-summary min-size on
+       BOTH axes; the morph.css `.collapsed .dock-layer--summary` rule LIFTS the
+       `.dock-layer` height-lock (`height: var(--dock-layer-height)`) for the
+       collapsed summary so the pane is square at this token (the prior oval —
+       38×50, aspect 0.76 — was the locked 40px height against a 28px min-width).
+       The 0.85× value is a TIGHT proportioned circle a step below the full control
+       (so the collapsed dot reads smaller than an expanded control row) while
+       staying large enough that the centred glyph is not cramped. A consumer
+       retunes the circle diameter via this one handle. */
+    --dock-collapsed-summary-min-size: calc(var(--dock-layer-height, 2.5rem) * 0.85);
+    /* AX.W61 — the collapsed padding now threads the ONE `--dock-scale` coarse-pointer
+       multiplier DIRECTLY (at HEAD it was a flat 0.25rem off the scale, so the
+       collapsed pad alone stayed desktop-sized at the 1.5x mobile scale while the
+       box/glyph/min-size grew — a desync the morph then interpolated FROM). The
+       summary min-size already threads `--dock-scale` transitively through
+       `--dock-layer-height` (itself `calc(* --dock-scale)` at every density rung); this
+       lands the collapsed pad on the same thread so the whole collapsed pill scales
+       coherently on touch. The 0.25rem base stays the ratified tight floor. */
+    --dock-collapsed-padding: calc(0.25rem * var(--dock-scale));
+
+    /* AX.W45-TUNE Q3/C3 + C5 — the dock-control family reads a real GLASS register
+       on hover/active, NOT a same-hue `--card` mix at an alpha adjacent to the dock's
+       own `--glass-bg-dock` substrate (a sub-1%-ΔL no-op — the loud Q3 tell: "nothing
+       on hover, something on click"). Both legs now point at NAMED glass tiers a
+       measurable step ABOVE the dock's 42%-opacity substrate:
+         • hover  → `--glass-bg-resting` (the 65% glass plate) — the control surface
+                    WAKES as a brighter glass tier on hover, reading the blurred dock
+                    substrate through it. The +ΔL above `--glass-bg-dock` is perceptible
+                    BEFORE click; the specular gleam + scale ride alongside (one register).
+         • active → `--glass-bg-floating` (the 80% glass plate) — a tier ABOVE hover,
+                    the keyframes-dock "selected element reads as glass" model the user
+                    named (`pass-3:13`): the selected tile is a glass tier that shows the
+                    substrate through it, NOT the flat `--surface-tint-12` ink wash. The
+                    active ≠ hover register is the glass-tier step, not an alpha nudge.
+       This is a REGISTER change (substrate→glass-tier), not a magnitude knob. The
+       per-control `--dock-icon-hover-bg` override still wins if a consumer set it. */
+    --dock-control-hover-bg: var(--glass-bg-resting);
+    --dock-control-active-bg: var(--glass-bg-floating);
+
+    /* AX.W45-TUNE C4/C5 — the small-tile specular override. The 40px dock-control
+       tile is a fraction of a card's plate, so the global `--glass-specular-size`
+       (36% of the plate) blooms a disproportionate disc on a hover/active dock tile
+       (the I.W6 finding). The dock controls scope a TIGHTER radius (22%) so the gleam
+       wakes as a restrained EDGE-catch on the small tile, not a tile-filling bloom —
+       the right resolution of I.W6 (sized-down on the small surface), not turning the
+       specular off everywhere. Read by the dock-control `::before` recipe (glass.css)
+       via the family-scoped override below; the global card/panel size is untouched. */
+    --dock-control-specular-size: 22%;
+
+    /* AZ.W-DOCK-RAIL — the layer-switcher rail is a HAIRLINE register, not a
+       fused tinted gutter. The `--surface-tint-8` filled plate (the "heavy dark
+       blob column" R3-1) is RETIRED: `--dock-layer-rail-bg` defaults TRANSPARENT
+       so the rail box paints no fill, and the single `--dock-layer-rail-divider`
+       hairline becomes the only visible rail edge — a thin rule between the
+       switcher column and the dock body (the iOS-grade hairline switcher).
+       The hover/active affordance stays a translucent GLASS tint: the active
+       indicator reads `--dock-layer-rail-active`, defaulting to the glass-floating
+       tier (the keyframes-dock "selected reads as glass" register), NOT a
+       saturated `--primary 15%` warm-red mix — the exact accent defers to
+       W-REGISTER-IOS's root register (the rail keeps a glass tint here, never
+       bakes a brand-red the de-red wave has to undo). */
+    --dock-layer-rail-bg: transparent;
+    --dock-layer-rail-divider: color-mix(in srgb, var(--border) 40%, transparent);
+    --dock-layer-rail-hover: color-mix(in srgb, var(--accent) 30%, transparent);
+    --dock-layer-rail-active: var(--glass-bg-floating);
+    /* AY.W-DOCK-NAV B6 — the switcher-rail TAB is a COMPACT square, distinct from
+       the 40px dock CONTROL. The prior fallback chain (`var(--dock-control-size,
+       1.75rem)`) resolved to the full 40px control, so a 3-tab column rail stood
+       ~140px tall — a giant pill of dead space. A dedicated tighter tab size
+       (1.75rem = 28px, density-scaled) keeps the rail a compact icon column the
+       indicator travels cleanly, and the dock grows only as tall as the rail needs.
+       Consumers retune the rail-tab size via this one handle. */
+    --dock-layer-tab-size: calc(1.75rem * var(--dock-scale));
+
+    /* BA.W-DOCK-SECTIONS — the divider-seam rail knobs.
+       `--dock-rail-extend-length` (declared in rail-extend.css) was RE-SEMANTICIZED:
+       it is no longer a one-way connector length but the SYMMETRIC per-side overrun of
+       the seam line (the line's cross-extent = dock extent + 2× the knob, centered on
+       the seam). `--dock-rail-retract-stub` is the residual protrusion FRACTION the
+       chips leave past the dock edge on collapse (the macOS fan-out "retract INTO the
+       rail leaving a slight protrusion"; 0 = fully retracted, 1 = no retract). The
+       `--dock-section-zone-gap` is the inter-control rhythm inside a <DockSection> zone
+       (defaults to the dock's own `--dock-gap`, so the section grouping adds no box). */
+    --dock-rail-retract-stub: 0.35;
+    --dock-section-zone-gap: var(--dock-gap, 0.25rem);
+
+    /* Dock active-state ladder (O.W6 Lane B)
+       Token-overridable active paint for `.dock-icon-button`. Promoted
+       from hardcoded `background: var(--muted); color: var(--foreground)`
+       per bbnf-buddy O11/c R1: 7 `:deep()` escapes at `ToolsLayer.vue`
+       redefine bg/color/scale/border/shadow on the active variant; the
+       ladder absorbs ~3 of 7 at a stroke. Defaults preserve the prior
+       visual contract (no transform, no border, no shadow) — overrides
+       take effect per-instance via `:root` or a parent scope, e.g.
+       `.tools-layer { --dock-active-scale: 1.2; --dock-active-bg: …; }`.
+       ≥ 2-consumer coverage: bbnf-buddy ToolsLayer (override consumer) +
+       speedtest dock (default consumer).
+
+       AX.W45 DK2 — re-pointed off the opaque `--muted` plate onto the glass-
+       correct `--dock-control-active-bg` (a translucent tint a ladder step above
+       hover), so the icon-button active no longer stamps a solid cream rectangle
+       over the dock glass. The O.W6 active-ladder override consumers still retint
+       per-instance; only the DEFAULT moved to glass-correct. */
+    --dock-active-bg: var(--dock-control-active-bg);
+    --dock-active-color: var(--foreground);
+    --dock-active-scale: 1;
+    --dock-active-border: none;
+    --dock-active-shadow: none;
+
+    /* AZ.W-REGISTER-IOS — the iOS-26/27 SELECTED register, at the ROOT.
+       R3-6 retired the brand-red (`--viz-fourier`) interactive register
+       (hover/active/selected/pressed) in favour of the iOS-glassy luminance-lift:
+       a translucent material-lift plate (`--dock-control-active-bg`, already the
+       `--glass-bg-floating` tier — C4-INV-1, UNCHANGED) + a brighter-material
+       accent that lifts LUMINANCE, never a saturated brand hue.
+
+       `--dock-selected-accent` is the SINGLE retint knob for the selected
+       affordance: it defaults to a translucent foreground-over-transparent
+       "brighter material" lift, so it auto-FLIPS with `--foreground` (dark mode
+       resolves a light luminance-lift over the dark plate — the iOS read). The
+       rail leading-edge accent BAR (`dock-controls.css` `::before`) consumes it;
+       the selected GLYPH stays `--foreground` warm-ink (arm-a — the glyph never
+       carries the accent token, only the bar does). A consumer retints the whole
+       selected affordance through this ONE token (token-first); red survives only
+       as static brand INK (the ℱ wordmark / data-viz strokes / the gold-CTA
+       family), never as an interactive register. */
+    --dock-selected-accent: color-mix(in oklab, var(--foreground) 14%, transparent);
+
+    /* AZ.W-REGISTER-IOS — the iOS press-DARKEN. Press today scales only
+       (`--scale-press-dock`, C4-INV-4); iOS lands "darken + shrink". This token
+       is a tier BELOW resting — `--glass-bg-resting` mixed ~7% toward `--foreground`
+       — read on the dock control `:active` alongside the scale-press so a press
+       lands the brief glass-darken. Auto-flips with `--foreground`/`--glass-bg-resting`. */
+    --dock-control-press-bg: color-mix(
+        in oklab,
+        var(--glass-bg-resting),
+        var(--foreground) 7%
+    );
+
+    /* Q.W3 Lane G (Q-cos-13) — the O.W6 Lane D `--icon-tooltip-hit-area`
+       token retired here. IconTooltip no longer owns a wrap-span; the
+       slotted child carries its own WCAG 2.5.5 hit-area (interactive
+       children via their four-state contract, bare glyphs via a
+       `min-h-11 min-w-11` host). No orphaned token left behind. */
+
+    /* O.W6 Lane D — Dock touch-target floor. Mirrors the IconTooltip
+       hit-area but for the dock-control surface. The base value tracks
+       the desktop default (`--size-icon-btn`); the
+       `@media (pointer: coarse)` block at `dock.css` lifts it to the
+       WCAG 2.5.5 floor on touch devices. */
+    --dock-touch-target: 2.75rem; /* 44px */
+
+    /* AQ.W3 §7 — canonical WCAG 2.5.5 (44px) touch-target floor for the
+       NON-dock coarse-pointer surfaces (`Button size="icon"`,
+       ExpandableContainer triggers, SegmentedTabs responsive mobile trigger). One
+       named rung the `@media (pointer: coarse)` block in utilities.css reads,
+       retiring the per-consumer one-liner `min-h-[44px]` patches. Equals
+       `--dock-touch-target` numerically; kept as a distinct token so the
+       dock floor and the general floor can be retuned independently. */
+    --touch-target: 2.75rem; /* 44px */
+
+    /* MetricBadge — stacked variant geometry. The 2-row stacked layout
+       (label / value+unit) wants a taller floor than the inline pill so the
+       label has breathing room above the baseline pair. T.W2.T2 +
+       audit B-spec §3.2 vertical-rhythm table land 42px (2.625rem) as the
+       min-height with 6px (0.375rem) block padding. The inline ladder
+       keeps its tight defaults via `--metric-badge-min-height` /
+       `--metric-badge-padding-block` (declared inline at the
+       `.metric-badge` selector). */
+    --metric-badge-min-height-stacked: 2.625rem;
+    --metric-badge-padding-block-stacked: 0.375rem;
+
+    /* Configurator — N.W2 Lane A density axis (4 rungs).
+       The `comfortable` rung restates the pre-N.W2 baked recipe exactly
+       (`gap-1.5 py-2` = 0.375rem / 0.5rem) so unparameterised consumers
+       see no visual change. `mobile` halves the vertical breathing room
+       for narrow-viewport studios; `spacious` doubles it for settings-
+       page hosts. See `<ConfiguratorRow>` scoped CSS for the attribute-
+       selector binding. */
+    --configurator-row-gap-mobile: 0.25rem;        /*  4px — tight */
+    --configurator-row-gap-compact: 0.3125rem;     /*  5px — slightly tighter */
+    --configurator-row-gap-comfortable: 0.375rem;  /*  6px — pre-N.W2 default */
+    --configurator-row-gap-spacious: 0.75rem;      /* 12px — generous */
+
+    --configurator-row-py-mobile: 0.25rem;         /*  4px — tight */
+    --configurator-row-py-compact: 0.375rem;       /*  6px — slightly tighter */
+    --configurator-row-py-comfortable: 0.5rem;     /*  8px — pre-N.W2 default */
+    --configurator-row-py-spacious: 0.875rem;      /* 14px — generous */
+
+    /* Configurator HIERARCHY VOCABULARY (AZ.W-HIERARCHY — D6-3). The three
+       NAMED registers the studios (blob, aurora) inherit instead of a flat
+       undifferentiated stack. DISTINCT from the density ladder above (which is
+       the per-row CADENCE, not the section/label/preset register).
+
+       1. Section register — the <ConfiguratorLayer> label reads as a SECTION,
+          not a row: the √φ subheading rung at weight 600, lifting off the prior
+          flat `text-small font-semibold`. */
+    --configurator-section-size: var(--type-subheading);  /* 20.4px — √φ section rung */
+    --configurator-section-weight: 600;                   /* the heading weight */
+
+    /* AZ.W-BLOB-REDRESS — the SINGLE-COLUMN stage-row FLOOR. Below `lg` the
+       Configurator stacks stage-over-aside; a percentage stage height against
+       an INDEFINITE auto-row resolves to 0 (the GooBlob hero painted 0×0 on a
+       phone). The single-column band's `grid-template-rows` floors the stage
+       row at this DEFINITE `minmax(…)` minimum so the percentage resolves;
+       the aside row takes the remainder and scrolls internally. */
+    --configurator-stage-min: 18rem;                      /* 288px — the mobile live-specimen stage floor */
+
+    /* 2. Preset-row PRIMARY-AFFORDANCE lift. The preset picker is the primary
+          interaction (C6-10); D6-3's defect is the preset row being spatially
+          CRAMPED. This token's binding SEMANTIC is the preset row's SPATIAL
+          rhythm — its block-padding / gap, NOT a font-weight — so the preset
+          row breathes ABOVE a body ConfiguratorRow. (The `-weight` name follows
+          the vocabulary's "register weight" framing; it lands on the padding/gap
+          slot of `.configurator-presets`, the heavier spatial cadence.) */
+    --configurator-preset-row-weight: 0.625rem;           /* 10px — > a body row's 8px py-comfortable */
+    --configurator-preset-row-gap: 0.5rem;                /*  8px — generous chip gap */
+
+    /* 3. The DIVIDER register — dark-adaptive (BA.W-CONFIG-CHASSIS.1 / CFG-4).
+       The section + inter-row dividers used to be inline `border-border/40` and
+       `border-border/30` Tailwind alphas; over the W-DARK-MATERIAL dark
+       `glass-floating` plate (a luminous transmissive material, --card L16) those
+       near-equal-luminance hairlines effectively VANISHED — "the sections run
+       together". This ONE token is consumed by every divider rule (the
+       <ConfiguratorLayer> section border, the dividers-prop inter-row border,
+       Configurator.vue's aside/preset/footer borders, configurator.css) so the
+       divider weight is retuned from a single override.
+
+       The dark-LIFTING arm is the load-bearing half: the divider must read on
+       BOTH plates. On LIGHT it is the resting `--border` warm-neutral at the
+       prior ~40% weight; on DARK it LIFTS off `--border` (L34 over the L16 plate
+       — too close) toward the `--foreground` warm-ink (L90) at a higher α, so a
+       visible luminance step survives the dark glass. `light-dark()` carries the
+       arm in ONE declaration (the same :root cascade context as the surface-tint
+       family; an engine without `light-dark()` falls back to the dark-arm.css
+       `.dark` floor minted in lockstep). The SECTION divider runs a touch
+       heavier than the inter-row hairline (a section reads as a section without
+       a second heading rung). */
+    --configurator-divider: light-dark(
+        color-mix(in srgb, var(--border) 55%, transparent),
+        color-mix(in srgb, var(--foreground) 22%, transparent)
+    );
+    --configurator-divider-section: light-dark(
+        color-mix(in srgb, var(--border) 70%, transparent),
+        color-mix(in srgb, var(--foreground) 30%, transparent)
+    );
+    /* The optional faint section-header tonal step — a whisper-light warm wash
+       behind a <ConfiguratorLayer> section so it reads as a grouped section
+       WITHOUT a new heading rung (within the W-HIERARCHY register). Default off
+       (transparent) on light where the hairline carries it; a faint
+       foreground-over-transparent lift on dark where the divider alone is
+       subtle. */
+    --configurator-section-tint: light-dark(
+        transparent,
+        color-mix(in srgb, var(--foreground) 3%, transparent)
+    );
+
+    /* Component font override (consumers override locally) */
+    --select-font: inherit;
+
+}