@mkbabb/glass-ui 4.1.0 → 5.0.0

package/src/styles/glass/glass-capsule.css

@@ -0,0 +1,175 @@
+/* ════════════════════════════════════════════════════════════════════════
+   .glass-capsule — the ONE shared glassy register (BD.W-TAB-IOS-CAPSULE).
+
+   The warm-transmissive lifted lozenge + the recessed warm channel it rides in
+   + the glass hover/press register, factored ONCE so EVERY consumer (segmented
+   pill · dock-tab selected · Button glass · chips · cards) COMPOSES it instead
+   of re-forking the lifted-plate composite. ≥3 consumers by construction — the
+   overfitting bar cleared by extraction. The tabs facility is the reference
+   implementation; "make buttons glassy like the tabs" is a one-recipe substitution.
+
+   Clean break — the prior inline `.segmented-indicator` composite (fill + rim +
+   lift) moves here VERBATIM and the pill COMPOSES the class. No alias, no legacy.
+
+   @layer components, @import-ed in index.css AFTER the glass ladder (so the
+   `--glass-bg-*`/`--glass-rim-*`/`--glass-shadow-*` tokens resolve) and BEFORE
+   the consuming tabs/dock/button recipes.
+
+   THREE states:
+     · REST  = .glass-capsule           — the warm-glass lifted plate.
+     · TRACK = .glass-capsule-track     — the recessed warm channel.
+     · HOVER = .glass-capsule-hover     — specular catch-light lift + press-snap.
+
+   Every channel is compositor-only + Safari-native by construction (the §7 floor):
+   no `backdrop-filter: url()`, no SVG goo, no WebGL. The recess is a STATIC inset
+   shadow built off a PLAIN per-mode token pair (NEVER a `light-dark()` fragment —
+   an inset-shadow leg inside light-dark() computes the WHOLE box-shadow to `none`,
+   the binding MEMORY lesson). The hover lift is a `scale` + `--glass-specular`
+   step (the SHARED specular-lift primitive `.glass-drag-lift` also composes).
+   ════════════════════════════════════════════════════════════════════════ */
+
+@layer components {
+    /* ── .glass-capsule — the raised lit warm-glass lozenge ──
+       The fill reads the SHARED element-level oklab-tinted floating pair (the W55
+       adaptive seam, `surfaces.css` `:where(.btn-glass, .segmented-indicator,
+       .glass-capsule)`) — over a bright field it darkens-to-legible, over a calm
+       field it stays warm-cream/near-white. The FORWARD-ness comes from the rim +
+       lift, NOT from cranking the same-hue alpha. */
+    .glass-capsule {
+        /* The WARM-FLOOR re-invent (BD.W-TAB-IOS-CAPSULE C6). The bare
+           `--glass-bg-floating-tinted` desaturates to near-gray over a vibrant
+           aurora (live-measured oklab(0.793 0.005 0.012), chroma 0.0128 < 0.02).
+           Compose a SMALL floor toward an explicitly WARM oklch source so the
+           CAPSULE's own resolved fill carries chroma — independent of the
+           `--glass-tint-strength: 0%` adaptive default (which is zero-delta at rest
+           and only lifts under the bright bucket). This exercises the REAL
+           `color-mix(in oklab)` seam over the live light-dark() fill (NOT a
+           hardcoded hsl look-alike — the amendment's fake-gate ban). The source is
+           a warm oklch (build-trap-(d) safe form — warm color, never bare
+           `transparent`); at `--glass-capsule-warm-floor: 16%` the painted capsule
+           clears meanChroma ≥ 0.02 BOTH modes with negligible L lift (stays near-
+           white). `--glass-capsule-warm` is a warm cream amber both modes. */
+        /* The fill is INDIRECTED through `--glass-capsule-fill` so a consumer can
+           re-point the rung (quiet/loud/selected — buttons' quiet triplet, the dock
+           selected pill) WITHOUT forking the register; the default keeps the warm
+           floor compose. */
+        background: var(
+            --glass-capsule-fill,
+            color-mix(
+                in oklab,
+                var(--glass-bg-floating-tinted),
+                var(--glass-capsule-warm) var(--glass-capsule-warm-floor)
+            )
+        );
+        backdrop-filter: var(--glass-blur-floating);
+        -webkit-backdrop-filter: var(--glass-blur-floating);
+        /* The lifted-plate composite: the directional rim (bright top catch-light +
+           warm bottom under-shadow — the iOS-27 top-light/bottom-shadow thickness)
+           PLUS a layered glass under-shadow lifting the plate ~2-3px off the quiet
+           track. */
+        box-shadow:
+            var(--glass-rim-top),
+            var(--glass-rim-bottom),
+            var(--glass-shadow-floating);
+        border-radius: var(--radius-pill);
+    }
+
+    /* ── .glass-capsule-track — the recessed warm channel (the iOS-27 sunken well) ──
+       The track SINKS: rim + a STATIC inset recess leg. The recess ink is a PLAIN
+       per-mode token pair (`tokens/glass-fx.css` light arm, `tokens/dark-arm.css`
+       dark arm) — NEVER a `light-dark()` fragment (the inset-shadow trap). The
+       recess is static (a sunken channel does not pulse — never a @keyframes
+       target; `proof:no-layout-animation` holds). */
+    .glass-capsule-track {
+        background: var(--glass-bg-quiet);
+        backdrop-filter: var(--glass-blur-quiet);
+        -webkit-backdrop-filter: var(--glass-blur-quiet);
+        box-shadow:
+            var(--glass-rim-top),
+            var(--glass-rim-bottom),
+            inset 0 1px 2px var(--tab-track-recess-ink);
+    }
+
+    /* ── .glass-capsule-hover — the SHARED specular-lift primitive ──
+       The two-channel glass hover (specular catch-light lift + a hair of scale) +
+       the press-snap, on the FAST bezier clock (hover is a bezier ease, not a
+       spring), volume-preserving, compositor-only. This is the SAME specular-lift
+       idiom `.glass-drag-lift` carries — factored here ONCE; `.glass-drag-lift`
+       re-composes `--glass-specular`-step + `will-change` rather than forking a
+       parallel block. The non-selected pill + the buttons greenfield compose this
+       wholesale: glass at rest + specular-lift on hover + press-snap on active. */
+    .glass-capsule-hover {
+        /* The SPATIAL leg (scale) rides the weighty cartoon-punch curve (the
+           liquid-weight-universal mandate — a hover lift carries inertia/overshoot,
+           never an abrupt bezier jerk; the SAME spatial currency `.glass-chip`/
+           `.glass-atom` ride, PRM-zeroed via the `--ease-cartoon-punch` fallback). The
+           EFFECTS leg (the `--specular-intensity` gleam channel) stays on the fast
+           bezier (motion-canon P1 — an effects cross-fade is not a spatial motion). */
+        transition:
+            scale var(--duration-fast) var(--ease-cartoon-punch),
+            --specular-intensity var(--duration-fast) var(--ease-standard);
+    }
+    /* The SHARED specular-lift step — declared ONCE here, COMPOSED by both the hover
+       register AND the drag-lift (BD.W-TAB-IOS-CAPSULE C7: one declaration of the
+       `--glass-specular` catch-light step, never a parallel fork). `.glass-drag-lift`
+       (segmented-tabs.css) re-points its grabbed-state catch-light onto THIS step
+       rather than re-declaring `--glass-specular`; it adds only its distinct grabbing
+       bits (the grab cursor + the `will-change` compositor hint). The W-GLASS-CAL
+       sub-perceptual catch — a hair brighter at the specular edge, disco-FREE. */
+    .glass-capsule-hover:hover,
+    .glass-drag-lift {
+        /* Drive the REAL gleam-opacity channel (`--specular-intensity`, read by the
+           moving-specular `::before` at material.css opacity) — not the dead
+           `--glass-specular` name. Composes with the material hover system; fires for
+           both the :hover register AND the grabbed `.glass-drag-lift` class. */
+        --specular-intensity: 0.14;
+    }
+    .glass-capsule-hover:hover {
+        /* the 1.5% press-ready lift (the lift is hover-only; the drag-lift carries no
+           scale of its own — the translate/squish are the morph primitive's writes) */
+        scale: 1.015;
+    }
+    .glass-capsule-hover:active {
+        /* the --scale-press snap */
+        scale: var(--scale-press-sm, 0.97);
+    }
+    @media (prefers-reduced-motion: reduce) {
+        /* the lift is motion; the specular catch (a static legibility cue) stays. */
+        .glass-capsule-hover:hover,
+        .glass-capsule-hover:active {
+            scale: 1;
+        }
+    }
+
+    /* ── BI.W-DOCK-CONTROLS — the folded dock-control safe-inset (the face token) ──
+       The `--dock-control-safe-inset` 10% band-aid the user rejected FOLDS into the
+       FACE: the painted plate insets (`background-clip: content-box` over the inset
+       `padding`), while the HIT CELL stays the full `--dock-control-size` (the WCAG
+       2.5.5 ≥44px touch floor on the CELL, never the plate). Hit box ≠ paint box —
+       the clip fix (W-DOCK-SPINE's L1 `overflow: visible`) and the touch floor are
+       now DECOUPLED: A11Y-5's 17×40px defect dies because the hit box reads the full
+       cell while the painted plate insets independently.
+
+       DOCK-SCOPED (`.glass-dock` descendant) so NO other `.glass-capsule` consumer
+       (a glass Button, a Badge/IconChip/chip OUTSIDE a dock) inherits the content-box
+       clip — `--dock-control-safe-inset` resolves to 0 outside a dock anyway, but the
+       scope keeps the content-box clip off the broad capsule family. This is the ONE
+       home of the safe-inset routing (the standalone `padding`/`background-clip`
+       sites in the dock-control recipe files collapsed onto it — proof:dock-controls
+       C3). Two legs, ONE token home:
+       • the SHARED fill-inset — the painted plate clips to the content box so the
+         fill insets within the control's own padding / the safe-inset. Applies to
+         the whole dock capsule family (icon active plate + hover register).
+       • the ICON-SHAPE safe-inset padding — the ONE `--dock-control-safe-inset`
+         read. A fixed-square icon control needs `padding` to define a content box
+         SMALLER than the cell (the plate insets within the square); a text control
+         (tab/trigger) uses its OWN text padding as the inset, so the padding leg is
+         scoped to the icon shape (`.dock-icon-button`) — it never clobbers a text
+         control's or a nested strip's padding. */
+    .glass-dock :is(.glass-capsule, .glass-capsule-hover) {
+        background-clip: content-box;
+    }
+    .glass-dock .dock-icon-button {
+        padding: var(--dock-icon-padding, var(--dock-control-safe-inset, 0));
+    }
+}

