@mkbabb/glass-ui 3.7.0 → 3.9.0

package/src/styles/tokens.css

@@ -33,21 +33,24 @@
     accent-color: var(--accent-color);
 
     /* ═══════════════════════════════════════════════
-       §0  THEME BRIDGE FALLBACKS
-
-       theme.css uses these non-Tailwind names to register v4 utility
-       namespaces without self-referential @theme variables. The public
-       runtime tokens remain --font-*, --leading-*, and --tracking-* in
-       typography.css.
-       ═══════════════════════════════════════════════ */
-    --font-stack-display: "Fraunces", Georgia, serif;
-    --font-stack-serif: "Fraunces", Georgia, "Times New Roman", serif;
-    --font-stack-sans: "Helvetica Neue", "Arial Nova", Arial, system-ui, sans-serif;
-    /* AC.W6b (v1.5.0) — self-hosted Fira Code engages by default for
-       every glass-ui consumer. The calibrated "Fira Code Fallback"
-       face (declared in typography.css) wraps the system mono stack
-       with metric overrides so the `font-display: swap` window is
-       geometry-neutral. */
+       §0  FONT TOKEN SOURCE-OF-TRUTH
+
+       The single authoritative declaration of the library's font register.
+       theme.css bridges each --font-stack-* to its Tailwind --font-* namespace
+       var; typography.css consumes the bridged --font-* names. The public
+       runtime knobs remain --font-*, --leading-*, --tracking-*.
+
+       ONE brand register: Plus Jakarta Sans (text + display) + Fira Code (mono).
+       --font-stack-text drives the body/heading/prose/display register — the
+       library DEFAULT is the register every live surface paints (the demo +
+       speedtest render Plus Jakarta everywhere). The calibrated "Plus Jakarta
+       Sans Fallback" / "Fira Code Fallback" faces (declared in typography.css)
+       wrap the system stacks with Capsize metric overrides so the swap window
+       is geometry-neutral (zero CLS). --font-stack-display aliases the text
+       register: there is no separate display-serif voice. */
+    --font-stack-text: "Plus Jakarta Sans", "Plus Jakarta Sans Fallback", system-ui, sans-serif;
+    --font-stack-display: var(--font-stack-text);
+    --font-stack-sans: var(--font-stack-text);
     --font-stack-mono: "Fira Code", "Fira Code Fallback", "Fira Mono", monospace;
 
     --type-leading-micro: 1.2;
@@ -155,6 +158,35 @@
        `smooth` wants a slightly faster visual settle than `gentle`'s
        patient curve. The 0.5% peak does not read as overshoot to the
        eye but does narrowly distinguish `smooth` from `gentle`.
+
+       ── EASING DOCTRINE (AX.W52 §6 — which easing fits which job) ──
+       ONE recorded rule so the animation easing stops forking live. This
+       FORMALIZES the already-correct `transitions.css` idiom (enter=spring,
+       exit=bezier) as the house rule every recipe reaches for:
+
+         | Transition kind                                  | Easing                              |
+         |--------------------------------------------------|-------------------------------------|
+         | Surface props (bg, border, color, box-shadow,    | `--ease-standard` (bezier — a       |
+         |   opacity)                                       |   colour cross-fade reads as a      |
+         |                                                  |   wobble on a spring)               |
+         | Transform — hover/press/active (scale, translate,| `--spring-smooth` (the ONE button/  |
+         |   rotate)                                         |   interactive scale register) or    |
+         |                                                  |   `--spring-snappy` (crisp press)   |
+         | Enter (mount, popover open, dialog in)           | `--spring-bouncy` / `--spring-snappy`|
+         | Exit (unmount, close)                            | `--ease-out` / `--ease-standard`    |
+         |                                                  |   (bezier, NO overshoot — an exit   |
+         |                                                  |   must never overshoot past gone)   |
+         | Position-tracked (specular pointer follow)       | `--ease-standard`                   |
+
+       The BUTTON family (`.btn-pill` / `.tap-squish` / `.glass-btn` /
+       `btn-interactive`) UNIFIES its `scale` transform leg onto ONE register —
+       `--spring-smooth` — so hover + press read as one motion language (the
+       hover lift is the restrained `--scale-hover-btn` = 1.035, not the 1.08
+       `--scale-hover`). Springs read alive on TRANSFORM and ENTER (overshoot =
+       physicality); a spring on a COLOR or an EXIT reads as a wobble/hesitation.
+       `--ease-apple` is the ambient-only register (consumed solely by the Pulse
+       aura `--animate-ambient-pulse-easing` — NOT a second smooth-ease authority
+       for interactive transforms; those use `--spring-smooth`).
        ═══════════════════════════════════════════════ */
     --spring-smooth: linear(0, 0.09804 2.041%, 0.29288 4.082%, 0.49447 6.122%, 0.66436 8.163%, 0.79208 10.204%, 0.88050 12.245%, 0.93754 14.286%, 0.97182 16.327%, 0.99083 18.367%, 1.00027 20.408%, 1.00413 22.449%, 1.00502 24.490%, 1.00453 26.531%, 1.00355 28.571%, 1.00254 30.612%, 1.00169 32.653%, 1.00105 34.694%, 1.00060 36.735%, 1.00031 38.776%, 1.00014 40.816%, 1.00005 42.857%, 1.00000 44.898%, 1.00000 46.939%, 1.00000 48.980%, 1.00000 51.020%, 1.00000 53.061%, 1.00000 55.102%, 1.00000 57.143%, 1.00000 59.184%, 1.00000 61.224%, 1.00000 63.265%, 1.00000 65.306%, 1.00000 67.347%, 1.00000 69.388%, 1.00000 71.429%, 1.00000 73.469%, 1.00000 75.510%, 1.00000 77.551%, 1.00000 79.592%, 1.00000 81.633%, 1.00000 83.673%, 1.00000 85.714%, 1.00000 87.755%, 1.00000 89.796%, 1.00000 91.837%, 1.00000 93.878%, 1.00000 95.918%, 1.00000 97.959%, 1);
     --spring-snappy: linear(0, 0.10438 2.041%, 0.32622 4.082%, 0.56668 6.122%, 0.77153 8.163%, 0.91961 10.204%, 1.01073 12.245%, 1.05549 14.286%, 1.06804 16.327%, 1.06171 18.367%, 1.04686 20.408%, 1.03044 22.449%, 1.01629 24.490%, 1.00596 26.531%, 0.99954 28.571%, 0.99633 30.612%, 0.99537 32.653%, 0.99575 34.694%, 0.99674 36.735%, 0.99786 38.776%, 0.99884 40.816%, 0.99956 42.857%, 1.00001 44.898%, 1.00024 46.939%, 1.00000 48.980%, 1.00000 51.020%, 1.00000 53.061%, 1.00000 55.102%, 1.00000 57.143%, 1.00000 59.184%, 1.00000 61.224%, 1.00000 63.265%, 1.00000 65.306%, 1.00000 67.347%, 1.00000 69.388%, 1.00000 71.429%, 1.00000 73.469%, 1.00000 75.510%, 1.00000 77.551%, 1.00000 79.592%, 1.00000 81.633%, 1.00000 83.673%, 1.00000 85.714%, 1.00000 87.755%, 1.00000 89.796%, 1.00000 91.837%, 1.00000 93.878%, 1.00000 95.918%, 1.00000 97.959%, 1);
