@mkbabb/glass-ui 3.13.0 → 4.0.1

package/src/styles/glass/reveal.css

@@ -0,0 +1,136 @@
+/* glass/reveal.css
+   BB.W-LIQUID-REVEAL — the `.glass-reveal` LIQUID-ENTER recipe: the spring-clocked,
+   coupled-channel top-layer open that REPLACES `popover-animate`'s fixed-bezier
+   zoom-95 (clean break, no alias). The zero-JS floor the reka portaled overlays
+   compose (they are not native top-layer, so they cannot ride `@starting-style`;
+   `.glass-reveal` is the data-state form). The `useLiquidReveal` JS leaf is the
+   source-rect REFINEMENT (the dialog-from-button / dock-from-pill bloom); this CSS
+   recipe is the everywhere floor.
+   @import-ed by glass.css in cascade order, in its own @layer components
+   (isomorphic to the monolith). See docs/precepts/design-idioms.md §cohesion-aware
+   partials. */
+
+/* ── THE LIQUID ENTER (the iOS-27 bloom-from-anchor) ──────────────────────────
+ *
+ * Three COUPLED channels, the SPATIAL/EFFECTS split (the Material-3 / §6 /
+ * W-MOTION-CANON doctrine):
+ *
+ *   (a) SCALE (the bloom — SPATIAL) rides `--spring-snappy` + its OWN settle clock
+ *       `--spring-snappy-duration` (the W-GLASS-CAL Unit 3 per-spring clock, NOT the
+ *       generic `--duration-normal` that re-timed every spring to one wall clock).
+ *       The overshoot interior of the spring `linear()` gives the canonical iOS
+ *       arrival. `transform-origin` anchors at the popper edge (`--reka-popper-
+ *       transform-origin`) so the surface blooms FROM its anchor, not center.
+ *   (b) OPACITY (the fade — EFFECTS) rides `--ease-out` (NO overshoot — a fade must
+ *       not bounce), coupled so scale+fade read as ONE continuous coalescing layer.
+ *   (c) BLUR-SETTLE (the iOS "light-bending modulation" decongest — EFFECTS)
+ *       `filter: blur(--glass-reveal-blur)` → `blur(0)`, on the SAME spring clock as
+ *       the scale so the surface clarifies AS it blooms. The decongest rides the
+ *       surface's OWN pixels (`filter`) NOT the backdrop (`backdrop-filter`), so it
+ *       does NOT clobber the resting `glass-floating` tier plate blur the overlay
+ *       carries at rest (a `backdrop-filter: blur(0)` open value would erase the
+ *       glass). A `filter` radius interp is COMPOSITOR-safe (never a layout property
+ *       — the proof:no-layout-animation floor).
+ *
+ * Uses the `scale:` / `translate:` LONGHANDS (not `transform:`), so it composes with
+ * any identity-base transform and mints no stacking context (the `.glass-top-layer`
+ * `scale:` discipline). NEVER animates a layout property (the zoom is `scale`, the
+ * side-slide is `translate` — the directional slide-in `popover-animate` +
+ * `slide-in-from-side` used to carry, now folded onto the compositor `translate` leg).
+ */
+
+@layer components {
+    .glass-reveal {
+        /* The one public start knob (the decongest radius). The spatial/effects
+           clocks read the shared spring tokens (read-only — the W-GLASS-CAL fence). */
+        --glass-reveal-blur: 4px;
+        --glass-reveal-slide: 0.5rem;
+        transform-origin: var(--reka-popper-transform-origin, center);
+        /* The coupled transition list — the SPATIAL legs (scale/translate) on the
+           snappy spring's OWN settle clock, the EFFECTS legs (opacity/filter blur-
+           settle) on the no-overshoot ease-out. ONE coherent glide. The blur rides
+           `filter` (the surface's own pixels) NOT `backdrop-filter` (which would
+           clobber the resting glass-floating plate blur). */
+        transition-property: scale, translate, opacity, filter, display, overlay;
+        transition-duration: var(--spring-snappy-duration), var(--spring-snappy-duration),
+            var(--spring-snappy-duration), var(--spring-snappy-duration),
+            var(--spring-snappy-duration), var(--spring-snappy-duration);
+        transition-timing-function: var(--spring-snappy), var(--spring-snappy),
+            var(--ease-out), var(--ease-out), linear, linear;
+        transition-behavior: allow-discrete;
+    }
+
+    /* OPEN — the settled, bloomed-in state (the spring-clocked scale/fade/blur-settle
+       interpolates FROM the closed values). `filter: blur(0)` clarifies the surface;
+       the resting `glass-floating` backdrop-filter is untouched. The `translate` leg
+       is set ONLY by the `data-side` variants below (a side-anchored popover slides
+       from its edge) — the BASE never writes `translate`, so a center-anchored Dialog
+       keeping its `-translate-x-1/2 -translate-y-1/2` centering is NEVER clobbered. */
+    .glass-reveal[data-state="open"] {
+        scale: 1;
+        opacity: 1;
+        filter: blur(0);
+    }
+
+    /* CLOSED — both the resting CLOSED snapshot AND the EXIT leg. The exit reads
+       `--ease-out` (a bezier, NO overshoot — a closing surface must never overshoot
+       past gone, the §6/W-MOTION-CANON P2 doctrine); NO `--spring-*` token on the
+       exit. The exit is faster + un-sprung — the surface recedes cleanly. */
+    .glass-reveal[data-state="closed"] {
+        scale: var(--glass-reveal-enter-scale, 0.95);
+        opacity: 0;
+        filter: blur(var(--glass-reveal-blur));
+        transition-timing-function: var(--ease-out);
+        transition-duration: var(--duration-fast);
+    }
+
+    /* The directional slide-in — the compositor `translate` leg keyed off the
+       popper's `data-side` (folds the retired `slide-in-from-side` `@utility`'s
+       directional entry onto the compositor channel; the panel enters from outside
+       the anchor's edge). On the SAME snappy spring + clock as the scale. ONLY a
+       side-anchored popover (with `data-side`) sets `translate`; the open settled
+       value is `0 0` (per side, so it slides home from the edge). A center-anchored
+       Dialog has no `data-side` and is never reached here. */
+    .glass-reveal[data-side="top"][data-state="open"],
+    .glass-reveal[data-side="bottom"][data-state="open"],
+    .glass-reveal[data-side="left"][data-state="open"],
+    .glass-reveal[data-side="right"][data-state="open"] {
+        translate: 0 0;
+    }
+    .glass-reveal[data-state="closed"][data-side="top"] {
+        translate: 0 var(--glass-reveal-slide);
+    }
+    .glass-reveal[data-state="closed"][data-side="bottom"] {
+        translate: 0 calc(-1 * var(--glass-reveal-slide));
+    }
+    .glass-reveal[data-state="closed"][data-side="left"] {
+        translate: var(--glass-reveal-slide) 0;
+    }
+    .glass-reveal[data-state="closed"][data-side="right"] {
+        translate: calc(-1 * var(--glass-reveal-slide)) 0;
+    }
+}
+
+/* ── REDUCED-MOTION CARVE (the vestibular floor — WCAG 2.3.3) ──────────────────
+ * Under `prefers-reduced-motion: reduce` the reveal SNAPS the spatial channels to
+ * their endpoints (scale → none, translate → none) and the blur-settle to none —
+ * ZERO transform/blur frames. The OPACITY fade SURVIVES (opacity is not a vestibular
+ * trigger; the surface fades, never flies, never disappears). The fade rides the
+ * short `--duration-fast` clock (the `.glass-top-layer` PRM precedent). */
+@media (prefers-reduced-motion: reduce) {
+    .glass-reveal {
+        scale: none;
+        translate: none;
+        /* The decongest snaps to clear (`filter: blur(0)`); the resting
+           `glass-floating` backdrop-filter plate blur is UNTOUCHED. */
+        filter: blur(0);
+        transition-property: opacity, display, overlay;
+        transition-duration: var(--duration-fast);
+        transition-timing-function: var(--ease-out);
+    }
+    .glass-reveal[data-state="closed"] {
+        scale: none;
+        translate: none;
+        filter: blur(0);
+    }
+}

