@mkbabb/glass-ui 4.0.0 → 4.1.0

package/src/styles/utilities/base.css

@@ -1,5 +1,12 @@
 /* utilities/base.css
-   The @layer components base half — section-description, labeled-field, popover-content, scrollbar, focus-ring, hairline-accent, interactive-item, tap-squish, status-dot, depth-text, preserve-3d, ios input fix, scroll-fade masks, fading-scroll (scroll-state-driven edge fade), deferred-section, scroll-timeline host, shimmer text, keyboard key.
+   The @layer components FORM/INTERACTION half — the @property fade pair (read by
+   the .fading-scroll rules in base-misc.css), section-description, labeled-field
+   (incl. the width-contract + error region), popover-content, scrollbar,
+   focus-ring, hairline-accent, interactive-item, tap-squish.
+   BB.W-CARVE3 carved the post-tap-squish tail (status-dot → kbd, incl. the
+   fading-scroll recipe) into the adjacent base-misc.css partial so each stays
+   under the no-god-module 500-line bound. The two adjacent same-`@layer
+   components` blocks compose identically — the dist is byte-isomorphic.
    Carved from the utilities.css cascade root; @import-ed by utilities.css in
    cascade order. See docs/precepts/design-idioms.md §cohesion-aware partials. */
 
@@ -127,8 +134,9 @@
        (PopoverContent, DropdownMenuContent, SelectContent, etc.).
        Covers radius + outline + popover-foreground; consumers compose
        this with `.glass-floating` (bg + blur + border + shadow), with
-       `.popover-animate` (data-state animation), and with the per-host
-       z-rung. The floating-tier shadow comes from
+       `.glass-reveal` (the spring-clocked data-state LIQUID-ENTER —
+       BB.W-LIQUID-REVEAL, off the retired `popover-animate`), and with the
+       per-host z-rung. The floating-tier shadow comes from
        `--glass-shadow-floating` via `.glass-floating`, replacing the
        `shadow-md`/`shadow-lg` literals that bypassed the canonical
        cascade. */
@@ -278,264 +286,42 @@
         }
     }
 
