@mkbabb/glass-ui 4.2.0 → 6.0.0

package/src/styles/accessibility.css

@@ -0,0 +1,48 @@
+/* Terminal accessibility cascade: adaptations replace the completed product
+   paint instead of competing with later component rules. */
+@import "./glass/a11y-fallback.css";
+@import "./utilities/a11y-overrides.css";
+
+/* Selection and validation keep a non-hue boundary when contrast is requested.
+   The system-color arm yields fully to the user's forced palette. */
+@media (prefers-contrast: more) {
+    :is(
+        [aria-current]:not([aria-current="false"]),
+        [aria-selected="true"],
+        [aria-pressed="true"],
+        [aria-checked="true"],
+        [data-state="checked"],
+        [data-state="on"]
+    ) {
+        border-color: currentColor !important;
+        border-style: solid !important;
+        border-width: 2px !important;
+    }
+
+    :is([aria-invalid="true"], :user-invalid) {
+        border-color: var(--destructive) !important;
+        border-style: solid !important;
+        border-width: 2px !important;
+    }
+}
+
+@media (forced-colors: active) {
+    :is(
+        [aria-current]:not([aria-current="false"]),
+        [aria-selected="true"],
+        [aria-pressed="true"],
+        [aria-checked="true"],
+        [data-state="checked"],
+        [data-state="on"]
+    ) {
+        border-color: Highlight !important;
+        border-style: solid !important;
+        border-width: 2px !important;
+    }
+
+    :is([aria-invalid="true"], :user-invalid) {
+        border-color: Mark !important;
+        border-style: solid !important;
+        border-width: 2px !important;
+    }
+}

package/src/styles/animations.css

@@ -1,18 +1,7 @@
 /* Shared @keyframes — global animations used across projects */
 
-/* ── Floating panel entrance ── */
-@keyframes floating-panel-in {
-    from {
-        opacity: 0;
-        filter: blur(4px);
-        scale: 0.96;
-    }
-    to {
-        opacity: 1;
-        filter: blur(0);
-        scale: 1;
-    }
-}
+/* (BI.W-GLASS-DEDUP — the `floating-panel-in` entrance @keyframes retired with
+   floating-panel.css / `--animate-floating-panel-in`; FAM-9 clean break.) */
 
 /* ── Collapsible (reka-ui) ── */
 @keyframes collapsible-open {
@@ -301,6 +290,57 @@
     }
 }
 
+/* ── .glass-reveal EXIT (BG.W-OVERLAY-ENTER-PAINT / F5.R1) ──────────────────
+ *
+ * The reka-portaled-overlay (Dialog/Popover/DropdownMenu/…) EXIT MUST be a
+ * @keyframes animation, NOT a CSS transition. reka-ui's `usePresence` gates the
+ * unmount on `getComputedStyle(node).animationName`: it dispatches ANIMATION_OUT
+ * and awaits `animationstart`/`animationend`, with NO `transitionend` path — so a
+ * transition-only exit is torn down (~11ms, <1 frame) before it can paint (the
+ * paint-judge FAIL: Dialog+Popover exit painted 0 frames). The Sheet exit paints
+ * only because its `sheet-animate` (`animate-out`) is a keyframe reka can await;
+ * this gives the `.glass-reveal` recipe (glass/reveal.css) the SAME kind.
+ *
+ * `glass-reveal-out` is the enter bloom REVERSED: scale 1 → (0.88 × squish),
+ * opacity 1 → 0, filter blur(0) → blur — the SAME three coupled channels, on the
+ * no-overshoot `--ease-out` clock (a closing surface must never overshoot past
+ * gone, §6/W-MOTION-CANON P2). NO `translate` (the base/Dialog has none; a side
+ * popover's slide-out stays a transition — a different property that coexists,
+ * never clobbering a center Dialog's `-translate-x-1/2 -translate-y-1/2`). The
+ * `to` values MIRROR the `.glass-reveal[data-state="closed"]` static end-state so
+ * a non-supporting engine still lands correctly. Compositor-only (scale/opacity/
+ * filter — the proof:no-layout-animation floor). The custom-property `var()`s
+ * resolve on the animated `.glass-reveal` element (they are declared on its base
+ * rule). */
+@keyframes glass-reveal-out {
+    from {
+        scale: 1 1;
+        opacity: 1;
+        filter: blur(0);
+    }
+    to {
+        scale: calc(var(--glass-reveal-enter-scale, 0.88) * var(--lq-stretch-x, 1.06))
+            calc(var(--glass-reveal-enter-scale, 0.88) * var(--lq-stretch-y, 0.945));
+        opacity: 0;
+        filter: blur(var(--glass-reveal-blur, 4px));
+    }
+}
+
+/* The reduced-motion EXIT — fade ONLY (no transform/blur frames, the vestibular
+ * floor, WCAG 2.3.3). Still a keyframe reka can await (a transition-only fade
+ * would be torn down the same way, and the surface would vanish rather than fade),
+ * so the fade PAINTS under `prefers-reduced-motion: reduce`. The reveal.css PRM
+ * carve swaps `animation-name` to this while snapping scale/translate/filter to
+ * their endpoints. */
+@keyframes glass-reveal-out-reduced {
+    from {
+        opacity: 1;
+    }
+    to {
+        opacity: 0;
+    }
+}
+
 /* ── §TOP-LAYER ENTRY/EXIT (AQ.W5 §Design 2) ───────────────────────────────
  *
  * A pure-CSS entry/exit grammar for NATIVE top-layer surfaces — `[popover]`
@@ -342,16 +382,21 @@
            leg, glass/reveal.css). */
         filter: blur(var(--top-layer-enter-blur, 4px));
         transition-property: opacity, scale, filter, display, overlay;