package/src/styles/glass/rim.css

@@ -0,0 +1,100 @@
+/* glass/rim.css
+   The BB.W-GLASS-ACCENT per-INSTANCE chromatic rim/accent group (the rim-ink +
+   --glass-material-rim ring + the per-rung --glass-border-accent border, light +
+   dark arms).
+   Carved from glass/ladder.css at BB.W-CARVE4 to hold the no-god-module bound (the
+   five-rung surface ladder + the W55 bright-bucket @container + the calm-tier re-point
+   + the contrast-color ink-flip + the opaque escape + the under-shadow modifier + the
+   grain ::after stay in ladder.css). @import-ed by glass.css in cascade order
+   IMMEDIATELY AFTER ladder.css — the SAME @layer components; the rim/accent group is
+   the SOLE writer of --glass-material-rim/--glass-border-accent (the rungs read those
+   + --glass-rim-ink as custom properties resolved at use-time on the SAME elements, so
+   the relocation is cascade-order-invariant), and the W55 bright-bucket is DELIBERATELY
+   kept in ladder.css (relocating it past the contrast-color @supports block would invert
+   their same-specificity source-order tie on supporting engines — a behaviour change the
+   byte-isomorphism bound forbids). The dist is byte-isomorphic. */
+@layer components {
+    /* (b) The unified rim — `--glass-edge-light` full-perimeter inset ring on
+       EVERY material surface (AW.W22). Previously the rim was wired only into
+       the floating/overlay tiers' box-shadow stack; promoting it to the material
+       group makes wash/quiet/resting/card/dock-control all carry the same
+       silhouette catch-light from ONE token. The rim is its OWN `box-shadow`
+       declaration on the material group so it composes uniformly without
+       perturbing each tier's elevation recipe (the floating/overlay tiers drop
+       their now-redundant inline `--glass-edge-light` layer below). The alpha is
+       deliberately low so the rim never eats AA legibility over a busy
+       backdrop. */
+    /* ── BB.W-GLASS-ACCENT — the per-INSTANCE chromatic-RIM tint ───────────────
+       The THIRD disjoint glass axis (LEVEL · TINT · ACCENT). The rim is TWO
+       resolved things — the `--glass-material-rim` inset RING (= `--glass-edge-
+       light`, an inset box-shadow) and the per-rung `--glass-border-*` BORDER —
+       and BOTH must carry the accent hue so the rim reads as ONE accent silhouette,
+       not a half-tinted edge.
+
+       The composition is `color-mix(in oklab, <current rim color>, var(--glass-
+       accent) var(--glass-accent-strength))` — the PERCEPTUAL oklab mix the W55
+       glass-tint seam + the `<IconChip>` chip already speak (NOT in-srgb — the
+       in-srgb fence is the `--surface-tint-*` brand-overlay family, a SEPARATE
+       axis this never touches). At the resting `--glass-accent-strength: 0%` (the
+       `@property` default) + `--glass-accent: transparent` (the neutral identity)
+       the mix resolves byte-identical to today's rim (the W2 no-op floor).
+
+       The RING: a box-shadow value cannot be `color-mix`-ed whole, so the rim ring
+       is REBUILT here as `inset 0 0 0 0.75px <mixed-color>` — the SAME 0.75px inset
+       geometry the `--glass-edge-light` token paints (AV.W15 M3), only its COLOR
+       stop composing the accent. At 0% strength the color resolves to the
+       `--glass-edge-light` base ink (`hsl(0 0% 100% / 0.18)` light / 0.22 dark —
+       read via `--glass-rim-ink`) so the ring is byte-identical to
+       `var(--glass-edge-light)`. The `.dark` arm re-points `--glass-rim-ink` to the
+       dark base so the dark rim composes off `--glass-edge-light-dark`.
+
+       The BORDER: each rung's `border-color` reads `--glass-border-accent`, which
+       composes the accent onto the rung's own `--glass-border-*` ink. The rung
+       borders are re-pointed at their declarations (the `border: 1px solid
+       var(--glass-border-accent)`) so ONE derived token carries the accent across
+       the band; `--glass-border-accent` reads the per-rung `--glass-border-rung`
+       the rung sets locally, mixed with the accent.
+
+       This axis NEVER touches the plate BACKGROUND (the W55 `--glass-tint-source`
+       cohort) — the accent is the rim+glint chromatic DECORATION, not the
+       whole-plate legibility darken (the distinct-axis-not-fork fence). */
+    .glass-material,
+    .glass-wash,
+    .glass-quiet,
+    .glass-resting,
+    .glass-floating,
+    .glass-overlay,
+    .glass-card,
+    .glass-specular-track,
+    .dock-icon-button {
+        /* the resolved rim ring INK (white-α light / lifted-white-α dark — the
+           SAME stop the `--glass-edge-light` token carries; the `.dark` arm below
+           re-points it). The accent mixes ONTO this ink. */
+        --glass-rim-ink: hsl(0 0% 100% / 0.18);
+        --glass-material-rim: inset 0 0 0 0.75px
+            color-mix(in oklab, var(--glass-rim-ink), var(--glass-accent) var(--glass-accent-strength));
+        /* the per-rung border ink, accent-composed. `--glass-border-rung` is set by
+           each rung at its own declaration (it reads the rung's `--glass-border-*`
+           token); the accent mixes onto it so the BORDER half of the rim carries the
+           same hue as the RING. At 0% strength === the un-mixed rung ink. */
+        --glass-border-accent: color-mix(
+            in oklab,
+            var(--glass-border-rung, var(--glass-border)),
+            var(--glass-accent) var(--glass-accent-strength)
+        );
+    }
+    .dark .glass-material,
+    .dark .glass-wash,
+    .dark .glass-quiet,
+    .dark .glass-resting,
+    .dark .glass-floating,
+    .dark .glass-overlay,
+    .dark .glass-card,
+    .dark .glass-specular-track,
+    .dark .dock-icon-button {
+        /* the dark rim ink is the lifted-α base (`--glass-edge-light-dark` stop) so
+           the accent composes off the dark silhouette device (W-DARK-MATERIAL). */
+        --glass-rim-ink: hsl(0 0% 100% / 0.22);
+    }
+
+}