@@ -175,10 +207,8 @@
 
     /* Apple-inspired — micro-interactions, switches, dock hover */
     --motion-ease-apple: cubic-bezier(0.25, 0.1, 0.25, 1);
-    --motion-ease-apple-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
 
     --ease-apple: var(--motion-ease-apple);
-    --ease-apple-spring: var(--motion-ease-apple-spring);
     --ease-spring: var(--spring-snappy);
     --ease-decelerate: var(--ease-out);
     --ease-accelerate: var(--ease-in);
@@ -189,17 +219,40 @@
        Breathing rhythm for `<Pulse variant="aura">`. The 6s duration is the
        canon ambient-pulse rate; scale 1.0 ↔ 1.15 reads as a quiet halo at
        intensity="normal" (Pulse remaps min/max from its `intensity` prop).
-       The aura always keeps a visible halo at the trough (opacity min 0.55).
        Reduced motion: Pulse.vue parks at the min stop, breath cycle disabled.
-       ═══════════════════════════════════════════════ */
+
+       AX.W57 (P6) — the aura re-baselined from a glowing DISC to an AMBIENT
+       halo. The egregiousness was doubly-stacked: a 0.55-density currentColor
+       radial multiplied by an element opacity the `ambient-pulse` keyframe
+       drove up to 0.95 mid-breath (so a saturated viz hue read as a near-
+       opaque throbbing blob). The fix is two decoupled, single-source knobs:
+         · `--pulse-aura-strength` (0..1) — the ONE gradient-density scalar
+           both color-mix stops derive via calc() (replaces the
+           `--pulse-aura-opacity-pct` / `-pct-num` twin desync trap — the
+           percent and the raw number had to be hand-kept in sync).
+         · `--pulse-aura-breath-{min,max}` — the aura's OWN element-opacity
+           range, decoupled from the shared `--pulse-aura-opacity-*` shimmer
+           tokens (those stay 0.55/0.95 for the neutral skeleton-breath, where
+           a grey shimmer at that range is the correct soft swell).
+       The loud old read is the explicit `intensity="vivid"` opt-in. */
     --animate-ambient-pulse-duration: 6s;
     --animate-ambient-pulse-scale-min: 1.0;
     --animate-ambient-pulse-scale-max: 1.15;
     --animate-ambient-pulse-easing: var(--ease-apple);
 
-    /* Aura opacity range — keep the trough visible (the colour reads
-       at every phase of the cycle). Consumers may override per site
-       (e.g. the completion one-shot uses min=0 to fade out). */
+    /* Aura gradient density — ONE scalar (0..1). The center stop paints at
+       `strength`, the mid stop at `strength * 0.35` (both via calc() in
+       Pulse.vue). 0.22 reads as an ambient wash, not a glowing disc. */
+    --pulse-aura-strength: 0.22;
+
+    /* Aura element-opacity breath range (the `ambient-pulse` keyframe stops).
+       Quiet: the halo stays a wash at every phase of the 6s cycle. */
+    --pulse-aura-breath-min: 0.28;
+    --pulse-aura-breath-max: 0.42;
+
+    /* Skeleton-breath shimmer range — the SHARED neutral-shimmer stops
+       (`.skeleton-breath` reads these; a grey shimmer at 0.55↔0.95 is the
+       correct soft swell, distinct from the aura's calmer breath above). */
     --pulse-aura-opacity-min: 0.55;
     --pulse-aura-opacity-max: 0.95;
 
@@ -411,13 +464,53 @@
 
     /* Muted-tinted surface rungs — canonical handles for the 9 raw
        `color-mix(in srgb, var(--muted) N%, transparent)` sites in
-       FuzzySearch / BouncyToggle / Slider scoped CSS. (AI.W5-δ — the
+       FuzzySearch / SegmentedTabs / Slider scoped CSS. (AI.W5-δ — the
        ProgressiveSidebar consumer retired at the wave; the canonical token
        rung lives on for the remaining consumers.) Auto-dark via --muted.
        R5 vocab.γ axis-1 row. */
     --muted-soft:   color-mix(in srgb, var(--muted) 30%, transparent);
     --muted-medium: color-mix(in srgb, var(--muted) 50%, transparent);
 