-        /* BA.W-GLASS-CAL Unit 3 — the enter rides the bouncy spring's OWN settle
-           clock (`--spring-bouncy-duration`, the 2%-band envelope settle) rather
-           than the generic `--duration-normal`, so the emphatic dialog/popover
-           entrance bounce reads fully instead of being clipped at 0.3s. The blur
-           decongest rides the no-overshoot `--ease-out` (EFFECTS), the scale the
-           bouncy spring (SPATIAL) — the W-MOTION-CANON split. */
-        transition-duration: var(--spring-bouncy-duration),
-            var(--spring-bouncy-duration), var(--spring-bouncy-duration),
-            var(--spring-bouncy-duration), var(--spring-bouncy-duration);
-        transition-timing-function: var(--spring-bouncy), var(--spring-bouncy),
+        /* BI.W-REGISTER-TABLE — the FOURTH register RETIRED: the native `.glass-top-layer`
+           @starting-style enter is FOLDED onto the `enter-overlay` register bundle (the
+           SAME register the reka portaled overlays ride via `.glass-reveal` — one enter
+           grammar, no fourth recipe). It gains the register CLOCK (`--enter-overlay-clock`
+           = the parity-fixed --spring-snappy-duration) + spring (`--enter-overlay-spring`);
+           the scale/blur re-point to the register via the `--top-layer-enter-*` tokens
+           (scroll-tokens.css). The prior BA.W-GLASS-CAL bouncy-own-clock is superseded —
+           the native dialog/popover enter now matches the reka Dialog enter. The blur
+           decongest keeps the no-overshoot `--ease-out` (EFFECTS), the scale the register
+           spring (SPATIAL) — the W-MOTION-CANON split. HoverPopover (the live consumer)
+           re-points onto the register by inheriting the folded recipe. */
+        transition-duration: var(--enter-overlay-clock),
+            var(--enter-overlay-clock), var(--enter-overlay-clock),
+            var(--enter-overlay-clock), var(--enter-overlay-clock);
+        transition-timing-function: var(--enter-overlay-spring), var(--enter-overlay-spring),
             var(--ease-out), linear, linear;
         transition-behavior: allow-discrete;
     }
@@ -393,6 +438,20 @@
             var(--background) calc(var(--top-layer-backdrop-dim, 0.5) * 100%),
             transparent
         );
