@mkbabb/glass-ui 4.0.0 → 4.0.1

package/src/styles/scroll-choreography.css

@@ -0,0 +1,300 @@
+/*
+ * scroll-choreography.css — the SOTA scroll-driven CHOREOGRAPHY register
+ * (BB.W-SCROLL-MOTION).
+ *
+ * Cascade rung AFTER scroll-driven.css. glass-ui owns the native scroll-driven
+ * SUBSTRATE (scroll-driven.css `scroll()`/`view()` + the `--demo-main-progress`
+ * named timeline + the `supportsCssTimeline` harden) but composes none of the
+ * CHOREOGRAPHY — the page-load BUILD, the section CASCADE, the scroll-PINNED
+ * fixed-stage-advances-time reveals + the smooth-scroll register. The award-winners
+ * hand-roll these on Lenis+GSAP (a 20-40KB JS dependency); glass-ui ships the
+ * NATIVE register — the platform now ships `scroll()`/`view()`/`timeline-scope`
+ * natively, off the compositor at 60fps (the no-net-dep fence; the 2026
+ * universal-support convergence). NO Lenis/GSAP/Locomotive dependency, ever.
+ *
+ *   .scroll-build   — the route-enter page-build (chrome -> hero -> body, a
+ *                     spring-clocked coupled-fade, @keyframes-on-mount [NOT a
+ *                     scroll timeline — the build fires on mount], PRM-snapped).
+ *   .scroll-cascade — the orchestrated section cascade (per-child view() timeline,
+ *                     the implicit stagger [NO setTimeout], the spring-clocked
+ *                     coupled transform+opacity build).
+ *   .scroll-pin     — the fixed-stage-advances-time scroll-pinned register
+ *                     (position: sticky stage + a named scroll-timeline linked via
+ *                     timeline-scope; the stage's internal phases advance with
+ *                     scroll progress, compositor channels only).
+ *   .smooth-scroll  — the native scroll-behavior: smooth opt-in (PRM-gated,
+ *                     zero runtime — a smooth-scroll under reduce is a vestibular
+ *                     concern, so the smooth interpolation is dropped under PRM).
+ *
+ * THE DISCIPLINE (mirrors scroll-driven.css EXACTLY — the exemplary outer-gate):
+ * the whole register sits under `@media (prefers-reduced-motion: no-preference)`
+ * so under PRM no scroll/build animation attaches at all and content renders in
+ * its terminal state (the `from` keyframe never applies because the animation
+ * never binds; the .scroll-pin stage shows its terminal phase, no sweep). The
+ * scroll-driven recipes sit under a second `@supports (animation-timeline: …)`
+ * gate so a non-supporting engine gets the STATIC layout (the .scroll-pin stage
+ * is a correct non-pinned read, never a broken silent stage).
+ *
+ * COMPOSITOR-ONLY (the proof:no-layout-animation floor BB.W-CARD-COMPOSITE): every
+ * @keyframes step + transition animates ONLY transform/translate/scale/opacity/
+ * clip-path — NEVER a layout-triggering property (no height/padding/inline-size/
+ * top/grid-template). The SPATIAL (transform) legs ride the per-spring `--spring-*`
+ * + the matching `--spring-*-duration` settle clock (P2/P4); the EFFECTS (opacity)
+ * legs ride the no-overshoot `--ease-out` bezier (P1/P3 — a fade must never
+ * overshoot). The spring tokens are READ-ONLY (the W-GLASS-CAL clock fence — this
+ * register THREADS them, it never re-tunes a spring value or a duration).
+ */
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * .scroll-build — the route-enter page-build.
+ *
+ * A MOUNT-driven entrance (route-enter), NOT a scroll-driven one — so it rides a
+ * plain `@keyframes ... animation` (NOT a `view()`/`scroll()` timeline; the build
+ * fires on first paint of the new route, not on scroll). It sits under the PRM
+ * no-preference gate ALONE (no `@supports (animation-timeline)` — it does not use a
+ * timeline, so it runs on every engine; under PRM it never binds, so the page
+ * mounts at its terminal state).
+ *
+ * The coordinated stagger: the .scroll-build container's direct children are the
+ * BEATS (chrome, hero, body), each delayed by `--scroll-build-step * --i` (the
+ * per-beat coordinated stagger — the page assembles chrome-first, then the hero,
+ * then the first section). `--i` is the beat index a consumer sets per child
+ * (0-based); the chassis sets it on the chrome/hero/section in reading order
+ * (W-HIERARCHY2 owns the ORDER; this register threads the entrance ON it).
+ * ─────────────────────────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: no-preference) {
+    @keyframes gl-page-build {
+        from {
+            opacity: 0;
+            /* SPATIAL leg — the build rise (a transform, compositor-only). */
+            transform: translateY(var(--scroll-build-rise, 1.5rem));
+        }
+        to {
+            opacity: 1;
+            transform: translateY(0);
+        }
+    }
+
+    /* The page-build container marks the entrance; the beats are its children. */
+    .scroll-build > * {
+        /* The coupled build: the SPATIAL transform rides the snappy spring settle
+           clock (P2/P4 — the page parts arrive with crisp gravity); the opacity is
+           a coupled leg in the SAME keyframe on the SAME clock so the fade tracks
+           the rise as ONE coherent glide (P3 — fade coupled to transform). The
+           no-overshoot bezier governs the FADE channel where the spring's
+           overshoot is not wanted: `--ease-out` is named on the build's title beat
+           (the hero <h1> — audacious type arrives with GRAVITY, not bounce, per
+           W-HIERARCHY2); the other beats ride the snappy spring. */
+        animation: gl-page-build var(--spring-snappy-duration, 0.34s)
+            var(--spring-snappy) both;
+        animation-delay: calc(var(--scroll-build-step, 90ms) * var(--i, 0));
+    }
+
+    /* The hero/title beat: the audacious-type-arrives-with-gravity register — the
+       no-overshoot `--ease-out` bezier (a strictly monotone settle, NO overshoot
+       past the terminal transform), the existing .story-hero-title--enter
+       discipline folded into the ONE entrance system. A consumer marks the hero
+       beat `.scroll-build-hero`. */
+    .scroll-build > .scroll-build-hero {
+        animation: gl-page-build 0.62s var(--ease-out, ease-out) both;
+    }
+}
+
+/* The EXPLICIT P6 carve — under prefers-reduced-motion: reduce the page-build DROPS
+   the spatial transform (no movement — the vestibular floor) but KEEPS a gentle
+   terminal fade-in (the EFFECTS channel survives per P6: fade-keeps, transform-
+   drops). This sits OUTSIDE the no-preference gate as the reduce-arm of the
+   coordinated build (mirroring the transitions.css fade-slide PRM arm — the
+   opacity leg alone under reduce). The build is mount-driven, so the no-preference
+   gate above never binds under reduce; this arm gives PRM users the coupled-FADE
+   terminal entrance with ZERO motion frames (no translateY), the genuine P6 read. */
+@media (prefers-reduced-motion: reduce) {
+    @keyframes gl-page-build-fade {
+        from {
+            opacity: 0;
+        }
+        to {
+            opacity: 1;
+        }
+    }
+    .scroll-build > * {
+        /* fade-keeps (opacity only), transform-DROPS (no translateY) — P6. */
+        animation: gl-page-build-fade var(--duration-fast, 0.16s) var(--ease-out, ease-out)
+            both;
+        animation-delay: 0s; /* no coordinated stagger under reduce — a single calm paint */
+    }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * .scroll-cascade — the orchestrated section cascade.
+ *
+ * Extends the bare `[data-scroll-reveal] > *` 6px fade into the SOTA coordinated
+ * build: the per-child `view()` timeline stays the implicit-stagger mechanism (each
+ * child owns its own timeline — NO setTimeout cascade), but the entrance is the
+ * spring-clocked coupled build (a deeper rise + a tighter reveal window). It sits
+ * under the PRM no-preference gate + the `@supports (animation-timeline: view())`
+ * gate (the scroll-driven.css discipline) — under PRM/non-support the sections
+ * render at their terminal state.
+ * ─────────────────────────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: no-preference) {
+    @supports ((animation-timeline: view()) and (animation-range: entry)) {
+        @keyframes gl-cascade-build {
+            from {
+                /* EFFECTS leg — the coupled fade (no overshoot). */
+                opacity: 0;
+                /* SPATIAL leg — the build rise (a transform, compositor-only). */
+                transform: translateY(var(--scroll-cascade-rise, 1.25rem));
+            }
+            to {
+                opacity: 1;
+                transform: translateY(0);
+            }
+        }
+
+        .scroll-cascade > * {
+            /* The view()-timeline drives the build off each child's OWN entry into
+               the viewport (the implicit stagger). The progress-bound timeline maps
+               the entrance across the `animation-range` window; the keyframe's
+               coupled transform+opacity build is the orchestrated cascade (vs the
+               bare 6px reveal). `linear` is the right easing for a SCROLL-bound
+               progress map (the spring shaping lives in the section's own settle
+               where the build is mount-driven; a scroll-bound timeline reads
+               1:1 with scroll position — a spring on a scrubbed timeline reads as
+               a scrubbed spring, which is correct here as the linear progress map). */
+            animation: gl-cascade-build auto linear both;
+            animation-timeline: view(block);
+            animation-range: entry 0% entry var(--scroll-cascade-range-end, 45%);
+        }
+
+        /* The horizontal-scroller variant — a `view(inline)` axis. */
+        .scroll-cascade.scroll-cascade--inline > * {
+            animation-timeline: view(inline);
+        }
+
+        /* The OPT-IN column-stagger variant (the Codrops nuance — even columns
+           from top, odd from below). A GRID-surface flourish, NOT the default (the
+           proportion fence: a uniform vertical cascade is the calm StoryPage
+           default; the column-stagger is the front-door grid showcase). A consumer
+           sets `--col` (the column index) per child; even/odd rise from opposite
+           directions, offset by `--scroll-cascade-column-stagger`. */
+        @keyframes gl-cascade-build-col-even {
+            from {
+                opacity: 0;
+                transform: translateY(calc(-1 * var(--scroll-cascade-rise, 1.25rem)));
+            }
+            to {
+                opacity: 1;
+                transform: translateY(0);
+            }
+        }
+        .scroll-cascade.scroll-cascade--columns > * {
+            animation-range: entry 0%
+                entry
+                calc(
+                    var(--scroll-cascade-range-end, 45%) +
+                        var(--scroll-cascade-column-stagger, 60ms) * 0
+                );
+        }
+        .scroll-cascade.scroll-cascade--columns > *:nth-child(even) {
+            animation-name: gl-cascade-build-col-even;
+        }
+    }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * .scroll-pin — the fixed-stage-advances-time scroll-pinned register.
+ *
+ * The SOTA "scrolling does not move the scene, it advances time inside it" model:
+ * a `.scroll-pin` tall container (the `--scroll-pin-stage-height` temporal space)
+ * holds a `.scroll-pin-stage` `position: sticky` element. The container declares
+ * a named `scroll-timeline`; the stage's internal phase animations bind to that
+ * named timeline via `timeline-scope` (so the stage animates against the
+ * CONTAINER'S scroll progress — the fixed stage advances time). The phase
+ * animations are compositor-only (transform/opacity/clip-path over the
+ * `animation-range` phase windows — the Codrops phased sequence: a reveal phase
+ * 0..45%, an expand phase 45..90%, a settle phase 90..100%).
+ *
+ * `timeline-scope` is the newest primitive — the `@supports` gate probes it (NOT
+ * just `scroll()`), so an engine with `scroll()`/`view()` but not `timeline-scope`
+ * gets the STATIC layout (a correct non-pinned read: the stage is a plain sticky
+ * element at its terminal phase, never a broken silent stage). In 2026
+ * `timeline-scope` ships alongside `scroll()`/`view()` (the universal-support
+ * convergence), so the CSS-only register is the ship; the JS fallback leaf (mirror
+ * useScrollProgress's dual-path single-writer) is BOOKED only on a material
+ * engine-gap reveal (the §Triumvirate support-matrix trigger) — never a JS scroll
+ * lib (the no-net-dep fence is binding either way).
+ * ─────────────────────────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: scroll()) and (timeline-scope: --gl-pin) {
+        @keyframes gl-pin-reveal {
+            from {
+                opacity: 0;
+                transform: translateY(var(--scroll-pin-lift, 2.5rem)) scale(0.96);
+            }
+            to {
+                opacity: 1;
+                transform: translateY(0) scale(1);
+            }
+        }
+        @keyframes gl-pin-settle {
+            from {
+                transform: scale(1);
+                opacity: 1;
+            }
+            to {
+                /* The settle phase — a gentle compositor drift, never a layout move. */
+                transform: scale(1.02) translateY(calc(-1 * var(--scroll-pin-lift, 2.5rem)));
+                opacity: 1;
+            }
+        }
+
+        /* The tall temporal container declares a named scroll-timeline + exposes it
+           to descendants via timeline-scope (the fixed-stage-advances-time link). */
+        .scroll-pin {
+            position: relative;
+            block-size: var(--scroll-pin-stage-height, 320vh);
+            scroll-timeline-name: --gl-pin;
+            scroll-timeline-axis: block;
+            timeline-scope: --gl-pin;
+        }
+
+        /* The sticky stage — pinned to the viewport while the container scrolls
+           past; its phases advance against the container's --gl-pin timeline. */
+        .scroll-pin-stage {
+            position: sticky;
+            inset-block-start: 0;
+        }
+
+        /* Phase 1 — the reveal (0..45% of the container scroll). */
+        .scroll-pin-stage .scroll-pin-phase-reveal {
+            animation: gl-pin-reveal auto linear both;
+            animation-timeline: --gl-pin;
+            animation-range: 0% var(--scroll-pin-phase-reveal-end, 45%);
+        }
+
+        /* Phase 2 — the settle/expand (the reveal-end..expand-end window). */
+        .scroll-pin-stage .scroll-pin-phase-settle {
+            animation: gl-pin-settle auto linear both;
+            animation-timeline: --gl-pin;
+            animation-range: var(--scroll-pin-phase-reveal-end, 45%)
+                var(--scroll-pin-phase-expand-end, 90%);
+        }
+    }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * .smooth-scroll — the native smooth-scroll opt-in.
+ *
+ * The native `scroll-behavior: smooth` (CSS-first, zero runtime — NOT a JS rAF
+ * momentum loop, which IS Lenis and is the fence). An OPT-IN class the scroller
+ * (`<main>`, a `.scroll-pin` container) applies. PRM-GATED: under
+ * `prefers-reduced-motion: reduce` the smooth interpolation is DROPPED and the
+ * jump-scroll is correct (a smooth-scroll over an anchor-jump is a vestibular
+ * concern). A consumer wanting Lenis-grade momentum brings it in THEIR app (the
+ * presets-in-consumers discipline); the library ships the native register.
+ * ─────────────────────────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: no-preference) {
+    .smooth-scroll {
+        scroll-behavior: smooth;
+    }
+}

package/src/styles/segmented-tabs.css

@@ -338,3 +338,34 @@
 .segmented-tabs--underline .segmented-tab:hover {
     color: color-mix(in oklab, var(--foreground) 70%, transparent);
 }
+
+/* ════════════════════════════════════════════════════════════════════════
+   BB.W-DRAG-MORPH — the `.glass-drag-lift` decoration (the pull affordance).
+
+   The `useDragMorph` consumer adds this class to the morph element while
+   `dragging` is true (the SegmentedTabs `:draggable` indicator; the
+   DockLayerGroup pull rail). It is the visual "this is grabbable + grabbed"
+   affordance — the GRAB cursor + a sub-perceptual `--glass-specular` catch-light
+   lift + the `will-change: transform` compositor hint that promotes the lozenge
+   to its own layer for the 1:1 follow. It carries NO transform itself (the
+   translate + squish are the primitive's own `translate`/`--stretch` writes, the
+   §6 compositor channels); this class only paints the affordance + the hint.
+
+   The grab cursor sits on the morph element AT REST too (a draggable indicator
+   reads grabbable before the grab), so `.glass-drag-grabbable` marks the rest
+   affordance and `.glass-drag-lift` adds the grabbing state. PRM does not gate
+   the cursor/hint (they are not motion); the lift is a static specular nudge. */
+.glass-drag-grabbable {
+    cursor: grab;
+    touch-action: none;
+}
+
+.glass-drag-lift {
+    cursor: grabbing;
+    /* Promote to its own compositor layer for the 1:1 follow (the translate write
+       is compositor-only; the hint keeps the plate off the main-thread paint). */
+    will-change: transform;
+    /* Sub-perceptual catch-light lift — the grabbed lozenge reads a hair brighter
+       at its specular edge (the W-GLASS-CAL specular register, disco-FREE). */
+    --glass-specular: 0.1;
+}

package/src/styles/theme/bridges.css

@@ -47,6 +47,9 @@
 
     /* Letter spacing → tracking-* utilities */
     --tracking-tight:  var(--type-tracking-tight);
+    /* BB.W-DISPLAY-TRACKING — the display-ONLY Apple −1.5% tracking rung bridged
+       to the `tracking-display` utility (the token-first consumer affordance). */
+    --tracking-display: var(--type-tracking-display);
     --tracking-snug:   var(--type-tracking-snug);
     --tracking-normal: var(--type-tracking-normal);
     --tracking-wide:   var(--type-tracking-wide);
@@ -219,6 +222,14 @@
     --color-silver-dark: var(--silver-dark);
     --color-silver-deep: var(--silver-deep);
 
+    /* BB.W-METAL-SHIMMER — the bronze brand metal (the third member of the
+       gold·silver·bronze triad; the @theme namespace bridge so a `text-bronze`/
+       `bg-bronze` utility resolves through, mirroring gold/silver). */
+    --color-bronze: var(--bronze);
+    --color-bronze-light: var(--bronze-light);
+    --color-bronze-dark: var(--bronze-dark);
+    --color-bronze-deep: var(--bronze-deep);
+
     --color-rainbow-red:    var(--rainbow-red);
     --color-rainbow-orange: var(--rainbow-orange);
     --color-rainbow-yellow: var(--rainbow-yellow);

package/src/styles/theme/literals.css

@@ -30,10 +30,19 @@
        band-pass vs one-pass sweep) want different tempos. The pre-V audit
        (C-c §5.3) flagged this as a "naming inversion"; it is intentional —
        documented here so the offset is searchable. The orphan
