@mkbabb/glass-ui 3.12.0 → 3.13.0

package/src/styles/glass/a11y-fallback.css

@@ -0,0 +1,245 @@
+/* glass/a11y-fallback.css
+   The accessibility + capability overrides — @media (prefers-reduced-transparency) / (prefers-contrast: more) / (forced-colors: active), the non-backdrop-filter @layer components fallback, and the :has()-less @supports fallback. LAST in cascade (they override the base ladder).
+   Carved from the glass.css cascade root; @import-ed by glass.css in cascade
+   order, each in its own @layer components (isomorphic to the monolith).
+   See docs/precepts/design-idioms.md §cohesion-aware partials. */
+/* ── Accessibility: reduced transparency ──────────
+   AX.W54 — the gestalt collapse: ONE `--glass-level: 0` replaces the ten per-rung
+   opacity+blur clobbers. The level-0 path resolves solid `--card` + `blur(0)`
+   through the SAME machinery (the opacity seam → 1, the blur seam → 0), so every
+   glass surface — current and future — flattens with no per-rung enumeration. The
+   grain + highlight kills stay (they sit off the level axis). */
+@media (prefers-reduced-transparency: reduce) {
+    :root {
+        --glass-level: 0;
+        --glass-grain-opacity: 0;
+        --glass-highlight: 0 0 0 0 transparent;
+    }
+}
+
+/* ── Accessibility: high contrast ─────────────────
+   AX.W54 — a single bounded `--glass-level: 0.3` (mostly-solid, not fully flat)
+   replaces the five per-rung opacity clobbers: every rung firms up toward solid
+   for AA while keeping a hint of the glass register. ONE knob, every rung.
+
+   AX.W55 — the Clear↔Tinted user-escape (Apple's iOS-26.2 analog) COORDINATES the
+   two axes here: the OPACITY axis rides W54's `--glass-level` (firm up toward solid)
+   AND the TINT axis biases toward ink — `--glass-tint-source` → the warm-ink +
+   `--glass-tint-strength` → the AA floor, the same darken the automatic bright
+   bucket applies, now reached by the explicit "more contrast" user request. The two
+   axes stay DISTINCT (level = opacity+blur, tint = darken) but share the bracket so
+   a high-contrast user gets BOTH a firmer plate and the ink-tint legibility lift —
+   one coordinated escape, not two parallel forks. */
+@media (prefers-contrast: more) {
+    :root {
+        --glass-level: 0.3;
+        --glass-tint-source: var(--glass-tint-ink);
+        --glass-tint-strength: var(--glass-tint-strength-aa);
+    }
+}
+
+/* ── Accessibility: forced-colors (Windows High Contrast) glass-language skin ──
+   AX.W36 — when the OS forces a palette (Windows High Contrast), the platform
+   strips the whole decorative glass register: `backdrop-filter` is dropped, the
+   `--glass-*` inset/box-shadow rungs vanish, and every meaning-bearing chroma
+   flattens to one system color. A `.glass-floating` Dialog over a `.glass-resting`
+   Card would read as two borderless transparent rectangles with no edge, and a
+   green-vs-red StatusDot would resolve to one indistinguishable dot. This skin
+   restores the STRUCTURE the glass chrome encoded — it does NOT pin glass-ui's
+   brand colours (no `forced-color-adjust: none`); the chrome is decorative and
+   YIELDS to the user's forced palette (css forced-colors guidance). Only the
+   standard WHC system keywords are used (`Canvas`/`CanvasText`/`Highlight`) — no
+   glass-ui token leaks into the WHC arm.
+
+   COORDINATES WITH W54 — the same `--glass-level: 0` opaque escape the reduced-
+   transparency / high-contrast brackets ride. Setting the ONE clarity knob to 0
+   collapses the `--glass-bg-*` opacity recipe to solid `--card` + `blur(0)` through
+   the SAME machinery (no parallel solid recipe), so the platform sees opaque plates
+   it maps to `Canvas`. The grain + highlight kills match the reduce bracket (they
+   sit off the level axis). The W55 tint axis is moot under WHC (the user's palette
+   supersedes the ink-darken) but harmless — the opaque plate is system-painted. */
+@media (forced-colors: active) {
+    :root {
+        --glass-level: 0;
+        --glass-grain-opacity: 0;
+        --glass-highlight: 0 0 0 0 transparent;
+    }
+
+    /* Every glass-material ladder rung relied on `backdrop-filter` + an inset
+       `box-shadow` rim for its silhouette — both gone under WHC. Restore a real
+       `border` keyed to the system text colour so each tier pane reads as a boxed
+       region. The selector group MIRRORS the ladder definition above (one source,
+       not a hand-rolled re-list) so a future rung added to the material group
+       inherits the WHC edge for free — and any `.glass-material` div picks up the
+       edge with no per-component arm. */
+    .glass-material,
+    .glass-wash,
+    .glass-quiet,
+    .glass-resting,
+    .glass-floating,
+    .glass-overlay,
+    .glass-card,
+    .glass-drawer {
+        border: 1px solid CanvasText;
+    }
+
+    /* The floating + overlay rungs (Dialog / Sheet / Popover / DropdownMenu /
+       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-drawer {
+        background: Canvas;
+    }
+
+    /* The decorative specular catch-light (`::before`) + grain overlay (`::after`)
+       paint nothing meaningful once chroma collapses — yield them entirely (the
+       same decorative-chrome cede the `--glass-level: 0` opaque escape performs on
+       the body). They are NOT part of the structure the skin restores. */
+    .glass-material::before,
+    .glass-wash::before,
+    .glass-quiet::before,
+    .glass-resting::before,
+    .glass-floating::before,
+    .glass-overlay::before,
+    .glass-card::before,
+    .glass-drawer::before,
+    .glass-wash::after,
+    .glass-quiet::after,
+    .glass-resting::after,
+    .glass-floating::after,
+    .glass-overlay::after {
+        display: none;
+    }
+
+    /* Meaning-bearing hue identity → a bordered glyph that keeps ok/warn/error
+       distinguishable by a WHC-HONORED system color, NOT a glass-ui hue (which WHC
+       strips to one fill). StatusDot reflects its variant onto `data-status`
+       (StatusDot.vue) and the inner dot carries `.status-dot__dot`; the
+       `role="img"` + `aria-label` accessible name already ships, so this is the
+       VISUAL differentiation only. A bare bordered dot + the per-status fill triplet
+       below means a sighted WHC user can still tell the row apart.
+
+       `!important` IS load-bearing here: StatusDot paints the dot fill via an INLINE
+       `:style="dotStyle"` (`background-color`, specificity 1,0,0,0), which outranks
+       any stylesheet selector AND which forced-colors then `forced-color-adjust:
+       auto`-remaps to a single Canvas-white — collapsing the row to one indistinct
+       dot. The WHC arm must override that inline fill, and inline can only be beaten
+       by `!important`; this is the documented forced-colors degradation path (the
+       arm only activates under WHC). The component keeps its inline hue in normal
+       mode untouched. */
+    .status-dot__dot {
+        border: 1px solid CanvasText;
+        /* The bordered ring alone separates a dot from its surround; the per-status
+           fill below adds the WHC-honored distinction. */
+    }
+    /* The inner painted fill (`.status-dot__fill`, `h-full w-full`) + the pulse ring
+       carry the SAME inline glass-ui hue StatusDot paints — under WHC they cover the
+       outer `.status-dot__dot` glyph with a `forced-color-adjust`-remapped Canvas
+       fill (the row collapses to one white dot even with the outer system color set).
+       Yield them so the outer bordered + system-color glyph is the sole visible dot. */
+    .status-dot__fill,
+    .status-dot__pulse {
+        display: none;
+    }
+    /* The ok/warn/error/idle distinction rides the standard WHC keyword palette:
+         active (ok)   → Highlight   (the affirmative system accent)
+         paused (warn) → Mark        (the marked/attention system color)
+         error         → CanvasText  (a solid filled dot — the strongest weight)
+         idle/custom   → Canvas      (a hollow dot — only the CanvasText ring reads)
+       Each stays distinguishable by the system color the user's palette assigns,
+       never glass-ui chroma. The `!important` beats the component's inline fill. */
+    .status-dot__dot[data-status="active"] {
+        background: Highlight !important;
+    }
+    .status-dot__dot[data-status="paused"] {
+        background: Mark !important;
+    }
+    .status-dot__dot[data-status="error"] {
+        background: CanvasText !important;
+    }
+    .status-dot__dot[data-status="idle"],
+    .status-dot__dot[data-status="custom"] {
+        background: Canvas !important;
+    }
+}
+
+/* ── @supports fallbacks for non-backdrop-filter browsers ── */
+@layer components {
+    /* GUARD 1 — the NO-BLUR-AT-ALL engine (supports NEITHER the unprefixed NOR the
+       webkit form): paint an opaque-leaning plate so text stays legible without any
+       blur. AY.W-A11Y-PERF O-2b note: this is the floor for the theoretical
+       neither-supported case. The Safari ≤17 webkit-only trap (supports the `-webkit-`
+       form, so this `@supports not (… or …)` is FALSE and the fallback does NOT fire)
+       is closed at the SOURCE OF THE PREFIX: O-2a's build pass guarantees the shipped
+       dist carries the `-webkit-backdrop-filter:` pair, so a Safari-17 engine renders
+       the BLUR off the prefixed rule (it no longer falls through to a transparent
+       unprefixed-only surface). The trap closes where the prefix is emitted, not here. */
+    @supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+        .glass-wash {
+            background: color-mix(in srgb, var(--card) 80%, transparent);
+        }
+        .glass-quiet {
+            background: color-mix(in srgb, var(--card) 88%, transparent);
+        }
+        .glass-resting {
+            background: color-mix(in srgb, var(--card) 94%, transparent);
+        }
+        .glass-floating {
+            background: color-mix(in srgb, var(--card) 98%, transparent);
+        }
+        .glass-overlay {
+            background: var(--card);
+        }
+        .glass-btn {
+            background: color-mix(in srgb, var(--background) 92%, transparent);
+        }
+    }
+
+    /* GUARD 2 — the WEBKIT-ONLY engine (supports `-webkit-backdrop-filter` but NOT the
+       unprefixed `backdrop-filter` — Safari ≤17). With O-2a's build-emitted prefix the
+       shipped rung carries the `-webkit-backdrop-filter:` pair, so this engine PAINTS
+       the blur off that prefixed declaration. This guard exists to DOCUMENT-and-confirm
+       that path (and would re-assert the translucent glass identity if a future change
+       ever stripped the rung bg under this engine) — it re-states the rungs' translucent
+       glass-mix so a webkit-only engine that DID get the prefix keeps the glass look,
+       never the opaque GUARD-1 plate. The `proof:webkit-backdrop` gate asserts the
+       shipped dist carries BOTH guards. */
+    @supports ((-webkit-backdrop-filter: blur(1px)) and (not (backdrop-filter: blur(1px)))) {
+        .glass-wash {
+            background: color-mix(in oklab, var(--glass-bg-wash), var(--glass-tint-source) var(--glass-tint-strength));
+        }
+        .glass-quiet {
+            background: color-mix(in oklab, var(--glass-bg-quiet), var(--glass-tint-source) var(--glass-tint-strength));
+        }
+        .glass-resting {
+            background: color-mix(in oklab, var(--glass-bg-resting), var(--glass-tint-source) var(--glass-tint-strength));
+        }
+        .glass-floating {
+            background: color-mix(in oklab, var(--glass-bg-floating), var(--glass-tint-source) var(--glass-tint-strength));
+        }
+        .glass-overlay {
+            background: color-mix(in oklab, var(--glass-bg-overlay), var(--glass-tint-source) var(--glass-tint-strength));
+        }
+        .glass-btn {
+            background: var(--glass-bg-wash);
+        }
+    }
+}
+
+/* ── :has() focus-elevation fallback (AQ.W3 §W3.1a) ──────────────────────
+   SOLE fallback for engines without `:has()`. `.is-focus-within` is toggled
+   by a ≤6-LOC focusin/focusout guard in `Card.vue` that runs ONLY when
+   `!CSS.supports('selector(:has(*))')` (modern engines run zero JS). The
+   class redefines the SAME `--card-focus-*` rungs as the `:has()` rule, so the
+   override values have one source. NOT a live+dead alias — `:has()` is the
+   enhancement, this the documented degradation path. */
+@supports not selector(:has(*)) {
+    .glass-card.is-focus-within {
+        --card-focus-shadow: var(--shadow-md);
+        --card-focus-border: var(--glass-border-floating);
+    }
+}