package/src/styles/glass/surface-axis.css

@@ -0,0 +1,113 @@
+/* glass/surface-axis.css — the ONE shared {glass·veil·opaque} surface-decoration
+   axis (BA.W-SURFACE-AXIS).
+
+   The house minted `--glass-level` (the opacity knob, AX.W54) and `--glass-tint-*`
+   (the legibility seam, AX.W55) as SHARED inheriting axes, but left the
+   {glass·veil·opaque} surface-DECORATION choice as a per-component one-off
+   (`<Card>` had the only true axis; `<Dialog>` a binary string; everyone else
+   none). This seam factors that choice ONCE — every enrolled surface composes a
+   base glass tier + the `[data-surface]` attribute, and these rules apply the
+   three-rung decoration UNIFORMLY:
+
+     glass   — the resolved tier's plain glass rung (IDENTITY; no rule needed —
+               the bare tier paints).
+     veil    — the borderless/rimless text-legibility plate: the `--glass-bg-quiet`
+               fill + blur with the box border AND rim STRIPPED (the boxed look
+               reads as a dividing line on a text plate). Reads `--glass-bg-quiet`
+               + the W55 `--glass-tint-*` seam through the SAME `--glass-*` ladder,
+               so `--glass-level` / the bright-bucket darken retune it in lockstep
+               with every glass surface — NO veil-local recipe fork.
+     opaque   — the `--glass-level:0` solid-card escape (the `.glass-opaque` rung):
+               solid `--card` + `blur(0)` through the ONE level knob, the tint axis
+               zeroed (a solid plate has no translucent backdrop to darken-over).
+
+   NO second axis: `cartoon` stays a Card-local decoration (it is NOT a
+   {glass·veil·opaque} member — the shared axis is the three-rung MATERIAL
+   decoration; cartoon rides Card's own `surface` superset). The `Surface` union +
+   the `surfaceClass(surface, tier)` resolver are the TS half
+   (`src/components/ui/_shared/useSurfaceAxis.ts`); this file is the CSS half.
+
+   Cascade: `@layer components`, @import-ed AFTER ladder.css so the attr rules
+   (specificity 0-1-0, equal to the `.glass-*` classes) win by source order over
+   the base rung's border/box-shadow. */
+@layer components {
+    /* ── veil — the borderless text-legibility plate ──────────────────────────
+       Composes the SAME deltas as the `veil-surface` @utility (cards.css), keyed
+       off the SAME `--glass-bg-quiet` + `--glass-tint-*` tokens (no recipe fork).
+       Each delta is an overridable `--veil-*` rung so a consumer re-points the
+       plate to any other ladder rung. */
+    [data-surface="veil"] {
+        --veil-bg: color-mix(
+            in oklab,
+            var(--glass-bg-quiet),
+            var(--glass-tint-source) var(--glass-tint-strength)
+        );
+        --veil-blur: var(--glass-blur-quiet);
+        /* The three veil deltas over a bare rung — each overridable. */
+        --veil-border: none;
+        --veil-shadow: none;
+        --veil-feather: none;
+
+        background: var(--veil-bg);
+        backdrop-filter: var(--veil-blur);
+        -webkit-backdrop-filter: var(--veil-blur);
+        border: var(--veil-border);
+        box-shadow: var(--veil-shadow);
+        /* The optional radial feather — a `mask-image` only painted when
+           `--veil-feather` is set to a gradient (default `none` = no mask = a
+           clean rectangle). `mask-image: none` is the identity. */
+        mask-image: var(--veil-feather);
+    }
+
+    /* ── opaque — the solid-card escape ───────────────────────────────────────
+       The level-0 endpoint of the SAME glass machinery — a solid `--card` plate
+       with `blur(0)`. A surface that ALSO carries a base tier keeps its glass
+       edge/rim/under-shadow (a solid plate with a glass edge, not a bare div).
+
+       THE SUBSTITUTION-VS-INHERITANCE TRAP (the recurring AX.W55 / dock-scale
+       class, live-found in the π readback): the `--glass-bg-*` tier tokens bake
+       `var(--glass-level)` at their `:root` DECLARATION (where level=1), so a
+       DESCENDANT element's `--glass-level: 0` does NOT re-resolve the `:root`-baked
+       `--glass-bg-floating` — the plate stayed translucent (α 0.8, NOT solid). The
+       `.glass-opaque` class works only when `--glass-level` is set at `:root` (the
+       cohesion fixture's pattern); a PER-ELEMENT opaque surface (the whole point of
+       `surface="opaque"`) needs the solid plate composed AT THE ELEMENT. So the
+       opaque rung sets the SOLID `--card` background + `blur(0)` DIRECTLY (the
+       level-0 endpoint resolved here, not via the baked token) — AND still flips the
+       `--glass-level: 0` / `--glass-tint-strength: 0%` knobs so a NESTED glass
+       descendant + any consumer reading the level scalar see the opaque register
+       coherently. The adaptive TINT axis is zeroed (a solid plate has no
+       translucent backdrop to darken-over — the bucket-INVARIANT contract). */
+    [data-surface="opaque"] {
+        --glass-level: 0;
+        --glass-tint-strength: 0%;
+        /* The SOLID --card plate composed at the element via the house color-mix
+           idiom (`--card` over transparent at 0% transparent = fully solid --card)
+           — functionally `var(--card)`, expressed as the cohesion-sanctioned mix
+           the token ladder already speaks. */
+        background: color-mix(in srgb, var(--card), transparent 0%);
+        backdrop-filter: none;
+        -webkit-backdrop-filter: none;
+    }
+
+    /* ── .paper-ink-mark — the PAPER ink-hairline MARK register ────────────────
+       (BA.W-SURFACE-AXIS scope 8). The 2px `--foreground` ink mark on a paper
+       surface — NO plate, NO blur, NO glass. This is a MARK register, NOT a
+       `[data-surface]` plate rung: a `[data-surface]` value DECORATES a glass
+       plate (fill + edge + rim); `.paper-ink-mark` is the opposite — a bare ink
+       hairline drawn directly on paper, the math-paper section-rail / underline-
+       tab vocabulary. Recorded here (the surface-decoration seam) co-located with
+       the plate axis but DISTINCT from it — the canon note is in CLAUDE.md.
+
+       ≥2 consumers at birth: (1) the math-paper section rail (the `border-l-[3px]`
+       family composes it for a VERTICAL left-edge ink rail); (2) W-TABS's re-cut
+       underline indicator (a HORIZONTAL 2px ink mark — W-TABS CONSUMES this seam,
+       a shape gap there triumvirates HERE per the DAG §5 seam rule). The register
+       exposes ONE knob (`--paper-ink-mark-weight`, default 2px) + the ink color;
+       the consumer applies the weight on whichever edge/axis it draws (a left
+       `border-inline-start-width` rail, a bottom `block-size` underline). */
+    .paper-ink-mark {
+        --paper-ink-mark-weight: 2px;
+        --paper-ink-mark-color: var(--foreground);
+    }
+}