+    /* ═══════════════════════════════════════════════
+       §5c CONSTELLATION — Canvas2D proximity-graph lattice (AX.W17)
+
+       The H.W4 legibility intelligence promoted from the slides deck to
+       LIBRARY identity: the node tones, the edge hairline color, the per-mode
+       edge-alpha multipliers, and the field-yields-to-type translucency knob.
+       Only `--constellation-accent` (the anomaly tint) stays a CONSUMER preset
+       (slides aliases it to `--ncsu-red`); the library ships a neutral default.
+
+       PLAIN-hsl LITERALS, per arm — NEVER `light-dark()` and NEVER a
+       `var(--neutral-*)`/`var(--foreground)`/`var(--border)`/`var(--card)`
+       alias. Canvas2D silently REJECTS a `light-dark()` value into
+       `strokeStyle`/`fillStyle` (the W30 86.3%-red-splatter cardinal defect),
+       and the rejection is identical whether the value is a literal
+       `light-dark(…)` OR a `var()` that RESOLVES to one — so the constellation
+       tokens are plain-hsl LEAVES, the `:root` vs `.dark` cascade carrying two
+       literals. `proof:constellation-tokens` clause (c) machine-locks this
+       (the no-`light-dark(`-substring NOR transitive-`var()` static assertion).
+       ═══════════════════════════════════════════════ */
+    /* Node tones — readable on the warm-cream ground. The two-tone split (the
+       `dim` half rides `-node-dim`). Warm-grey ink, NOT a neutral-ladder alias. */
+    --constellation-node:      hsl(36 8% 46%);
+    --constellation-node-dim:  hsl(36 8% 60%);
+    /* Edge hairline stroke — warm near-black on cream (the plain-hsl complement
+       the slides deck reads to fix the `--foreground` light-dark() leak). */
+    --constellation-line:      hsl(24 14% 14%);
+    /* Anomaly tint — NEUTRAL library default (a desaturated warm accent). The
+       consumer overrides this (slides → `--ncsu-red`); the library does NOT
+       bake a brand hue. This is the single consumer-preset boundary. */
+    --constellation-accent:    hsl(18 58% 46%);
+    /* Edge-alpha multipliers — replace the magic `0.17` hairline / pointer-web
+       literals. The cream ground lifts the node tones, so the field can recede;
+       the focus-proximity edge reads a touch stronger. */
+    --constellation-edge-alpha:          0.22;
+    --constellation-edge-focus-alpha:  0.34;
+    /* §7 field-yields-to-type translucency knob — the legible-but-RECESSIVE
+       MIDPOINT, NOT max-legibility. On cream the node tones already read, so the
+       field recedes further: BELOW the slides 0.92 max-legibility reference. */
+    --constellation-alpha:               0.80;
+
     /* ═══════════════════════════════════════════════
        §6  SECTION PALETTE — 13-stop jewel tones (light)
        ═══════════════════════════════════════════════ */
@@ -535,6 +628,22 @@
     --dock-shadow:           var(--shadow-dock);
     --dock-shadow-collapsed: var(--shadow-dock-collapsed);
 
+    /* AX.W04 F1 — the wrap/card-tier dock shadow. A wrapped multi-row dock (and
+       any finite-radius card silhouette) is a THICKER material than a flat thin
+       pill — WWDC25 §219 "material thickens as glass flexes larger". So when the
+       wrap dock expands it lifts its elevation onto the FLOATING-tier shadow
+       stack (the `--glass-shadow-floating` family — `--shadow-xl` + the
+       `--glass-material-rim` hairline + the `--glass-under-shadow-vivid` under-cast)
+       rather than carrying the flat `--shadow-dock` glow of a 40px pill. Composed
+       on `:root` as ONE consumer-overridable token (per the cartoon-shadow
+       override contract — override on the cascade, never a dead local). The dock
+       reads it via `calc()`-on-`--dock-expand-t` so the lift glides in lockstep
+       with the pill→card radius morph (ONE clock, ONE register). */
+    --glass-material-rim:    0 0 0 0.5px color-mix(in srgb, var(--shadow-color) 5%, transparent);
+    --shadow-dock-wrap:      var(--shadow-xl),
+        var(--glass-material-rim),
+        var(--glass-under-shadow-vivid);
+
     /* Cartoon shadow color primitives (kept for tiered cartoon utilities) */
     --shadow-cartoon-color:             rgb(0 0 0 / 0.12);
     --shadow-cartoon-color-soft:        rgb(0 0 0 / 0.06);
@@ -599,7 +708,12 @@
        opacity-only register. */
     --glass-blur-dock-radius:     11px;
 
-    --glass-blur-wash:     blur(var(--glass-blur-wash-radius)) saturate(1.05);
+    /* AX.W54 — each blur radius is scaled by the ONE `--glass-level` scalar (in
+       lockstep with the opacity seam above): level=1 byte-identical; level=0 →
+       blur(0) (the clean solid floor with the opacity); level>1 → more diffusion.
+       The per-rung `saturate()`/`brightness()` companions are UNTOUCHED (the level
+       scales the RADIUS, not the saturation — W52's calm light-concentration). */
+    --glass-blur-wash:     blur(calc(var(--glass-blur-wash-radius) * var(--glass-level))) saturate(1.05);
     /* AV.W15 M1 — the `quiet` rung gained `saturate(1.05) brightness(1.02)`
        so the lower ladder reads with the same saturation life as `resting`+
        (Apple: Liquid Glass concentrates light, it does not desaturate). The
@@ -607,12 +721,27 @@
        between bare `wash` and `resting` without over-brightening the rung.
        The `prefers-reduced-transparency: reduce` bracket at glass.css maps
        `--glass-blur-quiet: none`, so this whole chain drops with the blur. */