package/src/styles/glass/glass-chip.css

@@ -0,0 +1,211 @@
+/* ════════════════════════════════════════════════════════════════════════
+   .glass-chip — BD.W-CHIP-CONGRUENT-GLASS: the ONE warm-glass toggle register
+   the chip family (ToggleChip · SelectableChip + the toggle-group children)
+   composes. A stadium-pill warm-glass LENS that PUNCHES when you pick it: the
+   tonal band floods through the translucent lens on `--ease-cartoon-punch` with
+   anticipation → overshoot → settle, a one-shot accent-bloom trailing the
+   spatial leg.
+
+   CONSUME-ONLY — declares ZERO own glass tokens (the no-fork fence, Fence C3c).
+   It COMPOSES:
+     · `.glass-capsule`        — the warm-transmissive lozenge BODY (warm floor +
+                                 rim + lift + blur), on `--radius-pill`. The chip
+                                 is the ≥4th `.glass-capsule` consumer (after the
+                                 tab indicator + the button sites). NEVER inlines
+                                 `backdrop-filter` / `--glass-bg-*` / a rim.
+     · `.glass-capsule-hover`  — the SHARED specular-lift + press-snap step.
+     · `.accent-tone`          — the contrast-floored tonal channels (idle fill /
+                                 active band / active edge / contrast-safe ink).
+     · `--glass-fill-tint` / `--glass-fill-strength` (BE.W-TINTED-CHIP, glass.css)
+                                 — the per-instance plate-fill data hue the body
+                                 tints toward. The chip is its ≥3rd consumer; it
+                                 APPLIES the axis, never re-mints a tint.
+     · `--motion-weight` × `--ease-cartoon-punch` (BD.W-MOTION-WEIGHT /
+                                 -CARTOON-PUNCH) — the cartoon press/flood punch +
+                                 the PRM dial (`--motion-weight: 0`).
+
+   DISTINCT-not-fork of `.glass-atom` (the small-atom register: Badge/+N/slider):
+   both COMPOSE `.glass-capsule`. `.glass-atom` is the quiet always-on identity
+   chip; `.glass-chip` is the TOGGLE face whose state flip is the de-frauded
+   colour-flood punch. They never write each other's channels.
+
+   @layer components, @import-ed by index.css AFTER glass.css (so `.glass-capsule`
+   + `.accent-tone` + the `--glass-*` axes resolve) and BEFORE/AROUND the chip
+   recipes. Every channel is compositor-only + Safari-native (no
+   `backdrop-filter: url()`, no goo — Fence 8). The warm 0-alpha sources are
+   explicit `oklch(L C H / 0)` (NEVER bare `transparent` — the WebKit
+   black-premultiply hole, build-trap-(d)). Per-mode `.dark` arms (no
+   `light-dark()` fragment).
+   ════════════════════════════════════════════════════════════════════════ */
+
+/* The COMMIT-flood scalar — the ON-flip envelope. `inherits: TRUE` is the
+   load-bearing de-fraud (challenge R1): an `inherits:false` reg resolves to its
+   `initial-value` on the `::after` PSEUDO (a separate box from the element that
+   sets it), so the flood reads `0` forever. `inherits:true` lets the element's
+   `[data-state="on"]{--chip-flood-t:1}` reach the pseudo. Typed so the opacity
+   interpolates a NUMBER, not the textual representation. On a pre-Baseline engine
+   that drops the typed reg the scalar collapses to the initial 0 — the chip still
+   selects (the COLOUR event below is plain `data-state`, never tied to the
+   scalar; challenge R5). */
+@property --chip-flood-t {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 0;
+}
+
+@layer components {
+    /* ── .glass-chip — the warm-glass toggle lens ──
+       The chip wears `.glass-chip .glass-capsule .glass-capsule-hover .accent-tone`
+       (the component CVA composes all four). This rule owns only the chip-specific
+       layer: the warm idle floor (the #2 dormant-tint cure), the per-instance fill
+       tint over the capsule's warm body, the ONE `scale` write (hover/press/punch
+       folded), and the `::after` flood. The capsule owns the body/rim/blur. */
+    .glass-chip {
+        position: relative;
+        /* The flood `::after` sits ABOVE the translucent fill (challenge R2): a
+           new stacking context so `plus-lighter` blends over the lens body, never
+           occluded under an opaque layer. The capsule body is α<1, so the bloom
+           reads through. */
+        isolation: isolate;
+
+        /* ── The WARM IDLE FLOOR (root #2 cure) ──
+           The chip carries chroma at rest over warm-cream even with no vibrant
+           field behind. The floor RAISES the `.accent-tone` idle strength the chip
+           reads — a NON-self-referential floor (build-trap-(b): a property reading
+           ITSELF in its own `max()` is guaranteed-invalid and drops). A SEPARATE
+           input var is the source: the `.accent-tone` recipe's default idle
+           strength is 8%; the chip floors the resolved strength to
+           `--chip-tint-floor` so the idle AND the default-tone active band both
+           clear the 0.02 warm floor (the live finding: BOTH are gray over
+           `--primary`). PLAIN per-mode pair (12% light / 15% dark), NEVER
+           `light-dark()` (the inset-shadow trap). */
+        --chip-tint-floor: 12%;
+        --accent-fill-strength: max(8%, var(--chip-tint-floor));
+        /* Lift the DEFAULT-tone active band too (the §1b finding: the default
+           band reads C 0.013 — a darken, not a chroma lift). The band floors to a
+           bolder warm-clearing stop so a selected default chip is tonal, not gray. */
+        --accent-band-strength: max(18%, calc(var(--chip-tint-floor) + 10%));
+
+        /* ── The per-instance fill tint (BG.W-GLASS-CONSUMER-BAND CONSUME) ──
+           The translucent capsule body tints toward the consumer data hue via the
+           SHARED per-instance PLATE recipe `--glass-fill-tinted` (tokens/glass.css) —
+           NOT a forked `color-mix` re-spell (the chip read the SAME seam the atom
+           does, so this fold is net-neutral: both read the ONE plate). At the
+           `@property` defaults (`--glass-fill-tint: transparent` / strength 0%) it is
+           the byte-identical no-op (`color-mix(in oklab, X, transparent 0%)` ≡ X — the
+           warm floor above keeps the idle body warm even at a transparent tint). The
+           shared plate is `in oklab` over a warm `oklch(… / 0)` 0-alpha stop (never
+           bare `transparent` — the WebKit black-premultiply hole). ONE plate, ONE rim
+           (`--glass-material-rim`, the capsule carries it). */
+
+        /* ── The ONE scale write (hover/press/punch, single source of truth) ──
+           Folds the on-flood overshoot into ONE `scale` so it never collides with
+           the capsule-hover scale step (the CVA's `hover:scale-*` is retired in the
+           chip variants — this is the sole scale writer on the chip box). Volume-
+           preserving, center-pinned. The coefficient (0.12) is raised vs the
+           segmented-indicator's 0.06 so the dip/overshoot clear the gate's OWN
+           thresholds (≤0.996 dip / ≥1.04 overshoot at weight 1.0): the punch curve
+           peaks at 1.22 → 1 + 0.12·1.22·1.0 ≈ 1.026 over rest is too soft, so the
+           overshoot READ is carried by the curve's pre-dip (−0.04) + the COLOUR
+           event; the spatial leg adds the perceptible breathe without taffy. */
+        scale: calc(1 + 0.12 * var(--chip-flood-t, 0) * var(--motion-weight, 0.618));
+        transform-origin: center;
+
+        /* The SPATIAL legs (scale) settle on the punch clock; the EFFECTS legs
+           (background/border/color) stay on the bezier (motion-canon P1). */
+        transition:
+            scale var(--duration-normal) var(--ease-cartoon-punch),
+            background-color var(--duration-fast) var(--ease-standard),
+            border-color var(--duration-fast) var(--ease-standard),
+            color var(--duration-fast) var(--ease-standard);
+
+        /* ── The per-instance fill tint application ──
+           The capsule body (the `.glass-capsule` `background:` shorthand) is the
+           warm transmissive plate; the chip LAYERS the data-hue tint on top via
+           `background-image` (a later layer over the capsule's shorthand — the
+           proven `.paper-grid`/`.glass-atom` coexistence seam: paints OVER the
+           translucent fill, UNDER content). When `--glass-fill-tint` is unset the
+           tinted layer is the warm 0-alpha no-op (invisible) and the capsule's warm
+           body reads. */
+        background-image: linear-gradient(
+            var(--glass-fill-tinted),
+            var(--glass-fill-tinted)
+        );
+    }
+    .dark .glass-chip {
+        --chip-tint-floor: 15%;
+    }
+
+    /* ── The on-flip COLOUR event (the perceptible primary read) ──
+       OFF→ON floods the active band through the lens + lights the active rim + the
+       contrast-safe ink. Driven by PLAIN `data-state` (the reka Toggle contract),
+       NEVER tied to `--chip-flood-t` — so selection is legible even on a pre-
+       Baseline engine that drops the typed scalar (challenge R5). The `.accent-tone`
+       channels supply the colour; this rule only SWAPS which channel paints. */
+    .glass-chip[data-state="on"] {
+        background-color: var(--accent-band);
+        border-color: var(--accent-edge);
+        color: var(--accent-ink);
+        /* arm the spatial+bloom envelope */
+        --chip-flood-t: 1;
+    }
+
+    /* ── The COMMIT flood `::after` (the trailing accent bloom) ──
+       An additive radial bloom INSIDE the lens (`inset:0`, `border-radius:inherit`,
+       `plus-lighter`) ABOVE the translucent fill (inside `isolation:isolate`,
+       challenge R2). Its opacity reads `--chip-flood-t` (inherited from the element,
+       challenge R1) so it fires on ON and clears on OFF. The transition DELAY trails
+       the spatial leg (EFFECTS-trails-SPATIAL, the v3 f006→f007 ordering). The bloom
+       hue is the active band; default tone neutral → a provable near-no-op until a
+       consumer sets a vibrant `:tone`. */
+    .glass-chip::after {
+        content: "";
+        position: absolute;
+        inset: 0;
+        border-radius: inherit;
+        pointer-events: none;
+        background: radial-gradient(
+            120% 140% at 50% 50%,
+            color-mix(in oklab, var(--accent-band) 60%, oklch(0.9 0.05 75 / 0)),
+            oklch(0.9 0.05 75 / 0) 72%
+        );
+        mix-blend-mode: plus-lighter;
+        opacity: var(--chip-flood-t, 0);
+        transition: opacity var(--duration-normal) var(--ease-out) 60ms;
+    }
+
+    /* ── The CELL exception — a 72px icon+label TILE is a CARD, not a pill ──
+       The DELIBERATE 2-silhouette family (named honestly): the inline rungs are
+       stadium pills (the capsule's `--radius-pill`); the cell re-points to the
+       squircle card radius. It composes the SAME `.glass-chip` material + motion;
+       only the silhouette differs. The `::after` flood inherits the card radius. */
+    .glass-chip--cell {
+        border-radius: var(--radius-card);
+    }
+    .glass-chip--cell.glass-capsule {
+        border-radius: var(--radius-card);
+    }
+
+    /* ── PRM carve ──
+       Under reduced-motion `--motion-weight: 0` zeroes the spatial overshoot (the
+       `scale` calc collapses to 1) in ONE assignment; the bloom's MOTION rides the
+       same dial via the punch clock. The COLOUR cross-fade + the static lens lift
+       (the `.glass-capsule` rim/shadow) + the `--accent-band` swap REMAIN —
+       selection is always legible (challenge R7: zeroes the MOTION, not the bloom).
+       Vestibular-safe. */
+    @media (prefers-reduced-motion: reduce) {
+        .glass-chip {
+            --motion-weight: 0;
+        }
+    }
+
+    /* ── prefers-contrast: more — the active rim α floors UP ──
+       The active `--accent-edge` rim is the legibility CONTRACT; under more-contrast
+       floor the border ink so the selected lit edge clears ≥3:1 over the lens body.
+       The `--accent-ink` is already value.js contrast-safe (useAccentTone). */
+    @media (prefers-contrast: more) {
+        .glass-chip[data-state="on"] {
+            border-color: color-mix(in srgb, var(--foreground) 28%, transparent);
+        }
+    }
+}

