@mkbabb/glass-ui 3.7.0 → 3.8.0

package/src/styles/fonts.css

@@ -141,28 +141,3 @@
         U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF,
         U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
-
-/* ═══════════════════════════════════════════════
-   OFL FACE FILES — Fraunces (ornamental display)
-   ═══════════════════════════════════════════════ */
-
-/* Fraunces — Latin subset (basic Latin + ASCII punctuation + common
-   diacritics). The FULL variable font: a single woff2 carries wght 100..900
-   AND the opsz / SOFT / WONK axes typography.css drives
-   (`--font-display-variation-settings: "WONK" 1, "SOFT" 0`). Before AU.W4 the
-   `--font-stack-display: "Fraunces"` token (tokens.css:43) had NO shipped face,
-   so those axes were SILENTLY INERT (the slipped ship of the grand-audit/AS.W0b
-   lineage); this face resolves the dangling display token. `font-display: swap`
-   — the display register is a deliberate ornament, post-LCP, with the body
-   carried by the calibrated sans/mono fallbacks. */
-@font-face {
-    font-family: "Fraunces";
-    font-style: normal;
-    font-weight: 100 900;
-    font-display: swap;
-    src: url("@mkbabb/glass-ui/fonts/fraunces/fraunces-latin.woff2") format("woff2");
-    unicode-range:
-        U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA,
-        U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122,
-        U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
-}

package/src/styles/glass.css

@@ -100,21 +100,28 @@
            `var(--mouse-x, 50%)` floor is the centred fallback. */
         --specular-x: var(--mouse-x, 50%);
         --specular-y: var(--mouse-y, 50%);
-        /* The catch-light intensity floor at rest; hover/active lift it (the
-           interaction-light state machine below). */
-        --specular-intensity: 0.35;
-        /* The travelling catch-light — a soft warm-white circular glow centred
-           on the tracked pointer position (NOT iOS blue; keeps the warm-cream
-           identity). The `--specular-intensity` multiplier drives the layer
-           `opacity`, not a per-stop alpha (a registered-`@property` var() nested
-           in an hsl() alpha computes to 0 in Chromium). */
+        /* The catch-light intensity at REST — reads the token cohort
+           (tokens.css §specular-intensity), default 0 so a static, unwired
+           surface is CLEAN and the @property `initial-value: 0` dormancy is no
+           longer defeated by a floor. Hover/active lift it through the same
+           cohort (the interaction-light state machine below). */
+        --specular-intensity: var(--glass-specular-intensity-rest, 0);
+        /* The travelling catch-light — a genuinely WARM-CREAM, low-alpha circular
+           glow centred on the tracked pointer position (L < 100% so the warm hue
+           survives — the prior `hsl(40 30% 100%)` was PURE WHITE at L=100%, which
+           saturated the 30% away and blew out under the screen blend; the
+           warm-cream the comment claimed never painted). The `--specular-intensity`
+           multiplier drives the layer `opacity`, not a per-stop alpha (a
+           registered-`@property` var() nested in an hsl() alpha computes to 0 in
+           Chromium); the per-stop alphas here keep the core soft so even the lifted
+           hover/active states read as a lens, not a flash. */
         background: radial-gradient(
             circle at var(--specular-x, 50%) var(--specular-y, 50%),
-            hsl(40 30% 100% / 0.55) 0%,
-            hsl(40 30% 100% / 0.22) 22%,
+            hsl(40 30% 96% / 0.22) 0%,
+            hsl(40 30% 96% / 0.08) 22%,
             transparent 55%
         );
-        opacity: var(--specular-intensity, 0.35);
+        opacity: var(--specular-intensity, 0);
         /* Clip the glow to the plate so it rides the surface. `mask-image`
            Baseline 2023-12-07; a non-supporting engine ignores it and the
            `inset: 0` + radius-inherit already bound the glow. */