-       `--duration-shimmer-slow` (8s) was excised in V.W2 T5. */
+       `--duration-shimmer-slow` (8s) was excised in V.W2 T5.
+
+       BB.W-METAL-SHIMMER — `--animate-gold-shimmer` re-points onto the metal-
+       PARAMETERIZED `metal-shimmer-sweep` keyframe (the gold-only
+       `gold-shimmer-slide` RETIRED — clean break, no alias); the duration/tempo
+       are byte-preserved (the gold READ unchanged). `--animate-metal` is the
+       brand-metal family's own row on the slow `--duration-metal` (6s) clock — the
+       `.metal-{gold,silver,bronze}`/`.metal-*-border`/`.metal-rainbow-rim`
+       utilities read it (utilities/metal.css). */
     --animate-shimmer: shimmer var(--duration-shimmer-fast) linear infinite;
     --animate-shimmer-sweep: shimmer-sweep var(--duration-shimmer) ease-in-out infinite;
-    --animate-gold-shimmer: gold-shimmer-slide var(--duration-shimmer) linear infinite;
+    --animate-gold-shimmer: metal-shimmer-sweep var(--duration-shimmer) linear infinite;
+    --animate-metal: metal-shimmer-sweep var(--duration-metal) linear infinite;
     --animate-shake: shake 0.5s ease-in-out;
 
     /* ═══════════════════════════════════════════════

package/src/styles/theme/radius.css

@@ -64,7 +64,12 @@
        |x|^(2K) + |y|^(2K) = 1, so the curve exponent n = 2K. The CSS `squircle`
        keyword == `superellipse(2)` == n=4 — the iOS-idiomatic web squircle. The
        k-PRIMITIVE band (a consumer dials 1.7–2.4 to taste; W42's dock-morph calc()s
-       its animated k against this ONE vocabulary — do not re-define a second k). */
+       its animated k against this ONE vocabulary — do not re-define a second k).
+       (BB.W-DEAD-SWEEP re-ground: --corner-k-soft / --corner-k-sharp have no
+       runtime var() consumer but ARE pinned by proof:squircle-language (the
+       TOKEN-AXIS-EXISTS clause asserts both rungs are minted) — so KEPT, not
+       swept; the clean-break delete is a coordination follow-up once the gate
+       re-anchors.) */
     --corner-k-squircle: 2;   /* the squircle — superellipse(2), n=4               */
     --corner-k-soft:     1.7; /* gentler, between round and squircle — n≈3.4       */
     --corner-k-sharp:    2.4; /* crisper square-bias for large surfaces — n≈4.8    */

