@mkbabb/glass-ui 0.2.0 → 2.0.0

package/src/styles/floating-panel.css

@@ -5,45 +5,30 @@
         position: fixed;
         z-index: var(--z-overlay);
         border-radius: var(--radius-panel);
-        border: 1px solid var(--glass-border-medium);
-        background: var(--glass-bg-medium);
-        backdrop-filter: var(--glass-blur-medium);
-        -webkit-backdrop-filter: var(--glass-blur-medium);
+        border: 1px solid var(--glass-border-resting);
+        background: var(--glass-bg-resting);
+        backdrop-filter: var(--glass-blur-resting);
         color: var(--popover-foreground);
-        box-shadow: var(--glass-shadow-medium);
+        box-shadow: var(--glass-shadow-resting);
         pointer-events: auto;
-        animation: floating-panel-in var(--duration-fast) var(--ease-out);
-    }
-
-    .floating-panel-item {
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        gap: 0.5rem;
-        padding: 0.375rem;
-        border-radius: var(--radius-pill);
-        color: inherit;
-        cursor: pointer;
-        transition:
-            background-color var(--duration-fast) var(--ease-standard),
-            transform var(--duration-fast) var(--ease-standard);
-    }
-
-    .floating-panel-item:hover {
-        background-color: color-mix(in srgb, var(--foreground) 6%, transparent);
-    }
-
-    .floating-panel-item:focus-visible {
-        outline: none;
-        border-radius: var(--radius-pill);
-        box-shadow: var(--focus-ring-shadow);
+        /* V.W3.T9 — animation grammar routes through the canonical
+           Tailwind `animate-floating-panel-in` utility (defined in
+           `theme.css` as `--animate-floating-panel-in`), NOT the raw
+           `animation:` shorthand that bypassed the cascade. */
+        @apply animate-floating-panel-in;
     }
+}
 
-    .floating-panel-item:active:not(:disabled) {
-        transform: scale(0.95);
-    }
-    .floating-panel-item:disabled {
-        opacity: 0.35;
-        pointer-events: none;
-    }
+/* Dropdown-menu font knob (Q.W3 Lane C / Qβ-F3).
+   Migrated out of the lone scoped `<style>` blocks on
+   `DropdownMenuContent.vue` + `DropdownMenuSubContent.vue` — those were the
+   only scoped styles in an otherwise fully-global menu family, so the family
+   is now uniformly global-CSS. The `--dropdown-menu-font` token is the
+   consumer-facing knob (value.js overrides it to `var(--font-mono)`); the
+   `, inherit` fall-through MUST be preserved verbatim per the Qθ binding
+   constraint. Unlayered, like the retired scoped block — no other rule sets
+   `font-family` on these surfaces, so the cascade effect is identical. */
+.dropdown-menu-content,
+.dropdown-sub-content {
+    font-family: var(--dropdown-menu-font, inherit);
 }

package/src/styles/fonts.css