-    --glass-blur-quiet:    blur(var(--glass-blur-quiet-radius)) saturate(1.05) brightness(1.02);
-    --glass-blur-resting:  blur(var(--glass-blur-resting-radius)) saturate(1.05);
-    --glass-blur-floating: blur(var(--glass-blur-floating-radius)) saturate(1.4);
-    --glass-blur-overlay:  blur(var(--glass-blur-overlay-radius)) saturate(1.5);
+    --glass-blur-quiet:    blur(calc(var(--glass-blur-quiet-radius) * var(--glass-level))) saturate(1.05) brightness(1.02);
+    --glass-blur-resting:  blur(calc(var(--glass-blur-resting-radius) * var(--glass-level))) saturate(1.05);
+    /* AX.W52 D19 — the floating/overlay backdrop saturate tamed from 1.4/1.5 to a
+       gentle ~1.18/1.2 (real liquid glass concentrates light ~1.1–1.2×; the prior
+       1.4–1.5× over-juiced the bleed-through into a garish smear over a colored
+       substrate). wash/quiet/resting already sit at 1.05 — untouched. */
+    --glass-blur-floating: blur(calc(var(--glass-blur-floating-radius) * var(--glass-level))) saturate(1.18);
+    --glass-blur-overlay:  blur(calc(var(--glass-blur-overlay-radius) * var(--glass-level))) saturate(1.2);
     /* Dock blur composes blur() only — no saturate. */
-    --glass-blur-dock:     blur(var(--glass-blur-dock-radius));
+    --glass-blur-dock:     blur(calc(var(--glass-blur-dock-radius) * var(--glass-level)));
+
+    /* AX.W52 — the GLASS BUTTON blur. The `glass`/`glass-wash` button variants
+       compose the `.glass-wash` tier (`--glass-blur-wash` = blur(1px)) — a
+       sub-perceptual diffusion authored for a small detail TILE, not a button
+       the user reads as "glass." A button is a hero control: it wants a real
+       glass blur. `--glass-blur-btn` lifts the variant onto the `quiet`-tier
+       radius (10px — a genuine liquid-glass diffusion) with the same gentle
+       `saturate(1.05) brightness(1.02)` light-concentration the quiet rung
+       carries (NOT a colour-juice). The wash TILE tier (MetricCell et al.) keeps
+       its 1px — only the glass BUTTON variants reach for this. */
+    --glass-blur-btn:      blur(calc(var(--glass-blur-quiet-radius) * var(--glass-level))) saturate(1.05) brightness(1.02);
 
     /* Dock-specific opacity (0.42) — lighter than `resting` (0.65) so the dock
        reads as a translucent overlay rather than a panel, backdrop bleed
@@ -629,7 +758,14 @@
        muted icon weight the control mixes it down with `--opacity-icon-muted`.
        Defaults to `var(--foreground)` so the dock paints byte-identically to
        today; a consumer overrides it per-backdrop (e.g. a near-white over a
-       dark aurora) without touching library source. */
+       dark aurora) without touching library source.
+
+       AX.W55 — this is the FOREGROUND half of the adaptive story, now reconciled
+       INTO the `--glass-backdrop` probe (not a third fork): under the bright bucket
+       (`@container style(--glass-backdrop: light)` in dock.css) it re-points toward
+       the contrast-clearing ink, and an `@supports (color: contrast-color(…))`
+       block flips it natively on supporting engines. The `var(--foreground)`
+       default keeps the zero-delta rest state. */
     --dock-fg-on-aurora: var(--foreground);
 
     /* Chassis-specific opacity. Looser than `default` (0.50) so the
@@ -641,14 +777,24 @@
        `glass-bg-medium` (0.65) down to its own 0.32. */
     --glass-opacity-chassis: 0.28;
 
-    /* Composed backgrounds */
-    --glass-bg-wash:     color-mix(in srgb, var(--card) calc(var(--glass-opacity-wash) * 100%), transparent);
-    --glass-bg-quiet:    color-mix(in srgb, var(--card) calc(var(--glass-opacity-quiet) * 100%), transparent);
-    --glass-bg-resting:  color-mix(in srgb, var(--card) calc(var(--glass-opacity-resting) * 100%), transparent);
-    --glass-bg-floating: color-mix(in srgb, var(--card) calc(var(--glass-opacity-floating) * 100%), transparent);
-    --glass-bg-overlay:  color-mix(in srgb, var(--card) calc(var(--glass-opacity-overlay) * 100%), transparent);
-    --glass-bg-dock:     color-mix(in srgb, var(--card) calc(var(--glass-opacity-dock) * 100%), transparent);
-    --glass-bg-chassis:  color-mix(in srgb, var(--card) calc(var(--glass-opacity-chassis) * 100%), transparent);
+    /* Composed backgrounds — AX.W54: the opacity is threaded through the ONE
+       `--glass-level` clarity scalar. Each rung's effective alpha is
+       `1 - (1 - <rung-opacity>) * --glass-level`: at level=1 it collapses to the
+       hand-tuned `<rung-opacity>` (byte-identical); at level=0 it resolves `1`
+       (solid `--card` — the opaque escape); at level>1 it goes clearer. ONE
+       expression, the same seven rungs. */
+    --glass-bg-wash:     color-mix(in srgb, var(--card) calc((1 - (1 - var(--glass-opacity-wash)) * var(--glass-level)) * 100%), transparent);
+    --glass-bg-quiet:    color-mix(in srgb, var(--card) calc((1 - (1 - var(--glass-opacity-quiet)) * var(--glass-level)) * 100%), transparent);
+    --glass-bg-resting:  color-mix(in srgb, var(--card) calc((1 - (1 - var(--glass-opacity-resting)) * var(--glass-level)) * 100%), transparent);
+    --glass-bg-floating: color-mix(in srgb, var(--card) calc((1 - (1 - var(--glass-opacity-floating)) * var(--glass-level)) * 100%), transparent);
+    --glass-bg-overlay:  color-mix(in srgb, var(--card) calc((1 - (1 - var(--glass-opacity-overlay)) * var(--glass-level)) * 100%), transparent);
+    /* The dock bg ALSO rides the oklab tint seam (AX.W54 amendment): the same
+       `color-mix(in oklab, …, --glass-tint-source --glass-tint-strength)` wrapper
+       the rungs reach for, ZERO-delta at `--glass-tint-strength: 0%` — so W55's
+       adaptive darken can reach the dock (the G2 over-light surface) without a
+       second hand-rolled recipe. */
+    --glass-bg-dock:     color-mix(in oklab, color-mix(in srgb, var(--card) calc((1 - (1 - var(--glass-opacity-dock)) * var(--glass-level)) * 100%), transparent), var(--glass-tint-source) var(--glass-tint-strength));
+    --glass-bg-chassis:  color-mix(in srgb, var(--card) calc((1 - (1 - var(--glass-opacity-chassis)) * var(--glass-level)) * 100%), transparent);
 
     /* Composed borders — foreground-tinted */
     --glass-border-wash:     color-mix(in srgb, var(--foreground) 8%, transparent);
