@mkbabb/glass-ui 3.13.0 → 4.0.0

package/dist/styles/dock.css

@@ -41,6 +41,7 @@
 @import "./dock/layer-group.css";
 @import "./dock/overflow.css";
 @import "./dock/rail-extend.css";
+@import "./dock/section.css";
 @import "./dock/morph-bridge.css";
 
 /* AX.W01 — the SINGLE morph scalar. `useLayerTransition` writes it once per frame
@@ -81,10 +82,12 @@
         --dock-motion-fast: var(--duration-fast) var(--ease-standard);
         --dock-motion-standard: var(--duration-normal) var(--ease-standard);
         /* AT.W6-dock-c — the FLIP-fallback timing. `--dock-resize-spring` (the
-           `--spring-snappy` linear()) is the single source curve the native
+           `--spring-dock` linear()) is the single source curve the native
            View-Transition path ALSO consumes, so the morph is timing-identical
-           across engines. */
-        --dock-motion-resize: var(--duration-normal) var(--dock-resize-spring);
+           across engines. BA.W-GLASS-CAL Unit 3 — the duration leg re-times off
+           the generic `--duration-normal` (0.3s) onto `--spring-dock-duration`
+           (0.28s, the dock spring's OWN 2%-band envelope settle). */
+        --dock-motion-resize: var(--spring-dock-duration) var(--dock-resize-spring);
     }
 
     /* Shared four-state contract — the focus-visible ring + disabled paint are

package/dist/styles/drawer.css

@@ -60,6 +60,52 @@
     box-shadow: var(--glass-material-rim), var(--glass-shadow-overlay);
 }
 
+/*
+ * BA.W-SURFACE-AXIS — the shared {glass·veil·opaque} surface decoration ON TOP of
+ * the `.glass-drawer` recipe. `.glass-drawer` is UNLAYERED (this file), so the
+ * `@layer components` `[data-surface]` seam in glass/surface-axis.css would LOSE
+ * to it (an unlayered rule always beats a layered one — the AZ.W-DOCK-RAIL
+ * cascade-win trap). The fix is the SAME-LAYER carve: these `.glass-drawer[data-
+ * surface=…]` rules sit unlayered alongside `.glass-drawer` and win by specificity
+ * (attr+class > class), composing the SAME veil/opaque deltas the shared seam
+ * declares — NO `glass-drawer`-local recipe fork (they read the same `--veil-*` /
+ * `--glass-level` machinery). The `glass` rung is the identity (no rule).
+ */
+.glass-drawer[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);
+    background: var(--veil-bg);
+    -webkit-backdrop-filter: var(--veil-blur);
+
+    backdrop-filter: var(--veil-blur);
+    -webkit-backdrop-filter: var(--veil-blur);
+    border: none;
+    box-shadow: none;
+}
+
+.glass-drawer[data-surface="opaque"] {
+    /* The solid-card escape. The `.glass-drawer` background reads the `:root`-baked
+       `--glass-bg-overlay` token (which substitutes `--glass-level` at :root), so a
+       per-element `--glass-level: 0` cannot re-resolve it — the substitution-vs-
+       inheritance trap (mirrors surface-axis.css). Set the SOLID plate AT THE
+       ELEMENT; still flip the level/tint knobs for a nested glass descendant. */
+    --glass-level: 0;
+    --glass-tint-strength: 0%;
+    /* The SOLID --card plate via the house color-mix idiom (solid --card, expressed
+       as the cohesion-sanctioned mix the token ladder speaks — NOT the bare
+       `var(--card)` the cohesion D1 check forbids for the always-on drawer plate;
+       this is the EXPLICIT opt-out behind `surface="opaque"`, not the default). */
+    background: color-mix(in srgb, var(--card), transparent 0%);
+    -webkit-backdrop-filter: none;
+
+    backdrop-filter: none;
+    -webkit-backdrop-filter: none;
+}
+
 /*
  * Detented (snap-point) sheets fill the viewport height. vaul positions the
  * sheet by translating it DOWN by `innerHeight - (fraction * innerHeight)` —

package/dist/styles/feedback-tone.css

@@ -0,0 +1,104 @@
+/* feedback-tone.css — the ONE shared tinted-glass tone recipe (BA.W-FEEDBACK-TONE).
+
+   THE COLLAPSE: Toast, Notification, and Alert each carried an INDEPENDENT tone map
+   (the Toast variant map painted SOLID `bg-{success,warning,info,destructive}` opaque
+   token plates over a `glass-floating` base; the Notification type map painted
+   `bg-<tone>/90` near-opaque slabs; Alert alone was correct in SHAPE — glass-wash plate
+   + tone-on-rim — but HARDCODED its `border-<tone>/40` rim per variant). Three tone
+   maps, three calibration sites, and TWO of them painted a colored SLAB that occluded
+   the backdrop (the R8-12/R8-13 "not glassy at all" defect; the blur track survived but
+   was inert behind a 100%-opaque plate).
+
+   This file mints the tone register ONCE. Every feedback tone reads as COLORED GLASS:
+   a tinted-glass wash (the rung bg mixed a BOUNDED % toward the tone, the SAME
+   `color-mix(in oklab, <rung bg>, <tint> <strength>)` seam the W55 `--glass-tint-*`
+   legibility lift and the `--veil-bg` plate already run — ZERO new compositing path) +
+   a tone-keyed rim + a full-chroma glyph. The backdrop STILL shows through (α stays
+   translucent, the W2 π floor < ~0.92). The body ink stays `--foreground` /
+   `--card-foreground` for legibility (the Alert discipline — body never tone-tinted),
+   so the tone is ONE deliberate color event per surface (the AZ.W-SUFFUSE one-color-
+   event idiom), never a full-bleed fill.
+
+   THE ONE KNOB: `--feedback-tone-strength` tints all four tones at once (the bounded
+   mix %, the toast-glass §A band). The four tone hues map to the HOUSE tokens
+   `--success` / `--warning` / `--info` / `--destructive` (presets-in-consumers — NO new
+   colors). A consumer recalibrates the tone weight with ONE override.
+
+   THE RUNG: the register reads `--feedback-tone-rung` (default the floating-chrome rung
+   `--glass-bg-floating`, the Toast/Notification overlay register). Alert RE-POINTS it to
+   `--glass-bg-wash` on its own surface (a content panel rides wash, not floating — the
+   register difference is correct; only the tone SOURCE unifies, not the rung). The rung
+   reads `--glass-bg-*` DIRECTLY (the same tokens W-SURFACE-AXIS's glass arm routes), so
+   the tone tint rides ON the glass surface — a re-point, not a fork.
+
+   THE SUBSTITUTION TRAP (the recurring AX.W55 / dock-scale class): `--feedback-tone-rung`
+   resolves the `--glass-bg-floating` token, which BAKES `var(--glass-level)` at its
+   `:root` declaration (level=1). A descendant `--glass-level: 0` does NOT re-resolve the
+   baked rung — but that is the CORRECT register here: a feedback surface IS translucent
+   glass by design; the `opaque`/level-0 escape is W-SURFACE-AXIS's `[data-surface]`
+   concern, not a tone-register knob. The tone register composes the tint AT THE ELEMENT
+   off the resolved rung, so the `color-mix` re-resolves whenever `--tone`/`--feedback-
+   tone-strength`/the rung change (the W55 element-level tint discipline). */
+@layer components {
+    :root {
+        /* The bounded mix % — the tone wash strength. 18% reads as colored GLASS
+           (the backdrop shows through, the silhouette is unmistakably tinted) without
+           tipping toward a slab; the toast-glass §A band is ≈12–22%. ONE knob retunes
+           all four tones. */
+        --feedback-tone-strength: 18%;
+        /* The rung the tint mixes over — the floating-chrome register (Toast /
+           Notification). Alert re-points it to the wash rung on its own surface. */
+        --feedback-tone-rung: var(--glass-bg-floating);
+        /* The rim weight — a tone-keyed border, a thin tinted rim (not a loud edge). */
+        --feedback-tone-border-strength: 40%;
+    }
+
+    /* ── The parametric register ──────────────────────────────────────────────────
+       A surface declares `--tone` (one of the four house tokens) + composes
+       `.feedback-tone`; the tinted-glass wash + the tone-keyed rim resolve off the ONE
+       recipe. The glyph carries the FULL-chroma tone (`[&>svg]` via the consumer's own
+       class, or the `.feedback-tone-glyph` helper below). The `default` (un-toned)
+       surface simply omits `.feedback-tone` — the bare glass rung paints.
+
+       `--tone` has NO `:root` default ON PURPOSE: a `.feedback-tone` surface with no
+       `--tone` set would mix the rung toward `initial` (transparent) — a no-op wash, the
+       same as the bare rung; this is the safe degenerate, not a paint bug. Every real
+       consumer sets `--tone` via its `.feedback-tone-<name>` register. */
+    .feedback-tone {
+        background: color-mix(
+            in oklab,
+            var(--feedback-tone-rung),
+            var(--tone) var(--feedback-tone-strength)
+        );
+        border-color: color-mix(
+            in oklab,
+            transparent,
+            var(--tone) var(--feedback-tone-border-strength)
+        );
+    }
+
+    /* The four house tone registers — each binds `--tone` to its house token. A surface
+       maps its variant/type onto the matching class (Toast `variant` /
+       Notification `type` / Alert `variant`); the `error` notification type maps to the
+       destructive tone (the three-maps-into-one collapse — `error` IS destructive). */
+    .feedback-tone-success {
+        --tone: var(--success);
+    }
+    .feedback-tone-warning {
+        --tone: var(--warning);
+    }
+    .feedback-tone-info {
+        --tone: var(--info);
+    }
+    .feedback-tone-destructive {
+        --tone: var(--destructive);
+    }
+
+    /* The glyph helper — the leading status glyph carries the FULL-chroma tone (the one
+       color event's saturated note over the tinted wash). A consumer composes it on its
+       icon, or reads `var(--tone)` directly in an arbitrary `[&>svg]:text-(--tone)`
+       utility. */
+    .feedback-tone-glyph {
+        color: var(--tone);
+    }
+}