@@ -0,0 +1,143 @@
+/*
+ * fonts.css — payload-bearing @font-face declarations (OFL woff2 faces)
+ *
+ * AM-W1-α (entry-path weight split) — these are the ONLY @font-face rules
+ * that carry a font binary. At publish time the build plugin
+ * (vite.config.ts → publishStyleAssets) base64-inlines each
+ * `url("@mkbabb/glass-ui/fonts/<family>/<face>.woff2")` into a
+ * `data:font/woff2;base64,…` URI sourced from `src/fonts/`. That payload
+ * is ~99 KB gzipped — over half of the entire `./styles` critical CSS
+ * weight.
+ *
+ * This file is DELIBERATELY NOT `@import`ed by `styles/index.css`. The
+ * critical first-paint entry path (`@mkbabb/glass-ui/styles`) therefore no
+ * longer carries the font binary. Consumers import the faces once,
+ * separately and off the critical path:
+ *
+ *   @import "@mkbabb/glass-ui/styles";        (critical — no font payload)
+ *   @import "@mkbabb/glass-ui/styles/fonts";  (font corpus, loaded once)
+ *
+ * The calibrated `local()` fallback faces (San Francisco / Segoe UI /
+ * Roboto / Arial for the sans; SF Mono / Menlo / … for the mono) carry NO
+ * payload and remain in `typography.css` on the critical path — they are
+ * what paints during the `font-display: optional`/`swap` window, so they
+ * are genuinely first-paint critical. The metric overrides on those
+ * fallback faces (Capsize-calibrated; AC.W6b) reference the exact
+ * geometry of the faces declared here, so the split is purely a
+ * load-order/weight concern: the cascade is identical once both files load.
+ *
+ * Contract-v2 (docs/precepts/cross-repo-dev-resolution.md §2.1): this file
+ * is published into `dist/styles/fonts.css` and is reachable via the
+ * `./styles/fonts` exports key → `./dist/styles/fonts.css`. The build
+ * plugin walks EVERY `dist/styles/*.css` (not just index's transitive
+ * closure), so the inline rewrite applies here exactly as it did when these
+ * faces lived in typography.css. No `url()` resolves out of `dist/`.
+ *
+ * AM-W7-δ separate-files refinement — DEFERRED (base64 KEPT). The W1-close
+ * audit proposed de-base64ing THIS file to dist-relative
+ * `url("../fonts/<face>.woff2")` (referencing the already-shipped
+ * `dist/fonts/*` woff2 via the `./fonts/*` export), so the browser would
+ * fetch only the USED faces — unicode-range-deferring the ~35 KB latin-ext
+ * pair + gaining per-face HTTP caching. That refinement is STRUCTURALLY
+ * BLOCKED by the consumer's font-delivery idiom, verified at AM-W7-δ:
+ *
+ *   speedtest's W1-α.2 consumer loads this file via a Vite `?url` import
+ *   (`import fontsHref from "@mkbabb/glass-ui/styles/fonts?url"`), which
+ *   emits fonts.css VERBATIM as a content-hashed asset into the consumer's
+ *   OWN `dist/assets/fonts-<hash>.css` and injects it as an async `<link>`.
+ *   `?url` does NOT parse the CSS or follow its `url()` refs — so the
+ *   referenced woff2 are NEVER copied across the package boundary into the
+ *   consumer's dist (confirmed: zero `*.woff2` in speedtest/dist). A
+ *   dist-relative `url("../fonts/…")` inside the emitted
+ *   `/assets/fonts-<hash>.css` would resolve at runtime to `/fonts/…` on
+ *   the CONSUMER's origin, which has no such file → 404 on every face,
+ *   broken fonts. (This is the same symlink-realpath axis that defeated
+ *   "Option A" for the publisher in vite.config.ts → publishStyleAssets;
+ *   the `?url` consumer path inherits it.) The CSP also gates here:
+ *   `font-src 'self' data:` admits the `data:` URI but the dist-relative
+ *   file would not be present on `'self'`.
+ *
+ *   Base64 keeps the face request layer entirely self-contained: the woff2
+ *   travel INSIDE the emitted CSS, so the async `<link>` is the only
+ *   network fetch and it works regardless of how the consumer re-emits the
+ *   file. The unicode-range split below is preserved either way — it still
+ *   defers latin-ext glyph SHAPING — but with base64 the latin-ext bytes
+ *   ship in the (once-cached, off-critical-path) CSS rather than as a lazy
+ *   separate request. Working fonts > the marginal lazy-fetch win. Revisit
+ *   only if a consumer adopts a delivery that DOES bundle/copy `url()`
+ *   targets across the boundary (e.g. a real `@import` of the dist file).
+ */
+
+/* ═══════════════════════════════════════════════
+   OFL FACE FILES — Plus Jakarta Sans (brand display)
+   ═══════════════════════════════════════════════ */
+
+/* Plus Jakarta Sans — Latin subset (basic Latin + ASCII punctuation +
+   common diacritics). Variable font: a single woff2 covers wght 200..800.
+   `font-display: optional` keeps the LCP off the font-load critical path
+   — combined with the calibrated fallback face in typography.css, the swap
+   is no-shift on geometry and never disrupts paint. */
+@font-face {
+    font-family: "Plus Jakarta Sans";
+    font-style: normal;
+    font-weight: 200 800;
+    font-display: optional;
+    src: url("@mkbabb/glass-ui/fonts/plus-jakarta-sans/plus-jakarta-sans-latin.woff2") format("woff2");
+    unicode-range:
+        U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA,
+        U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122,
+        U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+/* Plus Jakarta Sans — Latin-ext subset (extended Latin diacritics, IPA,
+   wider Latin script). Carried because speedtest's ISP-name register
+   may surface non-ASCII Latin (e.g., Spectrum, Frontier, AT&T variants
+   transliterated). Lazy: only loads if a glyph in the range renders. */
+@font-face {
+    font-family: "Plus Jakarta Sans";
+    font-style: normal;
+    font-weight: 200 800;
+    font-display: optional;
+    src: url("@mkbabb/glass-ui/fonts/plus-jakarta-sans/plus-jakarta-sans-latin-ext.woff2") format("woff2");
+    unicode-range:
+        U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF,
+        U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF,
+        U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+
+/* ═══════════════════════════════════════════════
+   OFL FACE FILES — Fira Code (canonical mono)
+   ═══════════════════════════════════════════════ */
+
+/* Fira Code — Latin subset (ASCII + ligatures + box-drawing prereqs).
+   Variable font: a single woff2 covers wght 300..700. `font-display:
+   swap` is acceptable here because Fira Code is post-LCP (mono-register
+   admin labels + tabular numerics render below the fold; FOUT is a
+   minor visual blip, not a layout shift since the system mono fallback
+   matches geometry via the calibrated fallback face in typography.css). */
+@font-face {
+    font-family: "Fira Code";
+    font-style: normal;
+    font-weight: 300 700;
+    font-display: swap;
+    src: url("@mkbabb/glass-ui/fonts/fira-code/fira-code-latin.woff2") format("woff2");
+    unicode-range:
+        U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA,
+        U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122,
+        U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+/* Fira Code — Latin-ext subset. Carried for parity with the sans
+   coverage (admin labels may surface non-ASCII strings on
+   internationalized variants). */
+@font-face {
+    font-family: "Fira Code";
+    font-style: normal;
+    font-weight: 300 700;
+    font-display: swap;
+    src: url("@mkbabb/glass-ui/fonts/fira-code/fira-code-latin-ext.woff2") format("woff2");
+    unicode-range:
+        U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF,
+        U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF,
+        U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}

package/src/styles/glass.css

@@ -1,49 +1,80 @@
 /* Glass utilities — glassmorphism surface classes referencing --glass-* tokens */
 
 @layer components {
-    /* ── Four-tier surface classes (visual only, no geometry) ── */
+    /* ── 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`)
+         quiet     ~0.50α  + medium blur     (the missing rung)
+         resting   ~0.65α  + canonical blur  (was `default`; the speedtest plate)
+         floating  ~0.80α  + heavier blur    (was `elevated`)
+         overlay   ~0.95α  + heaviest blur   (NEW; modal-over-modal) */
+
+    /* The five-rung surface ladder declares the unprefixed
+       `backdrop-filter` only. Lightning CSS / autoprefixer in the
+       consumer's pipeline emits the `-webkit-` legacy form when
+       browserslist targets demand it. Authoring both forms manually
+       caused Lightning CSS in Tailwind v4 to dedup-and-keep-prefixed,
+       which modern Chromium then dropped from the CSSOM (the prefixed
+       alias is parser-rejected post-Chrome 113). Single-source-of-truth
+       authorship lets the build pipeline deliver the right matrix. */
+    .glass-wash {
+        position: relative;
+        background: var(--glass-bg-wash);
+        backdrop-filter: var(--glass-blur-wash);
+        border: 1px solid var(--glass-border-wash);
+        box-shadow: var(--glass-shadow-wash);
+    }
 
-    .glass-subtle {
+    /* AL-W10 SLIM under-shadow wiring (tokens.css §AL-W10 SLIM —
+       UNDER-SHADOW recipe rungs). Each tier composes its canonical
+       iOS Liquid Glass under-shadow (a 0.5px dark hairline along the
+       bottom edge reading as glass thickness) as a NON-INSET layer
+       PREPENDED to the existing `--glass-shadow-*` recipe — the under-
+       shadow lays the floor; the existing shadow stack lays the lift.
+         quiet   → `--glass-under-shadow-quiet`   (0 2px 8px -1px α0.04)
+         resting → `--glass-under-shadow-default` (0 4px 16px -2px α0.08)
+         floating→ `--glass-under-shadow-vivid`   (0 8px 32px -4px α0.12)
+       `.glass-wash` is sub-perceptual; `.glass-overlay` is modal-heavy
+       — neither composes an under-shadow rung (Y4/Y6/Y7 SLIM retention).
+       Spine tier wires its own rung at instrument-chassis.css. */
+    .glass-quiet {
         position: relative;
-        background: var(--glass-bg-subtle);
-        backdrop-filter: var(--glass-blur-subtle);
-        -webkit-backdrop-filter: var(--glass-blur-subtle);
-        border: 1px solid var(--glass-border-subtle);
-        box-shadow: var(--glass-highlight);
+        background: var(--glass-bg-quiet);
+        backdrop-filter: var(--glass-blur-quiet);
+        border: 1px solid var(--glass-border-quiet);
+        box-shadow: var(--glass-under-shadow-quiet), var(--glass-shadow-quiet);
     }
 
-    .glass-default {
+    .glass-resting {
         position: relative;
-        background: var(--glass-bg-default);
-        backdrop-filter: var(--glass-blur-default);
-        -webkit-backdrop-filter: var(--glass-blur-default);
-        border: 1px solid var(--glass-border-default);
-        box-shadow: var(--glass-highlight);
+        background: var(--glass-bg-resting);
+        backdrop-filter: var(--glass-blur-resting);
+        border: 1px solid var(--glass-border-resting);
+        box-shadow: var(--glass-under-shadow-default), var(--glass-shadow-resting);
     }
 
-    .glass-medium {
+    .glass-floating {
         position: relative;
-        background: var(--glass-bg-medium);
-        backdrop-filter: var(--glass-blur-medium);
-        -webkit-backdrop-filter: var(--glass-blur-medium);
-        border: 1px solid var(--glass-border-medium);
-        box-shadow: var(--glass-highlight);
+        background: var(--glass-bg-floating);
+        backdrop-filter: var(--glass-blur-floating);
+        border: 1px solid var(--glass-border-floating);
+        box-shadow: var(--glass-under-shadow-vivid), var(--glass-shadow-floating);
     }
 
-    .glass-elevated {
+    .glass-overlay {
         position: relative;
-        background: var(--glass-bg-elevated);
-        backdrop-filter: var(--glass-blur-elevated);
-        -webkit-backdrop-filter: var(--glass-blur-elevated);
-        border: 1px solid var(--glass-border-elevated);
-        box-shadow: var(--glass-highlight);
+        background: var(--glass-bg-overlay);
+        backdrop-filter: var(--glass-blur-overlay);
+        border: 1px solid var(--glass-border-overlay);
+        box-shadow: var(--glass-shadow-overlay);
     }
 
     /* Grain noise overlay — reuses paper texture SVG, no extra assets */
-    .glass-subtle::after,
-    .glass-default::after,
-    .glass-medium::after,
-    .glass-elevated::after {
+    .glass-wash::after,
+    .glass-quiet::after,
+    .glass-resting::after,
+    .glass-floating::after,
+    .glass-overlay::after {
         content: '';
         position: absolute;
         inset: 0;
@@ -56,33 +87,27 @@
         mix-blend-mode: overlay;
     }
 
-    .dark .glass-subtle::after,
-    .dark .glass-default::after,
-    .dark .glass-medium::after,
-    .dark .glass-elevated::after {
+    .dark .glass-wash::after,
+    .dark .glass-quiet::after,
+    .dark .glass-resting::after,
+    .dark .glass-floating::after,
+    .dark .glass-overlay::after {
         mix-blend-mode: soft-light;
     }
 
     /* ── Convenience shorthands (tier + shape) ── */
 
+    /* Static surface utility — no hover lift, no transition.
+       Interactive cards live in <Card> (which owns its own hover composition)
+       or in components that explicitly opt into a hover variant. */
     .glass-card {
         position: relative;
-        background: var(--glass-bg-default);
-        backdrop-filter: var(--glass-blur-default);
-        -webkit-backdrop-filter: var(--glass-blur-default);
-        border: 1px solid var(--glass-border-default);
+        background: var(--glass-bg-quiet);
+        backdrop-filter: var(--glass-blur-quiet);
+        border: 1px solid var(--glass-border-quiet);
         border-radius: var(--radius-card);
-        box-shadow: var(--glass-shadow-default);
-    }
-
-    .glass-pill {
-        position: relative;
-        background: var(--glass-bg-default);
-        backdrop-filter: var(--glass-blur-default);
-        -webkit-backdrop-filter: var(--glass-blur-default);
-        border: 1px solid var(--glass-border-default);
-        border-radius: var(--radius-pill);
-        box-shadow: var(--glass-shadow-subtle);
+        box-shadow: var(--shadow-card);
+        contain: layout style;
     }
 
     /* ── Glassmorphic circular icon button ── */
@@ -93,20 +118,20 @@
         width: var(--size-icon-btn);
         height: var(--size-icon-btn);
         border-radius: var(--radius-pill);
-        border: 1.5px solid var(--glass-border-subtle);
-        background: var(--glass-bg-subtle);
-        backdrop-filter: var(--glass-blur-subtle);
+        border: 1.5px solid var(--glass-border-wash);
+        background: var(--glass-bg-wash);
+        backdrop-filter: var(--glass-blur-wash);
         color: var(--muted-foreground);
         transition:
-            background var(--duration-fast) ease,
-            border-color var(--duration-fast) ease,
-            color var(--duration-fast) ease,
+            background var(--duration-fast) var(--ease-standard),
+            border-color var(--duration-fast) var(--ease-standard),
+            color var(--duration-fast) var(--ease-standard),
             transform var(--duration-normal) var(--spring-snappy);
     }
 
     .glass-btn:hover:not(:disabled) {
         background: color-mix(in srgb, var(--background) 85%, transparent);
-        border-color: color-mix(in srgb, var(--foreground) 20%, transparent);
+        border-color: var(--surface-tint-22);
         color: var(--foreground);
         transform: scale(var(--scale-hover));
     }
@@ -116,8 +141,8 @@
     }
 
     .glass-btn:focus-visible {
-        outline: var(--focus-ring-width) solid var(--ring);
-        outline-offset: var(--focus-ring-width);
+        outline: none;
+        box-shadow: var(--focus-ring-shadow);
     }
 
     .glass-btn:disabled {
@@ -126,9 +151,10 @@
         pointer-events: none;
     }
 
-    .glass-btn.is-active {
-        background: color-mix(in srgb, var(--foreground) 10%, transparent);
-        border-color: color-mix(in srgb, var(--foreground) 25%, transparent);
+    .glass-btn.is-active,
+    .glass-btn[aria-pressed="true"] {
+        background: var(--surface-tint-10);
+        border-color: var(--surface-tint-25);
         color: var(--foreground);
     }
 
@@ -140,7 +166,13 @@
         border-radius: var(--radius-pill);
         padding: 0.5rem 1rem;
         font-size: 1rem;
-        transition: all var(--duration-fast) var(--ease-standard);
+        transition:
+            background-color var(--duration-fast) var(--ease-standard),
+            border-color var(--duration-fast) var(--ease-standard),
+            box-shadow var(--duration-fast) var(--ease-standard),
+            color var(--duration-fast) var(--ease-standard),
+            opacity var(--duration-fast) var(--ease-standard),
+            transform var(--duration-fast) var(--ease-standard);
     }
 
     .btn-pill > * {
@@ -148,43 +180,10 @@
     }
 
 
-    .btn-pill:active:not(:disabled) {
-        transform: scale(0.96);
-    }
-
     .btn-pill:disabled {
-        opacity: 0.4;
+        opacity: var(--opacity-disabled);
         cursor: not-allowed;
-    }
-
-    .btn-pill-accent {
-        background: var(--th-accent-opaque, var(--primary));
-        color: var(--foreground);
-    }
-
-    .btn-pill-accent:hover:not(:disabled) {
-        opacity: 0.9;
-    }
-
-    .btn-pill-ghost {
-        background: transparent;
-        color: color-mix(in srgb, var(--foreground) 70%, transparent);
-    }
-
-    .btn-pill-ghost:hover:not(:disabled) {
-        background: color-mix(in srgb, var(--foreground) 8%, transparent);
-        color: var(--foreground);
-    }
-
-    .btn-pill-glass {
-        background: var(--glass-bg-subtle);
-        backdrop-filter: var(--glass-blur-subtle);
-        border: 1px solid var(--glass-border-default);
-        color: var(--foreground);
-    }
-
-    .btn-pill-glass:hover:not(:disabled) {
-        box-shadow: var(--glass-shadow-default);
+        pointer-events: none;
     }
 
     /* ── Pill input ───────────────────────────────── */
@@ -193,17 +192,22 @@
 
         height: 2.5rem;
         border-radius: var(--radius-pill);
-        border: 1.5px solid var(--glass-border-subtle);
-        background: var(--glass-bg-default);
-        backdrop-filter: var(--glass-blur-subtle);
+        border: 1.5px solid var(--glass-border-wash);
+        background: var(--glass-bg-quiet);
+        backdrop-filter: var(--glass-blur-wash);
         padding: 0 1rem;
         font-size: 1rem;
         color: var(--foreground);
-        transition: all var(--duration-fast) var(--ease-standard);
+        transition:
+            background-color var(--duration-fast) var(--ease-standard),
+            border-color var(--duration-fast) var(--ease-standard),
+            box-shadow var(--duration-fast) var(--ease-standard),
+            color var(--duration-fast) var(--ease-standard),
+            opacity var(--duration-fast) var(--ease-standard);
     }
 
     .input-pill::placeholder {
-        color: color-mix(in srgb, var(--foreground) 35%, transparent);
+        color: var(--surface-tint-35);
     }
 
     .input-pill:focus {
@@ -221,42 +225,49 @@
 /* ── Accessibility: reduced transparency ────────── */
 @media (prefers-reduced-transparency: reduce) {
     :root {
-        --glass-opacity-subtle: 1;
-        --glass-opacity-default: 1;
-        --glass-opacity-medium: 1;
-        --glass-opacity-elevated: 1;
-        --glass-blur-subtle: none;
-        --glass-blur-default: none;
-        --glass-blur-medium: none;
-        --glass-blur-elevated: none;
+        --glass-opacity-wash: 1;
+        --glass-opacity-quiet: 1;
+        --glass-opacity-resting: 1;
+        --glass-opacity-floating: 1;
+        --glass-opacity-overlay: 1;
+        --glass-blur-wash: none;
+        --glass-blur-quiet: none;
+        --glass-blur-resting: none;
+        --glass-blur-floating: none;
+        --glass-blur-overlay: none;
+        --glass-blur-dock: none;
         --glass-grain-opacity: 0;
-        --glass-highlight: none;
+        --glass-highlight: 0 0 0 0 transparent;
     }
 }
 
 /* ── Accessibility: high contrast ───────────────── */
 @media (prefers-contrast: more) {
     :root {
-        --glass-opacity-subtle: 0.88;
-        --glass-opacity-default: 0.92;
-        --glass-opacity-medium: 0.96;
-        --glass-opacity-elevated: 1;
+        --glass-opacity-wash: 0.85;
+        --glass-opacity-quiet: 0.90;
+        --glass-opacity-resting: 0.94;
+        --glass-opacity-floating: 0.98;
+        --glass-opacity-overlay: 1;
     }
 }
 
 /* ── @supports fallbacks for non-backdrop-filter browsers ── */
 @layer components {
     @supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
-        .glass-subtle {
+        .glass-wash {
+            background: color-mix(in srgb, var(--card) 80%, transparent);
+        }
+        .glass-quiet {
             background: color-mix(in srgb, var(--card) 88%, transparent);
         }
-        .glass-default {
-            background: color-mix(in srgb, var(--card) 92%, transparent);
+        .glass-resting {
+            background: color-mix(in srgb, var(--card) 94%, transparent);
         }
-        .glass-medium {
-            background: color-mix(in srgb, var(--card) 96%, transparent);
+        .glass-floating {
+            background: color-mix(in srgb, var(--card) 98%, transparent);
         }
-        .glass-elevated {
+        .glass-overlay {
             background: var(--card);
         }
         .glass-btn {

package/src/styles/glyph-face.css

@@ -0,0 +1,92 @@
+/* glyph-face.css — three-layer composition for <GlyphFace>.
+ *
+ * Per W2.7 §19 and Q.W3 §F2 + §F8. Wraps a slotted glyph (lucide stroke
+ * or DiscoGlyph SVG) with a phase-tinted radial backplate (visible only
+ * when [data-active="true"]) and a 165° linear-gradient catch-light cap.
+ * The slotted silhouette stays `currentColor` — Vignelli-clean — while
+ * the disco punch lives in the surrounding layers.
+ *
+ * Q.W3.A.1 inversion: when no silhouette resolves, the cap renders
+ * nothing (rather than a wrapper-rectangle fallback). Consumers passing
+ * `silhouette` continue to consume `clip-path: path(var(--gf-silhouette))`;
+ * the lucide consumer sites in ActionCluster + SettingsCog publish via
+ * the silhouette table from `@src/components/speedtest/icons/lucide-silhouettes.ts`,
+ * and DiscoGlyph hands its silhouette upward via provide/inject for
+ * disco wrappers. The fail-safe is now "no cap" not "wrong cap".
+ *
+ * Q.W3.A.2 default raise: --gf-cap-strength 0.35 → 0.55, mix-blend-mode
+ * overlay → screen. `screen` composes correctly against the translucent
+ * dock substrates (`--card` at 50–60% opacity); `overlay` collapses
+ * there because its contrast lift requires an opaque underlay. Consumers
+ * needing the metallic-overlay punch declare `mix-blend-mode: overlay`
+ * via class or `--gf-cap-blend` override.
+ *
+ * Self-contained sheet; no token additions beyond what's already in
+ * `tokens.css`. Consumers may override the cap blend mode and backplate
+ * radius with the documented `--gf-*` custom properties.
+ */
+
+@layer components {
+    .glyph-face {
+        position: relative;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        isolation: isolate;
+        --gf-tint: transparent;
+        --gf-cap-strength: 0.55;
+        --gf-cap-blend: screen;
+        --gf-cap-radius: 50%;
+    }
+
+    .glyph-face-backplate {
+        position: absolute;
+        inset: -25%;
+        border-radius: 50%;
+        background: radial-gradient(
+            ellipse at 30% 30%,
+            var(--gf-tint) 0%,
+            transparent 70%
+        );
+        opacity: 0;
+        transition: opacity var(--duration-fast) var(--spring-snappy);
+        z-index: -1;
+        pointer-events: none;
+    }
+
+    .glyph-face[data-active="true"] .glyph-face-backplate {
+        opacity: 1;
+    }
+
+    /* Cap fail-safe: by default render nothing. The cap only paints
+       when --gf-silhouette resolves (via prop or provide/inject from
+       a DiscoGlyph descendant). This closes the wrapper-rectangle
+       leak the lucide consumers in ActionCluster + SettingsCog hit
+       under the prior opt-in path. */
+    .glyph-face-cap {
+        position: absolute;
+        inset: 0;
+        background: transparent;
+        pointer-events: none;
+        mix-blend-mode: var(--gf-cap-blend);
+    }
+
+    .glyph-face[style*="--gf-silhouette"] .glyph-face-cap {
+        background: linear-gradient(
+            165deg,
+            rgba(255, 255, 255, var(--gf-cap-strength, 0.55)) 0%,
+            transparent 40%
+        );
+        clip-path: var(--gf-silhouette);
+    }
+
+    .dark .glyph-face {
+        --gf-cap-strength: 0.32;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        .glyph-face-backplate {
+            transition: none;
+        }
+    }
+}