@mkbabb/glass-ui 3.9.0 → 3.10.0

package/src/styles/animations.css

@@ -141,33 +141,89 @@
     100% { background-position: -200% 0; }
 }
 
-/* ── Sparkle sweep: four-point star traverses a surface diagonally ──
+/* ── Crayon-wipe: the scroll-scrubbed draw-on (D6.c M1) ──────────────────────
  *
- * Reserved for the chassis primary-action hover (dock-tab-button[data-tier="primary"])
- * and the `Complete!` shimmer cycle. Single keyframe, ~600ms per pass; the
- * consumer rule sets the duration and easing. Reduced-motion guard at the
- * consumer site (per surface — not all sparkle uses share the same gate).
+ * The bidirectional, scroll-scrubbed DRAW-ON of a hand-mark (the crayon/pen
+ * underline, a drawn rule). The wipe is a `clip-path: inset()` of the LEFT edge
+ * only — the mark draws from inset(0 100% 0 0) (fully clipped from the right, so
+ * NOTHING shows) to inset(0) (fully revealed) — so the underline DRAWS as the
+ * figure scrolls into view and UN-DRAWS as it scrolls back up. `clip-path` is the
+ * compositor-eligible, FILTER-STABLE wipe (the medium's grain `feTurbulence`
+ * rasters ONCE and is untouched by the clip — the cardinal "no per-frame raster"
+ * discipline ds2-motion-field M1 names): clip-path animates on the compositor and
+ * never re-runs the static filter, unlike a `stroke-dashoffset` draw under the
+ * grain filter (which re-rasters per frame). The grammar mirrors scroll-driven.css
+ * (the `view()`/`scroll()` timeline home): the keyframe lives here (the shared
+ * @keyframes register); a consumer binds it to a NAMED `view-timeline` so the
+ * draw-on SCRUBS bidirectionally with scroll (forward → draws, back → un-draws),
+ * never a one-shot. The `.crayon-wipe` utility below is the binding.
+ *
+ * The keyframe itself is timeline-agnostic — it is equally a load-clock draw-on
+ * (bound to a keyframes.js Sequence) or a scroll scrub (bound to a view-timeline).
+ * The DEFAULT consumer is the scroll scrub (the figure-item underline drawing into
+ * the lower third), hence the utility's `view()` binding.
+ *
+ * Reduced-motion: the utility (NOT the keyframe) gates — under PRM the mark is SET
+ * to inset(0) (fully drawn, never animated), the correct degrade for a permanent
+ * structural draw (information parity: the underline is present, just not drawn).
  */
