@mkbabb/glass-ui 0.2.0 → 2.0.0

package/src/styles/hover-popover.css

@@ -0,0 +1,44 @@
+/* hover-popover.css — substrate sheet for <HoverPopover>.
+ *
+ * Lands as the A5 §10 row 4 carry-forward: IconTooltip's tooltip register
+ * was too quiet for the chassis-tier dock consumers (SettingsCog,
+ * ActionCluster). This sheet ships a popover-tier substrate (glass +
+ * border + radius) sized for label-shaped content; richer slot content
+ * inherits the substrate without extra props.
+ *
+ * The collision-avoidance + side-flip cascade rests on reka-ui's
+ * HoverCard primitives; this sheet is purely visual.
+ */
+
+@layer components {
+    .hover-popover-panel {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.375rem;
+        padding-block: 0.375rem;
+        padding-inline: 0.625rem;
+        border-radius: var(--radius-lg, 0.5rem);
+        background: var(--glass-bg-floating, var(--popover, white));
+        backdrop-filter: var(--glass-blur-floating);
+        border: 1px solid var(--glass-border-floating, var(--border, transparent));
+        color: var(--popover-foreground, var(--foreground));
+        box-shadow: var(--glass-shadow-floating, var(--shadow-md));
+        font-size: var(--type-small, 0.8125rem);
+        line-height: 1.2;
+        max-width: 16rem;
+        white-space: normal;
+        outline: none;
+    }
+
+    .hover-popover-label {
+        display: inline-block;
+    }
+}
+
+/* The data-state animation grammar canonicalises onto `.popover-animate`
+   (V.W3.T9 / A5 §5.8). Authors compose `class="hover-popover-panel popover-animate"`
+   on the panel root so the canonical fade + zoom-95 entry/exit grammar
+   replaces the bespoke `hover-popover-in/out` keyframes that lived here.
+   The `prefers-reduced-motion` carve is handled at the canonical site
+   (`utilities.css`'s reduced-motion block) so it cascades to all four
+   popover-animation consumers automatically. */

package/src/styles/index.css

@@ -4,22 +4,92 @@
  * Import this in your project's main CSS file:
  *   @import "tailwindcss";
  *   @import "tw-animate-css";
- *   @import "@mkbabb/glass-ui/styles";
+ *   @import "@mkbabb/glass-ui/styles";        (critical — no font payload)
+ *   @import "@mkbabb/glass-ui/styles/fonts";  (OFL woff2 corpus, loaded once)
  *   (then add your project-specific token overrides locally)
  */
 