-    /* ── Status dot indicator ── */
-    .status-dot {
-        display: inline-block;
-        width: 0.5rem;
-        height: 0.5rem;
-        border-radius: var(--radius-pill);
-        flex-shrink: 0;
-        transition:
-            color var(--duration-fast) var(--ease-standard),
-            background var(--duration-fast) var(--ease-standard),
-            box-shadow var(--duration-fast) var(--ease-standard);
-    }
-    /* ── Depth text (layered offset stamp) ──
-       AW.W26 — composes the `--text-shadow-depth` @theme identity token (the
-       hard offset stack + soft ambient tail) instead of a hand-rolled multi-stop
-       literal. The token holds the stack inside the `@theme` defs (gate 4) and
-       re-tints under `.dark` via `--shadow`/`--shadow-color` BY CONSTRUCTION. */
-    .depth-text {
-        --depth-color-primary: var(--primary);
-
-        color: var(--depth-color-primary);
-        text-shadow: var(--text-shadow-depth);
-    }
-
-    /* ── 3D preserve ── */
-    .preserve-3d {
-        transform-style: preserve-3d;
-    }
-
-    /* ── iOS input font-size fix (prevent auto-zoom) ── */
-    .ios input,
-    .ios select,
-    .ios textarea,
-    .ios [contenteditable] {
-        font-size: max(1rem, 1em);
-    }
-
-    /* ── Scroll fade masks ──
-       Single-source `mask-image` (AV.W16 TW7): the `-webkit-` companion is
-       dropped — Tailwind v4's Lightning CSS build pipeline auto-prefixes per
-       the browserslist targets, mirroring the glass ladder's single-source
-       `backdrop-filter` (glass.css). NOTE: this is the consistency cut; it
-       does NOT conflict with W15's `@supports`-gated older-Safari mask
-       fallback (that fallback is the distinct case where the companion is
-       genuinely needed and W15 gates it). */
-    .scroll-fade-mask {
-        mask-image: linear-gradient(to right, transparent, black var(--mask-fade-width), black calc(100% - var(--mask-fade-width)), transparent);
-    }
-
-    .scroll-fade-top {
-        mask-image: linear-gradient(to bottom, transparent, black var(--mask-fade-width));
-    }
-
-    .scroll-fade-bottom {
-        mask-image: linear-gradient(to bottom, black calc(100% - var(--mask-fade-width)), transparent);
-    }
-
-    .scroll-fade-y {
-        mask-image: linear-gradient(to bottom, transparent, black var(--mask-fade-width), black calc(100% - var(--mask-fade-width)), transparent);
-    }
-
-    /* ── Fading scroll — the scroll-STATE-driven edge fade (BA.W-FADING-SCROLL) ──
-       `<FadingScroll>`'s recipe. SUPERSEDES the scroll-BLIND `.scroll-fade-*`
-       masks above (which feathered both edges unconditionally — the R8-08 "Shy"
-       defect). Here each edge's ramp width is a registered `--fade-start` /
-       `--fade-end` custom (above, default 0px = SHARP), driven by the
-       `scroll(self)` timeline so the start edge feathers only past `scroll > 0`
-       and the end edge only while trailing overflow remains.
-
-       The root IS the scroll port (the component sets overflow via the consumer's
-       utilities — `overflow-x-auto` / `overflow-y-auto` come from the class the
-       consumer passes; the axis floor below sets the OTHER axis). The 4-stop
-       mask reads the two customs; at rest both are 0px so the gradient is a flat
-       opaque pass-through (no feather). */
-    .fading-scroll {
-        /* The base mask is axis-specialized by the modifier classes below. The
-           default-x case uses the inline ramp; the y case the block ramp. */
-        mask-image: linear-gradient(
-            to right,
-            transparent 0,
-            black var(--fade-start),
-            black calc(100% - var(--fade-end)),
-            transparent 100%
-        );
-    }
-    .fading-scroll--x {
-        overflow-x: auto;
-        mask-image: linear-gradient(
-            to right,
-            transparent 0,
-            black var(--fade-start),
-            black calc(100% - var(--fade-end)),
-            transparent 100%
-        );
-    }
-    .fading-scroll--y {
-        overflow-y: auto;
-        mask-image: linear-gradient(
-            to bottom,
-            transparent 0,
-            black var(--fade-start),
-            black calc(100% - var(--fade-end)),
-            transparent 100%
-        );
-    }
-
-    /* The NATIVE primary path: drive the per-edge customs off a `scroll(self)`
-       timeline — ZERO JS on a supporting engine (the `scroll-driven.css` /
-       Baseline-Newly-Available bar). UNLIKE `scroll-driven.css` this is NOT
-       wrapped in `prefers-reduced-motion: no-preference` — the fade is a
-       LEGIBILITY cue, not motion, so it stays present under PRM (it merely stops
-       interpolating; the discrete overflow-edge presence stays correct, and the
-       registered customs make even the static endpoints land right). */
-    @supports (animation-timeline: scroll()) {
-        /* The start edge: from sharp (0) to feathered, completing within the
-           first `--fade-scroll-width` of scroll — so at `scroll = 0` the start is
-           SHARP and it ramps in only once the user genuinely scrolls past. */
-        @keyframes gl-fade-start-in {
-            from {
-                --fade-start: 0px;
-            }
-            to {
-                --fade-start: var(--fade-scroll-width);
-            }
-        }
-        /* The end edge: feathered while trailing overflow remains, ramping OUT to
-           sharp over the last `--fade-scroll-width` of scroll — so at the scroll
-           end (no trailing overflow) the end is SHARP. */
-        @keyframes gl-fade-end-out {
-            from {
-                --fade-end: var(--fade-scroll-width);
-            }
-            to {
-                --fade-end: 0px;
-            }
-        }
-        /* x axis — `scroll(self inline)`; two animations on the ONE element, each
-           gated by `animation-range` to the start / end sliver of the scroll
-           distance. `fadeStart`/`fadeEnd` props toggle their respective
-           animation off via the `[data-fade-*]` presence attrs. */
-        .fading-scroll--x[data-fade-start] {
-            animation: gl-fade-start-in linear both;
-            animation-timeline: scroll(self inline);
-            animation-range: 0 var(--fade-scroll-width);
-        }
-        .fading-scroll--x[data-fade-end] {
-            animation: gl-fade-end-out linear both;
-            animation-timeline: scroll(self inline);
-            animation-range: calc(100% - var(--fade-scroll-width)) 100%;
-        }
-        /* BOTH edges on one element compose as two named animations. */
-        .fading-scroll--x[data-fade-start][data-fade-end] {
-            animation:
-                gl-fade-start-in linear both,
-                gl-fade-end-out linear both;
-            animation-timeline: scroll(self inline), scroll(self inline);
-            animation-range:
-                0 var(--fade-scroll-width),
-                calc(100% - var(--fade-scroll-width)) 100%;
-        }
-        /* y axis — `scroll(self block)`. */
-        .fading-scroll--y[data-fade-start] {
-            animation: gl-fade-start-in linear both;
-            animation-timeline: scroll(self block);
-            animation-range: 0 var(--fade-scroll-width);
-        }
-        .fading-scroll--y[data-fade-end] {
-            animation: gl-fade-end-out linear both;
-            animation-timeline: scroll(self block);
-            animation-range: calc(100% - var(--fade-scroll-width)) 100%;
-        }
-        .fading-scroll--y[data-fade-start][data-fade-end] {
-            animation:
-                gl-fade-start-in linear both,
-                gl-fade-end-out linear both;
-            animation-timeline: scroll(self block), scroll(self block);
-            animation-range:
-                0 var(--fade-scroll-width),
-                calc(100% - var(--fade-scroll-width)) 100%;
-        }
-    }
-
-    /* ── Deferred section — render-skip an offscreen subtree (AQ.W3 §5) ──────
-       `content-visibility: auto` skips layout/paint/style of an offscreen
-       subtree — the INP-under-load lever (fourier γ, muster, speedtest, words).
-       `contain-intrinsic-size: auto <estimate>` is measurement-safe: the `auto`
-       prefix makes the engine REMEMBER the last-rendered size (no scroll-jump on
-       re-entry); plain `<estimate>` freezes the section + thrashes the scrollbar
-       — the trap this closes. Estimate is token-driven (`--deferred-section-
-       size`, default 30rem). `.deferred-section--cached` →
-       `content-visibility: hidden` (always skipped, state CACHED — cheaper to
-       re-show than `display:none`). Baseline Widely; unsupporting engines render
-       normally. JS HOOK: the engine fires `contentvisibilityautostatechange`
-       { skipped } at the render-skip boundary — pair with `useRAFLoop`
-       pause/resume: `el.addEventListener('contentvisibilityautostatechange',
-       e => e.skipped ? loop.pause() : loop.resume())`. */
-    .deferred-section {
-        content-visibility: auto;
-        contain-intrinsic-size: auto var(--deferred-section-size, 30rem);
-    }
-    .deferred-section--cached {
-        content-visibility: hidden;
-        contain-intrinsic-size: auto var(--deferred-section-size, 30rem);
-    }
-
-    /* ── Card scroll-timeline host (AI.W1-α) ───────────────────────────────
-       Canonical scroll-overflow host that emits the `--card-scroll` named
-       scroll-timeline consumed by `<CardHeader shrink>`. Apply to the
-       scroll-overflow ancestor (typically the `<Card>` itself OR a wrapper
-       inside it that carries `overflow-y: auto`).
-
-       `contain: layout style paint` isolates the named timeline so child
-       animations respond to THIS host's scroll only — not to portal-
-       triggered layout shifts in ancestor containers (the load-bearing
-       isolation guarantee the value.js `PaneHeader.vue:18-29` comment
-       called out and the AI.W1 spec §1.2 ratified as canon).
-
-       Disambiguated from `.scroll-fade-*` (mask-image fade gradient at
-       the container's leading/trailing edge) — `.card-scroll-host` does
-       NOT paint any visual; it only emits the timeline. */
-    .card-scroll-host {
-        contain: layout style paint;
-        scroll-timeline: --card-scroll block;
-    }
-
-    /* ── Shimmer text effects ──
-       The text-fill + background-clip composition is load-bearing visual
-       (the gold gradient itself); only the `animation:` line is wrapped in
-       the PRM no-preference bracket so PRM users see the static gradient
-       without the slide animation. */
-    .gold-shimmer {
-        background: linear-gradient(90deg, var(--color-gold-dark), var(--color-gold-light), var(--color-gold), var(--color-gold-light), var(--color-gold-dark));
-        background-size: 250% 100%;
-        background-clip: text;
-        -webkit-background-clip: text;
-        color: transparent;
-    }
-    @media (prefers-reduced-motion: no-preference) {
-        .gold-shimmer {
-            animation: gold-shimmer-slide var(--duration-shimmer) linear infinite;
-        }
-    }
-
-    /* ── Keyboard key ── */
-    .kbd {
-        display: inline-flex;
-        align-items: center;
-        justify-content: center;
-        min-height: 1.5rem;
-        min-width: 1.5rem;
-        padding: 0 0.375rem;
-        font-family: var(--font-mono);
-        font-size: var(--type-micro);
-        background: var(--muted);
-        border: 1px solid var(--border);
-        border-radius: var(--radius-sm);
-        box-shadow: 0 1px 0 1px color-mix(in srgb, var(--border) 30%, transparent);
-        line-height: 1;
+    /* ── Glass-press — the interactive press register (BB.W-PRESS-UNIFY) ──
+       The CSS half of the `<Card :pressable>` / interactive-glass press. Two
+       coupled legs on ONE `--card-press-t` drive (the `useLiquidPress` writes the
+       JS-driven value; the CSS `:active` is the no-JS / SSR floor):
+
+         • The SCALE leg is the co-composed `.tap-squish` (the Card binds both
+           classes), so the no-JS press already scales to `--scale-press` on the
+           `--spring-smooth` clock and the JS reciprocal squish wins while engaged.
+         • The BRIGHTNESS leg reads the `--card-press-t` drive directly — a sub-
+           perceptual `filter: brightness()` lift so the glass reads as DEFORMING +
+           catching light under the press, not just shrinking (the W-MOTION-CANON P3
+           coupling — fade/brightness coupled WITH the transform on the same drive).
+           `filter` is compositor-safe (the P5 ban targets layout props only —
+           `proof:no-layout-animation` greens it), so the lift never re-layouts.
+
+       The brightness leg rides the `--card-press-t` VALUE (the typed press drive),
+       NOT a CSS transition — it tracks the JS spring frame-for-frame and degrades to
+       the resting 0 (no lift) when JS is off. The press surface is INTERACTIVE: the
+       cursor + a WCAG-2.5.5 touch floor (`min-block-size`) read here, not on the
+       static-card register. The interruptibility + the PRM-instant snap are the JS
+       driver's (`useLiquidPress` → the kf `SpringProgress` re-seat + the PRM policy);
+       this is the CSS floor the JS enhances. */
+    .glass-press {
+        cursor: pointer;
+        min-block-size: max(0px, var(--control-floor, 0px));
+        /* The coupled brightness lift on the press drive (rest 0 → ~4% at full
+           press). The drive is the JS-written `--card-press-t`; with JS off it stays
+           the `@property` 0 initial so the filter is a no-op (`brightness(1)`). */
+        filter: brightness(calc(1 + var(--card-press-t, 0) * 0.04));
+    }
+    /* The press-drive typed registration so a downstream `calc()` interpolates the
+       VALUE (number) and an unwired/SSR card is the static rest frame. */
+    @property --card-press-t {
+        syntax: "<number>";
+        inherits: true;
+        initial-value: 0;
     }
 
 }