package/src/styles/tokens/dark-arm.css

@@ -57,7 +57,17 @@
        --accent{,-foreground} / --border / --input are pure var()-aliases —
        DELETED here (AQ.W2 §2a): they auto-track the --neutral-* ladder +
        --foreground above. Re-declaring them would be redundant. */
-    --foreground: hsl(48 10% 90%);
+    /* BB.W-DARK-INK-WARM — the dark --foreground warmed off hsl(48 10% 90%) (OKLab H95.1°,
+       the EXACT yellow-green W-NO-GRAY condemned as "a cast, not warm material") onto the
+       no-gray warm identity hsl(30 14% 90%) (OKLab L0.926 C0.0063 H75.4° — the --foreground
+       56° warm-amber family, L held within ±0.001 of HEAD, chroma off the gray floor,
+       chroma-only at constant L). The contrast contract holds (the dark ink over the L4 page
+       stays ≥ the body floor). EVERY dark var(--foreground) consumer (body copy, the lifted
+       muted register, --glass-tint-ink, the cartoon shadow, the configurator divider, the
+       dock-selected-accent, the --surface-tint-* relative-color recipe below) re-resolves
+       warm in lockstep, zero per-site edit. LOCKSTEP light-dark.css:92 (the §2c discipline —
+       both mode arms warm together or the FOUC/enhancement split paints two inks). */
+    --foreground: hsl(30 14% 90%);
     /* BA.W-DARK-MATERIAL scope 1 — the --card plate LIFTS L10→L16 (a warm-dark elevated
        surface, macOS-window territory) so it sits ~5× the deepened L4 page relL — a
        clearly distinct surface the five glass rungs ladder up from. LOCKSTEP light-dark.css:80. */