-/* Order matters: tokens first, then theme (for @theme), then component layers */
+/*
+ * FONT PAYLOAD SPLIT (AM-W1-α). The payload-bearing @font-face faces
+ * (Plus Jakarta Sans + Fira Code woff2, base64-inlined at publish into
+ * ~99 KB gzipped) are NOT imported here — they live in `fonts.css`,
+ * reachable via the `@mkbabb/glass-ui/styles/fonts` export. This keeps the
+ * critical first-paint `./styles` entry free of the font binary. The
+ * calibrated `local()` fallback faces (with Capsize metric overrides) DO
+ * stay on this critical path inside typography.css — they paint during the
+ * `font-display: optional`/`swap` window with zero CLS, so the deferred
+ * real-face import never causes a layout shift.
+ *
+ * NOTE: Font @import url(...) lines are NOT issued from here (and never
+ * were) — doing so would put them after @import "tailwindcss" in the
+ * consumer's output, which violates the CSS spec (and some bundlers then
+ * drop them). The split above is by separate export subpath, not @import.
+ */
+
+/*
+ * Cascade order — load order is load-bearing. Each layer references the one
+ * above it via CSS custom properties or selector cascade; reordering breaks
+ * fallbacks. Documented at L.W2 Lane B per Rε §B.5.1.
+ *
+ *   1. tokens.css            — CSS custom properties (color, easing, glass,
+ *                              paper, shadow, surface-tint rungs). Source-of-
+ *                              record for every visual axis.
+ *   2. typography.css        — golden-ratio scale (√φ); semantic type classes.
+ *                              Pure values, no token consumption.
+ *   3. theme.css             — @theme block (Tailwind aliases). Reads tokens
+ *                              from (1) so MUST come after them; defines the
+ *                              `dark` variant selector consumed by the cascade.
+ *   4. glass.css             — .glass-{wash,quiet,resting,floating,overlay}
+ *                              5-rung ladder + .glass-card / -pill / -btn.
+ *                              Consumes tokens (1) + theme aliases (3).
+ *   5. paper.css             — paper underpaint + grain overlay utilities.
+ *                              Pairs with (4) for paper-on-glass compositions.
+ *   6. dock.css              — .dock-icon-btn, .dock-select-trigger, etc.
+ *                              Component utility layer; consumes (1) + (3).
+ *   7. cards.css             — .cartoon-surface, .paper-texture.
+ *                              Component utility layer.
+ *   8. floating-panel.css    — .floating-panel + .floating-panel-item.
+ *                              Component utility layer.
+ *   9. transitions.css       — Vue <Transition> classes (fade, fade-slide,
+ *                              pop, dialog-scale, dropdown, tab-fade).
+ *  10. animations.css        — @keyframes for components consumed via
+ *                              `animation:` properties in (9) and component
+ *                              <style> blocks.
+ *  11. utilities.css         — focus-ring, btn-audacious + btn-interactive
+ *                              (press cluster; K W6 + Q.W3 Lane E),
+ *                              rainbow-vivid + rainbow-pastel. Consumes earlier
+ *                              animations + tokens.
+ *  12. instrument-chassis.css — P-tranche component CSS (chassis bezel +
+ *                              groove dividers). Loaded after utilities so
+ *                              component-local recipes can override.
+ *  13. instrument-rail.css   — AK-W2-α cockpit-ratio rail (flex-basis 1/φ²
+ *                              binding + bezel hairlines + sibling divider
+ *                              rule). Composes alongside instrument-chassis;
+ *                              shares the bezel-line twin-pixel idiom.
+ *  14. glyph-face.css        — P-tranche component CSS (cap + backplate).
+ *  15. disco-glyph.css       — P-tranche component CSS (layered fills).
+ *  16. hover-popover.css     — V.W3 popover-animation grammar.
+ *
+ * Per-package component CSS lives at (12)-(16) (loaded after utilities so
+ * component-local recipes can override). New per-package CSS files append
+ * to that tail.
+ */
 @import "./tokens.css";
 @import "./typography.css";
 @import "./theme.css";
 @import "./glass.css";
+@import "./paper.css";
 @import "./dock.css";
 @import "./cards.css";
-@import "./scroll-pane.css";
 @import "./floating-panel.css";
 @import "./transitions.css";
 @import "./animations.css";
 @import "./utilities.css";
+@import "./instrument-chassis.css";
+@import "./instrument-rail.css";
+@import "./glyph-face.css";
+@import "./disco-glyph.css";
+@import "./hover-popover.css";
 
 /* Ensure consumer's Tailwind scans glass-ui components for utility classes
    (e.g. CVA button variants like text-destructive-foreground) */

package/src/styles/instrument-chassis.css