package/src/styles/glass/surfaces.css

@@ -18,7 +18,12 @@
         position: relative;
         background: color-mix(in oklab, var(--glass-bg-quiet), var(--glass-tint-source) var(--glass-tint-strength));
         backdrop-filter: var(--glass-blur-quiet);
-        border: 1px solid var(--card-focus-border);
+        /* BB.W-GLASS-ACCENT — the card border feeds its focus-elevation ink into the
+           accent-composed `--glass-border-accent` (ladder.css rim group); byte-
+           identical at 0% strength. The focus rung still re-points `--card-focus-
+           border`, which flows through `--glass-border-rung`. */
+        --glass-border-rung: var(--card-focus-border);
+        border: 1px solid var(--glass-border-accent);
         border-radius: var(--radius-card);
         box-shadow: var(--glass-material-rim), var(--card-focus-shadow);
         /* AY.W-A11Y-PERF O-4 — upgrade `layout style` → include `paint` so the
@@ -43,6 +48,17 @@
 
     /* ── Glassmorphic circular icon button ── */
 
+    /* BA.W-DEMO-AFFORDANCES (IG-A4) — the two size registers below are
+       MUTUALLY EXCLUSIVE; never stack `.glass-btn` and `.btn-pill` on one
+       element. `.glass-btn` is the FIXED-square icon primitive (width/height:
+       var(--size-icon-btn) + contain:paint) — `.btn-pill` is the CONTENT-WIDTH
+       text pill. Stacked, the fixed square wins and contain:paint clips the
+       wrapped label into a ~40px blob (the R8-17 "play button" defect). A
+       text-bearing `.glass-btn` collapses the same way even without `.btn-pill`.
+       For a play/replay affordance reach for <StoryPlayButton> (demo) or a real
+       <Button> with a leading Lucide glyph, never an icon-button carrying text.
+       Machine-locked by proof:demo-affordances (W1 — no class co-occurrence,
+       no text-bearing icon button). */
     .glass-btn {
         @apply flex items-center justify-center cursor-pointer;
 
@@ -72,7 +88,7 @@
             background var(--duration-fast) var(--ease-standard),
             border-color var(--duration-fast) var(--ease-standard),
             color var(--duration-fast) var(--ease-standard),
-            scale var(--duration-normal) var(--spring-smooth);
+            scale var(--spring-smooth-duration) var(--spring-smooth);
     }
 
     .glass-btn:hover:not(:disabled) {
@@ -141,7 +157,7 @@
             box-shadow var(--duration-fast) var(--ease-standard),
             color var(--duration-fast) var(--ease-standard),
             opacity var(--duration-fast) var(--ease-standard),
-            scale var(--duration-fast) var(--spring-smooth);
+            scale var(--spring-smooth-duration) var(--spring-smooth);
     }
 
     .btn-pill > * {
@@ -170,6 +186,96 @@
        dedup-and-keep-prefixed, which modern Chromium then drops). */
     .btn-glass {
         backdrop-filter: var(--glass-blur-btn);
+
+        /* BB.W-BUTTON-GLASS (d) — the button-scoped DEPTH stack + the hover-specular
+           bump. The glass button was the flattest wash rung (a bare backdrop-filter,
+           no rim, no under-shadow) — it read as a tinted rectangle, not a lifted
+           glass lozenge. The `--glass-btn-*` knobs compose ALREADY-MINTED tokens (the
+           `--glass-edge-light` rim + the `quiet`/`resting`-tier `--glass-under-shadow-*`
+           drop) so a consumer retints the whole button depth from ONE override; NO new
+           compositing axis. The rim+under-shadow lifts the lozenge; the box-shadow is
+           additive over the variant's own focus/press shadow legs (the `.btn-pill`
+           transition carries box-shadow on the §6 bezier, so the depth cross-fades
+           coherently). */
+        --glass-btn-rim: var(--glass-edge-light);
+        --glass-btn-under-shadow: var(--glass-under-shadow-quiet);
+        --glass-btn-under-shadow-hover: var(--glass-under-shadow-default);
+        box-shadow: var(--glass-btn-rim), var(--glass-btn-under-shadow);
+        /* The button-scoped hover gleam bump (0.10 → ~0.14): a hovered glass button
+           reads a notch brighter at the grazing edge than the global hover whisper.
+           Token-scoped to `.btn-glass` (NOT the global `:root` cohort property-regs.css
+           owns) so only the button lifts. The active/rest rungs ride the global cohort
+           (the press whisper + the dormant rest). */
+        --glass-specular-intensity-hover: var(--glass-specular-btn-hover);
+    }
+
+    /* The depth deepens one rung on hover (the lifted-lozenge read) — additive over
+       the variant's own hover surface legs. The variants paint the bg/border on
+       hover; this adds the deeper drop. */
+    .btn-glass:hover:not(:disabled, [data-disabled]) {
+        box-shadow: var(--glass-btn-rim), var(--glass-btn-under-shadow-hover);
+    }
+
+    /* BB.W-BUTTON-GLASS (a) — the ELEMENT-LEVEL oklab-tinted hover/active fill pair
+       (the substitution-vs-inheritance trap fixed on the button register). The glass
+       button variants painted `hover:bg-(--glass-bg-resting) active:bg-(--glass-bg-
+       floating)` — the RAW `:root` rung tokens, which carry NO `color-mix(in oklab, …,
+       --glass-tint-source --glass-tint-strength)` wrapper. So the W55 adaptive darken
+       + the `contrast-color()` ink flip + the content-tier floor (all of which the REST
+       bg `.glass-wash` composes via the element-level oklab seam) DROPPED the moment the
+       pointer landed — "more glass would cost legibility" exactly inverted from the
+       iOS-27 ask. These two tokens wrap the raw rungs in the SAME element-level oklab
+       seam `ladder.css` composes for the rest bg + `--glass-bg-dock` for the dock — ZERO
+       new compositing axis, the literal darken-over-light recipe reached at the lit
+       fill. ZERO-delta at the `--glass-tint-strength: 0%`/floor default (the mix toward
+       the source is 0%); under the declared/sampled bright bucket the lit fill darkens
+       to AA in lockstep with the rest bg. The `:root` raw `--glass-bg-*` tokens are
+       UNTOUCHED (other surfaces compose them at the element correctly — the raw token +
+       the element-level oklab wrapper is the correct ladder shape). */
+    .btn-glass {
+        --glass-bg-resting-tinted: color-mix(
+            in oklab,
+            var(--glass-bg-resting),
+            var(--glass-tint-source) var(--glass-tint-strength)
+        );
+        --glass-bg-floating-tinted: color-mix(
+            in oklab,
+            var(--glass-bg-floating),
+            var(--glass-tint-source) var(--glass-tint-strength)
+        );
+    }
+
+    /* BB.W-BUTTON-GLASS (e) — the optional refraction-edge opt-in. CONSUMES the
+       EXISTING refraction axis (glass-refract.css, the `#glass-refract` SVG-filter
+       lens, `@supports (backdrop-filter: url(#…))`-gated with the un-gated blur base
+       as the off-Chromium floor) — NEVER a button-local lens fork. BB.W-LENSING landed
+       the squircle bevel-profile + the typed `--glass-refract` axis + the `.glass-lens`
+       opt-in class (renamed off `.glass-refract`, clean break); the button COMPOSES
+       `.glass-lens`.
+
+       A `<Button :liquid>` adds `.glass-lens` to the host; on a supporting engine the
+       button reads the edge-bend over its blur base. The base recipe (the
+       `@supports`-gated `.glass-lens` rule in glass-refract.css) already paints the
+       displacement filter over `--glass-blur-resting`; this block adds NOTHING to the
+       filter graph (it would fork the axis) — the button merely COMPOSES `.glass-lens`.
+
+       The `:active` LENS-SWELL is the CHEAP coupled read, NOT a per-frame displacement-
+       map re-rasterize (the §Triumvirate / R2 budget: `feDisplacementMap` is resize-
+       expensive — only the `scale` attr animates without rebuilding the map, and even
+       that re-rasterizes; the one-refractive-element-per-route budget forbids the per-
+       frame cost). The swell is the press SQUISH (Button.vue, the `useLiquidFlex`
+       reciprocal X/Y deform) + the coupled `--glass-specular-intensity-active` gleam
+       lift on the SAME `--glass-btn-press-t` drive — the glass reads as DEFORMING under
+       the press without re-rasterizing the lens map. Off-Chromium the whole arm degrades
+       to the un-gated `.btn-glass` blur+tint base (the no-workaround floor). The
+       `--glass-btn-press-t` typed drive (property-regs.css) is the ONE press scalar the
+       squish + the gleam coupling both read. */
+    .btn-glass.glass-lens {
+        /* The press drive scalar (0 rest → 1 pressed) Button.vue writes off the spring;
+           the resting default is 0 so an unwired refraction button is the static lens.
+           The `:active` LENS-SWELL on this drive lives in material.css's `.glass-lens`
+           block (`--glass-refract` bumps on press); this block only floors the drive. */
+        --glass-btn-press-t: 0;
     }
 
     /* ── Pill input ───────────────────────────────── */