@@ -142,8 +149,12 @@
     .dark .glass-card::before,
     .dark .glass-specular-track::before,
     .dark .dock-icon-button::before {
-        /* Softer over the deep canvas — the screen blend lifts harder on dark. */
-        --specular-intensity: 0.22;
+        /* Softer over the deep canvas — the screen blend lifts harder on dark.
+           The `.dark` magnitude lives in the token cohort (tokens.css §specular-
+           intensity `.dark` arm); the rest rung is already 0 so the dark arm only
+           softens hover/active via the cohort. The rest rung re-reads the (dark)
+           token here so a dark `:root` override resolves. */
+        --specular-intensity: var(--glass-specular-intensity-rest, 0);
     }
 
     /* (c) Interaction-light lockstep — hover/active lift the intensity in the
@@ -159,7 +170,7 @@
     .glass-card:hover::before,
     .glass-specular-track:hover::before,
     .dock-icon-button:hover::before {
-        --specular-intensity: 0.6;
+        --specular-intensity: var(--glass-specular-intensity-hover, 0.22);
     }
     .glass-material:active::before,
     .glass-wash:active::before,
@@ -170,7 +181,7 @@
     .glass-card:active::before,
     .glass-specular-track:active::before,
     .dock-icon-button:active::before {
-        --specular-intensity: 0.85;
+        --specular-intensity: var(--glass-specular-intensity-active, 0.32);
     }
 
     /* ── Five-tier surface ladder (v0.8.0; visual only, no geometry) ──
@@ -565,32 +576,6 @@
         border-color: var(--surface-tint-15);
     }
 
-    /* ── Deck-position rail (AW.W16) ──────────────────────────────────────
-       A CSS recipe that RESTYLES the shipped `<Progress variant="default">`
-       (the reka-ui ProgressRoot track + its indicator child) into the thin
-       bottom-of-deck position rail. It composes the EXISTING fill — it does NOT
-       re-author a second track/range mechanic. Every visual axis is a
-       `--progress-rail-*` token, so a consumer/dark-flip re-tints with zero
-       library edit (`:root { --progress-rail-fill: … }`). The viewport-pinned
-       chrome (`position: fixed`, `env(safe-area-inset-bottom)`, the z-index) is
-       CONSUMER-supplied — this recipe owns only the LOOK. */
-    .glass-progress-rail {
-        /* The track hairline — the rail reads as a thin sliver, not a 16px bar. */
-        height: var(--progress-rail-h, 3px);
-        border-radius: 0;
-        background: var(--progress-rail-track, color-mix(in srgb, var(--foreground) 8%, transparent));
-    }
-
-    /* The fill — the shipped ProgressIndicator child. A leading-edge glow on the
-       fill's trailing edge reads as a moving position head. */
-    .glass-progress-rail > * {
-        border-radius: 0;
-        background: var(--progress-rail-fill, var(--primary));
-        box-shadow:
-            var(--progress-rail-glow-x, 4px) 0 var(--progress-rail-glow-blur, 8px)
-            color-mix(in srgb, var(--progress-rail-fill, var(--primary)) var(--progress-rail-glow-strength, 55%), transparent);
-    }
-
     /* ── AW.W23 — chromatic edge dispersion (the polished-glass rim fringe) ──
        An opt-in `.glass-chromatic` composes the warm/cool oklab fringe OVER the
        W22 uniform rim (it does NOT replace it — the rim still rides each rung's
@@ -605,6 +590,80 @@
     }
 }
 
+/* ── Deck-position rail (AW.W16 · AX.W24) ───────────────────────────────────
+   A Tailwind `@utility` that RESTYLES the shipped `<Progress variant="default">`
+   (the reka-ui ProgressRoot track + its indicator child) into the thin
+   bottom-of-deck position rail. It composes the EXISTING fill — it does NOT
+   re-author a second track/range mechanic. Every visual axis is a
+   `--progress-rail-*` token, so a consumer/dark-flip re-tints with zero library
+   edit (`:root { --progress-rail-fill: … }`). The viewport-pinned chrome
+   (`position: fixed`, `env(safe-area-inset-bottom)`, the z-index) is CONSUMER-
+   supplied — this recipe owns only the LOOK.
+
+   AX.W24 — WHY `@utility`, not `@layer components`. The rail RESTYLES the default
+   Progress: it must override the `h-4` height + `rounded-pill` radius utilities the
+   variant bakes. Those utilities live in `@layer utilities`, which ALWAYS outranks
+   `@layer components` regardless of source order, so the prior `@layer components`
+   recipe's `height: 3px` was a silent no-op (the rail painted as a 16px bar). An
+   `@utility` lands the recipe IN `@layer utilities` alongside `h-4`, where a single-
+   class selector wins the geometry by source order — the idiomatic Tailwind-v4 way
+   to author a restyle-class that out-ranks base utilities (the `btn-audacious` /
+   `cartoon-surface` pattern).
+
+   The COLOUR fix is the SEPARATE token-read-at-source path (NOT a layer-juggle):
+   `ProgressDefault` reads `--progress-fill`/`--progress-track` and dropped its
+   `bg-secondary`/`bg-primary` utilities, so this recipe FEEDS those tokens rather
+   than fighting a utility colour. The `--progress-fill` set on the rail root cascades
+   to the indicator child (a CSS custom property inherits), so the indicator reads the
+   override hue. */
+@utility glass-progress-rail {
+    /* The track hairline + zero radius — the rail reads as a thin square sliver, not
+       the variant's 16px `rounded-pill` bar. A single-class @utility ties `h-4`/
+       `rounded-pill` on SPECIFICITY (both 0,1,0) and Tailwind's utility sort can emit
+       `h-4` later, so the bare tie loses. The doubled-class self-reference (`&&` →
+       `.glass-progress-rail.glass-progress-rail`, specificity 0,2,0) wins the geometry
+       DETERMINISTICALLY over the base utilities regardless of emit order — the precise,
+       contained way to out-rank a base utility without `!important`. */
+    && {
+        height: var(--progress-rail-h, 3px);
+        border-radius: 0;
+    }
+    /* Feed the token-read default variant — these route the consumer's
+       `--progress-rail-*` axes into the `--progress-fill`/`--progress-track` tokens
+       the variant reads at source (the cascade-correct colour path). */
+    --progress-track: var(
+        --progress-rail-track,
+        color-mix(in srgb, var(--foreground) 8%, transparent)
+    );
+    --progress-fill: var(--progress-rail-fill, var(--primary));
+
+    /* The fill — the shipped ProgressIndicator child. The indicator paints the
+       inherited `--progress-fill`; the leading-edge glow is re-authored (AX.W24 F2)
+       as a TRAILING right-edge INSET box-shadow that lives INSIDE the indicator's
+       own box. The prior `4px 0 8px` OUTSET rightward shadow extended PAST the fill
+       boundary into the ProgressRoot's load-bearing `overflow-hidden` clip and was
+       eaten — invisible at every value. An `inset` shadow offset leftward
+       (`inset -Npx 0 …`) brightens just inside the indicator's right (leading) edge
+       — the moving position head — and never crosses the fill boundary, so the clip
+       cannot eat it (the clip is never lifted; that would re-break the default
+       Progress look for every other consumer). `box-shadow` is a separate property
+       from `background`, so it composes cleanly over the token-read fill. */
+    && > * {
+        border-radius: 0;
+        box-shadow:
+            inset
+            calc(-1 * var(--progress-rail-glow-x, 4px))
+            0
+            var(--progress-rail-glow-blur, 8px)
+            calc(-1 * var(--progress-rail-glow-spread, 2px))
+            color-mix(
+                in srgb,
+                hsl(0 0% 100%) var(--progress-rail-glow-strength, 55%),
+                transparent
+            );
+    }
+}
+
 /* ── AW.W23 — corner-shape: squircle PE (Chrome 139+) ───────────────────────
    The literal iOS-26 superellipse corner geometry that `backdrop-filter`,
    borders, and shadows follow. `@supports (corner-shape: squircle)`-gated over

package/src/styles/theme.css

@@ -103,9 +103,17 @@
 
     /* ═══════════════════════════════════════════════
        Font families → font-* utilities
+
+       ONE brand register, bridged from tokens.css §0's --font-stack-* source.
+       --font-text is the body/heading/prose/display register (Plus Jakarta
+       Sans). --font-serif is a bridge alias for the demo configurator's "serif"
+       control slot — it resolves to the SAME text register (the library carries
+       no display-serif voice). A consumer rebrands the whole text register by
+       overriding --font-text once.
        ═══════════════════════════════════════════════ */