@@ -190,9 +200,14 @@
     --constellation-edge-floor:          0;
     --constellation-edge-accent-alpha:   0.34;
 
-    /* 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. */
+    /* Glass opacity + grain for dark — the per-tier canonical alpha, DARK arm
+       (BB.W-CARD-TIER-ALPHA). The SAME named `--glass-opacity-{tier}` register as
+       the light arm (tokens/glass.css), per-mode — the dark identity. 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. A
+       consumer reads these named tokens; a divergent register stays a consumer preset.
+       Machine-locked by `proof:card-tier-alpha` (the dark-arm-present + monotonic +
+       lift-over-light asserts). */
     --glass-opacity-wash:     0.38;
     --glass-opacity-quiet:    0.58;
     --glass-opacity-resting:  0.72;
@@ -218,6 +233,21 @@
     --glass-blur-overlay:  blur(calc(var(--glass-blur-overlay-radius) * var(--glass-level))) saturate(1.22) brightness(1.06);
     --glass-blur-dock:     blur(calc(var(--glass-blur-dock-radius) * var(--glass-level))) saturate(1.30) brightness(1.12);
 
+    /* BB.W-DEEP-GLASS — the DARK arm of the OPT-IN deep tier (the luminous-dark
+       deep mirror, the W-DARK-MATERIAL scope-2 "dark glass glows where light
+       passes" model). The deep tier is even more transmissive in dark — the deep
+       dark glass glows MORE where the backdrop passes — so its saturate/brightness
+       companion lifts HARDER than the calm dark floating (1.28/1.10): the deep
+       arm carries saturate(1.55) brightness(1.16), in LOCKSTEP with the light deep
+       arm (which sits at saturate 1.5 / depth-LERPed, glass-deep.css). The RADIUS
+       is the SAME --glass-blur-deep-active-radius × --glass-level (radius-only
+       across modes, the §2c discipline — only the saturate/brightness companions
+       differ between light/dark). This is a SEPARATE deep token the calm dark
+       ladder never reads (CALM-UNCHANGED in dark too — proof:glass-cal GREEN). */
+    --glass-blur-deep:
+        blur(var(--glass-blur-deep-active-radius))
+        saturate(1.55) brightness(1.16);
+
     /* BA.W-DARK-MATERIAL scope 3 — the dark arm of the adaptive --glass-tint-* seam (the
        SAME seam, NO third fork). The W55 self-engage block (glass/ladder.css) re-points
        --glass-tint-source → --glass-tint-ink at --glass-tint-strength-aa. In LIGHT that is
@@ -242,28 +272,59 @@
        mode arms — the content-tier self-engage needs no mode branch. */
     --glass-tint-strength-floor: 12%;
 