package/src/styles/utilities/btn.css

@@ -49,12 +49,23 @@
    Shared compound transition for interactive controls that animate their
    surface (background-color/color/box-shadow/border-color) on the four-state
    contract. Replaces the per-site
-   `transition-[background-color,color,box-shadow,border-color] duration-[var(--duration-fast)] ease-[var(--ease-standard)]`
+   `transition-[background-color,color,box-shadow,border-color] duration-[var(--duration-control)] ease-[var(--ease-standard)]`
    arbitrary wraps at ≥2 sites (TabsTrigger, SelectTrigger, Toggle `card`
-   variant). Binds the canonical --duration-fast + --ease-standard tokens. */
+   variant).
+
+   BC.W-CONTROL-SMOOTH — the surface legs read the QUICK control clock
+   `--duration-control` (0.12s, the named iOS control-press surface beat,
+   scheme-motion.css), NOT the 0.2s calm `--duration-fast`. A control the user
+   actively pokes wants the ~100-120ms quick beat that tracks the cursor; the
+   prior 0.2s dragged the colour/border/shadow VISIBLY behind the press (the §F
+   "super laggy" read). The bezier `--ease-standard` STAYS (a colour cross-fade
+   on a spring wobbles — §6 binding); the property list stays SURFACE-ONLY (no
+   `transform` leg — the press-squish is `.tap-squish`/`useSpringPress`'s spring
+   job, the canonical split). One token re-times the whole 12-consumer control
+   family. */
 @utility transition-control {
     transition-property: background-color, color, box-shadow, border-color;
-    transition-duration: var(--duration-fast);
+    transition-duration: var(--duration-control);
     transition-timing-function: var(--ease-standard);
 }
 