@@ -710,10 +856,58 @@
        and `--glass-tint-strength` is 0%, so the rung background mixes 0% toward
        the source = byte-identical to today. A consumer sets `--glass-tint-source`
        to a sampled aurora hue + a strength ≤30% to bias the surface. Alpha-safe:
-       the mix is bounded ≤30% and never re-points the card's own alpha. */
+       the mix is bounded ≤30% and never re-points the card's own alpha.
+
+       AX.W55 — the DEFAULTS stay `var(--card)`/`0%` (the zero-delta rest state).
+       The backdrop-luminance probe (`--glass-backdrop`, below) is what OVERRIDES
+       them under a bright backdrop; the `:root` defaults are NEVER touched — the
+       bucket blocks (glass.css / dock.css `@container style(--glass-backdrop:
+       light)`) do the lift, so a surface over today's rich/dark background reads
+       byte-identical. */
     --glass-tint-source:   var(--card);
     --glass-tint-strength: 0%;
 
+    /* AX.W55 — adaptive glass legibility (the iOS-26/27 "locally darken the glass
+       over light content" move; G2). There is NO web API that reads the pixels
+       painted BEHIND a `backdrop-filter` element, so the backdrop-luminance signal
+       is a DECLARATIVE BUCKET a consumer sets where it KNOWS the backdrop is bright
+       (a near-white card surface, a pale aurora bleed, a bright data grid). It is
+       read by the `@container style(--glass-backdrop: light)` blocks on every glass
+       family (the shipped density-cascade mechanism — utilities.css §density) which
+       lift `--glass-tint-strength` toward the AA floor + re-point `--glass-tint-
+       source` to the warm-ink below, mixing the rung TOWARD ink via the EXISTING
+       `color-mix(in oklab)` seam — ZERO new compositing seam.
+
+         --glass-backdrop:      the bucket. `dark` (or unset) = today's zero-delta;
+                                `light` engages the bright-bucket darken. An
+                                INHERITING ident set on any ancestor reaches every
+                                descendant glass surface (the @container read).
+         --glass-backdrop-luma: the numeric escape hatch — a sampled backdrop
+                                relative-luminance (0..1) a heavier JS observer sets
+                                when the declarative bucket is too coarse. The TOKEN
+                                is minted (the cascade reads it if set); the OBSERVER
+                                that sets it stays demo-private until a 2nd consumer
+                                arrives (the no-overfitting bar — the DEFAULT path is
+                                the declarative bucket, not a speculative sampler).
+         --glass-tint-ink:      the LOW-LUMINANCE warm-ink the bright bucket re-points
+                                `--glass-tint-source` to — the warm dark `--foreground`
+                                family (NOT white; a lightener over light content is
+                                exactly the W52-fixed wrong direction). It auto-flips
+                                with `--foreground` (dark-mode it resolves the light
+                                warm ink — but the bright-backdrop case is a light-mode
+                                concern). Overridable like every magnitude here.
+
+       The bright-bucket `--glass-tint-strength` is clamped to a BOUNDED AA-clearing
+       floor — `--glass-tint-strength-aa` (≤24%, the iOS clamp; the lowest value that
+       clears 4.5:1 over synthetic white, capped LOW so the surface STAYS translucent,
+       "let as much content through as possible"). Recorded here as the ceiling the
+       bucket blocks drive to; the live 4.5:1 readback (proof:adaptive-glass π arm)
+       ratifies the exact value. */
+    --glass-backdrop:           dark;
+    --glass-backdrop-luma:      ;
+    --glass-tint-ink:           var(--foreground);
+    --glass-tint-strength-aa:   18%;
+
     /* AW.W23 — chromatic edge dispersion (the "polished glass" rim fringe Apple
        shows). A warm fringe on one edge + a cool fringe on the other, low-alpha,
        biased warm-cream/NCSU-red (NOT iOS-blue). Composed OVER the W22 uniform
@@ -726,19 +920,36 @@
         inset 0.75px 0 0 0 var(--glass-fringe-warm),
         inset -0.75px 0 0 0 var(--glass-fringe-cool);
 
+    /* AX.W52 D19 — the moving-specular gleam radius (glass.css `.glass-material::
+       before`). The ONE knob that BOUNDS the gleam geometry as a percentage of the
+       plate so it can NEVER again become a whole-surface disc (the prior implicit
+       `circle at …` ran its stops to 55–75% of the half-diagonal — a wash on a
+       small tile). 36% reads as a tracked edge glint. Override on `:root` to retune
+       library-wide; a per-surface override clips the gleam tighter/wider. */
+    --glass-specular-size: 36%;
+
     /* Chassis curvature illusion — a subtle radial gradient at the chassis
        top centre that lifts the surface without committing to literal 3D.
-       Composed into <InstrumentChassis>'s background stack. */
+       Composed into <InstrumentChassis>'s background stack. AX.W52 D19 — the
+       prior pure-white `hsl(0 0% 100% / 0.06)` reaching `transparent 60%` was a
+       broad top-centre WASH (the #1 fixed-anchor rest-bloom culprit). Re-derived
+       onto the warm-cream house identity (`hsl(40 30% 96%)`, L < 100% so the warm
+       hue survives — mirroring the moving gleam), the alpha routed through the
+       SINGLE overridable `--glass-curvature-intensity` knob (0.02 default, a third
+       of the old 0.06), and the ellipse tightened to `transparent 38%` so it reads
+       as a thin top-edge sheen, not a central wash. */
+    --glass-curvature-intensity: 0.02;
     --glass-curvature-overlay: radial-gradient(
         ellipse at 50% -20%,
-        hsl(0 0% 100% / 0.06),
-        transparent 60%
-    );
-    --glass-curvature-overlay-dark: radial-gradient(
-        ellipse at 50% -20%,
-        hsl(0 0% 100% / 0.06),
-        transparent 60%
+        hsl(40 30% 96% / var(--glass-curvature-intensity)),
+        transparent 38%
     );
+    /* The light-arm dark alias kept on the same warm-cream + token recipe so a
+       non-`.dark` consumer reading `…-overlay-dark` still resolves a softened
+       sheen; the `.dark` block below lowers `--glass-curvature-intensity` so the
+       deep-canvas arm is genuinely softer (the prior byte-identical dark arm read
+       HARDER over the dark canvas). */
+    --glass-curvature-overlay-dark: var(--glass-curvature-overlay);
 
     /* Chart palette aliases — speedtest et al. read these for phase tinting.
        Defaults map to viz-basis hues; consumers can override per app. */
@@ -866,18 +1077,16 @@
        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);
 