-    /* BA.W-DARK-MATERIAL scope 5 — the --surface-tint-* dark arm. The light family is
-       color-mix(in srgb, var(--foreground) N%, transparent) — over a near-black dark card
-       a LIGHT-ink (dark --foreground IS light cream) tint composites to near-black: the
-       9-rung chip/hairline/divider scale is INVISIBLE in dark. The dark arm KEEPS the
-       in-srgb space (the AW.W26 fence — NEVER oklab) but re-anchors the mix ink to a
-       BRIGHTER warm off-white so a chip/hairline LIFTS off the deep card (the inverse
-       intent of light's dark-ink tint). This re-resolves every --surface-tint-* consumer
-       (chip backplates, the dock-rail divider, the spine, the timeline dot) in lockstep,
-       zero per-site edit. The brighter ink is a near-white warm (hsl(48 12% 96%)) so the
-       higher rungs read as genuine hairlines on the L16 card. */
-    --surface-tint-4:  color-mix(in srgb, hsl(48 12% 96%)  4%, transparent);
-    --surface-tint-6:  color-mix(in srgb, hsl(48 12% 96%)  6%, transparent);
-    --surface-tint-8:  color-mix(in srgb, hsl(48 12% 96%)  8%, transparent);
-    --surface-tint-10: color-mix(in srgb, hsl(48 12% 96%) 10%, transparent);
-    --surface-tint-12: color-mix(in srgb, hsl(48 12% 96%) 12%, transparent);
-    --surface-tint-15: color-mix(in srgb, hsl(48 12% 96%) 15%, transparent);
-    --surface-tint-18: color-mix(in srgb, hsl(48 12% 96%) 18%, transparent);
-    --surface-tint-22: color-mix(in srgb, hsl(48 12% 96%) 22%, transparent);
-    --surface-tint-25: color-mix(in srgb, hsl(48 12% 96%) 25%, transparent);
-    --surface-tint-35: color-mix(in srgb, hsl(48 12% 96%) 35%, transparent);
-    --surface-tint-40: color-mix(in srgb, hsl(48 12% 96%) 40%, transparent);
-    --surface-tint-70: color-mix(in srgb, hsl(48 12% 96%) 70%, transparent);
+    /* BB.W-ON-GLASS-FG — the surface-aware FOREGROUND register, DARK arm (the N13
+       whisper collapse where it bites hardest). The dark page-muted --neutral-5 (L62,
+       "AA: 7.64:1 vs page") COLLAPSES over the lifted luminous-dark plate (the L16 card
+       at the 12% --glass-tint-strength-floor composites the bright backdrop UP — the
+       measured 1.15-3.29:1). The on-glass muted rung lifts BRIGHTER (the mirror of the
+       light arm's darkening) so it clears AA over the composited dark plate WHILE
+       staying subordinate to the L90 --foreground ink (the quiet-subordinate hierarchy
+       preserved — NOT a blanket lift to full ink, which the bright bucket already does).
+       Warm-amber (the BB.W-DARK-INK-WARM identity), NOT the slides deck hsl(45 …) literal
+       (the deck is the REFERENCE; the library re-derives against its own --card). The
+       light arm lives in tokens/glass.css (the plain per-mode pair — the house idiom). */
+    --on-glass-muted:        hsl(34 16% 72%);   /* brighter than the collapsed --neutral-5 L62 (6.63:1 vs the luminous-dark plate; subordinate to --foreground) */
+    --on-glass-muted-strong: hsl(36 14% 78%);   /* the -strong rung, one step more present (7.75:1 vs plate) */
+    --input-on-glass:        hsl(26 12% 22%);   /* the form-well fill — grounded warm-dark so the L90 input TEXT reads against a stable base (9.3:1) */
+    --progress-track-on-glass: hsl(28 14% 26%); /* the recessed meter track — a warm-dark channel distinct from the fill silhouette */
+
+    /* BA.W-DARK-MATERIAL scope 5 + BB.W-DARK-INK-WARM — the --surface-tint-* dark arm,
+       --foreground-DERIVED. The light family is color-mix(in srgb, var(--foreground) N%,
+       transparent) — over a near-black dark card a LIGHT-ink (dark --foreground IS light
+       cream) tint composites to near-black: the 9-rung chip/hairline/divider scale is
+       INVISIBLE in dark. The dark arm re-anchors the mix ink to a BRIGHTER warm off-white
+       so a chip/hairline LIFTS off the deep card (the inverse intent of light's dark-ink
+       tint). BA executed that intent as a hardcoded hsl(48 12% 96%) literal ×12 — at the
+       EXACT OKLab H95.1° yellow-green the SAME tranche's W-NO-GRAY ruled "a cast, not warm
+       material", AND a per-rung literal a --foreground re-point can never reach (the
+       architectural asymmetry with the light arm + the substitution-vs-redeclaration trap
+       at the token mint). BB re-expresses each rung as a oklch(from var(--foreground) 0.975
+       c h) RELATIVE-COLOR derivation: the recipe extracts the (now-warmed) dark --foreground's
+       warm hue + chroma and lifts the lightness to 0.975 (≈ HEAD's 0.973 ink L, so the chip
+       lift off the L16 card is preserved) — the ink CARRIES the --foreground's warm hue
+       (OKLab H75.4°) BY DERIVATION (re-point the dark ink → every rung re-resolves warm; a
+       future re-tune reaches all 12 from ONE --foreground edit — the symmetry the light arm
+       has had since L.W5). The OUTER mix STAYS color-mix(in srgb, … N%, transparent) — the
+       SAME 12-rung α ladder + the SAME in-srgb interpolation space the light arm uses (the
+       AW.W26 fence holds — the oklch(from …) is the INK SOURCE, not the tint mix space).
+       This re-resolves every --surface-tint-* consumer (chip backplates, the dock-rail
+       divider, the spine, the timeline dot) in lockstep, zero per-site edit. The 0.975 lift
+       sits well under the sRGB gamut edge (the AX css-relative-color book's "browsers don't
+       gamut-map yet" caveat does not bite — at 0.975 the small high-L chroma resolves clean;
+       lift→1.0 drifts the hue, so 0.975 is the calibrated pin). The css-relative-color
+       chronic's FIRST live consumer (the tolerant α-mix the AX book was waiting for). */
+    --surface-tint-4:  color-mix(in srgb, oklch(from var(--foreground) 0.975 c h)  4%, transparent);
+    --surface-tint-6:  color-mix(in srgb, oklch(from var(--foreground) 0.975 c h)  6%, transparent);
+    --surface-tint-8:  color-mix(in srgb, oklch(from var(--foreground) 0.975 c h)  8%, transparent);
+    --surface-tint-10: color-mix(in srgb, oklch(from var(--foreground) 0.975 c h) 10%, transparent);
+    --surface-tint-12: color-mix(in srgb, oklch(from var(--foreground) 0.975 c h) 12%, transparent);
+    --surface-tint-15: color-mix(in srgb, oklch(from var(--foreground) 0.975 c h) 15%, transparent);
+    --surface-tint-18: color-mix(in srgb, oklch(from var(--foreground) 0.975 c h) 18%, transparent);
+    --surface-tint-22: color-mix(in srgb, oklch(from var(--foreground) 0.975 c h) 22%, transparent);
+    --surface-tint-25: color-mix(in srgb, oklch(from var(--foreground) 0.975 c h) 25%, transparent);
+    --surface-tint-35: color-mix(in srgb, oklch(from var(--foreground) 0.975 c h) 35%, transparent);
+    --surface-tint-40: color-mix(in srgb, oklch(from var(--foreground) 0.975 c h) 40%, transparent);
+    --surface-tint-70: color-mix(in srgb, oklch(from var(--foreground) 0.975 c h) 70%, transparent);
 
     /* Hairline-accent dark mirror — see light counterpart at line ~404. */
     --hairline-catch-light: inset 0 0.5px 0 0 rgb(255 255 255 / 0.05);