@@ -189,16 +295,21 @@
            `:focus-visible` accent ring + the `:user-invalid`/`[aria-invalid]`
            destructive ring below still win by order + specificity.
            AX.W54 — moved off the srgb `--surface-tint-15` fork onto the glass
-           border seam (`--glass-border-floating`, the matching 15%α rung) so the
-           pill is ONE glass model with the rest of the ladder, not a divergent
-           tint axis. */
-        border: 1.5px solid var(--glass-border-floating);
-        background: var(--glass-bg-quiet);
-        /* AX.W54 — the pill reads as REAL glass: the quiet-tier 10px blur (the
-           same `--glass-blur-quiet` its `--glass-bg-quiet` background pairs with),
-           not the sub-perceptual `blur(1px)` wash it carried — and the
-           `--glass-level` knob now clarifies it in lockstep with every surface. */
-        backdrop-filter: var(--glass-blur-quiet);
+           border seam so the pill is ONE glass model with the rest of the ladder.
+           BA.W-SURFACE-AXIS scope 7 — re-pointed onto the SHARED `--control-surface-*`
+           REST register so Input/Textarea/NumberField/Select/Combobox/TagsInput are
+           ONE material at rest (the input rung was the warmer of the two; Select rode
+           the `glass-wash` gray — the no-gray control-family seam). The register reads
+           the same `--glass-*` ladder, so `--glass-level`/the W55 bright bucket retune
+           the whole form family in lockstep (--control-surface-border defaults to the
+           `--glass-border-floating` 15%α rung, --control-surface-bg to `--glass-bg-quiet`,
+           --control-surface-blur to `--glass-blur-quiet`). */
+        border: 1.5px solid var(--control-surface-border);
+        background: var(--control-surface-bg);
+        /* The control's REAL glass blur — the shared register's quiet-tier radius
+           (the same `--control-surface-blur` pairs with `--control-surface-bg`); the
+           `--glass-level` knob clarifies it in lockstep with every surface. */
+        backdrop-filter: var(--control-surface-blur);
         padding: 0 calc(1rem * var(--ui-scale));
         font-size: var(--control-text);
         color: var(--foreground);