-    /* AT.W7-dock-a — the `overflow="wrap"` desktop snap-back breakpoint, named
-       once. Below this viewport width a wrap-mode dock reads as a multi-row pill
-       that narrows to the viewport gutter; at/above it the pill snaps back to a
-       single nowrap row. The single source-of-record for the threshold the
-       `@media` in dock.css realizes (a `var()` cannot drive a media-query
-       feature in Baseline CSS, so the MQ carries the literal value of THIS
-       token; consumers reading the breakpoint do so through this name). */
-    --dock-overflow-bp: 640px;
-
     /* 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
@@ -926,6 +1135,105 @@
     /* ═══════════════════════════════════════════════
        §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. */
+    --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;
@@ -959,6 +1267,96 @@
     --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: 1;
+    /* 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. */
+    --dock-collapsed-summary-min-size: calc(var(--dock-layer-height, 2.5rem) * 0.7);
+    /* 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%;
+
+    /* AX.W45 DK8 — the layer-switcher rail surface ladder. The rail
+       (`.dock-layer-rail` inside a `<DockLayerGroup>`) gets its own quiet plate +
+       a tunable hover/active affordance, replacing the raw `--primary 15%` /
+       `--accent 40%` mixes the indicator/tab used against an absent plate. */
+    --dock-layer-rail-bg: var(--surface-tint-8);
+    --dock-layer-rail-hover: color-mix(in srgb, var(--accent) 40%, transparent);
+    --dock-layer-rail-active: color-mix(in srgb, var(--primary) 15%, transparent);
+
     /* 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)`
@@ -969,8 +1367,14 @@
        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). */
-    --dock-active-bg: var(--muted);
+       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;
@@ -991,7 +1395,7 @@
 
     /* AQ.W3 §7 — canonical WCAG 2.5.5 (44px) touch-target floor for the
        NON-dock coarse-pointer surfaces (`Button size="icon"`,
-       ExpandableContainer triggers, ResponsiveTabs mobile trigger). One
+       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
@@ -1033,6 +1437,21 @@
        §11 INTERACTIVE SCALES & FOCUS
        ═══════════════════════════════════════════════ */
     --scale-hover: 1.08;
+    /* AX.W52 — the restrained BUTTON hover lift. `--scale-hover` (1.08) is an
+       8% jump — emphatic for a marquee CTA, jarring as the general hover. The
+       button family (the audacious CTAs + `btn-interactive`) lifts on the
+       smaller `--scale-hover-btn` routed through `--spring-smooth` (the
+       sub-perceptual settle, not the snappy bounce), so the hover reads as ONE
+       coherent glide with the surface-leg cross-fade rather than a mechanical
+       pop. The dock keeps its proportionally-larger `--scale-hover-dock` (small
+       icon, bigger lift reads smaller).
+       AX.W54 Q3 — lifted 1.035 → 1.05: the 1.035 overshot DOWN (W52 tamed the
+       1.08 snap so hard the lift read as nothing), so the glass hover now reads
+       as THREE legs together on hover — the specular gleam waking, a perceptible
+       scale, and the bg/border cross-fade — distinguishable from rest BEFORE the
+       click. Still sub-perceptual-bounce on `--spring-smooth`; the magnitude
+       moved, the easing register did not. */
+    --scale-hover-btn: 1.05;
     --scale-hover-dock: 1.1;
     --scale-press: 0.96;
 
@@ -1050,6 +1469,18 @@
     --scale-press-dock: var(--scale-press);
     --scale-press-sm: 0.97;
     --scale-press-btn: var(--scale-press-sm);
+
+    /* AX.W53 — the SegmentedTabs travel-squish cap. The active indicator
+       (segmented/pill slider OR the underline rule) STRETCHES along its travel
+       axis as it glides between tabs, then settles to fit — the Material 3
+       ELASTIC / Apple Liquid-Glass "controls insist on animating themselves"
+       register, kept RESTRAINED. The deform is volume-preserving (stretch X,
+       compress Y in lockstep: `scale: var(--stretch) calc(1 / var(--stretch))`)
+       so it reads as an elastic warp, never a size pump. The cap holds the peak
+       LOW (1.08 ≈ +8%) — iOS 26.2 dialed motion DOWN; a high-frequency control
+       wants a whisper of squish, not a bounce. A consumer dials the elasticity
+       (or to 1 for none) without touching source. */
+    --tab-indicator-max-stretch: 1.08;
     --opacity-disabled: 0.5;
     --opacity-icon-muted: 0.8;
 