@@ -0,0 +1,313 @@
+/* instrument-chassis.css — chassis surface + region dividers + phase cascade.
+ *
+ * Composes the three-region <InstrumentChassis> per W2.7 §1, §2, §3, §11, §16.
+ * The chassis is one glass surface with an engraved-bezel ::before stroke and
+ * a radial-gradient curvature overlay; both persist at all phases (chassis
+ * character, not interactive accent).
+ *
+ * Region dividers compose two 1px lines — top catch-light, bottom under-
+ * shadow — into a hairline groove. This twin-line idiom is the chassis
+ * signature; every divider in the system uses it.
+ *
+ * `--phase-color` cascades from the chassis root via `data-phase`. Phase
+ * label, hero number, and phase progress fill all read it; one mutation at
+ * the chassis level retints every consumer with a single 450ms transition.
+ *
+ * Disco accents (specular swap, sparkle, phase-glow, disco-grain) live on
+ * `.dock-tab-button[data-tier="primary"]` in `dock.css` and on
+ * `.metric-badge[data-just-resolved="true"]` in `utilities.css`. They fire
+ * on hover / phase-finish only. Idle is purely Vignelli.
+ */
+
+@layer components {
+    .instrument-chassis {
+        position: relative;
+        display: flex;
+        flex-direction: column;
+        /* AI.W4-M.1 — chassis tint companion. The backdrop composes the
+           resting glass plate with a `color-mix` toward `--phase-color`
+           by `--phase-tint-amount`. At idle the typed amount sits at 0%
+           (initial-value from tokens.css §18) so the surface reads the
+           pure resting plate; the [data-phase] selectors below ramp the
+           amount toward `--phase-tint-peak` (6% default), and the
+           transition interpolates the typed percentage over the speed-
+           test-owned phase-handoff clock. Fallback 600ms keeps a non-
+           speedtest consumer's chassis cross-fading smoothly even
+           without the consumer-side token declared. */
+        background:
+            var(--glass-curvature-overlay, none),
+            color-mix(
+                in oklab,
+                var(--glass-bg-chassis),
+                var(--phase-color, var(--muted-foreground)) var(--phase-tint-amount, 0%)
+            );
+        transition: --phase-tint-amount
+            var(--motion-duration-phase-handoff, 600ms)
+            var(--motion-ease-standard);
+        backdrop-filter: var(--glass-blur-quiet);
+        /* AK-FD1 §2.4 — glass-variant outer border softened one rung down the
+           foreground-tinted border ladder (quiet 10% → wash 8%) so it reads at
+           the intended resting-glass register. The spine variant carries its
+           own `--glass-spine-border` (re-declared below) and is unaffected. */
+        border: 1px solid var(--glass-border-wash);
+        border-radius: var(--radius-card);
+        box-shadow:
+            var(--glass-shadow-quiet),
+            inset 0 -0.5px 0 0 rgb(0 0 0 / 0.06);
+        overflow: hidden;
+
+        /* `--phase-color` defaults to muted-foreground at idle. data-phase
+           selectors below retint to the chart hue. Consumers register
+           --chart-* aliases in their preset; tokens.css ships safe defaults.
+
+           `--phase-color-label` is the WCAG companion (AC.W6c F1.V-04). It
+           pairs with `--phase-color` 1:1 — same `data-phase` cascade, but
+           routes through `--chart-{phase}-label` (L≈0.40 in OKLCH) so
+           text-on-background callsites clear the 4.5:1 contrast floor.
+           Canvas / fill / gradient consumers continue to read `--phase-color`
+           (saturated brand register, correct against the meter dial).
+           Label / text consumers read `--phase-color-label` with the
+           untinted token as a fallback so an unhydrated subtree still
+           paints something readable. */
+        --phase-color: var(--muted-foreground);
+        --phase-color-label: var(--muted-foreground);
+    }
+
+    .dark .instrument-chassis {
+        background:
+            var(--glass-curvature-overlay-dark, var(--glass-curvature-overlay, none)),
+            color-mix(
+                in oklab,
+                var(--glass-bg-chassis),
+                var(--phase-color, var(--muted-foreground)) var(--phase-tint-amount, 0%)
+            );
+    }
+
+    /* Engraved-bezel inner stroke. Reads as the polished sleeve of an
+       instrument-panel module. Subtle but load-bearing for the disco-skeu
+       reading. */
+    .instrument-chassis::before {
+        content: "";
+        position: absolute;
+        inset: 0.5px;
+        border-radius: calc(var(--radius-card) - 0.5px);
+        border: 1px solid var(--surface-tint-4);
+        pointer-events: none;
+        z-index: 1;
+    }
+
+    .dark .instrument-chassis::before {
+        border-color: var(--surface-tint-6);
+    }
+
+    /* ─────────────────────────────────────────────────────────────
+       AL-W1-α augmented — spine variant (HOUSING register)
+
+       Per AL-X5 §4.1 + Y7. The `variant="spine"` chassis is the
+       polished SLEEVE that frames an inner card on quiet-content
+       App-level mounts. NOT glass:
+         - opacity 0 (no plate; `--glass-spine-opacity` is the canon)
+         - NO backdrop-filter (housing is not refracting)
+         - hairline outer stroke at `--glass-spine-border`
+         - interior radial vignette (`--glass-spine-vignette`) that
+           reads the phase-color cascade through `color-mix()` at
+           ~8% opacity — the housing breathes with the active phase
+           without competing with the inner card's saturated register
+         - tight under-shadow rim via `--glass-under-shadow-spine`
+         - inset from viewport by `clamp(0.5rem, 2vw, 1.25rem)` so
+           the chassis edge sits BEYOND the inner card's outer edge
+         - retires the engraved-bezel `::before` (the spine carries
+           its own stroke at the outer edge; the inner bezel would
+           collide with the inner card's hairline ring)
+
+       The phase cascade above (`[data-phase="…"]`) is orthogonal —
+       the `--phase-color` retint reaches the spine vignette via the
+       `color-mix(in oklab, var(--phase-color) 8%, transparent)` recipe
+       at `--glass-spine-vignette`. One mutation at the chassis level
+       still retints every consumer.
+       ───────────────────────────────────────────────────────────── */
+    .instrument-chassis[data-variant="spine"] {
+        background: var(--glass-spine-vignette);
+        backdrop-filter: none;
+        border: 1px solid var(--glass-spine-border);
+        box-shadow: var(--glass-under-shadow-spine);
+        margin: clamp(0.5rem, 2vw, 1.25rem);
+    }
+
+    /* The engraved-bezel inner stroke is a `"glass"`-variant feature —
+       retire it at the spine variant so the hairline outer stroke reads
+       alone (the inner card paints its own inner ring). */
+    .instrument-chassis[data-variant="spine"]::before {
+        display: none;
+    }
+
+    /* Phase-color cascade — single property, full chassis-wide retint.
+       `--phase-color-label` mirrors the cascade through the WCAG companion
+       tokens (AC.W6c F1.V-04). The label register falls back to the canvas
+       hue so a consumer that hasn't migrated its labels still paints.
+
+       AI.W4-M.1 — `--phase-tint-amount` lifts to `--phase-tint-peak`
+       (6% default) on every active phase, including `complete`. The chassis
+       backdrop reads the typed amount in its `color-mix` recipe above; the
+       transition interpolates over the phase-handoff clock so the warmth
+       cross-fades alongside the hue. Idle returns to 0% by inheritance
+       (the typed @property initial-value). */
+    .instrument-chassis[data-phase="ping"] {
+        --phase-color: var(--chart-ping, var(--viz-chebyshev));
+        --phase-color-label: var(--chart-ping-label, var(--chart-ping, var(--viz-chebyshev)));
+        --phase-tint-amount: var(--phase-tint-peak);
+    }
+    .instrument-chassis[data-phase="download"] {
+        --phase-color: var(--chart-download, var(--viz-fourier));
+        --phase-color-label: var(--chart-download-label, var(--chart-download, var(--viz-fourier)));
+        --phase-tint-amount: var(--phase-tint-peak);
+    }
+    .instrument-chassis[data-phase="upload"] {
+        --phase-color: var(--chart-upload, var(--viz-amber));
+        --phase-color-label: var(--chart-upload-label, var(--chart-upload, var(--viz-amber)));
+        --phase-tint-amount: var(--phase-tint-peak);
+    }
+    .instrument-chassis[data-phase="jitter"] {
+        --phase-color: var(--chart-jitter, var(--viz-legendre));
+        --phase-color-label: var(--chart-jitter-label, var(--chart-jitter, var(--viz-legendre)));
+        --phase-tint-amount: var(--phase-tint-peak);
+    }
+    .instrument-chassis[data-phase="complete"] {
+        --phase-color: var(--color-gold);
+        --phase-color-label: var(--color-gold-dark, var(--color-gold));
+        --phase-tint-amount: var(--phase-tint-peak);
+    }
+
+    /* PRM bracket — the typed-property transition retires; the chassis
+       still cross-fades hue + amount instantaneously on phase change
+       (the discrete state IS the affirmation). */
+    @media (prefers-reduced-motion: reduce) {
+        .instrument-chassis {
+            transition: none;
+        }
+    }
+
+    /* Region wrappers ─────────────────────────────────────────── */
+
+    .instrument-strip {
+        position: relative;
+        display: flex;
+        align-items: center;
+        gap: var(--instrument-strip-gap, 0.75rem);
+        padding:
+            var(--instrument-strip-padding-block, 0.875rem)
+            var(--instrument-strip-padding-inline, 1.25rem);
+        z-index: 2;
+    }
+
+    .instrument-dial {
+        position: relative;
+        display: grid;
+        grid-template-columns: var(--instrument-dial-columns, minmax(0, 1.2fr) 1px minmax(0, 1fr));
+        align-items: center;
+        gap: var(--instrument-dial-gap, 1.5rem);
+        padding:
+            var(--instrument-dial-padding-block, 1.5rem)
+            var(--instrument-dial-padding-inline, 1.5rem);
+        z-index: 2;
+    }
+
+    .instrument-control {
+        position: relative;
+        display: flex;
+        align-items: center;
+        gap: var(--instrument-control-gap, 0.5rem);
+        padding:
+            var(--instrument-control-padding-block, 0.875rem)
+            var(--instrument-control-padding-inline, 1.25rem);
+        z-index: 2;
+    }
+
+    /* Chassis dividers — twin-line hairline grooves ─────────────── */
+
+    .chassis-divider {
+        flex-shrink: 0;
+        position: relative;
+        background: transparent;
+        z-index: 2;
+        pointer-events: none;
+    }
+
+    .chassis-divider--horizontal {
+        display: flex;
+        flex-direction: column;
+        height: 2px;
+        width: 100%;
+    }
+
+    .chassis-divider--vertical {
+        display: flex;
+        flex-direction: row;
+        width: 2px;
+        height: var(--chassis-divider-vertical-height, 70%);
+        align-self: center;
+        justify-self: center;
+    }
+
+    .bezel-line {
+        display: block;
+        flex-shrink: 0;
+    }
+
+    .chassis-divider--horizontal .bezel-line {
+        height: 1px;
+        width: 100%;
+    }
+
+    .chassis-divider--vertical .bezel-line {
+        width: 1px;
+        height: 100%;
+    }
+
+    /* Q.W4.A — bezel-line α lift in light mode per audit-A4 §1 row 2-3 +
+       §11 #2-#3 + §12 Action 2. The 0.04 / 0.06 light-mode pair was
+       calibrated against a flat bg; under the saturated-aurora chassis
+       composition the catch-light + under-shadow read as one slightly
+       darker pixel, and the twin-line groove fails its job. Bumping to
+       0.10 / 0.12 holds the divider against the bleed without committing
+       to the dark-mode pair's contrast (the dark mode already runs at
+       0.06 / 0.18 against a low-light bg). */
+    .bezel-line.top    { background: rgb(255 255 255 / 0.10); }
+    .bezel-line.bottom { background: rgb(0 0 0 / 0.12); }
+
+    .dark .bezel-line.top    { background: rgb(255 255 255 / 0.06); }
+    .dark .bezel-line.bottom { background: rgb(0 0 0 / 0.18); }
+
+    /* Inner dial divider — same primitive, vertical on desktop. Speedtest
+       slots its <ChassisDivider orientation="vertical" class="dial-divider" />
+       between the meter canvas and the readout column; consumers may also
+       compose their own vertical dividers via the same primitive. */
+    .instrument-chassis .dial-divider {
+        align-self: stretch;
+    }
+
+    /* Mobile reflow — dial stacks vertically; the inner divider rotates from
+       a vertical groove (desktop) to a horizontal groove (mobile). Same
+       twin-line idiom, different orientation. */
+    @media (max-width: 720px) {
+        .instrument-chassis .instrument-dial {
+            grid-template-columns: 1fr;
+            grid-template-rows: auto auto auto;
+            gap: var(--instrument-dial-gap-mobile, 1.5rem);
+        }
+
+        .instrument-chassis .instrument-dial .dial-divider,
+        .instrument-chassis .instrument-dial .chassis-divider--vertical {
+            flex-direction: column;
+            width: 70%;
+            height: 2px;
+            margin-inline: auto;
+        }
+
+        .instrument-chassis .instrument-dial .dial-divider .bezel-line,
+        .instrument-chassis .instrument-dial .chassis-divider--vertical .bezel-line {
+            width: 100%;
+            height: 1px;
+        }
+    }
+}