@@ -214,6 +325,24 @@
         color: var(--surface-tint-35);
     }
 
+    /* BA.W-SURFACE-AXIS scope 7 — the shared control REST surface class. The
+       NON-pill control families (the Select trigger, the TagsInput root) that do
+       NOT compose `.input-pill` but want the SAME resting material read this — so
+       the whole form band is ONE register at rest (the Select default rode the
+       lighter `glass-wash` gray before; this is the no-gray control-family seam).
+       It carries the bg/border/blur ONLY (each control owns its own height/radius/
+       padding/font), so a non-pill control composes `.control-surface` + its own
+       geometry. The hover lift brightens the fill one step toward the resting rung. */
+    .control-surface {
+        background: var(--control-surface-bg);
+        border: 1px solid var(--control-surface-border);
+        backdrop-filter: var(--control-surface-blur);
+        -webkit-backdrop-filter: var(--control-surface-blur);
+    }
+    .control-surface:hover:not(:disabled, [data-disabled]) {
+        background: var(--control-surface-bg-hover);
+    }
+
     /* AQ.W4 §W4.6 — keyboard-focus ring only. Was bare `:focus` (showed the
        accent ring on a mouse click); `:focus-visible` matches the
        `.focus-ring` / `.glass-btn` / dock-control discipline. Ordered BEFORE
@@ -255,8 +384,11 @@
        invalid field shows the destructive ring on focus too. */
     .input-pill:where(:user-invalid, .user-invalid-fallback, [aria-invalid="true"]):focus-visible {
         border-color: var(--destructive);
-        box-shadow: 0 0 0 var(--focus-ring-width)
-            color-mix(in srgb, var(--destructive) 35%, transparent);
+        /* BB.W-INVALID-RING — the shared destructive ring register (the
+           --focus-ring-shadow sibling). The byte-identical recipe is now ONE
+           token; the `8%` at-rest bg arm above stays `.input-pill`-local (a
+           glass-tint substrate the bare-ring surfaces do not carry). */
+        box-shadow: var(--invalid-ring);
     }
 
     /* AQ.W4 §W4.3 — `field-sizing: content` autosize (opt-in via the Textarea
@@ -291,6 +423,48 @@
         border-color: var(--surface-tint-15);
     }
 
+    /* ── BA.W-PAGER — the glass pager pill chassis (.glass-pager-ring) ──────────
+       The ONE pager-CHASSIS ring register: a `--radius-pill` glass-floating pill
+       (the DockRail-chip recipe — `--glass-bg-floating` + `--glass-blur-floating`
+       + `--glass-edge-light`/`--glass-specular` + the soft drop + the `.dark`
+       box-shadow arm). It encapsulates BOTH the `<PagerDots ring>` dot rail AND
+       the `<CarouselPager>` counter (the counter re-registers OFF the opaque
+       `bg-card` slab onto this — the R9/R10-5 dark-slab class dies in the same
+       edit). NEVER an opaque `bg-card` plate: this is the house "controls in a
+       glass pill" idiom, translucent (reads the substrate through it), already
+       dark/light-safe, already specular-rimmed (≥2-consumer-proven on the dock
+       rail-extend chips + the dock collapsed pill). The legibility floor over the
+       carousel's image content rides the SAME rebuilt registers
+       (W-DARK-MATERIAL/W-NO-GRAY) — no local opaque fallback. */
+    .glass-pager-ring {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.375rem;
+        padding-inline: 0.625rem;
+        padding-block: 0.3125rem;
+        border-radius: var(--radius-pill);
+        background: var(--glass-bg-floating);
+        backdrop-filter: var(--glass-blur-floating);
+        -webkit-backdrop-filter: var(--glass-blur-floating);
+        box-shadow:
+            var(--glass-edge-light),
+            var(--glass-specular),
+            0 2px 6px -2px color-mix(in srgb, var(--shadow-color) 22%, transparent);
+        /* §6 EASING DOCTRINE — the surface channel cross-fades on the bezier
+           `--ease-standard` (NEVER a spring; a surface prop on a spring is the
+           violation). */
+        transition:
+            background-color var(--duration-fast) var(--ease-standard),
+            box-shadow var(--duration-fast) var(--ease-standard),
+            border-color var(--duration-fast) var(--ease-standard);
+    }
+    .dark .glass-pager-ring {
+        box-shadow:
+            var(--glass-edge-light-dark),
+            var(--glass-specular-dark),
+            0 2px 6px -2px color-mix(in srgb, var(--shadow-color) 30%, 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