@@ -1300,12 +1731,14 @@
     --top-layer-backdrop-dim: 0.5;
 
     --vt-duration: var(--duration-normal);
-    /* AV.W3 C2 — the spring-coverage sweep: every spring-flavored transition
-       reads a `--spring-*` token. `--ease-apple-spring`'s +27.5% overshoot maps
-       to `--spring-bouncy` (the closest `linear()` overshoot stop-set), so the
-       VT default and the cards/top-layer transitions share one spring primitive
-       (CPU + GPU sample the same curve). The apple-spring cubic-bezier survives
-       as a token DEFINITION only (a `@supports not (linear())` fallback seed). */
+    /* AX.W05 — ONE iOS-spring vocabulary: every spring-flavored transition reads
+       a governed `--spring-*` register. The legacy apple-spring cubic-bezier
+       (+27.5% overshoot) was a SECOND authority beside the regen `--spring-*`
+       cohort; it is EXCISED. Its emphatic-overshoot register maps to the playful
+       `--spring-bouncy` (the closest `linear()` overshoot stop-set), so the VT
+       default + the cards/top-layer transitions share one spring primitive
+       (CPU + GPU sample the same curve). No cubic-bezier fallback seed survives —
+       the `linear()` spring degrades to `ease` where `linear()` is unsupported. */
     --vt-ease: var(--spring-bouncy);
     --vt-rise: 8px;
 
@@ -1338,6 +1771,24 @@
     --dock-press-spring: var(--duration-fast) var(--spring-bouncy);
 }
 
+/* AX.W51 D18 — the GLOBAL coarse-pointer comfort amplification. The WHOLE library
+   — buttons, inputs, badges, toggles, the dock (a specialization that reads
+   `--ui-scale`) — grows ~1.5× on touch from this ONE place, the W45 dock-only 1.5×
+   lifted to the master scalar so the touch scale is CONSISTENT across the library
+   (at HEAD the dock grew but the buttons did not — the three-scale split). The
+   WCAG-2.5.5 44px touch floor is enforced HERE too: `--control-floor` lifts to
+   `--touch-target`, so every scaled control-height `max(scaled, floor)` clamps at
+   ≥ 44px regardless of the scalar (a consumer dialing `--ui-scale` below 1 still
+   cannot drop a control under the target). Fine-pointer is byte-identical
+   (`--ui-scale` stays 1). `--ui-coarse-scale` is the public default a consumer
+   retunes. */
+@media (pointer: coarse) {
+    :root {
+        --ui-scale: var(--ui-coarse-scale, 1.5);
+        --control-floor: var(--touch-target, 2.75rem);
+    }
+}
+
 /* AV.W7 F2 — high-resolution overlay-blur restore. On a 2dppx+ display the
    richer 24px overlay wash is amortised by the extra device pixels (the blur
    samples a denser backing store), so the design ceiling is restored where it
@@ -1400,7 +1851,14 @@
 
         --primary:                 light-dark(hsl(24 10% 10%), hsl(48 10% 90%));
         --primary-foreground:      light-dark(var(--neutral-0), hsl(24 10% 10%));
-        --destructive:             light-dark(hsl(0 72% 50%), hsl(0 62.8% 30.6%));
+        /* AX.W44 — dark-arm lift. The stock shadcn dark `hsl(0 62.8% 30.6%)`
+           (L≈30.6) was a saturated-PLATE value used AS INK over `--card` by the
+           Alert destructive variant — 1.75:1 over card (illegible) / 1.91:1 vs the
+           page. Lifted to `hsl(0 80% 60%)`: 4.60:1 as text over `--card` (clears the
+           4.5 body floor) AND 5.03:1 as a plate vs the dark page (clears the 3.0
+           graphic floor). The light arm is UNCHANGED (already 4.70:1). Lockstep with
+           the `.dark` fallback floor below (§2c). */
+        --destructive:             light-dark(hsl(0 72% 50%), hsl(0 80% 60%));
         --destructive-foreground:  light-dark(var(--neutral-0), hsl(48 10% 90%));
         --ring:                    light-dark(hsl(24 10% 10%), hsl(48 10% 70%));
         --shadow:                  light-dark(hsl(24 10% 10%), hsl(0 0% 5%));
@@ -1522,7 +1980,11 @@
 
     --primary: hsl(48 10% 90%);
     --primary-foreground: hsl(24 10% 10%);
-    --destructive: hsl(0 62.8% 30.6%);
+    /* AX.W44 — the `.dark` class fallback floor, in LOCKSTEP with the light-dark()
+       enhancement arm above (§2c). Same lifted `hsl(0 80% 60%)` so a
+       @supports-split engine and a class-toggle engine paint the SAME dark red
+       (4.60:1 as ink over --card / 5.03:1 as a plate vs page). */
+    --destructive: hsl(0 80% 60%);
     --destructive-foreground: hsl(48 10% 90%);
     --ring: hsl(48 10% 70%);
     --shadow: hsl(0 0% 5%);
@@ -1589,6 +2051,25 @@
     --shadow-cartoon-color:            rgb(255 255 255 / 0.07);
     --shadow-cartoon-color-soft:       rgb(255 255 255 / 0.03);
 