package/src/styles/instrument-rail.css

@@ -0,0 +1,128 @@
+/* instrument-rail.css — cockpit-ratio rail with bezel hairlines + sibling
+ * divider rule.
+ *
+ * AK-W2-α — see A3 §8.T-1 + FD1 TRANSPOSITION 6 + G-AK-D9. Resolves D-4
+ * (desktop survey cockpit ratio 0.222 → 0.382). The rail carries the
+ * golden-gestalt 1/φ² flex-basis as a typed term with min/max clamp
+ * safety, the engraved-bezel ::before stroke that <InstrumentChassis>
+ * established as chassis grammar, and a twin-line groove between sibling
+ * children via the same `bezel-line` α pair the chassis-divider primitive
+ * uses (light 0.10 / 0.12; dark 0.06 / 0.18 — Q.W4.A canon).
+ *
+ * The rail is a layout primitive: no animation, no phase cascade, no
+ * disco accent. PRM cascades through children (each owns its own
+ * animation contract). Phase color inherits from a parent
+ * <InstrumentChassis> if present — the rail itself reads no phase token.
+ */
+
+@layer components {
+    .instrument-rail {
+        position: relative;
+        display: flex;
+        flex-direction: column;
+        /* The cockpit-ratio binding. Default 0.382 = 1/φ² (golden gestalt).
+           Min/max clamp pins the realised width to a readable register so
+           a degenerate ratio or a very narrow / very wide parent still
+           lands inside the bezel-instrument vocabulary. */
+        flex: 0 0 calc(var(--instrument-rail-ratio, 0.382) * 100%);
+        min-width: 15rem;
+        max-width: 28rem;
+        box-sizing: border-box;
+        gap: var(--instrument-rail-gap, 1rem);
+        padding:
+            var(--instrument-rail-padding-block, 1.25rem)
+            var(--instrument-rail-padding-inline, 1.25rem);
+        container-type: inline-size;
+        container-name: instrument-rail;
+    }
+
+    .instrument-rail[data-variant="horizontal"] {
+        flex-direction: row;
+        flex: 0 0 auto;
+        min-width: 0;
+        max-width: none;
+        min-height: 15rem;
+        max-height: 28rem;
+        block-size: calc(var(--instrument-rail-ratio, 0.382) * 100%);
+        container-type: size;
+    }
+
+    /* Engraved-bezel inner stroke — the chassis signature detail, applied
+       to the rail so it reads as a chassis-internal module rather than an
+       unbordered slot. Subtle but load-bearing for the disco-skeu reading
+       (FD1 TRANSPOSITION 3). */
+    .instrument-rail[data-bezel-hairlines]::before {
+        content: "";
+        position: absolute;
+        inset: 0.5px;
+        border-radius: calc(var(--radius-card, 1rem) - 0.5px);
+        border: 1px solid var(--surface-tint-4);
+        pointer-events: none;
+        z-index: 1;
+    }
+
+    .dark .instrument-rail[data-bezel-hairlines]::before {
+        border-color: var(--surface-tint-6);
+    }
+
+    /* Sibling divider rule — twin-line hairline groove between every
+       child after the first. The twin-line idiom (catch-light over
+       under-shadow) is the chassis-divider signature; rendering it via
+       a sibling ::before/::after stack keeps consumers free of manual
+       <ChassisDivider> slotting. Status header is excluded — the
+       opening-edge status light reads as a region, not a sibling. */
+    .instrument-rail[data-divider-rule][data-variant="vertical"]
+        > :not(:first-child):not(.instrument-rail-status)::before {
+        content: "";
+        display: block;
+        height: 1px;
+        margin-block-end: 1px;
+        background: rgb(255 255 255 / 0.10);
+    }
+
+    .instrument-rail[data-divider-rule][data-variant="vertical"]
+        > :not(:first-child):not(.instrument-rail-status)::after {
+        content: "";
+        display: block;
+        height: 1px;
+        margin-block-start: -1px;
+        background: rgb(0 0 0 / 0.12);
+    }
+
+    .instrument-rail[data-divider-rule][data-variant="horizontal"]
+        > :not(:first-child):not(.instrument-rail-status)::before {
+        content: "";
+        display: block;
+        width: 1px;
+        margin-inline-end: 1px;
+        background: rgb(255 255 255 / 0.10);
+    }
+
+    .instrument-rail[data-divider-rule][data-variant="horizontal"]
+        > :not(:first-child):not(.instrument-rail-status)::after {
+        content: "";
+        display: block;
+        width: 1px;
+        margin-inline-start: -1px;
+        background: rgb(0 0 0 / 0.12);
+    }
+
+    .dark .instrument-rail[data-divider-rule] > :not(:first-child):not(.instrument-rail-status)::before {
+        background: rgb(255 255 255 / 0.06);
+    }
+
+    .dark .instrument-rail[data-divider-rule] > :not(:first-child):not(.instrument-rail-status)::after {
+        background: rgb(0 0 0 / 0.18);
+    }
+
+    /* Status header — pinned to the opening edge, flush against the
+       bezel. The rail's bezel ::before draws over the surface-edge so the
+       status region sits inside the bezel sleeve. */
+    .instrument-rail-status {
+        position: relative;
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        z-index: 2;
+    }
+}