+        /* SCRIM COUPLES TO LAUNCH (BG.W-OVERLAY-ENTER-PAINT / F5.R1) — the ENTER dim
+           rides its OWN launch-coupled clock (`--top-layer-backdrop-in`, a fast
+           no-overshoot `--ease-out`) so the scrim reaches ≥80% of its target dim
+           within ~100ms of launch, coupled to the panel window rather than trailing
+           the panel on the slower `--duration-normal`/`--ease-standard` clock (the
+           HEAD defect: the scrim decoupled + dimmed over ~400ms AFTER the panel
+           seated). This ENTER transition is read from the [open] after-change state;
+           the base `::backdrop` transition stays the EXIT clock — released cleanly
+           WITH the panel, no overshoot past gone. The `@starting-style` from-state
+           makes the dim interpolate from transparent (the discrete allow-discrete
+           display/overlay legs stay). */
+        transition: display var(--top-layer-backdrop-in, 0.15s) allow-discrete,
+                    overlay var(--top-layer-backdrop-in, 0.15s) allow-discrete,
+                    background-color var(--top-layer-backdrop-in, 0.15s) var(--ease-out);
         @starting-style {
             background-color: color-mix(in srgb, var(--background) 0%, transparent);
         }

package/src/styles/draw-in.css

@@ -0,0 +1,89 @@
+/* draw-in.css
+   BI.W-DRAW-IN — the codified self-drawing arrival register (D-MOTION PASS-1 §2.4;
+   SUFFUSION-MAP R21). ONE named law for a hairline / divider / underline that DRAWS
+   ITSELF in — `.draw-rule` / `[data-draw-in]`.
+
+   THE LAW: a rule drawing itself NEVER overshoots past full width. Draw-in is a
+   SPATIAL channel on the NO-OVERSHOOT arrival ease `--ease-out-expo` (REUSED from the
+   §6 easing table, scheme-spring.css — never re-minted; a duplicate alias reds
+   proof:animation-coherence), categorically NOT a spring. This closes UF-G6 ("refined
+   drawing animations … codify this to not be ad-hoc … the divider draw-in is a bit
+   too bouncy. Needs smoothing.") — the ad-hoc masthead divider rode `--ease-cartoon-
+   punch` (+22% overshoot); it re-points onto this register (a rule that strikes past
+   its own end and springs back reads as jitter, not craft).
+
+   Compositor-only: the draw rides `transform: scaleX()` (the DEFAULT) OR a `clip-path:
+   inset()` wipe — NEVER `width`/`inline-size` (proof:no-layout-animation holds by
+   construction; proof:draw-in asserts the keyframes touch no reflow prop).
+
+   The clock is `--draw-in-duration = calc(<base> * var(--motion-tempo))` — the tuned
+   masthead-strike base (0.52s) co-scaled by the ONE governing `--motion-tempo` axis
+   (property-regs.css §M11) so draw-in tightens/loosens in lockstep with every other
+   motion clock (P7 one-clock). The direction anchors at the drawing edge via
+   `--draw-in-origin` (default `left`); a delay stages a strike via `--draw-in-delay`.
+
+   PRM: the base rule paints the rule at rest (`scaleX(1)` / no clip) and the animation
+   engages ONLY under `prefers-reduced-motion: no-preference`, so under reduce (and on a
+   gap engine) the rule is STATIC — the opacity is kept, `scaleX` snaps to 1, zero
+   motion frames.
+
+   The register NAMES the shared arrival law; it does NOT re-author the two hero-scale
+   draw MEMBERS — CompletionSeal's gold `--seal-draw` stroke-dashoffset wipe and
+   HandMark's `draw-on` (dashoffset / clip-path) both keep their OWN recipes; they are
+   recorded as members (the ≥2-consumer evidence) in
+   docs/tranches/BI/audit/W-DRAW-IN-REGISTER.md. */
+
+:root {
+    /* The draw-in clock — a hairline draws itself in <base> × tempo. */
+    --draw-in-duration: calc(0.52s * var(--motion-tempo));
+}
+
+/* The scaleX draw (the DEFAULT) — a rule grows from its anchored edge to full width. */
+@keyframes draw-rule-in {
+    from {
+        transform: scaleX(0);
+    }
+    to {
+        transform: scaleX(1);
+    }
+}
+
+/* The clip-path wipe (the opt-in alternate — `.draw-rule--wipe` / `[data-draw-in="wipe"]`).
+   For a rule whose own transform is load-bearing (it cannot spend `scaleX`), the reveal
+   rides a compositor-safe `clip-path: inset()` wipe on the SAME expo arrival. */
+@keyframes draw-rule-wipe {
+    from {
+        clip-path: inset(0 100% 0 0);
+    }
+    to {
+        clip-path: inset(0 0 0 0);
+    }
+}
+
+/* The RESTING rule — painted at full width. This is the static fallback on a gap engine
+   AND the PRM (reduce) end-state (the animation engages only under no-preference, so
+   under reduce the rule simply reads at scaleX(1), no motion frames). */
+.draw-rule,
+[data-draw-in] {
+    transform-origin: var(--draw-in-origin, left);
+    transform: scaleX(1);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+    /* The scaleX draw — the DEFAULT register (everything that is NOT the wipe opt-in). */
+    .draw-rule:not(.draw-rule--wipe),
+    [data-draw-in]:not([data-draw-in="wipe"]) {
+        transform: scaleX(0);
+        animation: draw-rule-in var(--draw-in-duration) var(--ease-out-expo)
+            var(--draw-in-delay, 0s) both;
+    }
+
+    /* The clip-path wipe opt-in. */
+    .draw-rule--wipe,
+    [data-draw-in="wipe"] {
+        transform: none;
+        clip-path: inset(0 100% 0 0);
+        animation: draw-rule-wipe var(--draw-in-duration) var(--ease-out-expo)
+            var(--draw-in-delay, 0s) both;
+    }
+}