@@ -69,7 +80,9 @@
 }
 
 /* ── Sheet/drawer slide-out animation grammar ──
-   Mirror of `.popover-animate` for sheet/drawer panels. Pairs with
+   The sheet/drawer-panel analogue of the overlay enter (the popover-class
+   surfaces now ride the spring-clocked `.glass-reveal`, BB.W-LIQUID-REVEAL).
+   Pairs with
    `slide-in-from-{top,right,bottom,left}-N` to compose side-keyed entries.
    The open path uses --duration-panel (slow, deliberate); the close path
    uses --duration-fast so dismiss feels snappy. R5 vocab.γ gap row 6;

package/src/styles/utilities/components.css

@@ -31,11 +31,17 @@
         background: var(--metric-badge-bg, var(--glass-bg-quiet));
         backdrop-filter: var(--metric-badge-blur, var(--glass-blur-quiet));
         box-shadow: var(--metric-badge-shadow, 0 1px 6px color-mix(in srgb, var(--shadow-color) 8%, transparent), var(--glass-highlight));
+        /* SPATIAL/EFFECTS split (motion-canon P1): the EFFECTS legs
+           (background/border-color/box-shadow) ride the bezier --ease-standard;
+           the SPATIAL hover-lift legs (translate/scale) ride the --spring-smooth
+           hover register on its own settle clock --spring-smooth-duration (the
+           ONE interactive transform register .btn-pill/.glass-btn settle on). */
         transition:
             background var(--duration-fast) var(--ease-standard),
             border-color var(--duration-fast) var(--ease-standard),
             box-shadow var(--duration-fast) var(--ease-standard),