+    --font-text:    var(--font-stack-text);
     --font-display: var(--font-stack-display);
-    --font-serif:   var(--font-stack-serif);
+    --font-serif:   var(--font-stack-text);
     --font-sans:    var(--font-stack-sans);
     --font-mono:    var(--font-stack-mono);
 
@@ -358,7 +366,6 @@
     --ease-in: var(--motion-ease-in);
     --ease-out-expo: var(--motion-ease-out-expo);
     --ease-apple: var(--motion-ease-apple);
-    --ease-apple-spring: var(--motion-ease-apple-spring);
     --ease-spring: var(--spring-snappy);
     --ease-decelerate: var(--motion-ease-out);
     --ease-accelerate: var(--motion-ease-in);

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;
@@ -175,10 +178,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);
@@ -418,6 +419,46 @@
     --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 +576,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);
@@ -866,18 +923,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
@@ -1300,12 +1355,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;
 
@@ -1589,6 +1646,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. */
@@ -1726,3 +1802,34 @@
     inherits: false;
     initial-value: 0;
 }
+
+/* ── 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 to a SUBTLE ladder (≈ half the retired `0.35/0.6/0.85`):
+     • rest   0    — static, unwired surfaces are CLEAN; the catch-light wakes
+                     only on hover/active or on a pointer-wired surface. This
+                     aligns the painted rest behaviour with the @property
+                     `--specular-intensity { initial-value: 0 }` dormancy the
+                     prior unconditional `0.35` floor defeated.
+     • hover  0.22 — a subtle warm-cream lens, not a flash.
+     • active 0.32 — the press whisper; ≈ 0.22α × the warm-cream core, a lens
+                     not the prior ≈ 0.47 pure-white-screen hotspot. */
+:root {
+    --glass-specular-intensity-rest: 0;
+    --glass-specular-intensity-hover: 0.22;
+    --glass-specular-intensity-active: 0.32;
+}
+
+/* Over the deep canvas the `screen` blend lifts harder, so the dark arm runs a
+   touch softer on the interaction rungs (rest already 0). */
+.dark {
+    --glass-specular-intensity-hover: 0.18;
+    --glass-specular-intensity-active: 0.26;
+}