package/src/styles/glass/grain-overlay.css

@@ -0,0 +1,79 @@
+/* glass/grain-overlay.css
+   The glass-tier paper-grain `::after` overlay (BB.W-LIQUIDHOVER — the always-present
+   texture + the opacity-only engage + the PRM/reduced-motion carve + the `.dark`
+   soft-light arm).
+   Carved from glass/ladder.css at BG.W-CLOSEFIX-9SITE to hold the no-god-module 500-line
+   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
+   stay in ladder.css; the rim/accent group is glass/rim.css). @import-ed by glass.css in
+   cascade order IMMEDIATELY AFTER ladder.css and BEFORE accent-tone.css — the SAME @layer
+   components; the grain `::after` is the SOLE writer of the `.glass-*::after` overlay so
+   the relocation is cascade-order-invariant (the grain block was the tail of ladder.css;
+   the dist is byte-isomorphic).
+   See docs/precepts/design-idioms.md §cohesion-aware partials. */
+@layer components {
+    /* Grain noise overlay — reuses paper texture SVG, no extra assets.
+       BB.W-LIQUIDHOVER — the disco-grain pop (T8-F6) killed at the COMPOSITION CLASS:
+       the `background-image` is ALWAYS PRESENT (decoded once at rest, NEVER toggled to
+       `none`), and any STATE-driven grain engagement cross-fades the `opacity` ONLY on
+       the thin `--glass-grain-engage-duration` (~120ms linear) clock. A `background-
+       image: none → var(--paper-clean-texture)` engage decodes-and-appears in one frame
+       (the pop); the opacity cross-fade is a compositor-cheap interpolation with the
+       image constant — the only sanctioned grain engage. The `transition` lives HERE so
+       a hover/active grain lift (wherever a glass surface raises grain on interaction)
+       reads as a smooth fade by construction, not a discrete swap. */
+    .glass-wash::after,
+    .glass-quiet::after,
+    .glass-resting::after,
+    .glass-floating::after,
+    .glass-overlay::after {
+        content: '';
+        position: absolute;
+        inset: 0;
+        border-radius: inherit;
+        /* The grain texture is the `background-image` longhand (NOT the `background`
+           shorthand) so the image stays a STABLE always-present layer the engage
+           never re-declares — the structural anti-pop: opacity is the only animated
+           channel, the image is never `none → image`. */
+        background-image: var(--paper-clean-texture);
+        background-repeat: repeat;
+        background-size: var(--paper-texture-size);
+        opacity: var(--glass-grain-opacity);
+        /* The opacity cross-fade engage — plain ~120ms linear direct-write (no spring,
+           no overshoot — instant-but-smooth per the ask). Under the PRM / reduced-
+           transparency brackets the clock collapses to 0ms (the a11y bracket below). */
+        transition: opacity var(--glass-grain-engage-duration, 120ms) linear;
+        pointer-events: none;
+        mix-blend-mode: overlay;
+    }
+
+    /* BB.W-LIQUIDHOVER — the grain engage collapses to INSTANT under reduced motion (a
+       grain that cross-fades on hover under reduce is still motion; accessibility is
+       absolute). The reduced-transparency / forced-colors brackets already zero
+       `--glass-grain-opacity` (a11y-fallback.css), so the grain is inert there; this
+       bracket covers the reduced-MOTION case where the grain still paints but must not
+       animate. */
+    @media (prefers-reduced-motion: reduce) {
+        .glass-wash::after,
+        .glass-quiet::after,
+        .glass-resting::after,
+        .glass-floating::after,
+        .glass-overlay::after {
+            transition: none;
+        }
+    }
+
+    /* The unified rim (AW.W22) + the BB.W-GLASS-ACCENT per-INSTANCE chromatic-RIM
+       tint group (the rim-ink + --glass-material-rim ring + the per-rung
+       --glass-border-accent border, light + dark arms) lives in glass/rim.css
+       (carved at BB.W-CARVE4 — the next adjacent @layer components block, the SOLE
+       writer of --glass-material-rim/--glass-border-accent). */
+
+    .dark .glass-wash::after,
+    .dark .glass-quiet::after,
+    .dark .glass-resting::after,
+    .dark .glass-floating::after,
+    .dark .glass-overlay::after {
+        mix-blend-mode: soft-light;
+    }
+}