+    /* §5c CONSTELLATION — dark arm (AX.W17). The H.W4 dark-mode lift: the node
+       tones step UP off the ink ground (the light arm's mid-grey would vanish on
+       L6 black), the hairline goes warm off-white, the field carries a touch more
+       presence to read at all. PLAIN-hsl literals, NEVER light-dark()/var(). */
+    --constellation-node:      hsl(42 9% 72%);
+    --constellation-node-dim:  hsl(42 8% 56%);
+    --constellation-line:      hsl(45 12% 86%);
+    /* Anomaly — brightened for the deep canvas (same neutral-default register;
+       the consumer still overrides to its brand). */
+    --constellation-accent:    hsl(20 70% 60%);
+    /* The dark hairlines lift harder over the ink ground, so the edge multipliers
+       run a touch lower than light to keep the field recessive. */
+    --constellation-edge-alpha:          0.20;
+    --constellation-edge-focus-alpha:  0.32;
+    /* §7 — the ink ground needs MORE field presence than cream to read at all, so
+       the dark alpha is modestly HIGHER than the light arm — but still BELOW the
+       slides 1.0 max-legibility reference (the recessive midpoint, not 1.0). */
+    --constellation-alpha:               0.88;
+
     /* Glass opacity + grain for dark — five-tier ladder, alpha-monotonic.
        Each rung lifts ~0.08 from its light counterpart so the dark surfaces
        carry comparable read-weight against the deeper canvas. */
@@ -1619,11 +2100,13 @@
        resolves the dark card). */
     --glass-fringe-warm: oklch(0.78 0.07 40 / 0.18);
     --glass-fringe-cool: oklch(0.74 0.06 230 / 0.14);
-    --glass-curvature-overlay: radial-gradient(
-        ellipse at 50% -20%,
-        hsl(0 0% 100% / 0.06),
-        transparent 60%
-    );
+    /* AX.W52 D19 — the curvature sheen is genuinely SOFTER on the deep canvas (the
+       prior dark arm re-declared the overlay BYTE-IDENTICAL to light, so it read
+       HARDER over the dark substrate — an unsoftened-dark defect). The `:root`
+       `--glass-curvature-overlay` already reads `var(--glass-curvature-intensity)`,
+       so lowering just the intensity here re-resolves the SAME warm-cream recipe at
+       a softer alpha — no byte-identical re-declaration. */
+    --glass-curvature-intensity: 0.012;
 
     /* Gold — boosted for dark (oklch; AV.W16 TW2) */
     --gold: oklch(0.784 0.143 86.0);
@@ -1726,3 +2209,73 @@
     inherits: false;
     initial-value: 0;
 }
+
+/* AX.W54 — the GLASS-FIRST single knob. `--glass-level` is the ONE clarity
+   scalar threaded through BOTH glass ladders at their single sites (the
+   `--glass-bg-*` opacity recipe + the `--glass-blur-*` radii). It is a typed,
+   INHERITING <number> so a host setting it on any ancestor retunes every
+   descendant glass surface (the @container-free cascade path) — and so it
+   animates smoothly rather than snapping. The level acts as a clarity multiplier
+   that PRESERVES level=1 (byte-identical to the hand-tuned ladder):
+     • level 1 — the calibrated glass (today's surfaces, unchanged).
+     • level 0 — the OPAQUE escape: solid `--card` + `blur(0)` through the SAME
+                 machinery (the `.glass-opaque` rung + the a11y brackets ride it).
+     • level >1 — clearer (more transparent + more diffuse) in lockstep.
+   Glass is the DEFAULT surface register for EVERY band (USER-DECIDED MAXIMAL);
+   the opaque level-0 rung is the explicit opt-out. W55 carries the over-light
+   legibility on the SEPARATE `--glass-tint-*` axis (the `--glass-backdrop` probe
+   lifts the tint toward ink — level = opacity+blur, tint = darken-over-light, the
+   two axes coordinate but never collapse: the a11y Clear↔Tinted escape rides
+   level-up here AND tint-toward-ink under `prefers-contrast: more`). */
+@property --glass-level {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 1;
+}
+
+/* AX.W51 D18 — the master comfortable-sizing scalar registered typed. The
+   `<number>` syntax guarantees `calc(<base> * var(--ui-scale))` is always valid (a
+   malformed override CLAMPS to the initial value 1, not an invalidated calc — the
+   fail-safe); `inherits: true` (unlike the per-element specular @property cohort)
+   so a SCOPED override (a dense data-table region) cascades to every descendant
+   control without a per-element set; the type makes it animatable (a density
+   toggle COULD spring it). Mirrors the `--glass-level` registration above (the
+   cascading-scalar idiom), distinct from the per-element specular @property cohort
+   (those are `inherits: false`). */
+@property --ui-scale {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 1;
+}
+
+/* ── The specular-intensity magnitude cohort (AX.W09) ──────────────────────
+   The catch-light alpha multiplier at each interaction state, as a SINGLE
+   overridable token cohort (was three buried literals across glass.css —
+   `0.35` rest floor / `0.6` hover / `0.85` active — and the `.dark` arm's
+   `0.22`). `glass.css`'s `.glass-material::before` rest/hover/active rules READ
+   these, so the subtle-vs-extreme magnitude is a knob a consumer (or the dark
+   arm) retunes ON THE CASCADE — never a re-buried literal. Override on `:root`
+   to retune library-wide; the cartoon-shadow override contract is the precedent.
+
+   Re-baselined AGAIN at AX.W52 D19 — with the central screen-disc replaced by a
+   BOUNDED plus-lighter edge gleam (glass.css), the gleam is a whisper at every
+   rung, so the cohort drops further (the W09 0.22/0.32 ceiling still lifted the
+   whole-tile disc on hover):
+     • rest   0    — static, unwired surfaces are CLEAN; the gleam wakes only on
+                     hover/active or on a pointer-wired surface. Aligns the painted
+                     rest with the @property `--specular-intensity { initial-value:
+                     0 }` dormancy.
+     • hover  0.10 — a whisper edge gleam, not a bloom.
+     • active 0.16 — the press whisper. */
+:root {
+    --glass-specular-intensity-rest: 0;
+    --glass-specular-intensity-hover: 0.1;
+    --glass-specular-intensity-active: 0.16;
+}
+
+/* Over the deep canvas `plus-lighter` still lifts, so the dark arm runs a touch
+   softer on the interaction rungs (rest already 0). */
+.dark {
+    --glass-specular-intensity-hover: 0.08;
+    --glass-specular-intensity-active: 0.12;
+}