@mkbabb/glass-ui 4.0.0 → 4.1.0

package/dist/styles/tokens/glass-fx.css

@@ -0,0 +1,376 @@
+/* tokens/glass-fx.css
+   §8 glass EFFECT knobs — the grain/specular/edge-light + the adaptive tint-source
+   + backdrop-luma bucket + the decorative fringe/curvature/chart-palette + the
+   per-tier shadow/spine/under-shadow/overlay-scrim recipes.
+   Carved from tokens/glass.css at BB.W-CARVE4 to hold the no-god-module bound (the
+   §8 opacity/blur/saturate LADDER + composed bg/border + the control-REST register
+   stay in glass.css; this is the contiguous decorative/fx tail). @import-ed by
+   tokens.css in cascade order IMMEDIATELY AFTER glass.css — the carve splits the ONE
+   §8 :root block into two adjacent same-selector :root{} blocks at the same cascade
+   slot (the AY.W-CSS1 isomorphism precedent), dist byte-identical. */
+:root {
+    /* Shared decorative. Light grain dropped 0.035 → 0.025 in P.W1.B —
+       at the chassis scale the original alpha read as crawl over the new
+       lower-alpha chassis bg; the grain's role is texture, not reading,
+       so it sits at the perceptual floor. Dark companion drops 0.06 →
+       0.045 below to keep the soft-light blend alive without stippling. */
+    --glass-grain-opacity: 0.025;
+    /* BB.W-LIQUIDHOVER — the grain ENGAGE clock: a hover/active grain lift cross-fades
+       the grain `::after` OPACITY on this thin ~120ms linear write while the
+       `background-image` stays ALWAYS PRESENT (never a none→image swap — the one-frame
+       decode-and-pop, the T8-F6 disco-grain pop); collapses to 0ms under PRM. */
+    --glass-grain-engage-duration: 120ms;
+    /* BA.W-GLASS-CAL — `--glass-grain-opacity-disco` (0.08) DELETED with the disco
+       recipe retirement (H2a): no surviving consumer once `btn-audacious` + the
+       dock-tab primary phase-grain collapse onto the calm glass register. */
+    --glass-highlight: inset 0 0.5px 0 0 hsl(0 0% 100% / 0.25);
+
+    /* Hairline-accent — 0.5px catch-light + under-shadow pair.
+       Single token composes the canonical 2-stop hairline used by dock,
+       instrument-chassis. The `.hairline-accent` utility
+       (utilities.css §hairline) adopts these via `box-shadow:`. */
+    --hairline-catch-light: inset 0 0.5px 0 0 rgb(255 255 255 / 0.06);
+    --hairline-under-shadow: 0 0.5px 0 0 rgb(0 0 0 / 0.04);
+    --border-hairline: var(--hairline-catch-light), var(--hairline-under-shadow);
+
+    /* BC.W-AX-METAL-GLOW — the brand-metal catch-light DEFAULTS (the consumer
+       retune seam). The metal-shimmer family (`.metal-{gold,silver,bronze}`,
+       metal.css) halos the text-clip with a `drop-shadow` of the metal's OWN base
+       hue at this radius + strength — the gold reads as LIT metal, not a flat fill.
+       Shared by the loop sweep AND the one-shot headline (the W-AX-COMPLETION-SEAL
+       seal glint reads `--metal-glow-blur`/`--metal-glow-opacity` — the ≥2-consumer
+       register). The defaults are a soft warm WHISPER bounded by the warm-cream
+       identity — a halo radius proportional to the text (0.5em) at a low strength
+       (0.35), NOT a neon bloom (the §6 calm register; the disco family stays gone).
+       A garish high-opacity glow is the consumer's preset choice, never the default;
+       a consumer who wants NO glow sets `--metal-glow-opacity: 0`. */
+    --metal-glow-blur-default: 0.5em;
+    --metal-glow-opacity-default: 0.35;
+
+    /* Specular catch-light — 1.5px-tall top-edge highlight that swaps in for
+       --glass-highlight on interactive moments (e.g. primary-action hover).
+       Reads as a real catch-light on a curved surface. The `-dark` companion
+       is overridden inside `.dark`; the named token here is the explicit
+       handle consumers can reference to compose dark-aware layers. */
+    --glass-specular: inset 0 1.5px 0 0 hsl(0 0% 100% / 0.45);
+    --glass-specular-dark: inset 0 1.5px 0 0 hsl(0 0% 100% / 0.30);
+
+    /* AV.W15 M3 — Full-perimeter rim light (the "rim that defines the
+       silhouette", WWDC25 sess. 219). Distinct from the top-only
+       `--glass-highlight` (a 0.5px top-edge catch-light): this is a 0.75px
+       inset ring around the WHOLE silhouette, four edges, reading as the
+       catch-light that wraps the glass plate the way iOS-26 Liquid Glass
+       carries a rim, not just a top highlight. Composed as a SECOND inset
+       box-shadow layer alongside `--glass-highlight` on the floating/dock
+       tiers (glass.css wires it). The alpha is deliberately low (0.18 light
+       / 0.10 dark) — the rim is decoration and must not eat AA legibility
+       over a busy backdrop; it sits below the perceptual reading threshold
+       on text. The `-dark` companion is overridden inside `.dark` mirroring
+       the `--glass-specular-dark` precedent. */
+    --glass-edge-light:      inset 0 0 0 0.75px hsl(0 0% 100% / 0.18);
+
+    /* BC.W-BLACK-BAR D2 — the DIRECTIONAL rim register (the iOS-27 glass-thickness
+       physics: light catch-light rims the TOP, a faint warm shadow grounds the
+       BOTTOM, so the plate reads as a physical pane lifted off the page — NEVER a
+       dark full-perimeter ink hairline). This RETIRES the load-bearing dark-rim role
+       of the per-rung `--glass-border-*` (now ≤5% α, glass.css): the silhouette is
+       carved by these two stops, not by the perimeter ink.
+         --glass-rim-top: the BRIGHT catch-light on the top edge (the kevinbism
+           `inset 0 1px white` motif; 0.30 α = apple-ios27.md §1.3 community value
+           rgba(255,255,255,0.3)). Subsumes the old omnidirectional white rim RING.
+         --glass-rim-bottom: the FAINT warm under-shadow grounding the plate (the
+           warm-ink that used to ring the whole perimeter, now only the bottom, at a
+           whisper 6% — riding --foreground so it stays warm-not-grey, BA.W-NO-GRAY).
+       Plain per-mode arms — NEVER an inset fragment inside light-dark() (the dark arm
+       re-declares both in dark-arm.css; light-dark() round an inset computes the WHOLE
+       box-shadow to none). The dark arm lifts the top to 0.40 (dark glass glows where
+       light passes) + keeps the bottom under-shadow at 6%. */
+    --glass-rim-top:         inset 0 1px 0 hsl(0 0% 100% / 0.30);
+    --glass-rim-bottom:      inset 0 -1px 0 color-mix(in srgb, var(--foreground) 6%, transparent);
+    /* BA.W-DARK-MATERIAL scope 2 — the dark edge/rim is the PRIMARY silhouette device in
+       dark. The light register's fill+shadow carry the plate; in dark the fill barely
+       separates (the deep page is near-black), so the EDGE + the transmitted glow carry the
+       silhouette — two registers, one design language. HEAD α 0.10 sits below the reading
+       threshold over the deep canvas; lifted to 0.22 so the rim DEFINES the plate (the
+       WWDC25 "rim that defines the silhouette" device, dialed up for the dark substrate). */
+    --glass-edge-light-dark: inset 0 0 0 0.75px hsl(0 0% 100% / 0.22);
+
+    /* AW.W23 — content-aware adaptive tint (the Baseline-2025 "tint informed by
+       surrounding content" axis, WWDC25 sess. 219). A surface can tint toward a
+       consumer-provided dominant backdrop color via a `color-mix(in oklab, …)`
+       recipe (oklab is the mwg-preferred space for THIS tint generation; NEVER a
+       lightness-shift in `oklch(from …)` in the glass-tint mix). BB.W-DARK-INK-WARM landed `oklch(from var(--foreground) …)` live on the dark `--surface-tint-*` arm.
+
+       DEFAULT is zero delta: `--glass-tint-source` is the warm-white card itself
+       and `--glass-tint-strength` is 0%, so the rung background mixes 0% toward
+       the source = byte-identical to today. A consumer sets `--glass-tint-source`
+       to a sampled aurora hue + a strength ≤30% to bias the surface. Alpha-safe:
+       the mix is bounded ≤30% and never re-points the card's own alpha.
+
+       AX.W55 — the DEFAULTS stay `var(--card)`/`0%` (the zero-delta rest state).
+       The backdrop-luminance probe (`--glass-backdrop`, below) is what OVERRIDES
+       them under a bright backdrop; the `:root` defaults are NEVER touched — the
+       bucket blocks (glass.css / dock.css `@container style(--glass-backdrop:
+       light)`) do the lift, so a surface over today's rich/dark background reads
+       byte-identical. */
+    --glass-tint-source:   var(--card);
+    --glass-tint-strength: 0%;
+
+    /* AX.W55 — adaptive glass legibility (the iOS-26/27 "locally darken the glass
+       over light content" move; G2). There is NO web API that reads the pixels
+       painted BEHIND a `backdrop-filter` element, so the backdrop-luminance signal
+       is a DECLARATIVE BUCKET a consumer sets where it KNOWS the backdrop is bright
+       (a near-white card surface, a pale aurora bleed, a bright data grid). It is
+       read by the `@container style(--glass-backdrop: light)` blocks on every glass
+       family (the shipped density-cascade mechanism — utilities.css §density) which
+       lift `--glass-tint-strength` toward the AA floor + re-point `--glass-tint-
+       source` to the warm-ink below, mixing the rung TOWARD ink via the EXISTING
+       `color-mix(in oklab)` seam — ZERO new compositing seam.
+
+         --glass-backdrop:      the bucket. `dark` (or unset) = today's zero-delta;
+                                `light` engages the bright-bucket darken. An
+                                INHERITING ident set on any ancestor reaches every
+                                descendant glass surface (the @container read).
+         --glass-backdrop-luma: the numeric escape hatch — a sampled backdrop
+                                relative-luminance (0..1) a heavier JS observer sets
+                                when the declarative bucket is too coarse. The TOKEN
+                                is minted (the cascade reads it if set); the OBSERVER
+                                that sets it stays demo-private until a 2nd consumer
+                                arrives (the no-overfitting bar — the DEFAULT path is
+                                the declarative bucket, not a speculative sampler).
+         --glass-tint-ink:      the LOW-LUMINANCE warm-ink the bright bucket re-points
+                                `--glass-tint-source` to — the warm dark `--foreground`
+                                family (NOT white; a lightener over light content is
+                                exactly the W52-fixed wrong direction). It auto-flips
+                                with `--foreground` (dark-mode it resolves the light
+                                warm ink — but the bright-backdrop case is a light-mode
+                                concern). Overridable like every magnitude here.
+
+       The bright-bucket `--glass-tint-strength` is clamped to a BOUNDED AA-clearing
+       floor — `--glass-tint-strength-aa` (≤24%, the iOS clamp; the lowest value that
+       clears 4.5:1 over synthetic white, capped LOW so the surface STAYS translucent,
+       "let as much content through as possible"). Recorded here as the ceiling the
+       bucket blocks drive to; the live 4.5:1 readback (proof:adaptive-glass π arm)
+       ratifies the exact value. */
+    --glass-backdrop:           dark;
+    --glass-tint-ink:           var(--foreground);
+
+    /* BC.W-ADAPTIVE-RECONCILE — the ONE retune knob for the continuous observer
+       driver. `--glass-backdrop-luma` (the measured sampled relative-luminance the
+       useGlassBackdropLuminance observer WRITES, registered typed in property-regs.css)
+       is now READ on the RHS of the `--glass-tint-strength` clamp (glass/ladder.css +
+       dock/morph.css): below this knee the plate holds the calm warm-cream floor; above
+       it the strength ramps CONTINUOUSLY toward the ≤24% AA ceiling (the iOS-27 dynamic-
+       range shift, apple-ios27.md §1.5 ~0.6 light threshold). The dead-knob is closed —
+       the loop READS. A consumer raising the knee darkens LATER (a brighter backdrop is
+       tolerated before the lift); the ONE override point for the whole adaptive axis. */
+    --glass-backdrop-luma-knee: 0.6;
+    /* AZ.W-ADAPTIVE-AUTO Arm 1 — recalibrated 18% → 20%. The bump strengthens the
+       G2 surface-SILHOUETTE darken (ΔL ≈ 0.40 over synthetic white, the plate is
+       distinguishable from a bright page behind) while staying bounded ≤ 24% (the
+       iOS clamp — the surface STAYS translucent, "let content through"). The body
+       register over the engaged plate is the full warm-ink `--foreground` (~10.6:1
+       over white at 20%) — the muted L40 tier is lifted to the full ink by the
+       self-engage rules (it cannot clear 4.5:1 on a translucent darkened plate;
+       darkening moves the plate toward muted's own luminance). The shipped overlay-
+       band engaged appearance re-ratifies at the new floor: `--foreground` reads
+       ~10.6–10.9:1 (within the ~11:1 ratified register — the bump is a silhouette
+       strengthening, not a silent re-tint below AA). The live π readback ratifies. */
+    --glass-tint-strength-aa:   20%;
+
+    /* BA.W-DARK-MATERIAL scope 7 — the calm-light recalibration (R9-1; the slides gray-slab
+       fix). The AZ unconditional content-tier self-engage applied the full 20% AA darken to
+       EVERY .glass-card/.glass-resting/.glass-quiet/.glass-wash mode- and backdrop-agnostically
+       — over a plain LIGHT page (not a bright/busy backdrop) the 20% warm-ink darken + the
+       muted→ink lift composited the translucent cream card into a flat gray slab (the slides
+       presenter card: 20% → oklab(0.785) gray). The recalibration: the FULL AA darken is now
+       gated on the declared/sampled bright signal (the @container --glass-backdrop:light bucket /
+       the observer); the UNCONDITIONAL content-tier floor drops to this sub-perceptual SILHOUETTE
+       tint — just enough edge over a busy backdrop without graying a calm-light card (the
+       calm-light plate stays warm, L ≈ 0.94 at the slides-equivalent fixture). The overlay band
+       (.glass-floating/.glass-overlay) keeps the FULL unconditional darken (floating over an
+       UNKNOWN consumer surface, darkening is the correct default). A consumer opts out on a
+       light-page ancestor via --glass-tint-strength: 0%. Bounded > 0%, ≤ 10%. The DARK arm
+       re-tunes --glass-tint-strength-aa directly (dark-arm.css scope 3) — the luminous-dark lift
+       is the desired default there, NOT a sub-perceptual floor, so the floor is a light-mode knob. */
+    --glass-tint-strength-floor: 4%;
+
+    /* The on-glass FOREGROUND register (BB.W-ON-GLASS-FG) lives in tokens/on-glass-fg.css. */
+    /* R5-7 — the VEIL text-plate feather. The `veil-surface` decoration
+       (cards.css) paints a borderless/rimless translucent glass plate as a LOCAL
+       text-legibility surface over a busy backdrop; its `--veil-feather` axis is
+       an OPTIONAL `mask-image` that fades the plate edges into the page (the
+       soft-edged "bleed" the slides deck text plates use). The default is `none`
+       (a clean rectangle); a consumer opts into the feather by pointing
+       `--veil-feather` at this ready-made radial, or any `mask-image` value.
+       The 70%→100% falloff feathers the outer ~30% of the plate; override the
+       token to retune the fade radius library-wide. */
+    --veil-feather-radial: radial-gradient(
+        ellipse 100% 100% at 50% 50%,
+        black 0%,
+        black 70%,
+        transparent 100%
+    );
+
+    /* AW.W23 — chromatic edge dispersion (the "polished glass" rim fringe Apple
+       shows). A warm fringe on one edge + a cool fringe on the other, low-alpha,
+       biased warm-cream/NCSU-red (NOT iOS-blue). Composed OVER the W22 uniform
+       rim under `prefers-reduced-transparency: no-preference`; dropped under
+       `reduce` (it is a transparency garnish). The two directional inset rings
+       read as light refracting through the glass edge. */
+    --glass-fringe-warm: oklch(0.92 0.06 40 / 0.22);
+    --glass-fringe-cool: oklch(0.90 0.05 230 / 0.16);
+    --glass-edge-dispersion:
+        inset 0.75px 0 0 0 var(--glass-fringe-warm),
+        inset -0.75px 0 0 0 var(--glass-fringe-cool);
+
+    /* AX.W52 D19 — the moving-specular gleam radius (glass.css `.glass-material::
+       before`). The ONE knob that BOUNDS the gleam geometry as a percentage of the
+       plate so it can NEVER again become a whole-surface disc (the prior implicit
+       `circle at …` ran its stops to 55–75% of the half-diagonal — a wash on a
+       small tile). 36% reads as a tracked edge glint. Override on `:root` to retune
+       library-wide; a per-surface override clips the gleam tighter/wider. */
+    --glass-specular-size: 36%;
+
+    /* Chassis curvature illusion — a subtle radial gradient at the chassis
+       top centre that lifts the surface without committing to literal 3D.
+       Composed into <InstrumentChassis>'s background stack. AX.W52 D19 — the
+       prior pure-white `hsl(0 0% 100% / 0.06)` reaching `transparent 60%` was a
+       broad top-centre WASH (the #1 fixed-anchor rest-bloom culprit). Re-derived
+       onto the warm-cream house identity (`hsl(40 30% 96%)`, L < 100% so the warm
+       hue survives — mirroring the moving gleam), the alpha routed through the
+       SINGLE overridable `--glass-curvature-intensity` knob (0.02 default, a third
+       of the old 0.06), and the ellipse tightened to `transparent 38%` so it reads
+       as a thin top-edge sheen, not a central wash. */
+    --glass-curvature-intensity: 0.02;
+    --glass-curvature-overlay: radial-gradient(
+        ellipse at 50% -20%,
+        hsl(40 30% 96% / var(--glass-curvature-intensity)),
+        transparent 38%
+    );
+    /* The light-arm dark alias kept on the same warm-cream + token recipe so a
+       non-`.dark` consumer reading `…-overlay-dark` still resolves a softened
+       sheen; the `.dark` block below lowers `--glass-curvature-intensity` so the
+       deep-canvas arm is genuinely softer (the prior byte-identical dark arm read
+       HARDER over the dark canvas). */
+    --glass-curvature-overlay-dark: var(--glass-curvature-overlay);
+
+    /* Chart palette aliases — speedtest et al. read these for phase tinting.
+       Defaults map to viz-basis hues; consumers can override per app. */
+    --chart-ping:     var(--viz-chebyshev);
+    --chart-download: var(--viz-fourier);
+    --chart-upload:   var(--viz-amber);
+    --chart-jitter:   var(--viz-legendre);
+
+    /* O.W6 Lane D — WCAG companion `--chart-{phase}-label` tokens
+       (speedtest AC.W6c.T2 — F1.V-04 closure).
+
+       The canvas-side hues above preserve their saturated brand register
+       (correct against the meter dial); the COMPANION tokens darken to
+       L≈0.40 so phase-label text on `--background` clears the WCAG 2.1
+       AA-body 4.5:1 contrast floor. Mirrors the two-token discipline
+       already established by `--meter-{background-color,track-stroke}`:
+       one token feeds the canvas/visual, the second feeds the label
+       text.
+
+       Light-mode L≈0.40 in OKLCH preserves the hue rotation while
+       dropping luminance enough for body contrast; dark-mode flips to
+       L≈0.85 against the dark canvas. Consumers reach these via
+       `color: var(--chart-ping-label)` (etc.) on label elements ONLY —
+       chart strokes/fills continue to read `--chart-ping`. */
+    --chart-ping-label:     oklch(0.40 0.18 230);
+    --chart-download-label: oklch(0.40 0.20 22);
+    --chart-upload-label:   oklch(0.40 0.16 55);
+    --chart-jitter-label:   oklch(0.40 0.20 305);
+
+    /* O.W6 Lane D — Meter track stroke (speedtest AC.W6c.T3 — F1.V-02
+       closure). Promoted from speedtest's consumer-side declaration so
+       glass-ui owns the canonical light + dark values. The light-mode
+       value reads opaque foreground (composes through canvas
+       `globalAlpha` in consumer renderers; e.g., speedtest's `rings.ts`
+       `globalAlpha = 0.22` lands the phantom-track at the perceptual
+       sweet-spot). The dark-mode companion lives under `.dark` below
+       and ALSO reads `var(--foreground)` — the prior speedtest value
+       `var(--background)` rendered bg-on-bg invisible at dark mode. */
+    --meter-track-stroke: var(--foreground);
+
+    /* Shadow per tier — complete box-shadow lists for glass surface classes */
+    --glass-shadow-wash:     var(--shadow-sm), var(--glass-highlight);
+    --glass-shadow-quiet:    var(--shadow-md), var(--glass-highlight);
+    --glass-shadow-resting:  var(--shadow-lg), var(--glass-highlight);
+    --glass-shadow-floating: var(--shadow-xl),
+        0 0 0 0.5px color-mix(in srgb, var(--shadow-color) 5%, transparent),
+        var(--glass-highlight);
+    --glass-shadow-overlay:  var(--shadow-2xl),
+        0 0 0 0.5px color-mix(in srgb, var(--shadow-color) 8%, transparent),
+        var(--glass-highlight);
+    --glass-shadow:    var(--glass-shadow-quiet);
+
+    /* ─────────────────────────────────────────────────────────────
+       AL-W1-α augmented — SPINE 8th tier (HOUSING register)
+
+       Closes the AK W2 chassis-spine architectural underclaim per
+       AL-X5 §4.1. The spine register is a polished SLEEVE, not glass:
+       NO backdrop-filter, NO plate opacity, hairline outer stroke,
+       interior radial vignette that subtly carries the phase-color
+       cascade. Consumed exclusively by `<InstrumentChassis variant="spine">`
+       at App-level mount paths (quiet-content routes).
+
+       The 4 tokens here cover the minimum viable substrate the SLIM
+       Y4/Y6/Y7 retention set ratified. The 35 rejected axes (saturate
+       band, edge-light per tier, depth-shadow per tier, tier-up macro)
+       stay rejected per the conservative-creation mandate. (BB.W-DEAD-SWEEP KEEP:
+       --glass-spine-opacity/-blur — no var() consumer, pinned by InstrumentChassis.spine-variant.test.ts; Batch-6 re-anchor.)
+       ───────────────────────────────────────────────────────────── */
+    --glass-spine-opacity: 0;
+    --glass-spine-blur: 0px;
+    --glass-spine-border: var(--surface-tint-8);
+    --glass-spine-vignette: radial-gradient(
+        ellipse at 50% 0%,
+        color-mix(in oklab, var(--phase-color, var(--surface-tint-8)) 8%, transparent),
+        transparent 60%
+    );
+
+    /* ─────────────────────────────────────────────────────────────
+       AL-W10 SLIM — UNDER-SHADOW recipe rungs
+
+       Per AL-X5 §4 + Y7 §3. iOS Liquid Glass surfaces carry a 0.5px
+       dark hairline along the bottom edge (reads as under-shadow /
+       glass thickness). The substrate `--hairline-under-shadow`
+       already publishes one quiet rung; the four-rung ladder here
+       names the SLIM retention set (Y4 §3.2 / Y6 §4.3) — `quiet`,
+       `default`, `vivid`, `spine` cover the consumer landings without
+       multiplying tokens per tier. The 3 hand-rolled literals at
+       `instrument-chassis.css:52`, `dock.css:279`, `dock.css:952`
+       retire to these.
+
+       Composes as a NON-INSET box-shadow layer alongside the existing
+       `--glass-shadow-*` recipe (the inset under-shadow stays at the
+       hand-rolled literal where it's load-bearing on chassis-internal
+       surfaces).
+       ───────────────────────────────────────────────────────────── */
+    --glass-under-shadow-quiet:   0 2px 8px -1px oklch(0 0 0 / 0.04);
+    --glass-under-shadow-default: 0 4px 16px -2px oklch(0 0 0 / 0.08);
+    --glass-under-shadow-vivid:   0 8px 32px -4px oklch(0 0 0 / 0.12);
+    --glass-under-shadow-spine:   0 1px 0 0 oklch(0 0 0 / 0.06);
+
+    /* Overlay scrim rungs — substrate-aware modal/dialog backdrop tints.
+       Three weights cover the deployed range: dialog-scroll (subtle),
+       canonical modal (default), drawer/full-cover (strong).
+
+       AY.W-PRIM-POLISH D3 — the scrim is its OWN identity token, NOT derived
+       from `--shadow-color`. A scrim's role is to RECEDE: it must pin to INK in
+       BOTH modes. The cartoon-shadow family rides `--shadow-color: var(--foreground)`
+       (correct — a shadow re-tints under `.dark` by construction), but a scrim
+       that does the same FLOODS the dark room with a cream fog (the old dark
+       overlay painted `srgb(0.91… / 0.5)`, a near-white wash that BRIGHTENED the
+       page at the modal moment). `--overlay-scrim-ink` is a fixed warm near-black
+       (the light-mode `--foreground` value), re-resolved verbatim in `.dark` so
+       the scrim recedes in both modes. Clean break, no alias (no-backwards-compat).
+       The `--shadow-color` / `--shadow-cartoon-*` family is UNTOUCHED. */
+    --overlay-scrim-ink:     hsl(24 10% 10%);
+    --overlay-scrim:         color-mix(in srgb, var(--overlay-scrim-ink) 50%, transparent);
+    --overlay-scrim-strong:  color-mix(in srgb, var(--overlay-scrim-ink) 80%, transparent);
+    --overlay-scrim-subtle:  color-mix(in srgb, var(--overlay-scrim-ink) 40%, transparent);
+
+}