package/src/styles/glass/ladder-undershadow.css

@@ -0,0 +1,61 @@
+/* glass/ladder-undershadow.css
+   The ladder tail: the AX.W54 .glass-opaque level-0 escape + the AV.W15 M4 content-aware under-shadow modifier (.glass-over-text / [data-over-content]).
+   Carved from glass/ladder.css to hold the no-god-module 500-line bound (BI.W-STYLE-REDRAIN); its own @layer components block @import-ed by glass.css IMMEDIATELY AFTER ladder.css (the tail of the ladder @layer, unique selectors, source-order-after — byte-isomorphic). */
+@layer components {
+    /* ── The opaque escape (AX.W54) ───────────────────
+       The level-0 endpoint of the SAME glass machinery — a solid `--card` plate
+       (the opacity seam → 1) with `blur(0)` (the blur seam → 0), routed through
+       the ONE `--glass-level` knob. NOT a parallel solid `background:` recipe:
+       a `.glass-*` surface that ALSO carries `.glass-opaque` keeps its glass edge,
+       rim, and under-shadow (a solid plate with a glass edge, not a bare div), and
+       the @supports fallback + the a11y brackets compose coherently. This is the
+       explicit opt-out from the MAXIMAL glass default (dense data, forced-colors,
+       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) ──────────────
+       Apple raises the under-shadow over text (so the glass reads as
+       lifting OFF the text) and drops it over solid light. The modifier
+       is ATTRIBUTE-DRIVEN, no JS: a consumer adds `.glass-over-text`
+       (or `[data-over-content="text"]`) to a text-bearing glass surface to
+       swap it ONE under-shadow rung heavier, or `[data-over-content="solid"]`
+       to lighten it one rung over a solid-light backdrop. It reuses the
+       existing `--glass-under-shadow-{quiet,default,vivid}` rungs (no new
+       shadow value — `vivid` is sufficient over text), redefining only the
+       leading under-shadow layer per tier; the lift stack is untouched.
+
+       The selectors are per-tier so the swap is rung-correct
+       (quiet→default, resting→vivid). `.glass-floating` already sits at the
+       `vivid` ceiling over text, so the heavier variant is a no-op there
+       (the rung saturates) — documented, not an error. */
+    .glass-quiet.glass-over-text,
+    .glass-quiet[data-over-content="text"] {
+        box-shadow: var(--glass-under-shadow-default), var(--glass-shadow-quiet);
+    }
+    .glass-resting.glass-over-text,
+    .glass-resting[data-over-content="text"] {
+        box-shadow: var(--glass-under-shadow-vivid), var(--glass-shadow-resting);
+    }
+
+    /* The inverse — over a solid-light backdrop the under-shadow lightens
+       one rung (the glass need not lift as hard off a flat bright field). */
+    .glass-resting[data-over-content="solid"] {
+        box-shadow: var(--glass-under-shadow-quiet), var(--glass-shadow-resting);
+    }
+    .glass-floating[data-over-content="solid"] {
+        box-shadow:
+            var(--glass-material-rim),
+            var(--glass-under-shadow-default),
+            var(--glass-shadow-floating);
+    }
+}