@@ -304,5 +365,16 @@
     --silver: oklch(0.792 0.012 255);
     --silver-light: oklch(0.912 0.010 255);
     --silver-dark: oklch(0.648 0.014 255);
+
+    /* Bronze — lifted for dark (BB.W-METAL-SHIMMER; mirrors gold's dark arm: the
+       warm metal lifts ~+0.03 L so the bronze register reads on the deep canvas.
+       `--bronze-deep` is mode-invariant — NOT re-declared here, exactly as
+       `--gold-deep`/`--silver-deep` are omitted from this dark block). The warm hue
+       holds; the chroma stays above the W-NO-GRAY floor. The `.dark`-class fallback
+       for engines without `light-dark()` (the §2c lockstep — the light-dark arm AND
+       this dark fallback move TOGETHER). */
+    --bronze: oklch(0.650 0.090 54.0);
+    --bronze-light: oklch(0.790 0.110 60.0);
+    --bronze-dark: oklch(0.560 0.085 50.0);
 }
 

package/src/styles/tokens/glass-deep.css

@@ -0,0 +1,75 @@
+/*
+ * glass-deep.css — BB.W-DEEP-GLASS — the OPT-IN deep-glass token family.
+ *
+ * A SEPARATE `--glass-blur-deep-*` token family ABOVE the W-GLASS-CAL calm
+ * default (the Apple iOS-27 Liquid-Glass deep register: `saturate(1.8) blur(20px)`
+ * measured on Apple's live nav material; glass-ui lands the deep tier in the
+ * 14-20px band at a budget-clearing 16px + saturate 1.5). The calm content
+ * default is BYTE-UNTOUCHED — this family is minted ALONGSIDE the calm
+ * `--glass-blur-*` ladder (tokens/glass.css), which NEVER reads these tokens, so
+ * `proof:glass-cal` B1-B3 stay GREEN by construction (the calm default is the
+ * user's "a hair too much" call, INVIOLATE).
+ *
+ * This is the §8-ladder partial sibling of tokens/glass.css (kept OUT of glass.css
+ * so the ratchet-baselined glass.css stays at 505); @import-ed in tokens.css
+ * AFTER glass.css (the deep family resolves in the same :root cascade slot,
+ * adjacent same-selector blocks). The dark deep arm lives in tokens/dark-arm.css
+ * (the W-DARK-MATERIAL discipline — the luminous-dark companion beside the calm
+ * dark companions).
+ *
+ * ── The Apple-range derivation (DELTA cross-ref) ───────────────────────────
+ * Apple home nav:       saturate(1.8) blur(20px)  (the canonical measure)
+ * Apple product tiers:  blur(14-20px)             (the band)
+ * glass-ui calm ceiling: floating 13px / saturate 1.18  (W-GLASS-CAL dial-back)
+ * glass-ui DEEP:        16px / saturate 1.5        (STRICTLY deeper on BOTH axes,
+ *                       in-band, the budget-clearing landing — the full 20px is
+ *                       a BOOKED successor with the recorded throttle number).
+ * The deep saturate lands at the LOW end of the 1.5-1.8 band: the Apple 1.8 is
+ * measured over a NEUTRAL backdrop; glass-ui's deep tier sits over warm-aurora,
+ * and the warm-cream light-concentration ceiling (AX.W52 D19 — a saturate that
+ * over-juices a colored substrate reads as a garish smear) keeps it just-rich.
+ * The deepest BLUR carries the "more glass" read; the saturate stays restrained.
+ */
+:root {
+    /* The Apple-range deep ENDPOINTS — the radius + saturate the deep tier reaches
+       at full depth (`--glass-depth: 1`). The calm `floating` rung (13px / 1.18)
+       is the depth-0 floor; the deep recipe LERPs between the two on `--glass-depth`
+       so the axis is a genuine driver, not a literal. */
+    --glass-blur-deep-radius:    16px; /* in [14,20], STRICTLY > calm floating 13px */
+    --glass-saturate-deep:       1.5;  /* >= 1.5 (toward Apple 1.8), > calm floating 1.18 */
+
+    /* The deep blur RADIUS — LERPed from the calm floating radius (depth 0) to the
+       Apple-deep radius (depth 1) on `--glass-depth`, THEN scaled by the ONE
+       `--glass-level` clarity scalar (the W54 seam reaches the deep plate, so the
+       opaque escape + the a11y brackets compose: at `--glass-level: 0` the deep
+       blur resolves blur(0), the same solid floor). NOT a parallel recipe — the
+       deep blur COMPOSES `var(--glass-level)` exactly like every calm rung, and
+       reads `var(--glass-depth)` so a host dials the depth on any ancestor. */
+    --glass-blur-deep-active-radius:
+        calc(
+            (
+                var(--glass-blur-floating-radius)
+                + (var(--glass-blur-deep-radius) - var(--glass-blur-floating-radius))
+                * var(--glass-depth)
+            )
+            * var(--glass-level)
+        );
+    /* The deep SATURATE — LERPed from the calm floating saturate (1.18, depth 0)
+       to the deep saturate (depth 1) on `--glass-depth`. The saturate is the
+       light-concentration lift (chroma-only — it LIFTS the backdrop's existing
+       chroma, it does NOT inject a hue; the warm-cream `--card` base is the same). */
+    --glass-saturate-deep-active:
+        calc(
+            1.18 + (var(--glass-saturate-deep) - 1.18) * var(--glass-depth)
+        );
+
+    /* The composed deep backdrop-filter — the SEPARATE deep family. The calm
+       ladder never reads this; `.glass-deep` (glass/deep.css) is its only
+       consumer. The brightness companion mirrors the calm floating arm's
+       light-concentration (the calm floating carries saturate only; the deep
+       tier adds a small brightness lift for the thicker-glass read — still no
+       hue inject). */
+    --glass-blur-deep:
+        blur(var(--glass-blur-deep-active-radius))
+        saturate(var(--glass-saturate-deep-active));
+}