package/src/styles/glass/a11y-fallback.css

@@ -35,6 +35,12 @@
         --glass-level: 0.3;
         --glass-tint-source: var(--glass-tint-ink);
         --glass-tint-strength: var(--glass-tint-strength-aa);
+        /* BG.W-GLASS-DEFAULT-DEFINITION (GA-1) — definition is the MID rung of the SAME
+           a11y ladder `--glass-level: 0.3` rides: an explicit "more contrast" request
+           lifts every glass surface to the DEFINED tier library-wide (a read-carrying
+           warm rim + the warm-cream floor), joining the level+tint escape as ONE
+           coordinated bracket, not a third fork. */
+        --glass-definition: 1;
     }
 }
 
@@ -167,79 +173,16 @@
     }
 }
 
-/* ── @supports fallbacks for non-backdrop-filter browsers ── */
-@layer components {
-    /* GUARD 1 — the NO-BLUR-AT-ALL engine (supports NEITHER the unprefixed NOR the
-       webkit form): paint an opaque-leaning plate so text stays legible without any
-       blur. AY.W-A11Y-PERF O-2b note: this is the floor for the theoretical
-       neither-supported case. The Safari ≤17 webkit-only trap (supports the `-webkit-`
-       form, so this `@supports not (… or …)` is FALSE and the fallback does NOT fire)
-       is closed at the SOURCE OF THE PREFIX: O-2a's build pass guarantees the shipped
-       dist carries the `-webkit-backdrop-filter:` pair, so a Safari-17 engine renders
-       the BLUR off the prefixed rule (it no longer falls through to a transparent
-       unprefixed-only surface). The trap closes where the prefix is emitted, not here. */
-    @supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
-        .glass-wash {
-            background: color-mix(in srgb, var(--card) 80%, transparent);
-        }
-        .glass-quiet {
-            background: color-mix(in srgb, var(--card) 88%, transparent);
-        }
-        .glass-resting {
-            background: color-mix(in srgb, var(--card) 94%, transparent);
-        }
-        .glass-floating {
-            background: color-mix(in srgb, var(--card) 98%, transparent);
-        }
-        .glass-overlay {
-            background: var(--card);
-        }
-        .glass-btn {
-            background: color-mix(in srgb, var(--background) 92%, transparent);
-        }
-    }
-
-    /* GUARD 2 — the WEBKIT-ONLY engine (supports `-webkit-backdrop-filter` but NOT the
-       unprefixed `backdrop-filter` — Safari ≤17). With O-2a's build-emitted prefix the
-       shipped rung carries the `-webkit-backdrop-filter:` pair, so this engine PAINTS
-       the blur off that prefixed declaration. This guard exists to DOCUMENT-and-confirm
-       that path (and would re-assert the translucent glass identity if a future change
-       ever stripped the rung bg under this engine) — it re-states the rungs' translucent
-       glass-mix so a webkit-only engine that DID get the prefix keeps the glass look,
-       never the opaque GUARD-1 plate. The `proof:webkit-backdrop` gate asserts the
-       shipped dist carries BOTH guards. */
-    @supports ((-webkit-backdrop-filter: blur(1px)) and (not (backdrop-filter: blur(1px)))) {
-        .glass-wash {
-            background: color-mix(in oklab, var(--glass-bg-wash), var(--glass-tint-source) var(--glass-tint-strength));
-        }
-        .glass-quiet {
-            background: color-mix(in oklab, var(--glass-bg-quiet), var(--glass-tint-source) var(--glass-tint-strength));
-        }
-        .glass-resting {
-            background: color-mix(in oklab, var(--glass-bg-resting), var(--glass-tint-source) var(--glass-tint-strength));
-        }
-        .glass-floating {
-            background: color-mix(in oklab, var(--glass-bg-floating), var(--glass-tint-source) var(--glass-tint-strength));
-        }
-        .glass-overlay {
-            background: color-mix(in oklab, var(--glass-bg-overlay), var(--glass-tint-source) var(--glass-tint-strength));
-        }
-        .glass-btn {
-            background: var(--glass-bg-wash);
-        }
-    }
-}
-
-/* ── :has() focus-elevation fallback (AQ.W3 §W3.1a) ──────────────────────
-   SOLE fallback for engines without `:has()`. `.is-focus-within` is toggled
-   by a ≤6-LOC focusin/focusout guard in `Card.vue` that runs ONLY when
-   `!CSS.supports('selector(:has(*))')` (modern engines run zero JS). The
-   class redefines the SAME `--card-focus-*` rungs as the `:has()` rule, so the
-   override values have one source. NOT a live+dead alias — `:has()` is the
-   enhancement, this the documented degradation path. */
-@supports not selector(:has(*)) {
-    .glass-card.is-focus-within {
-        --card-focus-shadow: var(--shadow-md);
-        --card-focus-border: var(--glass-border-floating);
-    }
-}
+/* ── Legacy backdrop-filter + :has() capability ladders COLLAPSED
+   (BG.NF.2 W-LEGACY-LADDER-COLLAPSE — the NO-MASKING-FALLBACK floor).
+   The former GUARD-1 (no-blur opaque plate) + GUARD-2 (webkit-only glass-mix
+   restatement) `@supports` arms served engines supporting NEITHER form / the
+   webkit-only form (Safari ≤17) — years pre-target (target = current Chrome +
+   current Safari). `backdrop-filter` is Baseline on that set, and the real
+   webkit path is the BUILD-EMITTED `-webkit-backdrop-filter:` prefix pair
+   (`vite.style-assets.ts` O-2a), asserted in the shipped dist by
+   `proof:webkit-backdrop`, NOT a live source-side restatement. The
+   `@supports not selector(:has(*))` `.is-focus-within` arm (AQ.W3) collapsed
+   too — `:has()` is Chrome 105+/Safari 15.4+ AND its `Card.vue` toggler never
+   existed on disk (an orphan behind a lying comment); `.glass-card:has(:focus-
+   visible)` (`glass/surfaces.css`) is the sole focus-elevation mechanism. */