package/src/styles/paper.css

@@ -0,0 +1,68 @@
+/*
+ * paper.css — Paper-texture primitives
+ *
+ * Two composable Tailwind `@utility` declarations:
+ *   - paper-underpaint: fixed, app-root, fullscreen SVG turbulence at z-index -1
+ *   - paper-grain-overlay: ::after overlay for individual surfaces
+ *
+ * Texture: feTurbulence baseFrequency 0.65, 4 octaves, desaturated via
+ * feColorMatrix, blended multiply (light) / soft-light (dark). Tiles ~60px.
+ */
+
+@utility paper-underpaint {
+    position: fixed;
+    inset: 0;
+    z-index: -1;
+    pointer-events: none;
+    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);
+    mix-blend-mode: multiply;
+}
+
+:where(.dark) .paper-underpaint,
+.dark .paper-underpaint {
+    mix-blend-mode: soft-light;
+}
+
+@utility paper-grain-overlay {
+    position: relative;
+    isolation: isolate;
+
+    &::after {
+        content: "";
+        position: absolute;
+        inset: 0;
+        border-radius: inherit;
+        pointer-events: none;
+        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);
+        mix-blend-mode: overlay;
+    }
+}
+
+:where(.dark) .paper-grain-overlay::after,
+.dark .paper-grain-overlay::after {
+    mix-blend-mode: soft-light;
+}
+
+/* ═══════════════════════════════════════════════
+   A11y — respect user motion + transparency preferences
+   ═══════════════════════════════════════════════ */
+@media (prefers-reduced-transparency: reduce) {
+    .paper-underpaint,
+    .paper-grain-overlay::after {
+        opacity: 0;
+    }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .paper-underpaint {
+        /* Static noise is fine at rest; only kill animated grain shimmer if any.
+           The underpaint is currently a still texture, but guard future motion. */
+        animation: none !important;
+    }
+}