-            scale var(--duration-fast) var(--ease-standard);
+            translate var(--spring-smooth-duration) var(--spring-smooth),
+            scale var(--spring-smooth-duration) var(--spring-smooth);
     }
 
     .metric-badge > span {
@@ -49,11 +55,17 @@
 
     .metric-badge:hover {
         /* Hover lifts to the `resting` rung — one step up the canonical
-           ladder (audit U.W0.C-c §7.2). */
+           ladder (audit U.W0.C-c §7.2). BC.W-AX-METRIC-HOVER lifts the badge
+           into a tactile VALUE-LIFT: it nudges UP (--metric-badge-hover-translate
+           -2px) + scales a hair more (1.04) + casts the cartoon-sticker offset
+           shadow (--shadow-cartoon-sm) — token-first, so a consumer zeroes the
+           lift from :root (--metric-badge-hover-translate: 0). Compositor-only
+           (translate/scale/box-shadow — proof:no-layout-animation holds). */
         border-color: var(--metric-badge-hover-border, var(--glass-border-resting));
         background: var(--metric-badge-hover-bg, var(--glass-bg-resting));
-        box-shadow: var(--metric-badge-hover-shadow, 0 2px 10px color-mix(in srgb, var(--shadow-color) 12%, transparent), var(--glass-highlight));
-        scale: var(--metric-badge-hover-scale, 1.02);
+        box-shadow: var(--metric-badge-hover-shadow, var(--shadow-cartoon-sm), var(--glass-highlight));
+        translate: 0 var(--metric-badge-hover-translate, -2px);
+        scale: var(--metric-badge-hover-scale, 1.04);
     }
 
     .metric-badge:active {
@@ -212,7 +224,14 @@
         backdrop-filter: var(--glass-blur-floating);
 
         padding: 0 0.75rem;
-        height: 2.25rem;
+        /* BC.W-SEARCH-CUSTOM — the height reads the shared `--control-pill-h`
+           element-override seam (the SAME rung `.input-pill` reads), DEFAULTING to
+           `--control-h-sm` so a bare search bar is byte-identical to the HEAD
+           2.25rem pill. `controlSizeClass(size)` (_shared/useControlSize.ts) re-points
+           the seam per rung (sm→`--control-h-xs`-ish via the cohort, lg→`--control-h-lg`),
+           so the SearchBar/FuzzySearch `size` prop retunes the field height WITHOUT a
+           recipe fork — ONE substitution rung, the cohort is still the source. */
+        height: var(--control-pill-h, var(--control-h-sm));
         max-width: var(--max-width-input);
         width: 100%;
         transition:
@@ -226,7 +245,13 @@
 
     .input-bar-field {
         font-family: var(--font-mono, monospace);
-        font-size: var(--type-small);
+        /* BC.W-SEARCH-CUSTOM — the field font reads the shared `--control-pill-text`
+           seam (the SAME rung `.input-pill` reads), DEFAULTING to `--control-text`
+           (≈ the prior `--type-small` register at scale 1 — byte-near-identical). The
+           `controlSizeClass("sm")` rung re-points it to `--control-text-sm` (quieter);
+           `default`/`lg` keep `--control-text`. So the search field type tracks the
+           cohort under `--ui-scale`, NOT a static `--type-small` literal. */
+        font-size: var(--control-pill-text, var(--control-text));
         background: transparent;
         border: none;
         outline: none;

package/src/styles/utilities/metal.css

@@ -0,0 +1,215 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   BB.W-METAL-SHIMMER — the brand-metal utility family
+   ═══════════════════════════════════════════════════════════════════════════
+   ONE single-home partial for the gold·silver·bronze metal register (so a new
+   metal pop is ONE class, not a re-paste — the W-SUFFUSE icon-chip consolidation
+   discipline). Three registers, ALL metal-PARAMETERIZED off the SAME shared recipe
+   reading the `--metal-shimmer-color` channel + its four resolved stop slots:
+
+     • `.metal-{gold,silver,bronze}` — the text-clip metal gradient (the
+       `.gold-shimmer` recipe GENERALIZED): a `linear-gradient(90deg, dark, light,
+       base, light, dark)` band off the bound metal quad, `background-clip: text`.
+     • `.metal-{gold,silver,bronze}-border` — the swept metallic RIM (the §N6
+       selected-item-border consumer): the SAME `--metal-shimmer-color`-bound
+       gradient on a `border-image`-sliced rim, swept by the SAME keyframe.
+     • `.metal-rainbow-rim` — the prismatic gilt-figure / record-badge rim: it
+       COMPOSES W-GLASS-ACCENT's `--glass-accent` rim seam (it does NOT re-author
+       the rim) by binding the accent channel to a swept rainbow hue.
+
+   The PARAMETERIZATION: `--metal-shimmer-color` is the metal-NAME marker each
+   `.metal-{name}` SETS (`gold`/`silver`/`bronze`); the shared recipe resolves the
+   gradient off the four `--metal-stop-*` slots each class binds to its quad. The
+   `metal-shimmer-sweep` keyframe (animations.css) is PURE position — ZERO baked
+   metal color — so the SAME keyframe sweeps any of the three metals depending only
+   on which slots the class bound. A silver/bronze sweep is a NEW CLASS that binds
+   the slots, NEVER a forked keyframe (the N-copy this wave exists to kill).
+
+   THE PRM-STATIC BRACKET (the §6 calm register, the `.gold-shimmer` model byte-
+   faithfully): every utility paints the FULL static metal gradient at REST (the
+   load-bearing visual — the metal sheen itself); ONLY the `animation:` line sits
+   inside `@media (prefers-reduced-motion: no-preference)`. A PRM user sees the
+   full static metal gradient WITHOUT the slide — the metal still READS as metal,
+   the motion is the only thing gated. The sweep is a slow `--duration-metal` (6s)
+   one-pass — the disco family is GONE and STAYS gone (no sparkle/grain/ripple). */
+
+@layer components {
+    /* ── The shared metal recipe (the metal-agnostic engine) ─────────────────
+       The four stop slots default to GOLD (the neutral metal — so a bare
+       `--metal-shimmer-color`-bearing surface paints gold, matching the
+       `.gold-shimmer` precedent); each `.metal-{name}` re-binds them to its quad.
+       The `--metal-shimmer-color` marker carries the metal NAME for the gate's
+       parameterization assert + for any consumer query. */
+    .metal-gold,
+    .metal-silver,
+    .metal-bronze {
+        --metal-stop-dark: var(--color-gold-dark);
+        --metal-stop-light: var(--color-gold-light);
+        --metal-stop-base: var(--color-gold);
+        background: linear-gradient(
+            90deg,
+            var(--metal-stop-dark),
+            var(--metal-stop-light),
+            var(--metal-stop-base),
+            var(--metal-stop-light),
+            var(--metal-stop-dark)
+        );
+        background-size: 250% 100%;
+        background-clip: text;
+        -webkit-background-clip: text;
+        color: transparent;
+
+        /* ── BC.W-AX-METAL-GLOW — the gold catch-light (the lit-metal halo) ──────
+           A soft glow halo of the metal's OWN base hue behind the gradient text-clip
+           so the gold reads as LIT metal (light catching its surface), not a flat
+           gradient fill. Because `background-clip: text` makes the text transparent,
+           a `filter: drop-shadow` follows the clipped glyph shape — the halo hugs the
+           letters. ONE recipe on the shared selector (every metal lit, never a per-
+           metal re-paste); the glow reads `--metal-stop-base` so gold halos gold,
+           silver halos silver, bronze halos bronze (NOT a fixed gold-on-every-metal
+           mismatch). The earned-gold register (Q2): `.metal-gold`'s base is
+           `--color-gold`, so the gold catch-light is the earned-gold warm glow.
+
+           PRM-STATIC: the glow paints HERE, at rest, OUTSIDE the no-preference
+           bracket — the lit metal reads for PRM users; ONLY the sweep `animation:`
+           is gated (the §6 calm register; the disco family stays gone — this is a
+           soft warm whisper bounded by `--metal-glow-opacity`, not a neon bloom). */
+        --metal-glow-blur: var(--metal-glow-blur-default, 0.5em);
+        --metal-glow-opacity: var(--metal-glow-opacity-default, 0.35);
+        filter: drop-shadow(
+            0 0 var(--metal-glow-blur)
+                color-mix(
+                    in srgb,
+                    var(--metal-stop-base) calc(var(--metal-glow-opacity) * 100%),
+                    transparent
+                )
+        );
+    }
+
+    /* Per-metal: set the channel marker + re-bind the stop slots to the quad. */
+    .metal-gold {
+        --metal-shimmer-color: gold;
+        --metal-stop-dark: var(--color-gold-dark);
+        --metal-stop-light: var(--color-gold-light);
+        --metal-stop-base: var(--color-gold);
+    }
+    .metal-silver {
+        --metal-shimmer-color: silver;
+        --metal-stop-dark: var(--color-silver-dark);
+        --metal-stop-light: var(--color-silver-light);
+        --metal-stop-base: var(--color-silver);
+    }
+    .metal-bronze {
+        --metal-shimmer-color: bronze;
+        --metal-stop-dark: var(--color-bronze-dark);
+        --metal-stop-light: var(--color-bronze-light);
+        --metal-stop-base: var(--color-bronze);
+    }
+
+    /* ── The swept metallic RIM (the §N6 selected-item-border consumer) ───────
+       The SAME `--metal-shimmer-color`-bound gradient applied to a `border-image`
+       slice — a swept metallic RIM, not a text fill. `border-image` reads the same
+       `background`-position-swept gradient (the metal-shimmer-sweep keyframe drives
+       the `background-position`; the `border-image-source` references the SAME
+       gradient via the stop slots), so ONE keyframe drives both registers. The rim
+       sits over the surface's own background (no `background-clip: text`). */
+    .metal-gold-border,
+    .metal-silver-border,
+    .metal-bronze-border {
+        --metal-stop-dark: var(--color-gold-dark);
+        --metal-stop-light: var(--color-gold-light);
+        --metal-stop-base: var(--color-gold);
+        border: var(--metal-border-width, 2px) solid transparent;
+        border-image: linear-gradient(
+                90deg,
+                var(--metal-stop-dark),
+                var(--metal-stop-light),
+                var(--metal-stop-base),
+                var(--metal-stop-light),
+                var(--metal-stop-dark)
+            )
+            1;
+        /* The sweep rides a backing gradient `background-position` on the same band
+           (the `border-image` slice tracks the host's background extent); the
+           250% size + the position sweep give the rim its travelling sheen. */
+        background-image: linear-gradient(
+            90deg,
+            var(--metal-stop-dark),
+            var(--metal-stop-light),
+            var(--metal-stop-base),
+            var(--metal-stop-light),
+            var(--metal-stop-dark)
+        );
+        background-size: 250% 100%;
+        background-clip: border-box;
+    }
+    .metal-gold-border {
+        --metal-shimmer-color: gold;
+        --metal-stop-dark: var(--color-gold-dark);
+        --metal-stop-light: var(--color-gold-light);
+        --metal-stop-base: var(--color-gold);
+    }
+    .metal-silver-border {
+        --metal-shimmer-color: silver;
+        --metal-stop-dark: var(--color-silver-dark);
+        --metal-stop-light: var(--color-silver-light);
+        --metal-stop-base: var(--color-silver);
+    }
+    .metal-bronze-border {
+        --metal-shimmer-color: bronze;
+        --metal-stop-dark: var(--color-bronze-dark);
+        --metal-stop-light: var(--color-bronze-light);
+        --metal-stop-base: var(--color-bronze);
+    }
+
+    /* ── The prismatic rainbow rim (the gilt-figure / record-badge sheen) ─────
+       COMPOSES W-GLASS-ACCENT's `--glass-accent` rim seam (it binds the accent
+       channel, it does NOT re-author the rim `color-mix`/`::before`). The host is
+       a glass surface (carrying the `--glass-material-rim` ring + the
+       `--glass-border-accent` border W-GLASS-ACCENT minted); this utility drives
+       the accent through the spectrum so the rim sheen SHIFTS through the rainbow.
+       `--glass-accent` is a typed `<color>` `@property` (NOT animatable as a
+       conic per-frame), so the prismatic shift is the swept metal-gradient overlay
+       PLUS the accent engaged at a metal-warm hue — the rim reads as a shifting
+       metallic sheen over the W-GLASS-ACCENT rim. The accent STRENGTH lifts to a
+       rim whisper (the demo specimen engages ~45%, the accent's documented ceiling
+       for the rim/glint). The sweep is the SAME `metal-shimmer-sweep` over the
+       rainbow band on the host's own background. */
+    .metal-rainbow-rim {
+        /* Engage W-GLASS-ACCENT's rim seam at a warm-metal hue + the rim whisper
+           strength (the accent channel — NOT a second rim recipe). */
+        --glass-accent: var(--color-gold);
+        --glass-accent-strength: 45%;
+        --metal-shimmer-color: rainbow;
+        /* The swept prismatic band rides the host's own background-image (the rim
+           ring + border come from the W-GLASS-ACCENT seam the host already carries). */
+        background-image: linear-gradient(
+            90deg,
+            var(--rainbow-red),
+            var(--rainbow-orange),
+            var(--rainbow-yellow),
+            var(--rainbow-green),
+            var(--rainbow-blue),
+            var(--rainbow-indigo),
+            var(--rainbow-violet),
+            var(--rainbow-red)
+        );
+        background-size: 250% 100%;
+        background-clip: border-box;
+    }
+
+    /* ── The PRM-static bracket: the ONLY motion declaration ──────────────────
+       Every metal utility paints the static gradient above (un-bracketed — the
+       metal READS for PRM users); the `animation:` is the sole thing gated. The
+       slow `--duration-metal` (6s) clock — the calm dignified pass. */
+    @media (prefers-reduced-motion: no-preference) {
+        .metal-gold,
+        .metal-silver,
+        .metal-bronze,
+        .metal-gold-border,
+        .metal-silver-border,
+        .metal-bronze-border,
+        .metal-rainbow-rim {
+            animation: metal-shimmer-sweep var(--duration-metal) linear infinite;
+        }
+    }
+}