package/dist/styles/glass/ladder.css

@@ -141,6 +141,13 @@
         .glass-card {
             --glass-tint-source: var(--glass-tint-ink);
             --glass-tint-strength: var(--glass-tint-strength-aa);
+            /* BA.W-DARK-MATERIAL scope 7 — the --muted-foreground lift moves HERE, into the
+               declared/sampled BRIGHT condition. The muted L40 tier cannot clear 4.5:1 on a
+               translucent FULL-AA-darkened plate (darkening moves the plate toward muted's
+               own luminance), so it lifts to the full ink ONLY where the plate actually
+               darkens — NOT on the calm-light unconditional floor (where it stays the muted
+               register, the slides caption read). */
+            --muted-foreground: var(--foreground);
         }
     }
 
@@ -182,19 +189,35 @@
        TOWARD muted's own luminance), so the low-contrast muted register resolves to
        the legible dark ink (clears ~10:1) — a token re-point on the same inheriting
        axis as the tint. */
-    :where(
-            .glass-floating,
-            .glass-overlay,
-            .glass-card,
-            .glass-resting,
-            .glass-quiet,
-            .glass-wash
-        ) {
+    /* The OVERLAY band (.glass-floating/.glass-overlay — Dialog/Sheet/Popover/DropdownMenu/
+       HoverCard/Command/Tooltip/Toast/Select-content) keeps the FULL unconditional AA darken
+       + the muted lift: it floats over WHATEVER the consumer painted (frequently a light/
+       near-white app surface — the canonical G2 case), so darkening toward the warm-ink is
+       the correct DEFAULT over an UNKNOWN surface. Over a DARK page this becomes the
+       luminous-dark LIFT (the dark-arm re-tunes --glass-tint-strength-aa to 12% — the plate
+       lifts off the deep page). A dark-substrate consumer who wants the pristine plate sets
+       `--glass-tint-strength: 0%`. */
+    :where(.glass-floating, .glass-overlay) {
         --glass-tint-source: var(--glass-tint-ink);
         --glass-tint-strength: var(--glass-tint-strength-aa);
         --muted-foreground: var(--foreground);
     }
 
+    /* BA.W-DARK-MATERIAL scope 7 — the plain CONTENT tiers self-engage the SUB-PERCEPTUAL
+       FLOOR unconditionally, NOT the full AA darken (the R9-1 slides gray-slab fix). Over a
+       calm LIGHT page the floor (--glass-tint-strength-floor: 4%) is a silhouette whisper —
+       the translucent cream card stays warm (L ≈ 0.94), no gray slab. Over a DARK page the
+       floor re-resolves to the luminous-dark lift (12% in the dark arm — the plate lifts off
+       the deep page, the desired register). The FULL AA darken engages on these tiers ONLY
+       under the declared/sampled BRIGHT signal (the @container --glass-backdrop:light bucket
+       above — where the muted lift also lives now). NO unconditional --muted-foreground lift
+       here: on the calm-light floor the caption keeps the muted register (the slides read).
+       A consumer opts a light-page card out via `--glass-tint-strength: 0%` on an ancestor. */
+    :where(.glass-card, .glass-resting, .glass-quiet, .glass-wash) {
+        --glass-tint-source: var(--glass-tint-ink);
+        --glass-tint-strength: var(--glass-tint-strength-floor);
+    }
+
     /* AX.W55 — the `contrast-color()` foreground-ink flip (Chrome 147+/Safari 26+).
        A PROGRESSIVE-ENHANCEMENT layer, NEVER the load-bearing floor (Open-Q #5
        ratified): the declarative bucket above already carries AA on ALL engines (it
@@ -207,6 +230,20 @@
        white, illegible on the still-light translucent plate). The bucket is the floor;
        this is the native refinement. Scoped to the bright bucket. */
     @supports (color: contrast-color(white)) {
+        /* The bright-bucket ink flip — the content tiers + overlay band over a DECLARED/
+           sampled bright backdrop. BA.W-DARK-MATERIAL scope 6 — the SYSTEMIC contrast-color()
+           selection-inversion fix (approach A, lockstep-lift). At HEAD this block lifted only
+           --muted-foreground (and the surface `color`) to contrast-color(--card) (white over
+           a light plate, L100), but the ACTIVE control register (a SegmentedTabs active tab,
+           the curve-picker selected label) reads var(--foreground) DIRECTLY (L90, un-lifted) —
+           a control sets its OWN `color: var(--foreground)` which wins over the inherited
+           surface `color`, so the inactive (muted→white) read BRIGHTER than the active
+           (--foreground), inverting selection. The fix lifts --foreground ITSELF in lockstep
+           with --muted-foreground: now an active register reading --foreground resolves the
+           SAME anchored contrast-color ink as the lifted inactive, so selected ≥ unselected
+           everywhere (the inversion gone for ANY --muted-foreground/--foreground selection
+           pairing inside a glass card — the SYSTEMIC library-seam fix, not a curve-picker
+           one-off). Progressive enhancement only — the declarative darken is the AA floor. */
         @container style(--glass-backdrop: light) {
             .glass-material,
             .glass-wash,
@@ -216,25 +253,26 @@
             .glass-overlay,
             .glass-card {
                 color: contrast-color(var(--card));
+                --foreground: contrast-color(var(--card));
+                --muted-foreground: contrast-color(var(--card));
             }
         }
-        /* AY.W-A11Y-PERF O-1 / AZ.W-ADAPTIVE-AUTO Arm 1 — the same contrast-color
-           refinement for the SELF-ENGAGED band + content tiers (the @container block
-           above queries an ancestor; these surfaces engage their own tint
-           unconditionally, so their ink-flip companion mirrors that). The muted
-           register flips to the same anchored dark ink. Progressive enhancement only
-           — the declarative darken above is the AA floor on all engines. */
-        :where(
-                .glass-floating,
-                .glass-overlay,
-                .glass-card,
-                .glass-resting,
-                .glass-quiet,
-                .glass-wash
-            ) {
+        /* The OVERLAY band self-engages the darken UNCONDITIONALLY (it floats over an
+           UNKNOWN consumer surface), so its ink-flip companion mirrors that — UNCONDITIONAL.
+           --foreground lifts in lockstep with --muted-foreground (the scope-6 lockstep). */
+        :where(.glass-floating, .glass-overlay) {
             color: contrast-color(var(--card));
+            --foreground: contrast-color(var(--card));
             --muted-foreground: contrast-color(var(--card));
         }
+        /* BA.W-DARK-MATERIAL scope 7 — the content-tier ink flip is GATED on the bright
+           signal (it moved INTO the @container bucket above), NOT unconditional. Over a calm
+           LIGHT page the content tiers only carry the 4% silhouette floor (still a warm cream
+           plate), so flipping the ink to the contrast-color DARK ink there is correct only
+           where the plate ACTUALLY darkens to the bright-bucket AA — the unconditional flip
+           would force a white-on-cream / dark-on-darkened mismatch on the calm card. The
+           content tiers therefore take NO unconditional contrast-color flip; their flip lives
+           in the @container bucket with the rest of the bright-condition darken. */
     }
 
     /* ── The opaque escape (AX.W54) ───────────────────
@@ -248,6 +286,14 @@
        a consumer that wants a flat surface). */
     .glass-opaque {
         --glass-level: 0;
+        /* BA.W-DARK-MATERIAL scope 7 — the opaque escape suppresses the adaptive TINT axis
+           too (not just the opacity/blur level). A solid opaque plate has no translucent
+           backdrop to darken-over, so the self-engage tint is meaningless on it; zeroing the
+           strength keeps the opaque escape bucket-INVARIANT (the unset floor and the bright
+           bucket resolve the SAME solid plate — the byte-identity canary). Without this, the
+           scope-7 unconditional content-tier floor (4%) tinted even the solid plate, breaking
+           the opt-out's "flat surface" contract. */
+        --glass-tint-strength: 0%;
     }
 
     /* ── Content-aware under-shadow modifier (AV.W15 M4) ──────────────

package/dist/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/dist/styles/glass/surfaces.css

@@ -43,6 +43,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 +83,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 +152,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 > * {
@@ -189,16 +200,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 +230,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
@@ -291,6 +325,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

package/dist/styles/glass.css

@@ -40,11 +40,14 @@
  * docs/precepts/design-idioms.md §cohesion-aware partials.
  */
 
-/* CSS @import rules must precede every other rule. The six partials @import in
-   cascade order: */
+/* CSS @import rules must precede every other rule. The seven partials @import in
+   cascade order (surface-axis.css AFTER ladder/surfaces so its [data-surface]
+   decoration attr rules win over the base rung by source order; BEFORE the
+   squircle + a11y @supports overrides, which must stay last): */
 @import "./glass/material.css";
 @import "./glass/ladder.css";
 @import "./glass/surfaces.css";
+@import "./glass/surface-axis.css";
 @import "./glass/progress-rail.css";
 @import "./glass/squircle.css";
 @import "./glass/a11y-fallback.css";