package/src/styles/glass/control-surfaces.css

@@ -93,38 +93,42 @@
        specificity). `:focus-visible` Baseline Widely — no fallback. */
     .input-pill:focus-visible {
         outline: none;
-        border-color: var(--color-accent-opaque, var(--ring));
-        box-shadow: 0 0 0 2px var(--color-accent, color-mix(in srgb, var(--ring) 30%, transparent));
+        /* BG.W-DESHADCN — the focus fallback reads the renamed house
+           `--focus-ring-color` (off the shadcn `--ring`; value unchanged). */
+        border-color: var(--color-accent-opaque, var(--focus-ring-color));
+        box-shadow: 0 0 0 2px var(--color-accent, color-mix(in srgb, var(--focus-ring-color) 30%, transparent));
     }
 
     /* AQ.W4 §W4.1 — validity vocabulary on `.input-pill` (Input + Textarea).
-       The forgiving `:where(:user-invalid, .user-invalid-fallback,
-       [aria-invalid="true"])` group is ONE rule covering THREE trigger surfaces:
-       native constraint-validation (`:user-invalid`), the `useUserInvalidAria`
-       fallback class for engines without `:user-invalid` (css §3.2; NOT a
-       live+dead alias — the class is the SOLE fallback), AND (AW.W18) the
-       imperative `[aria-invalid="true"]` attribute. The `[aria-invalid]` arm
-       serves APP-DRIVEN validity — a custom key match, an async server check —
-       where there is no native constraint to trip `:user-invalid`, so the app
-       sets the ARIA attribute and the library's own ring paints with no
-       `:deep()` re-paint at the consumer. The destructive/success tints reuse
-       the semantic tokens via `color-mix` per the house pattern (W2). Non-color
+       The `:where(:user-invalid, [aria-invalid="true"])` group is ONE rule
+       covering TWO trigger surfaces: native constraint-validation
+       (`:user-invalid`, Baseline Chrome 119+/Safari 16.5+ on the target set) AND
+       (AW.W18) the imperative `[aria-invalid="true"]` attribute. The
+       `[aria-invalid]` arm serves APP-DRIVEN validity — a custom key match, an
+       async server check — where there is no native constraint to trip
+       `:user-invalid`, so the app sets the ARIA attribute and the library's own
+       ring paints with no `:deep()` re-paint at the consumer. The legacy
+       `.user-invalid-fallback` / `.user-valid-fallback` class members (for
+       engines without `:user-invalid`) were COLLAPSED at BG.NF.2
+       W-LEGACY-LADDER-COLLAPSE — the aria-BRIDGE half of `useUserInvalidAria`
+       KEEPS (a11y, not a ladder). The destructive/success tints reuse the
+       semantic tokens via `color-mix` per the house pattern (W2). Non-color
        reinforcement is the error TEXT (W4.5 `error` slot) + the `required`
        asterisk — the border/bg shift is the supplementary cue, never the sole
        one. `:user-valid` is intentionally subtle (border only, no bg fill) so
        a long valid form is not a wall of green. */