-@keyframes sparkle-sweep {
-    0% {
-        transform: translate(-30%, -30%) scale(0.5);
-        opacity: 0;
-    }
-    25% {
-        opacity: 1;
+@keyframes crayon-wipe {
+    from {
+        /* clipped from the RIGHT by 100% → the mark is fully hidden (nothing
+           drawn yet); the left edge is the pen-tip about to move right. */
+        clip-path: inset(0 100% 0 0);
     }
-    100% {
-        transform: translate(180%, 180%) scale(1.2);
-        opacity: 0;
+    to {
+        /* fully revealed — the mark is wholly drawn. */
+        clip-path: inset(0 0 0 0);
     }
 }
 
-@media (prefers-reduced-motion: reduce) {
-    @keyframes sparkle-sweep {
-        0%, 100% { opacity: 0; transform: none; }
+/* ── .crayon-wipe — bind the wipe to a scroll view-timeline (D6.c M1) ──────────
+ * The scroll-scrubbed draw-on utility. A consumer puts `.crayon-wipe` on a
+ * hand-mark surface (the underline span, a drawn rule) and the mark draws/un-draws
+ * as it scrolls through its OWN `view()` timeline — a bidirectional scrub, free,
+ * off the main thread. The animation is `paused` with `animation-timeline: view()`
+ * so the scroll position IS the playhead (the native scroll-driven model — the
+ * timeline drives the frame, time does not). The named timeline is overridable
+ * (`--crayon-wipe-timeline`, default the element's own `view()`) so a consumer can
+ * scrub off a SHARED beat timeline (the §--beat-tl the atlas scroll-driven.css
+ * names) instead of the per-element view — that is the "named view-timeline so a
+ * consumer scrubs a draw-on bidirectionally" contract.
+ *
+ * @supports-gated + PRM-OUTER-gated, mirroring scroll-driven.css exactly: the
+ * whole binding sits under `prefers-reduced-motion: no-preference`, so under PRM
+ * the animation never attaches and the mark renders in its terminal `inset(0)`
+ * (fully-drawn) state — the static-draw degrade. The draw range is `entry`-keyed
+ * (the mark draws as it ENTERS the lower viewport), tunable via
+ * `--crayon-wipe-range-{start,end}`. */
+@media (prefers-reduced-motion: no-preference) {
+    @supports ((animation-timeline: view()) and (animation-range: entry)) {
+        .crayon-wipe {
+            animation: crayon-wipe auto linear both;
+            animation-timeline: var(--crayon-wipe-timeline, view(block));
+            animation-range: var(--crayon-wipe-range-start, entry 0%)
+                var(--crayon-wipe-range-end, cover 35%);
+        }
     }
 }
 
+/* ── Sparkle sweep: TOMBSTONE (D6.b — the disco-star excision) ──
+ *
+ * @deprecated 3.10 — DELETE in 3.11. The four-point `✦` star sweep was the one
+ * garish gesture in the library; the user named it for removal ("remove the disco
+ * star from all glass-ui elements"). Every in-tree consumer is re-homed: the
+ * `btn-audacious` hover affirmation now rides the specular catch-light alone; the
+ * gold-CTA rides the `btn-gold-bg-sweep` metal-catch; the chassis `complete`
+ * celebration re-homes to the `.text-gilt` one-shot (utilities.css). The keyframe
+ * body is EMPTIED rather than deleted for ONE minor so any out-of-tree consumer
+ * (the slides decks) fails SOFT — a no-op animation, not an unknown-animation
+ * error. The `--duration-sparkle` token is `@deprecated` alongside (tokens.css).
+ * Full delete (this block + the token + the theme bridge) lands in 3.11. */
+@keyframes sparkle-sweep {
+    /* intentionally empty — tombstoned, see deprecation note above */
+}
+
 /* ── Pulse dot bounce: dots variant of <Pulse> ──
  *
  * Three-dot loading indicator. Opacity 0.35 ↔ 1, scale 0.8 ↔ 1.2. Consumer

package/src/styles/cards.css

@@ -38,8 +38,8 @@
        mints the stacking context once. Longhand maps `translate(x, y)` 1:1. */
     translate: 0;
     transition:
-        translate var(--duration-normal) var(--spring-bouncy),
-        box-shadow var(--duration-normal) var(--ease-apple);
+        translate var(--duration-normal) var(--spring-smooth),
+        box-shadow var(--duration-normal) var(--ease-standard);
 
     &:hover:not(:disabled) {
         translate: var(--lift-sm) var(--lift-sm);

package/src/styles/dock/layer-group.css

@@ -183,7 +183,19 @@
        it at the top tab and it NEVER reached the active tab below (the mis-alignment
        the user screenshotted). The default rule below travels Y; the `.vertical`
        group's ROW rail overrides back to X. The active-tab plate reads the tunable
-       `--dock-layer-rail-active` rung. Both morph on `--dock-motion-resize`. */
+       `--dock-layer-rail-active` rung.
+
+       AY.W-DOCK2 (D5 one-clock) — the rail indicator travel moves OFF the fixed-
+       linear `--dock-motion-resize` SECOND clock (DK7 killed exactly this pattern
+       for the leaving-pane opacity but left it alive on the rail; H-dock §D7 L2) onto
+       the `--spring-snappy` register. DECISION: a rail tab switch is a DISCRETE
+       selection (the user picks a pane), NOT the box collapse↔expand morph — so it
+       does NOT fold onto `--dock-morph-t` (the morph scalar). It uses the iOS
+       segmented-control register (`--spring-snappy`, the SAME curve `SegmentedTabs`'
+       indicator rides — the confirmed discrete-selection register), so the rail
+       indicator glides between tabs on the house spring, never a fixed-linear timer.
+       The binding outcome: NO `--dock-motion-resize` survives on the rail (recorded
+       in W-DOCK2-DELTA.md). */
     .dock-layer-rail .dock-layer-tab-indicator {
         position: absolute;
         left: 0;
@@ -197,9 +209,9 @@
             color-mix(in srgb, var(--primary) 15%, transparent)
         );
         transition:
-            width var(--dock-motion-resize),
-            height var(--dock-motion-resize),
-            transform var(--dock-motion-resize);
+            width var(--duration-fast) var(--spring-snappy),
+            height var(--duration-fast) var(--spring-snappy),
+            transform var(--duration-fast) var(--spring-snappy);
         pointer-events: none;
     }
 

package/src/styles/dock-controls.css

@@ -24,23 +24,21 @@
        toward `--scale-press-dock` settles on a NO-OVERSHOOT spring (Apple,
        "Designing Fluid Interfaces": default 100% damping — no bounce — for a tap;
        reserve bounce for surfaces driven by gesture MOMENTUM). The dock controls
-       are tap surfaces (no momentum), so the press re-binds `--dock-press-spring`
-       from the bouncy preset (`--spring-bouncy`, ~+20% overshoot, defined in
-       tokens.css §-2) to `--spring-smooth` — the critically-damped (ζ≈1, ~0.4%
-       peak) iOS tap curve. Token-routed (an existing spring preset, never a raw
-       cubic-bezier); the `--duration-fast` prefix is kept so the squish-back stays
-       quick. Every dock-control `scale var(--dock-press-spring)` press transition
-       (and the select chevron's `rotate`) inherits this one binding. A future
-       momentum-gated surface (none today) would override this back to a bouncy
-       preset on its own scope. The `:where()` group keeps zero specificity so a
-       consumer override of `--dock-press-spring` still wins. */
+       are tap surfaces (no momentum).
+
+       AY.W-DOCK2 (D6) — the per-surface re-point of `--dock-press-spring` to
+       `--spring-smooth` is DELETED here: the ROOT token (`tokens.css`) IS the §6
+       doctrine register now (`--spring-smooth`), so the re-point was a dead
+       byte-identical redeclaration — the exact per-surface fork the §6 doctrine
+       claims to have killed. The dock controls inherit the correct smooth
+       transform-press register straight from the ROOT token; this `:where()` group
+       keeps ONLY the small-tile specular sizing below. */
     :where(
         .dock-icon-button,
         .dock-tab-button,
         .dock-select-trigger,
         .dock-dropdown-trigger
     ) {
-        --dock-press-spring: var(--duration-fast) var(--spring-smooth);
         /* AX.W45-TUNE C4/C5 — the small-tile specular sizing. The dock controls are
            ~40px tiles, a fraction of a card's plate, so the global 36% specular
            radius blooms a tile-filling disc (the I.W6 finding). The family re-points
@@ -329,21 +327,28 @@
     /* Tier — primary ────────────────────────────────────────────
      *
      * Per W2.7 §9, §12, §13, §17. The primary tier composes three at-rest
-     * marks (top-highlight, bottom under-shadow, baseline glass) with three
-     * disco accents on hover (specular swap, sparkle sweep, disco-grain).
+     * marks (top-highlight, bottom under-shadow, baseline glass) with two
+     * disco accents on hover (specular swap, disco-grain).
+     *
+     * D6.b — the disco-STAR is GONE (the sparkle-sweep sweep is excised from the
+     * underlying `btn-audacious`, utilities.css). The primary dock button's gold
+     * identity — the "golden dock button" the user likes — is RE-EXPRESSED sans
+     * star: a tooled `--gold-rim` gilt edge (the brushed-brass-under-glass read)
+     * plus the surviving specular catch-light + disco-grain on hover. Three quiet
+     * golds replacing one loud star.
      *
      * Reservation: disco fires on hover only. At rest the button reads as
-     * a Vignelli-restrained composed glass surface. The `--phase-color`
-     * cascade (provided by `<InstrumentChassis>` via `data-phase`) tints
-     * the disco-grain radial only on hover; idle is neutral.
+     * a Vignelli-restrained composed glass surface with a hairline gilt edge.
+     * The `--phase-color` cascade (provided by `<InstrumentChassis>` via
+     * `data-phase`) tints the disco-grain radial only on hover; idle is neutral.
      *
-     * K.W6 Lane B — the canonical disco-grain + sparkle-sweep + specular
-     * recipe lifted to `@utility btn-audacious` (utilities.css). The Vue
-     * <DockTabButton> attaches `btn-audacious` automatically when the
-     * consumer passes `data-tier="primary"`. The dock-local rules below
-     * are STRICTLY the dock extension: structural shell (padding, base
-     * surface tint, min-height) + phase-tint extensions (hover radial
-     * uses `--phase-color`, plus the `[data-phase]` `::before` halo).
+     * K.W6 Lane B — the canonical disco-grain + specular recipe lifted to
+     * `@utility btn-audacious` (utilities.css). The Vue <DockTabButton> attaches
+     * `btn-audacious` automatically when the consumer passes `data-tier="primary"`.
+     * The dock-local rules below are STRICTLY the dock extension: structural shell
+     * (padding, base surface tint, min-height) + the gilt-edge gold identity +
+     * phase-tint extensions (hover radial uses `--phase-color`, plus the
+     * `[data-phase]` `::before` halo).
      */
     .dock-tab-button[data-tier="primary"] {
         --dock-tab-min-height: 4rem;
@@ -351,6 +356,17 @@
         background: color-mix(in srgb, var(--card) 60%, transparent);
         color: var(--foreground);
 
+        /* D6.b — the gilt edge: a 1px inner `--gold-rim` ring + a faint gold
+           top-catch, the tooled-brass identity that replaces the excised star.
+           A box-shadow (no layout, no paint cost), composing UNDER the hover
+           specular/grain. The gold reads as a bevel light at the edge, never a
+           fill — the surface still reads as composed glass. Idiom mirrors the
+           `.glass-gilt` modifier (glass.css region) at the dock-button scale. */
+        box-shadow:
+            inset 0 0 0 1px var(--gold-rim),
+            inset 0 0.5px 0 0
+                color-mix(in oklab, var(--gold-light) 30%, transparent);
+
         /* Phase-tint hover override — same disco-grain composition as
          * `btn-audacious`, but the radial uses `--phase-color` (instrument-
          * cluster axis) instead of the canonical `--primary`. The `--paper-

package/src/styles/drawer.css

@@ -42,12 +42,20 @@
     height: auto;
     max-height: 97vh;
     margin-top: 6rem;
-    border: 1px solid var(--border);
+    /* The overlay-band glass surface — the heaviest rung (the Drawer is a
+       modal-band sheet, z-index: --z-modal). The oklab tint composite reads the
+       W55 bright bucket (a live-behind sheet over a bright page is the canonical
+       over-light case); the --glass-level knob flattens it to solid --card +
+       blur(0) with the rest of the band; the --glass-shadow-overlay ladder rung
+       carries the rim + the --shadow-2xl lift through the ladder. */
+    background: color-mix(in oklab, var(--glass-bg-overlay), var(--glass-tint-source) var(--glass-tint-strength));
+    backdrop-filter: var(--glass-blur-overlay);
+    -webkit-backdrop-filter: var(--glass-blur-overlay);
+    border: 1px solid var(--glass-border-overlay);
     border-bottom: 0;
     border-start-start-radius: var(--radius-panel);
     border-start-end-radius: var(--radius-panel);
-    background-color: var(--background);
-    box-shadow: var(--shadow-2xl);
+    box-shadow: var(--glass-material-rim), var(--glass-shadow-overlay);
 }
 
 /*
@@ -74,7 +82,7 @@
     margin-top: 0;
     margin-bottom: 6rem;
     border-top: 0;
-    border-bottom: 1px solid var(--border);
+    border-bottom: 1px solid var(--glass-border-overlay);
     border-radius: 0 0 var(--radius-panel) var(--radius-panel);
 }
 

package/src/styles/glass.css

@@ -46,8 +46,15 @@
 
        The `.glass-dock` SHELL is OUT of this group BY DESIGN — it hand-rolls a
        parallel surface (its own `--glass-*-dock` family + a local rim + an
-       instrument-strip `::before`) the dock arm owns; the dock's catch-light
-       lives on its CONTROL (`.dock-icon-button`, listed below), not the shell.
+       instrument-strip `::before`) the dock arm owns. The COHESION CONSEQUENCE is
+       DELIBERATE: the dock shell carries NO shared edge-gleam / moving-specular
+       `::before` (its only `::before` is the `variant-instrument-strip` engraved
+       bezel, dock/shell.css — a different effect). The dock's catch-light lives on
+       its CONTROLS (`.dock-icon-button` et al., listed below + in the opt-in
+       transition block), which ARE in the material group — NOT on the shell plate.
+       Adding a shell gleam would re-introduce glass-on-glass over the controls, so
+       the shell-without-gleam is a NAMED EXEMPTION, gated as `dock-shell-exempt` in
+       proof:glass-cohesion (the only exemption beside the legibility allowlist).
 
        The selector GROUP is the single source. Adding a surface to the band
        material is one comma-entry here, not a new opt-in class string. */
@@ -146,6 +153,37 @@
            a plain low-alpha warm overlay (the gleam composes normally — no blend, no
            blowout), the no-workaround floor; NOT a `screen` fallback. */
         mix-blend-mode: plus-lighter;
+        /* The moving-specular TRANSITION is NOT declared here. An idle/unwired
+           `::before` is STATIC (no interpolation track), so a bare glass rung / an
+           un-armed Card / a glass Button at rest attaches ZERO animation tracks (the
+           keyframes.js runtime counts 0 idle tracks, not 19). The transition rides
+           ONLY the WIRED + interactive surfaces — the opt-in scoped block below. */
+    }
+
+    /* AY.W-GLASS — the moving-specular transition is OPT-IN (the Card wire-or-omit
+       pattern, generalized). It attaches ONLY to a WIRED surface
+       (`.glass-specular-track` — Card emits it conditionally, the dock controls + the
+       Slider thumb compose it) OR to any glass surface under `:hover`/`:active` (the
+       pointer is present, so the interpolation is legitimately live). An idle/unwired
+       `.glass-floating` / `.glass-wash` / bare-rung `::before` carries NO transition
+       and thus NO keyframes.js track. The §6 register is PRESERVED (still
+       `--ease-standard` on the position-tracked + surface-opacity legs — H-motion §6
+       "position-tracked → --ease-standard"; only the SELECTOR scope changes). The dock
+       controls keep the always-on transition (they are interactive controls; their rest
+       intensity is 0 so they paint nothing at rest, but a control legitimately carries
+       the transition). */
+    .glass-specular-track::before,
+    .glass-material:hover::before,    .glass-material:active::before,
+    .glass-wash:hover::before,        .glass-wash:active::before,
+    .glass-quiet:hover::before,       .glass-quiet:active::before,
+    .glass-resting:hover::before,     .glass-resting:active::before,
+    .glass-floating:hover::before,    .glass-floating:active::before,
+    .glass-overlay:hover::before,     .glass-overlay:active::before,
+    .glass-card:hover::before,        .glass-card:active::before,
+    .dock-icon-button::before,
+    .dock-tab-button::before,
+    .dock-select-trigger::before,
+    .dock-dropdown-trigger::before {
         /* Smooth the position + intensity between pointer samples (the typed
            @property regs make the percentage stops interpolable). */
         transition:
@@ -222,6 +260,97 @@
         --specular-intensity: var(--glass-specular-intensity-active, 0.16);
     }
 
+    /* ── LIQUID by tier — the moving-specular hover catch-light is the
+       FLOATING / OVERLAY tier's PROPERTY, not a per-surface wire (D6.c M10) ──────
+       The shared `:hover::before` rule above already lifts `--specular-intensity`
+       to the hover rung on EVERY material surface, so the catch-light wakes on
+       hover library-wide. What this block promotes is the FLOATING / OVERLAY
+       tier's identity: a navigation/overlay-band surface (a Dialog, a Sheet, a
+       Popover, the dock crest's `.glass-floating`) reads as LIQUID OUT OF THE BOX
+       — the catch-light is a tier guarantee, documented here so a consumer reaches
+       for `variant="floating"` and inherits the lens without a `useSpecularTracking`
+       wire. The pointer-anchored TRACKING still rides `useSpecularTracking` (a
+       host can sharpen the lens to the cursor); un-wired, the catch-light sits at
+       the centred `50%` fallback and breathes on hover — felt, not garish.
+
+       The magnitude rides the SAME `--glass-specular-intensity-hover` cohort the
+       aurora-calibrated π-ledger judges (tokens.css §specular-intensity), so the
+       liquid tier never out-shouts a number — it is the SAME gleam, named as a
+       tier default. The OPT-OUT survives: `.glass-no-liquid` on a floating/overlay
+       surface pins the rest rung (a flat tier for dense data, the deft escape). */
+    .glass-floating:not(.glass-no-liquid),
+    .glass-overlay:not(.glass-no-liquid) {
+        --glass-liquid: 1; /* the tier carries the liquid identity (informational marker) */
+    }
+    .glass-floating.glass-no-liquid:hover::before,
+    .glass-overlay.glass-no-liquid:hover::before,
+    .glass-floating.glass-no-liquid:active::before,
+    .glass-overlay.glass-no-liquid:active::before {
+        /* The deft escape — a dense-data floating surface that wants a FLAT tier
+           pins the catch-light at the clean rest rung even on hover/active. */
+        --specular-intensity: var(--glass-specular-intensity-rest, 0);
+    }
+    @media (prefers-reduced-motion: reduce) {
+        /* PRM fence — the liquid tier degrades to the static centred gleam. The
+           `useSpecularTracking` write is already PRM-gated (it skips the pointer
+           write under reduce); this pins the CSS half (`--specular-x/y: 50%`
+           centred) AND kills the position-track `transition` so an un-wired liquid
+           tile does NOT animate a travelling catch-light on hover under PRM. The
+           gleam may still LIFT on hover (a discrete opacity step, no interpolation
+           track) — the correct PRM degrade: no MOTION, the surface still responds.
+           This mirrors the shared moving-specular PRM bracket (one static-pin
+           convention across the specular cohort). */
+        .glass-floating::before,
+        .glass-overlay::before {
+            --specular-x: 50%;
+            --specular-y: 50%;
+            transition: none;
+        }
+    }
+
+    /* ── The GILT EDGE — `.glass-gilt`, the gilt-tooled glass modifier (D6.c M3/M12) ──
+       A fine book's cover is gold-tooled at the EDGE — never a gold fill. The
+       modifier composes on ANY tier (the tier is the FROST; the gilt is the
+       hairline gold catch on its rim) so a featured card OR the dock crest wears
+       the same recipe over its own backdrop. Two box-shadow layers ride INSIDE
+       the tier (they do not perturb the tier's own elevation stack — they are
+       additive inset rings):
+         (1) a 1px inset ring on `--gold-rim` — the tooled gold edge (D6.b lands
+             `--gold-rim` = `--gold` at ~40%α over the surface; referenced by name,
+             so the gilt resolves the moment the token cohort is minted), and
+         (2) a 0.5px gold top-catch highlight — the bevel light reading off the
+             upper edge, `--gold-light` at low α so it is a catch, not a band.
+       The surface still reads as cream-glass; the gold is the bevel light, the
+       SCARCE flourish (the consumption budget — at most one gilt surface per
+       route — is the atlas's D7 rule, not enforced here). */
+    .glass-gilt {
+        box-shadow:
+            inset 0 0 0 1px var(--gold-rim, color-mix(in oklab, var(--gold) 40%, transparent)),
+            inset 0 0.5px 0 0 color-mix(in oklab, var(--gold-light) 35%, transparent),
+            var(--glass-material-rim),
+            var(--glass-shadow-floating);
+    }
+
+    /* The liquid-metal CATCH-LIGHT (D6.c M12) — `.glass-gilt` overrides the
+       moving-specular `::before` sweep COLOR from warm-cream to GOLD, so the light
+       travelling across the gilt edge is golden the way gold leaf catches a warm
+       highlight. This is the single richest moment in the platform — gold + liquid
+       + specular — and therefore the most scarce (ONE surface ever, the title-page
+       flourish; the budget lives in D7). The geometry (bounded circle, the
+       `--glass-specular-size` falloff, the `plus-lighter` blend, the mask) is
+       INHERITED verbatim from the shared `::before`; only the gradient color stops
+       shift to the warm-gold mix. The intensity still rides the `--specular-intensity`
+       opacity multiplier (0 at rest), so a resting gilt surface paints NO gold sweep
+       — it wakes on hover like every liquid tier. */
+    .glass-gilt::before {
+        background: radial-gradient(
+            circle var(--glass-specular-size, 36%) at var(--specular-x, 50%) var(--specular-y, 50%),
+            color-mix(in oklab, var(--gold-light) 60%, hsl(40 35% 92%)) 0%,
+            hsl(40 35% 92% / 0) 70%,
+            transparent 100%
+        );
+    }
+
     /* ── Five-tier surface ladder (v0.8.0; visual only, no geometry) ──
        Tier semantics, alpha-monotonic per R3-spec §A:
          wash      ~0.30α  + light blur      (was `subtle`)
@@ -430,7 +559,10 @@
         background: var(--paper-clean-texture);
         background-repeat: repeat;
         background-size: var(--paper-texture-size);
-        opacity: var(--glass-grain-opacity);
+        /* D6.c M5 — the grain rung lifted off the dead 0.025 floor to a felt-but-
+           deft 0.038 (the page rung; the kitsch ceiling is ~0.05). The canonical
+           token still wins; this is the felt floor a no-override mount inherits. */
+        opacity: var(--glass-grain-opacity, 0.038);
         pointer-events: none;
         mix-blend-mode: overlay;
     }
@@ -947,17 +1079,20 @@
     .glass-resting,
     .glass-floating,
     .glass-overlay,
-    .glass-card {
+    .glass-card,
+    .glass-drawer {
         border: 1px solid CanvasText;
     }
 
     /* The floating + overlay rungs (Dialog / Sheet / Popover / DropdownMenu /
-       HoverCard compose them) get the canonical `Canvas` fill so the modal reads as
-       a DISTINCT boxed region OVER the page, not a transparent overlap — the
-       hierarchy survives. The `CanvasText` edge above already draws the box; this
-       opaque fill separates the floating layer from the content beneath it. */
+       HoverCard compose them) + the Drawer (the overlay-band sheet, drawer.css)
+       get the canonical `Canvas` fill so the modal reads as a DISTINCT boxed
+       region OVER the page, not a transparent overlap — the hierarchy survives.
+       The `CanvasText` edge above already draws the box; this opaque fill
+       separates the floating layer from the content beneath it. */
     .glass-floating,
-    .glass-overlay {
+    .glass-overlay,
+    .glass-drawer {
         background: Canvas;
     }
 
@@ -972,6 +1107,7 @@
     .glass-floating::before,
     .glass-overlay::before,
     .glass-card::before,
+    .glass-drawer::before,
     .glass-wash::after,
     .glass-quiet::after,
     .glass-resting::after,

package/src/styles/paper.css

@@ -7,8 +7,54 @@
  *
  * Texture: feTurbulence baseFrequency 0.65, 4 octaves, desaturated via
  * feColorMatrix, blended multiply (light) / soft-light (dark). Tiles ~60px.
+ *
+ * ── THE GRAIN RUNGS (D6.c M5 — the printed-paper tooth, FELT not seen) ─────────
+ * The warm-paper grain must be FELT at rest — a premium editorial stock has a
+ * felt depth, and the measured finding (ds2-medium M5 / fd-usf-gallery §F) is
+ * that the shipped `--glass-grain-opacity: 0.025` floor reads as NOTHING. This
+ * file lifts the grain off that floor and mints a SECOND rung for chart plates:
+ *
+ *   --glass-grain-opacity        — the PAGE grain. Lifted here to a perceptible-
+ *                                  but-deft 0.038 default (the local floor below).
+ *                                  Numeric justification: the kitsch line is
+ *                                  ~0.05 (above it the grain reads as screen-noise
+ *                                  / a dirty monitor, ds2-medium M5); 0.025 is
+ *                                  sub-perceptual ("felt as nothing"). 0.038 is
+ *                                  the calibrated MIDPOINT — ~1.5× the dead floor,
+ *                                  ~0.76× the kitsch ceiling — felt at rest, never
+ *                                  seen AS grain. (The canonical token still lives
+ *                                  in tokens.css; this utility reads it with the
+ *                                  lifted fallback so a no-override mount is felt.)
+ *   --glass-grain-opacity-plate  — the PLATE grain (NEW rung). A chart plate is
+ *                                  the FIGURE's "paper", so it wants slightly more
+ *                                  tooth than the page (M5): 0.045 — still below
+ *                                  the 0.05 kitsch ceiling, distinctly felt so the
+ *                                  plate reads as PRINTED on the same stock as the
+ *                                  page, not pasted onto it.
+ *
+ * THE DATA-REGION MASK CONTRACT (M5, non-negotiable). Grain on the FRAME, never
+ * under the FIGURE — a fleck over a choropleth reads as a data artifact; on the
+ * plate margin it reads as paper. `paper-grain-overlay` exposes a custom-property
+ * MASK SLOT (`--paper-grain-mask`) so a consumer can carve the data viewport out
+ * of the grain ::after: set it to a gradient/`url()` that is transparent over the
+ * data region and opaque over the frame, and the grain is masked off the figure.
+ * Default `none` (the whole surface is grained — the page/card case, no data to
+ * fence). The plate rung is opt-in via `[data-grain="plate"]`.
  */
 
+/* The grain rung DEFAULTS — lifted off the tokens.css floor (D6.c M5). These are
+   plain custom-property fallbacks the utilities read; a consumer/tokens.css value
+   still wins (`var(--glass-grain-opacity, <floor>)`), so this only sets the floor
+   a no-override mount inherits. The plate rung is minted here (no canonical
+   tokens.css home is touched in this lane — D6.b owns tokens.css). */
+@layer components {
+    :root {
+        /* The PLATE grain rung — distinct from the page rung; the figure's paper
+           wants more tooth. Minted in this lane; a consumer overrides at :root. */
+        --glass-grain-opacity-plate: 0.045;
+    }
+}
+
 @utility paper-underpaint {
     position: fixed;
     inset: 0;
@@ -17,7 +63,8 @@
     background-image: url("data:image/svg+xml,%3Csvg width='60' height='60' viewBox='0 0 60 60' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='4' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3CfeBlend mode='multiply' in2='SourceGraphic'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='1'/%3E%3C/svg%3E");
     background-repeat: repeat;
     background-size: 60px 60px;
-    opacity: var(--glass-grain-opacity);
+    /* Lifted floor — the page grain is FELT at rest (0.038), not the dead 0.025. */
+    opacity: var(--glass-grain-opacity, 0.038);
     mix-blend-mode: multiply;
 }
 
@@ -39,8 +86,27 @@
         background-image: url("data:image/svg+xml,%3Csvg width='60' height='60' viewBox='0 0 60 60' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='4' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3CfeBlend mode='multiply' in2='SourceGraphic'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='1'/%3E%3C/svg%3E");
         background-repeat: repeat;
         background-size: 60px 60px;
-        opacity: var(--glass-grain-opacity);
+        /* Lifted floor — felt on the frame at rest (0.038). */
+        opacity: var(--glass-grain-opacity, 0.038);
         mix-blend-mode: overlay;
+        /* THE DATA-REGION MASK SLOT (M5). Default `none` = the whole surface is
+           grained (page/card — no data to fence). A consumer that grains a chart
+           plate sets `--paper-grain-mask` to a gradient/url() transparent over the
+           data viewport + opaque over the frame, carving the figure out of the
+           grain so no fleck lands on a tier fill. `mask` is Baseline; a
+           non-supporting engine ignores it and keeps the full-surface grain (the
+           page case is unaffected — the mask only matters when a consumer fences
+           the data region). */
+        mask: var(--paper-grain-mask, none);
+        -webkit-mask: var(--paper-grain-mask, none);
+    }
+
+    /* The PLATE rung — a chart plate opts in via `[data-grain="plate"]` to the
+       higher-tooth `--glass-grain-opacity-plate` (the figure's paper reads as the
+       same stock as the page, with a touch more tooth). Pair with the mask slot to
+       fence the data viewport. */
+    &[data-grain="plate"]::after {
+        opacity: var(--glass-grain-opacity-plate, 0.045);
     }
 }
 

package/src/styles/theme.css

@@ -308,6 +308,13 @@
     --color-gold: var(--gold);
     --color-gold-light: var(--gold-light);
     --color-gold-dark: var(--gold-dark);
+    --color-gold-deep: var(--gold-deep);
+    /* D6.b — the gilt family: the rim (gilt edge) + the legible gold ink. The
+       `@theme` bridge surfaces `text-gold-ink` / `border-gold-rim` utilities
+       beside the existing gold quad. `--gold-ink` clears cream-law ② on `--card`
+       in both arms (proof:gold-ink-contrast). */
+    --color-gold-rim: var(--gold-rim);
+    --color-gold-ink: var(--gold-ink);
 
     --color-rainbow-red:    var(--rainbow-red);
     --color-rainbow-orange: var(--rainbow-orange);