package/src/styles/glass/ladder.css

@@ -0,0 +1,337 @@
+/* glass/ladder.css
+   The five-tier .glass-{wash,quiet,resting,floating,overlay} surface ladder + the W55 adaptive-legibility @container style(--glass-backdrop: light) bucket (co-located with its rung) + the .glass-opaque escape + the content-aware under-shadow.
+   Carved from the glass.css cascade root; @import-ed by glass.css in cascade
+   order, each in its own @layer components (isomorphic to the monolith).
+   See docs/precepts/design-idioms.md §cohesion-aware partials. */
+@layer components {
+    /* ── 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 IN SOURCE. Authoring both forms manually here
+       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). AY.W-A11Y-PERF O-2a — the
+       build now OWNS the prefix: `vite.style-assets.ts publishStyleAssets()`
+       injects the `-webkit-backdrop-filter:` pair into the SHIPPED
+       `dist/styles/*.css` as a LAST pass (the source stays unprefixed, so
+       the Lightning dedup never sees both forms; the build emits the pair
+       after the cascade is assembled). This GUARANTEES the prefix reaches
+       dist/ regardless of the consumer's autoprefixer/browserslist — a
+       Safari ≤17 engine (webkit-form-only) paints the blur instead of
+       silently dropping the unprefixed rule. Verified by
+       `proof:webkit-backdrop` (count-parity over the shipped dist). */
+    /* AW.W23 — every rung's background composes the adaptive-tint recipe
+       (`color-mix(in oklab, <rung bg>, var(--glass-tint-source) var(--glass-tint-
+       strength))`). With the default `--glass-tint-strength: 0%` the mix is a
+       no-op = byte-identical to the un-tinted rung; a consumer biases the surface
+       toward a sampled backdrop hue by setting `--glass-tint-source` + a
+       strength ≤30%. oklab is the mwg-preferred tint space (NEVER an
+       `oklch(from …)` lightness-shift — browsers don't gamut-map yet). */
+    .glass-wash {
+        position: relative;
+        background: color-mix(in oklab, var(--glass-bg-wash), var(--glass-tint-source) var(--glass-tint-strength));
+        backdrop-filter: var(--glass-blur-wash);
+        border: 1px solid var(--glass-border-wash);
+        box-shadow: var(--glass-material-rim), var(--glass-shadow-wash);
+    }
+
+    /* 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: color-mix(in oklab, var(--glass-bg-quiet), var(--glass-tint-source) var(--glass-tint-strength));
+        backdrop-filter: var(--glass-blur-quiet);
+        border: 1px solid var(--glass-border-quiet);
+        box-shadow:
+            var(--glass-material-rim),
+            var(--glass-under-shadow-quiet),
+            var(--glass-shadow-quiet);
+    }
+
+    .glass-resting {
+        position: relative;
+        background: color-mix(in oklab, var(--glass-bg-resting), var(--glass-tint-source) var(--glass-tint-strength));
+        backdrop-filter: var(--glass-blur-resting);
+        border: 1px solid var(--glass-border-resting);
+        box-shadow:
+            var(--glass-material-rim),
+            var(--glass-under-shadow-default),
+            var(--glass-shadow-resting);
+    }
+
+    /* AV.W15 M3 / AW.W22 — the floating tier carries the full-perimeter rim (the
+       catch-light that "defines the silhouette", WWDC25 sess. 219). The rim now
+       comes from the unified `--glass-material-rim` (= `--glass-edge-light`) so
+       it shares ONE source with the rest of the ladder; it rides INSIDE the
+       box-shadow stack so it composes with the under-shadow floor + the lift. */
+    .glass-floating {
+        /* AY.W-A11Y-PERF O-1 — engage the W55 bright-backdrop bucket BY DEFAULT on
+           the overlay band: a floating surface floats over WHATEVER the consumer
+           painted (frequently a light/near-white app surface — the canonical G2
+           case), so the library opts its own overlay-band glass in at its own root
+           via the SELF-CONTAINER reach below (`.glass-floating { --glass-backdrop }`
+           + `:where(.glass-floating) > * `-less: the rung re-points its OWN tint
+           through the companion self-rule, not only the ancestor @container). `dark`
+           (the :root default at tokens.css) stays the explicit per-surface override a
+           dark-substrate consumer dials in on an ancestor. */
+        --glass-backdrop: light;
+        position: relative;
+        background: color-mix(in oklab, var(--glass-bg-floating), var(--glass-tint-source) var(--glass-tint-strength));
+        backdrop-filter: var(--glass-blur-floating);
+        border: 1px solid var(--glass-border-floating);
+        box-shadow:
+            var(--glass-material-rim),
+            var(--glass-under-shadow-vivid),
+            var(--glass-shadow-floating);
+    }
+
+    .glass-overlay {
+        /* AY.W-A11Y-PERF O-1 — the overlay band engages the W55 bucket by default
+           (see .glass-floating). */
+        --glass-backdrop: light;
+        position: relative;
+        background: color-mix(in oklab, var(--glass-bg-overlay), var(--glass-tint-source) var(--glass-tint-strength));
+        backdrop-filter: var(--glass-blur-overlay);
+        border: 1px solid var(--glass-border-overlay);
+        box-shadow: var(--glass-material-rim), var(--glass-shadow-overlay);
+    }
+
+    /* ── Adaptive legibility: the bright-backdrop bucket (AX.W55 — the iOS-26/27
+       "locally darken the glass over light content" move; G2) ──────────────────
+       When a consumer sets `--glass-backdrop: light` on any ancestor (a near-white
+       card surface, a pale aurora bleed, a bright data grid), the `@container
+       style()` read engages here and LIFTS the tint toward ink: `--glass-tint-
+       strength` climbs from the `0%` rest default to the bounded AA floor
+       (`--glass-tint-strength-aa`, ≤24% — translucent floor preserved) and `--glass-
+       tint-source` re-points from `var(--card)` to the warm-ink `--glass-tint-ink`.
+       Both are INHERITING custom properties the rungs' `background:` composite
+       already reads, so re-pointing them on the material group re-resolves the
+       EXISTING `color-mix(in oklab, <rung bg>, …)` toward ink — ZERO new compositing
+       seam, the literal darken-over-light recipe. The `.glass-*::before` specular
+       `plus-lighter` gleam (W52) is untouched (it composes ON the darkened plate;
+       the darkening is the orthogonal oklab-tint axis). No `@supports` wrapper:
+       style queries introduce no new `container-type` value (every element is a
+       style container by default), so an engine without style-query support parses
+       the unknown at-rule as invalid, drops the block, and keeps the zero-delta
+       glass (the graceful degradation — the surface is today's-glass, the pre-W55
+       state; see utilities.css §density for the same precedent). */
+    @container style(--glass-backdrop: light) {
+        .glass-material,
+        .glass-wash,
+        .glass-quiet,
+        .glass-resting,
+        .glass-floating,
+        .glass-overlay,
+        .glass-card {
+            --glass-tint-source: var(--glass-tint-ink);
+            --glass-tint-strength: var(--glass-tint-strength-aa);
+        }
+    }
+
+    /* AY.W-A11Y-PERF O-1 — SELF-ENGAGE the overlay band by default. The
+       `@container style()` rule above queries an ANCESTOR (CSS style queries never
+       self-match — verified on Chrome 148), so the `.glass-floating { --glass-backdrop:
+       light }` default we set on the rung would NOT darken the rung's OWN surface, only
+       its descendants. AND the `:root` library default is `--glass-backdrop: dark`
+       (tokens.css), so a `@container style(--glass-backdrop: dark)` revert would ALWAYS
+       fire (every element has the dark :root as an ancestor) — it cannot distinguish an
+       explicit consumer `dark` from the default. So the overlay band self-engages
+       UNCONDITIONALLY as the library default: a floating/overlay surface floats over
+       WHATEVER the consumer painted (frequently a light/near-white app surface — the
+       canonical G2 case the user reported), so darkening the translucent plate toward
+       the warm-ink is the correct default. This re-points the tint tokens DIRECTLY on
+       the overlay-band surfaces (`.glass-floating` / `.glass-overlay` — the Dialog/
+       Sheet/Popover/DropdownMenu/HoverCard/Command/Tooltip/Toast/Select-content band),
+       engaging the SAME oklab tint axis (zero new compositing seam). Over a DARK page
+       the darken is sub-perceptual (warm-ink over an already-dark plate is a small
+       shift); a dark-substrate consumer who wants the pristine plate sets
+       `--glass-tint-strength: 0%` on the band or uses `.glass-opaque`. The in-srgb
+       `--surface-tint-*` family is never touched (this edits only the in-oklab glass
+       tint axis).
+
+       AZ.W-ADAPTIVE-AUTO Arm 1 — the self-engage now EXTENDS to the plain CONTENT
+       tiers (`.glass-card`/`.glass-resting`/`.glass-quiet`/`.glass-wash`), not just
+       the overlay band. The W54 glass-first MAXIMAL default makes content-on-glass-
+       over-a-bright-backdrop the common case, so every content tier self-darkens over
+       light WITHOUT consumer opt-in — closing the C5-7 asymmetry (the content tiers
+       painted near-invisible over light on every route). The prior W55 overlay-only
+       scoping (which kept the default-path byte-identity canary green by testing
+       `.glass-card`/`.glass-resting` with a bare no-ancestor div) is SUPERSEDED: the
+       three now-self-engaged kinds are no longer byte-identical to the dark bucket
+       (the canary narrows to the legitimately-zero-delta surfaces — the `.glass-opaque`
+       escape + an explicit per-surface `--glass-backdrop: dark` override — and the new
+       in-situ G1 π readback becomes the binding default-path truth). The muted body
+       register lifts to the full warm-ink under the engaged plate: the muted L40 tier
+       cannot clear 4.5:1 on a translucent darkened plate (darkening moves the plate
+       TOWARD muted's own luminance), so the low-contrast muted register resolves to
+       the legible dark ink (clears ~10:1) — a token re-point on the same inheriting
+       axis as the tint. */
+    :where(
+            .glass-floating,
+            .glass-overlay,
+            .glass-card,
+            .glass-resting,
+            .glass-quiet,
+            .glass-wash
+        ) {
+        --glass-tint-source: var(--glass-tint-ink);
+        --glass-tint-strength: var(--glass-tint-strength-aa);
+        --muted-foreground: var(--foreground);
+    }
+
+    /* AX.W55 — the `contrast-color()` foreground-ink flip (Chrome 147+/Safari 26+).
+       A PROGRESSIVE-ENHANCEMENT layer, NEVER the load-bearing floor (Open-Q #5
+       ratified): the declarative bucket above already carries AA on ALL engines (it
+       darkens the translucent plate so dark text clears ~11:1 over white at the 18%
+       floor — the live π readback ratifies). On a supporting engine `contrast-color()`
+       REFINES the foreground-ink pick natively, anchored on the LIGHT BACKDROP signal
+       (`--card`, the warm-white surface base the bright bucket implies) — NOT on the
+       ink. `contrast-color(var(--card))` over the light backdrop resolves to the
+       maximally-legible DARK ink (anchoring on the dark ink instead would invert to
+       white, illegible on the still-light translucent plate). The bucket is the floor;
+       this is the native refinement. Scoped to the bright bucket. */
+    @supports (color: contrast-color(white)) {
+        @container style(--glass-backdrop: light) {
+            .glass-material,
+            .glass-wash,
+            .glass-quiet,
+            .glass-resting,
+            .glass-floating,
+            .glass-overlay,
+            .glass-card {
+                color: contrast-color(var(--card));
+            }
+        }
+        /* AY.W-A11Y-PERF O-1 / AZ.W-ADAPTIVE-AUTO Arm 1 — the same contrast-color
+           refinement for the SELF-ENGAGED band + content tiers (the @container block
+           above queries an ancestor; these surfaces engage their own tint
+           unconditionally, so their ink-flip companion mirrors that). The muted
+           register flips to the same anchored dark ink. Progressive enhancement only
+           — the declarative darken above is the AA floor on all engines. */
+        :where(
+                .glass-floating,
+                .glass-overlay,
+                .glass-card,
+                .glass-resting,
+                .glass-quiet,
+                .glass-wash
+            ) {
+            color: contrast-color(var(--card));
+            --muted-foreground: contrast-color(var(--card));
+        }
+    }
+
+    /* ── The opaque escape (AX.W54) ───────────────────
+       The level-0 endpoint of the SAME glass machinery — a solid `--card` plate
+       (the opacity seam → 1) with `blur(0)` (the blur seam → 0), routed through
+       the ONE `--glass-level` knob. NOT a parallel solid `background:` recipe:
+       a `.glass-*` surface that ALSO carries `.glass-opaque` keeps its glass edge,
+       rim, and under-shadow (a solid plate with a glass edge, not a bare div), and
+       the @supports fallback + the a11y brackets compose coherently. This is the
+       explicit opt-out from the MAXIMAL glass default (dense data, forced-colors,
+       a consumer that wants a flat surface). */
+    .glass-opaque {
+        --glass-level: 0;
+    }
+
+    /* ── Content-aware under-shadow modifier (AV.W15 M4) ──────────────
+       Apple raises the under-shadow over text (so the glass reads as
+       lifting OFF the text) and drops it over solid light. The modifier
+       is ATTRIBUTE-DRIVEN, no JS: a consumer adds `.glass-over-text`
+       (or `[data-over-content="text"]`) to a text-bearing glass surface to
+       swap it ONE under-shadow rung heavier, or `[data-over-content="solid"]`
+       to lighten it one rung over a solid-light backdrop. It reuses the
+       existing `--glass-under-shadow-{quiet,default,vivid}` rungs (no new
+       shadow value — `vivid` is sufficient over text), redefining only the
+       leading under-shadow layer per tier; the lift stack is untouched.
+
+       The selectors are per-tier so the swap is rung-correct
+       (quiet→default, resting→vivid). `.glass-floating` already sits at the
+       `vivid` ceiling over text, so the heavier variant is a no-op there
+       (the rung saturates) — documented, not an error. */
+    .glass-quiet.glass-over-text,
+    .glass-quiet[data-over-content="text"] {
+        box-shadow: var(--glass-under-shadow-default), var(--glass-shadow-quiet);
+    }
+    .glass-resting.glass-over-text,
+    .glass-resting[data-over-content="text"] {
+        box-shadow: var(--glass-under-shadow-vivid), var(--glass-shadow-resting);
+    }
+
+    /* The inverse — over a solid-light backdrop the under-shadow lightens
+       one rung (the glass need not lift as hard off a flat bright field). */
+    .glass-resting[data-over-content="solid"] {
+        box-shadow: var(--glass-under-shadow-quiet), var(--glass-shadow-resting);
+    }
+    .glass-floating[data-over-content="solid"] {
+        box-shadow:
+            var(--glass-material-rim),
+            var(--glass-under-shadow-default),
+            var(--glass-shadow-floating);
+    }
+
+    /* Grain noise overlay — reuses paper texture SVG, no extra assets */
+    .glass-wash::after,
+    .glass-quiet::after,
+    .glass-resting::after,
+    .glass-floating::after,
+    .glass-overlay::after {
+        content: '';
+        position: absolute;
+        inset: 0;
+        border-radius: inherit;
+        background: var(--paper-clean-texture);
+        background-repeat: repeat;
+        background-size: var(--paper-texture-size);
+        opacity: var(--glass-grain-opacity);
+        pointer-events: none;
+        mix-blend-mode: overlay;
+    }
+
+    /* (b) The unified rim — `--glass-edge-light` full-perimeter inset ring on
+       EVERY material surface (AW.W22). Previously the rim was wired only into
+       the floating/overlay tiers' box-shadow stack; promoting it to the material
+       group makes wash/quiet/resting/card/dock-control all carry the same
+       silhouette catch-light from ONE token. The rim is its OWN `box-shadow`
+       declaration on the material group so it composes uniformly without
+       perturbing each tier's elevation recipe (the floating/overlay tiers drop
+       their now-redundant inline `--glass-edge-light` layer below). The alpha is
+       deliberately low so the rim never eats AA legibility over a busy
+       backdrop. */
+    .glass-material,
+    .glass-wash,
+    .glass-quiet,
+    .glass-resting,
+    .glass-floating,
+    .glass-overlay,
+    .glass-card,
+    .glass-specular-track,
+    .dock-icon-button {
+        --glass-material-rim: var(--glass-edge-light);
+    }
+
+    .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;
+    }
+
+}