-    .input-pill:where(:user-invalid, .user-invalid-fallback, [aria-invalid="true"]) {
+    .input-pill:where(:user-invalid, [aria-invalid="true"]) {
         border-color: var(--destructive);
         background: color-mix(in srgb, var(--destructive) 8%, var(--glass-bg-quiet));
     }
-    .input-pill:where(:user-valid, .user-valid-fallback) {
+    .input-pill:where(:user-valid) {
         border-color: var(--success);
     }
     /* Invalid + keyboard-focused → destructive ring (overrides the accent
        `:focus-visible` ring above by order + the extra invalid compound). The
        `[aria-invalid]` arm rides the same widened group so an app-driven
        invalid field shows the destructive ring on focus too. */
-    .input-pill:where(:user-invalid, .user-invalid-fallback, [aria-invalid="true"]):focus-visible {
+    .input-pill:where(:user-invalid, [aria-invalid="true"]):focus-visible {
         border-color: var(--destructive);
         /* BB.W-INVALID-RING — the shared destructive ring register (the
            --focus-ring-shadow sibling). The byte-identical recipe is now ONE

package/src/styles/glass/deep.css

@@ -34,11 +34,81 @@
  * BEFORE the a11y @media brackets (which still win by the :root level re-point).
  */
 @layer components {
-    /* The deep decoration: re-point the floating rung's blur token to the deep
-       family. The base `.glass-floating` rule (`backdrop-filter:
-       var(--glass-blur-floating)`) then paints the deep `blur(16px) saturate(1.5)`
-       at `--glass-depth: 1` — the Apple-deep register, opt-in. */
+    /* The deep decoration: COMPUTE the deep LERP here (at the consuming element) +
+       re-point the floating rung's blur token to it.
+
+       THE FREEZE-FIX (BG.W-GLASS-DEPTH-TIER — the C18 dual-engine painted dead-knob,
+       2026-07-05). The LERP intermediates read `var(--glass-depth)`, a REGISTERED
+       `@property` (`inherits: true; initial-value: 1`). Per the CSS Properties &
+       Values API a `var()` to a registered custom property inside ANOTHER custom
+       property is eager-substituted with the referenced property's COMPUTED value AT
+       THE DECLARING ELEMENT. So these intermediates MUST be declared HERE (on
+       `.glass-deep`), NOT at `:root` (tokens/glass-deep.css) — at `:root` the tier
+       grade is not yet in scope and `--glass-depth` computes to its `initial-value` 1,
+       freezing the whole calc at the depth-1 endpoint (every deep surface paints the
+       16px / 1.8 ceiling, tier grade inert). The tier map below sets `--glass-depth`
+       per tier ON THE BASE RUNG the `.glass-deep` decoration composes with (same
+       element), so declared here `var(--glass-depth)` resolves to the element's LIVE
+       tier grade and the ladder PAINTS: content ~14px < popover ~15px < menu 16px.
+
+       The composition is IDENTICAL to the retired `:root` form — same endpoints
+       (`--glass-blur-floating-radius` depth-0 floor / `--glass-blur-deep-radius`
+       depth-1 ceiling, `--glass-saturate-floating` / `--glass-saturate-deep`), same
+       `* var(--glass-level)` clarity scale (so the opaque escape + the a11y brackets
+       reach the deep plate through the ONE level path; at `--glass-level: 0` the deep
+       blur resolves blur(0)). Only the DECLARING SELECTOR moved (:root → .glass-deep).
+       The base `.glass-floating` rule (`backdrop-filter: var(--glass-blur-floating)`)
+       then paints the deep blur — the Apple-deep register, opt-in. */
     .glass-deep {
+        --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)
+            );
+        --glass-saturate-deep-active:
+            calc(
+                var(--glass-saturate-floating)
+                + (var(--glass-saturate-deep) - var(--glass-saturate-floating))
+                * var(--glass-depth)
+            );
+        --glass-blur-deep:
+            blur(var(--glass-blur-deep-active-radius))
+            saturate(var(--glass-saturate-deep-active));
         --glass-blur-floating: var(--glass-blur-deep);
     }
+
+    /* ── The tier-ladder depth MAP (BG.W-GLASS-DEPTH-TIER) ──────────────────────
+       Map --glass-depth onto the tier ladder so the deep register's thickness
+       tracks surface PROMINENCE by construction: the overlay/menu rungs default a
+       HIGHER depth than the content rungs (menu > popover > button). Each rung sets
+       the ONE --glass-depth scalar from its named grade (tokens/glass-deep.css) — a
+       pure per-rung DEFAULT, NOT a new blur recipe. So a deep surface inherits its
+       tier's depth: a `deep` Card (glass-floating glass-deep) resolves the popover
+       grade (~15px), the hero CTA button (glass-wash btn-glass glass-deep) resolves
+       the content grade (~14px), a deep overlay/modal reaches the full 16px ceiling
+       — thickness tracks prominence by construction, ZERO new machinery.
+
+       D5-SAFE: no rung reads var(--glass-blur-deep) here — --glass-depth only DRIVES
+       the deep LERP (glass-deep.css), so a NON-deep tier surface is BYTE-UNCHANGED
+       (a plain popover stays the calm 13px; the calm ladder never reads --glass-depth)
+       and only a `.glass-deep`-composed surface consumes the graded depth.
+
+       SUBSTITUTION-vs-INHERITANCE (the recorded seam): zero-specificity :where() so
+       a consumer overrides the default at the element (`--glass-depth` inline / a
+       higher-specificity rule). To retune a whole band from an ancestor, override the
+       named grade token (`--glass-depth-popover: …`) — the tier rules read it, so it
+       cascades in (the per-band twin of the global --glass-depth ancestor dial). */
+    :where(.glass-overlay) {
+        --glass-depth: var(--glass-depth-menu);
+    }
+    :where(.glass-floating) {
+        --glass-depth: var(--glass-depth-popover);
+    }
+    :where(.glass-card, .glass-resting, .glass-quiet, .glass-wash) {
+        --glass-depth: var(--glass-depth-content);
+    }
 }

package/src/styles/glass/defined.css

@@ -0,0 +1,88 @@
+/* glass/defined.css
+   BG.W-GLASS-DEFAULT-DEFINITION (GA-1) — the DEFINED glass tier.
+
+   Glass is the maximal default (AX.W54), but the blur is imperceptible over a FLAT page
+   — a bare <Button>/.input-pill reads as a near-gray shape (chroma 0.0138, BD GOLDEN).
+   This tier splits glass into TWO registers on the ONE existing --glass-level/edge
+   machinery (NOT a fork of the cascade, NOT a competing backdrop-filter, NOT a parallel
+   recipe):
+     · transmissive (today's maximal glass) — the DEFAULT for surfaces WITH a colorful
+       backdrop (cards over the field, overlays over content, the dock over aurora).
+       BYTE-UNTOUCHED.
+     · defined — a `.glass-defined` TOKEN-SUBSTITUTION decoration on a base rung (the
+       .glass-opaque/.glass-deep precedent) that reads as a SHAPE over ANY backdrop by
+       composing three things the material ALREADY owns: (a) a stronger warm rim
+       (--glass-border-defined), (b) a warm-cream floor-fill (--glass-floor-fill) layered
+       UNDER the transmissive plate, (c) the shipped W-BUTTON-GLASS lit register
+       (specular + --glass-btn-* depth stack, unchanged). ONE engage scalar,
+       @property --glass-definition (property-regs.css; 0 = transmissive, 1 = defined) —
+       both legs read it, so the scalar is genuinely load-bearing (dead-knob-proof) and a
+       host dials definition on any ancestor.
+
+   The DEFAULT flip (the wave's PURPOSE): the control cohort — Button glass variants
+   (.btn-glass) · .input-pill (Input/Textarea/NumberField) · .control-surface
+   (SelectTrigger) — is DEFINED by default, so a control reads as a control over a flat
+   page (the AX.W54 over-reach transposition BD §3.3 invited). A CONTENT surface composes
+   NO .glass-defined and stays transmissive (the negative arm — the flip does not bleed).
+   Menu ROWS stay transmissive inside an already-defined panel (KS-GLASS §3.2 decided
+   sub-question — a row inside a defined panel needs state fills, not its own floor).
+
+   @import-ed after deep.css in glass.css (a decoration ON a base rung, the deep.css
+   sibling); the tokens live in tokens/glass.css. */
+@layer components {
+    /* The floor layers UNDER the plate via TWO image layers: CSS image layers always
+       paint OVER background-color, so a two-image plate-over-floor is the ONLY ordering
+       that reads plate-over-floor. The base rung paints its plate via the `background:`
+       SHORTHAND (→ background-COLOR), so `background-color: transparent` is LOAD-BEARING
+       — un-zeroed the composite would be plate(image) ⊕ floor(image) ⊕ plate(color), the
+       plate counted TWICE. Zeroed, the stack is EXACTLY one plate over one floor (the
+       calibration target). Each family maps --glass-defined-plate to its OWN fill token
+       so the floor sits under the fill it actually paints; a bare `.glass-*` rung +
+       .glass-defined falls back to the ladder-rung plate (--glass-plate-tinted). */
+    .glass-defined,
+    .btn-glass,
+    .input-pill,
+    .control-surface {
+        --glass-definition: 1;
+        /* The substitution-vs-inheritance fix (the --dock-scale re-declare / --glass-bg-dock
+           pre-substituted-seam precedent — CLAUDE.md "The substitution-vs-inheritance trap").
+           --glass-floor-fill + --glass-border-defined are composed at :root, where
+           --glass-definition is 0 — and a custom property's inner var() substitutes at the
+           element that DECLARES it, so the :root copies resolve TRANSPARENT (calc(0 * N%)) and
+           inherit DOWN already-resolved. Flipping --glass-definition: 1 here would be a DEAD KNOB
+           (the floor/rim keep their :root-resolved transparent value). RE-DECLARE both on this
+           definition-1 rule so their var(--glass-definition) re-resolves against THIS element's
+           value (card@15% floor + foreground@14% rim actually paint). The :root copies stay the
+           transmissive default (definition 0 -> transparent) for a content surface. Both legs
+           still read the scalar (dead-knob-proof); --glass-floor-fill-max stays the one knob. */
+        --glass-floor-fill: color-mix(
+            in srgb,
+            var(--card) calc(var(--glass-definition) * var(--glass-floor-fill-max)),
+            transparent
+        );
+        --glass-border-defined: color-mix(
+            in srgb,
+            var(--foreground) calc(var(--glass-definition) * 14%),
+            transparent
+        );
+        background-color: transparent;
+        background-image:
+            linear-gradient(
+                var(--glass-defined-plate, var(--glass-plate-tinted)),
+                var(--glass-defined-plate, var(--glass-plate-tinted))
+            ),
+            linear-gradient(var(--glass-floor-fill), var(--glass-floor-fill));
+        border-color: var(--glass-border-defined);
+    }
+
+    /* Per-family plate mapping — the floor layers under the fill each family PAINTS
+       (btn-glass composes its own tinted --glass-fill; the form controls read the shared
+       --control-surface-bg REST register). */
+    .btn-glass {
+        --glass-defined-plate: var(--glass-fill);
+    }
+    .input-pill,
+    .control-surface {
+        --glass-defined-plate: var(--control-surface-bg);
+    }
+}