@godxjp/ui 28.13.0 → 30.0.0

package/docs/themes/glassmorphism.css

@@ -0,0 +1,958 @@
+/**
+ * glassmorphism theme — a CONSUMER-SURFACE experiment, not a framework change.
+ *
+ * Everything below is a `--custom-property` declaration inside `[data-theme-style="glass"]`.
+ * No selector here targets a `.ui-*` internal class, no `backdrop-filter`/`background`/
+ * `box-shadow` is written directly — every visual effect below is produced by EXISTING
+ * `src/styles/**` rules that already read the token being set. That is the whole point of the
+ * exercise: find out what a consumer can reach through the published theme API alone, the way an
+ * Ant Design consumer is limited to `theme.token` / `theme.components`.
+ *
+ * Where a component has no such hook, this file does not fake one.
+ *
+ * ── A STANDING RULE FOR THIS FILE, AND IT WAS EARNED TWICE ──────────────────────────────────
+ * **No comment here — and no sentence on the showcase page — may assert that a surface is
+ * unreachable.** A reachability claim is true on the day it is written and false the moment
+ * someone adds a knob, and it silently becomes the most damaging kind of wrong, because the whole
+ * claim of this exercise is to be a measurement. It has rotted twice already. The Sheet is the
+ * worked example: this file and the page it fed both said "sheet.tsx bakes `bg-background` into
+ * its className, there is no `--sheet-background` to set", and gh#880 had added
+ * `--sheet-surface-background` hours earlier — the panel renders `rgba(29, 33, 53, 0.92)` while a
+ * paragraph inside it described a dead end.
+ *
+ * So the only claims kept below are the ones this file DEMONSTRATES by setting a token and the
+ * ones a reader can re-run: `scripts/measure-glass.mjs` reads the computed value of every surface
+ * and every overlay and is the authority on what a theme reaches. If a surface interests you, run
+ * it; do not trust a sentence here about a token this file does not set.
+ *
+ * ── The one trick this file leans on: an alpha suffix inside an HSL-triplet token ────────────
+ * Most colour tokens in this system are declared as a bare "H S% L%" triplet and consumed as
+ * `hsl(var(--token))` at the call site (src/styles/**). CSS Color 4's `hsl()` also accepts a
+ * `/ A` alpha component in that same string, so a token can carry `"H S% L% / A%"` and the
+ * existing `hsl(var(--token))` call becomes `hsl(H S% L% / A%)` — a real translucent colour —
+ * with ZERO change to the consuming stylesheet. This works ONLY where the token is the sole
+ * content of an `hsl()` call; several tokens below are consumed as a COMPLETE value instead
+ * (`background-color: var(--token, hsl(...)))`), so those are written as a full `hsl(...)` string
+ * instead of a bare triplet. Each declaration below says which form the consumer expects.
+ *
+ * ── The shadow seed — and the freeze trap it hits, measured, not assumed ─────────────────────
+ * `--shadow-color` (src/tokens/foundation.css:290) is the documented brand-shadow seed —
+ * `--shadow-xs` … `--shadow-2xl` all derive `rgb(var(--shadow-color) / <fixed alpha>)`, and Select/
+ * DropdownMenu/Dialog/`.ui-button--outline` read one of those steps DIRECTLY, so retinting
+ * `--shadow-color` (plus restating the one or two steps actually used — see below) was all they
+ * needed. Card/Sheet/Popover/Tooltip/Segmented instead go through a component-tier MIRROR
+ * (`--card-shadow: var(--shadow-sm)`, declared once in src/tokens/components/*.css) — the exact
+ * two-hop shape `docs/showcase/theme-customization.tsx` already documents for `--ring: var(
+ * --primary)`: a `var()` resolves at the element that DECLARES the referencing property, and
+ * since `--card-shadow` is declared only at `:root`, it resolved once against `:root`'s original
+ * `--shadow-sm` and inherits that frozen result — restating `--shadow-sm` alone left every one of
+ * these five surfaces' shadow at `rgba(0, 0, 0, …)`, confirmed with `getComputedStyle`. Closing it
+ * costs one more line per mirror, each just re-pointing at the (now-scoped) step it already named.
+ */
+[data-theme-style="glass"] {
+  /* ── THE POLARITY LAYER (gh#896) ────────────────────────────────────────────────────────────
+   * Five private knobs, holding every value in this file that FLIPS between light and dark. The
+   * declarations below read them instead of repeating a literal, so the dark branch at the bottom
+   * of this file is those five lines and not a second copy of the theme.
+   *
+   * THE FREEZE RULE DOES NOT BITE HERE, and it is worth saying why, because it bites everywhere
+   * else in this system (docs/TOKEN-RESOLUTION.md §3). A `var()` substitutes where the referencing
+   * property is DECLARED — so a knob declared at `:root` and overridden in a scope below is frozen
+   * and unreachable. These five are declared on the SAME ELEMENT as every declaration that reads
+   * them (the theme scope div), and `.dark [data-theme-style="glass"]` re-declares them on that
+   * same element with higher specificity. Same element, so the reads resolve against the winning
+   * value. This is the one shape where a private indirection layer is safe.
+   *
+   * Counts are measured, not estimated — how many literal sites each knob replaced. */
+  --glass-ink: 230 30% 14%; /* primary ink */
+  --glass-ink-muted: 230 22% 26%; /* secondary ink — same ratio, lower emphasis */
+  --glass-ink-soft: 230 20% 22%; /* muted / tertiary */
+  --glass-focus: 262 95% 32%; /* the focus mark, which must survive ANY backdrop */
+  --glass-panel: 0 0% 100%; /* the opaque-end overlay panels: select · dropdown · toast · dialog · sheet */
+  --glass-panel-sl: 0% 100%; /* the same panel for the relative-colour layer, where the hue is the seed's */
+  --glass-status-l: 21%; /* status ink lightness — the hue carries the meaning, this carries legibility */
+  --glass-canvas-sl: 55% 86%; /* S L of the page canvas */
+  --glass-muted-sl: 40% 80%;
+  --glass-accent-sl: 45% 74%;
+  --glass-secondary-sl: 38% 78%;
+  /* THE BACKDROP IS THE HALF THE FIRST FLIP MISSED, and it is the half you SEE. `--background`
+   * was lightened while `--gradient-glow` — which `.app-main` paints ON TOP of it — kept a
+   * `linear-gradient(160deg, hsl(230 55% 11%), hsl(210 45% 16%))` floor. L 11% and 16% is a DARK
+   * page, so dark ink landed on a dark ground and the content area was unreadable while the token
+   * that names the canvas said "light". Reported as "mode light sao chữ ko đọc được gì".
+   *
+   * A light glass theme is NOT a dark one with the ink inverted. Signal 2 of the standard says the
+   * palette comes from the backdrop, so the backdrop is what has to move: bright, airy, still
+   * saturated. The three lobes keep their distinct lightnesses and their spread — they are
+   * deliberately different and the dark branch has to stay byte-identical. */
+  /* THE BRAND INK ON GLASS. Six declarations in the seed layer hardcoded L 88% / 90% — pale
+   * violet, right on a dark pane and invisible on a light one. Three of the six
+   * (`--text-link`/`-brand`/`-primary`) are ALSO emitted by `tenantTheme` as inline literals and so
+   * are overridden anyway; the other three — the active sidebar row, its icon, MegaMenu's current
+   * trigger — are not, which is why the sidebar's selected label was the one string still washed
+   * out after the backdrop was fixed. Measured: `color(srgb 0.875 0.805 0.995)` on a
+   * `rgba(124,58,237,0.26)` pill. */
+  --glass-brand-ink-l: 30 24%;
+  --glass-brand-ink-strong-l: %;
+  --glass-lobe-a-l: 58%;
+  --glass-lobe-a-alpha: 0.5;
+  --glass-lobe-b-l: 52%;
+  --glass-lobe-b-alpha: 0.45;
+  --glass-lobe-c-l: 60%;
+  --glass-lobe-c-alpha: 0.4;
+  --glass-floor-l-1: 70%;
+  --glass-floor-l-2: 60%;
+  --glass-edge: 0 0% 100% / 55%; /* the glass RIM — decorative, brighter than the pane */
+  --glass-rule: 230 22% 38% / 60%; /* a boundary that CARRIES MEANING: >= 3:1, WCAG 2.2 SC 1.4.11 */
+
+  /* ── Seed: seven surfaces' elevation, retinted at once — BUT ONLY once the freeze trap below is
+   *    also closed (see docblock above and the note here; this is the SAME trap
+   *    docs/showcase/theme-customization.tsx documents for `--ring` and `--radius`).
+   *    `--shadow-sm` / `--shadow-md` / `--shadow-lg` are declared at `:root`
+   *    (src/tokens/foundation.css:291-296) as `rgb(var(--shadow-color) / <fixed alpha>)`. A `var()`
+   *    substitutes where the CONSUMING property is declared, and `--shadow-sm` etc. are declared
+   *    ONLY at `:root` — never re-declared inside this scope — so they resolve once against
+   *    `:root`'s `--shadow-color` and inherit that already-resolved value down. Measured: setting
+   *    `--shadow-color` here alone left Card/Popover/Tooltip/Segmented/Select/DropdownMenu's shadow
+   *    at `rgba(0, 0, 0, …)`, unchanged. Closing it costs one restatement per step actually consumed
+   *    by this component set (sm/md/lg) — the exact fix `[data-godx-theme] { --ring: var(--primary);
+   *    }` already uses for the same class of bug. */
+  --shadow-color: 30 27 75; /* cool indigo, instead of the default neutral black */
+  --shadow-sm: 0 1px 2px 0 rgb(var(--shadow-color) / 0.05);
+  --shadow-md:
+    0 4px 6px -1px rgb(var(--shadow-color) / 0.1), 0 2px 4px -2px rgb(var(--shadow-color) / 0.1);
+  --shadow-lg:
+    0 10px 15px -3px rgb(var(--shadow-color) / 0.1), 0 4px 6px -4px rgb(var(--shadow-color) / 0.1);
+  /* The trap is TWO LAYERS deep for anything that goes through a component-tier "shadow" MIRROR
+   * (Card/Sheet/Popover/Tooltip/Segmented all do; Select/DropdownMenu/Dialog/`.ui-button--outline`
+   * read `--shadow-md`/`--shadow-lg`/`--shadow-sm` DIRECTLY and needed nothing further, confirmed
+   * by measurement). `--card-shadow: var(--shadow-sm)` (src/tokens/components/card.css) is ITSELF
+   * declared only at `:root`, so restating the foundation step above was not enough — measured:
+   * Card/Popover/Tooltip/Segmented's shadow stayed `rgba(0, 0, 0, …)` until these five mirrors were
+   * ALSO restated here, each one line, each just pointing at the (now-scoped) step it already
+   * named. */
+  --card-shadow: var(--shadow-sm);
+  --card-hover-shadow: var(--shadow-md);
+  --sheet-shadow: var(--shadow-lg);
+  --popover-shadow: var(--shadow-md);
+  --tooltip-shadow: var(--shadow-md);
+  --segmented-item-selected-shadow: var(--shadow-md);
+
+  /* ── Border — the SAME shared-role shape as `--card`/`--popover` below: no dedicated token
+   *    exists for Select/DropdownMenu/Sidebar/Tabs-panel/AppShell's `.app-topbar`, or — the one
+   *    that matters most — Dialog's own panel (dialog-layout.css:55 hard-codes
+   *    `border: 1px solid hsl(var(--border))`). Verified no consumer composes a SECOND alpha after
+   *    it (unlike `--background`, see below), so a bare triplet + alpha is safe here and reaches
+   *    all of the above at once — the widest-reaching single line in this file. */
+  --border: var(--glass-edge);
+
+  /* ── `--background` IS SHARED, and the sharing is the constraint — not the syntax, which the
+   *    seed layer at the bottom of this file dissolves. It is consumed BOTH bare
+   *    (`hsl(var(--background))` — the page canvas, base.css:260) AND pre-composed with its own
+   *    alpha (`hsl(var(--background) / var(--topbar-background-alpha))`, shell-layout.css:2648,
+   *    the Topbar glass rule). A bare-triplet alpha suffix here makes Topbar's rule read
+   *    `hsl(H S% L% / A% / …)` — invalid CSS, two `/` — which drops `background-color` to
+   *    `transparent`; measured, the Topbar's fill vanished and the page canvas went see-through.
+   *    Relative colour removes exactly that syntactic problem (see the seed layer). What it does
+   *    not remove is that one alpha here would make the PAGE CANVAS translucent too, which is why
+   *    this token stays opaque and the surfaces that want translucency use their own knobs. ──── */
+
+  /* ── Ambient backdrop — .app-main already exposes this as an opt-in hook
+   *    (src/styles/shell-layout.css: "background-image: var(--gradient-glow)"; default `none`).
+   *    A vivid gradient ground is what makes translucency legible at all — glass is invisible on
+   *    a flat canvas. `--app-shell-main-background` (also consumed as a complete value, not
+   *    wrapped in hsl()) is the solid floor underneath it. ────────────────────────────────── */
+  --gradient-glow:
+    radial-gradient(
+      circle at 12% 18%,
+      hsl(262 83% var(--glass-lobe-a-l) / var(--glass-lobe-a-alpha)),
+      transparent 42%
+    ),
+    radial-gradient(
+      circle at 88% 12%,
+      hsl(199 89% var(--glass-lobe-b-l) / var(--glass-lobe-b-alpha)),
+      transparent 48%
+    ),
+    radial-gradient(
+      circle at 55% 92%,
+      hsl(330 81% var(--glass-lobe-c-l) / var(--glass-lobe-c-alpha)),
+      transparent 52%
+    ),
+    linear-gradient(
+      160deg,
+      hsl(230 55% var(--glass-floor-l-1)),
+      hsl(210 45% var(--glass-floor-l-2))
+    );
+  --app-shell-main-background: hsl(222 var(--glass-canvas-sl));
+
+  /* ── Gradient is not only a PAGE-backdrop thing — three more surfaces have a real, CLEAN
+   *    single-slot `background-image: var(--token)` hook (verified with `getComputedStyle`, not
+   *    assumed): AppShell's `.app-topbar` (shell-layout.css:389, `--topbar-gradient`), `.app-sidebar`
+   *    (shell-layout.css:230, `--sidebar-gradient`), and `PageContainer`'s own header band
+   *    (layout.css:892, `.ui-page-header { background-image: var(--gradient-hero) }` — rendered
+   *    here because this page passes `title`/`subtitle`). All three take an arbitrary
+   *    `linear-gradient(...)` string with NO artifact, because the call site assigns the token
+   *    ONCE, unlike Card below. ──────────────────────────────────────────────────────────────── */
+  --topbar-gradient: linear-gradient(
+    120deg,
+    hsl(262 83% var(--glass-lobe-a-l) / 0.35) 0%,
+    hsl(199 89% var(--glass-lobe-b-l) / 0.2) 100%
+  );
+  --sidebar-gradient: linear-gradient(
+    160deg,
+    hsl(330 81% var(--glass-lobe-c-l) / 0.22) 0%,
+    hsl(262 83% var(--glass-lobe-a-l) / 0.16) 100%
+  );
+  /* NO `--gradient-hero`, AND THAT IS THE POINT (reported twice: "phần header tự dưng tại sao có
+   * bg riêng grandient riêng thế??? trông nó ko đồng bộ tí đéo nào cả", then "cái header này tự
+   * dưng cho bg làm gì ?? đã nói nó ko đồng bộ mà").
+   *
+   * It was `linear-gradient(100deg, pink/0.25, violet/0.15)` — a saturated wash at 100deg across
+   * one band of a page whose backdrop runs at 160deg with three radial lobes. Two independent
+   * gradients, so the header read as a stripe pasted over the page. My first fix softened it to a
+   * white scrim on the page's own axis, which was still A BAND: subtler, same defect, and the
+   * report came back.
+   *
+   * The reason I kept it was that exercising a hook is this file's job — and that was my agenda,
+   * not a requirement. A theme that demonstrates a knob at the cost of looking wrong has answered
+   * the wrong question. So the declaration is gone and `.ui-page-header` falls back to the
+   * library's own `--gradient-hero: none`: no background-image, so the PAGE backdrop is what shows
+   * through the header, continuous with everything around it. Signal 2 of the standard says the
+   * palette comes from ONE backdrop; a header is not an exception to that.
+   *
+   * The hook is still proven reachable by `--topbar-gradient` and `--sidebar-gradient` above,
+   * which are SHELL chrome at the page's edge — a wash there reads as chrome. `.ui-page-header`
+   * sits inside the content column, where a separate fill can only ever read as a stripe. */
+
+  /* ── Card — dedicated tokens, consumed AS hsl(var(--token)), so a bare triplet + alpha works.
+   *    src/styles/card-layout.css:44 (border), :49 (background). ────────────────────────────── */
+  --card-alpha: 12%;
+  --card-border: var(--glass-edge);
+
+  /* ── Dialog — `--dialog-content-glow` is an additive box-shadow LAYER, not the panel fill: the
+   *    glass edge highlight, on top of the retinted elevation. The panel's own fill is set in the
+   *    seed layer through `--dialog-surface-background`. ─────────────────────────────────────── */
+  --dialog-content-glow: inset 0 1px 0 hsl(0 0% 100% / 0.5);
+
+  /* ── Sheet — the panel fill is set in the seed layer through `--sheet-surface-background`, at
+   *    92%: §4 of the standard, a drawer covers content that must stay unreadable-but-present, so
+   *    it sits at the opaque end of the range. Its border rides the `--border` restatement above —
+   *    measured, not assumed: an earlier draft claimed Sheet drew no border at all and
+   *    `getComputedStyle` said `border-width: 0 0 0 1px`, translucent. ──────────────────────── */
+
+  /* ── Popover / Tooltip — dedicated background and border tokens, both consumed as a COMPLETE
+   *    value (dialog-layout.css:342-343, :362-363), so each needs its own `hsl(...)` wrapper here
+   *    rather than a bare triplet. The Popover's fill is re-set darker in the seed layer, for the
+   *    reason measured there. ───────────────────────────────────────────────────────────────── */
+  --popover-surface-border-color-alpha: 30%;
+
+  /* Dark frosted chip — the conventional tooltip treatment even inside an otherwise light-glass
+   * page. Re-derived from the seed in the seed layer. */
+  --tooltip-background: hsl(230 45% 12% / 78%);
+  --tooltip-border-color-alpha: 14%;
+
+  /* ── `--popover` is the FOUNDATION-tier role several floating panels fall back to when their own
+   *    knob is unset; it is always consumed as `hsl(var(--popover))`, so a bare triplet with an
+   *    alpha reaches every one of them at once. Select's and DropdownMenu's own dedicated fills
+   *    are set in the seed layer, which is what they actually render. ───────────────────────── */
+  --popover-alpha: 22%;
+
+  /* ── Table — three different levers for three different lines, verified individually:
+   *      · The OUTER frame (`.ui-data-table-surface`, what a reader actually sees around a plain
+   *        DataTable) hard-codes `border: 1px solid hsl(var(--border))` (table-layout.css:372) —
+   *        bare role, already covered by the `--border` restatement above. `--table-border-color`
+   *        does NOT reach it (measured: the rendered alpha was 32%, `--border`'s, not this
+   *        token's 30% — confirms which one actually wins before trusting the doc comment).
+   *      · `--table-border-color` is real, but scoped to internal cell/row dividers under
+   *        `<Table bordered>` (table-layout.css:685,689) — not exercised by this page's plain
+   *        DataTable, kept here for completeness.
+   *      · The header BAND is its own dedicated token, consumed as a complete value
+   *        (table-layout.css:159) — confirmed applying (measured 18% alpha, exact match).
+   *      · The table's own SURFACE re-uses `--card-background` (table-layout.css:540), already
+   *        set above: DataTable in a Card gets the Card's glass for free, by design ("Card +
+   *        CardContent flush + DataTable" is the documented composition). ─────────────────────── */
+  --table-border-color: hsl(var(--glass-rule));
+
+  /* ── Input / Select trigger / TagInput — the SHARED `.ui-control-surface` base
+   *    (src/lib/control-styles.ts:1791-1792), both consumed as a complete value. This is the one
+   *    component-tier knob pair the form-control family has; there is no per-control override. */
+  /* 18%, not 35%. §4b asks a field to be MORE opaque than the card it sits on — it is (the Card is
+   * at 12%) — but 35% white over a dark canvas put the Select's own value at 4.20:1, just under
+   * the floor, on every seed. The border keeps its 45% because §4b's other requirement is a
+   * boundary at 3:1 or better, and that one is carried by the edge rather than the fill. */
+  --control-surface-background-alpha: 18%;
+  --control-surface-border-color: hsl(var(--glass-rule));
+
+  /* ── Button — its three variant fills are set further down, through their own knobs. Its BORDER
+   *    and its SHADOW ride the `--border` and `--shadow-sm` restatements above for free. ────── */
+
+  /* ── Badge — the only knobs are the two MIX PERCENTAGES color-mix reads
+   *    (badge-layout.css:64-70), not colours themselves; no shadow property exists on a badge at
+   *    all (flat chip by design). ──────────────────────────────────────────────────────────── */
+  --badge-tint-fill: 22%;
+  --badge-tint-edge: 45%;
+
+  /* ── Tabs — the "card" tab-list and its panel, both consumed as hsl(var(--token))
+   *    (navigation-layout.css:482,653). The default (underline) tab list paints nothing, so it is
+   *    already "glass" by having no surface; its own list and active-trigger fills are set further
+   *    down. ─────────────────────────────────────────────────────────────────────────────────── */
+  --tabs-panel-background-alpha: 18%;
+  --tabs-card-background-alpha: 30%;
+
+  /* ── Alert — only the FOUR TONED variants (destructive/warning/success/info) resolve their
+   *    SURFACE through `--alert-bg-alpha` / `--alert-border-alpha` (alert-layout.css:25-44). The
+   *    default/neutral tone's border is `hsl(var(--border))` bare — covered by the restatement
+   *    above. Its background composes `--muted` with its own alpha, so this file does not try to
+   *    add a second one there; run the instrument rather than trusting this sentence. */
+  --alert-bg-alpha: 16%;
+  --alert-border-alpha: 35%;
+
+  /* ── Toast (Sonner) — sonner.tsx sets `--normal-bg: hsl(var(--popover))` /
+   *    `--normal-border: hsl(var(--border))` inline on the Toaster, so it rides the two shared
+   *    roles above; its own `--toast-background` is set in the seed layer and is what renders. */
+
+  /* ── Avatar — its own dedicated token (data-display-layout.css:14), consumed as a complete
+   *    value. No border or shadow property exists on `.ui-avatar` at all (flat fill by design). */
+  /* 14%, not 40%. At 40% the chip composited LIGHT over the dark canvas while the fallback
+   * initials inherit the theme's near-white ink: measured 1.70:1 on three avatars in a row and
+   * 1.81:1 on the Topbar's. A fallback is TEXT, so the chip is a text ground and has to be
+   * treated as one. */
+  --avatar-background-alpha: 14%;
+
+  /* ── Progress — track has a dedicated token, consumed as a complete value
+   *    (data-display-layout.css:203); the FILL is deliberately left alone — it is the data
+   *    (WCAG 2.2 SC 1.4.11 contrast mark), not a decorative surface. */
+  --progress-track-background-alpha: 25%;
+
+  /* ── Sidebar — Sidebar itself is `display: contents` (no box of its own); the surface a
+   *    consumer actually sees is AppShell's `.app-sidebar`, which hard-codes
+   *    `border-inline-end: 1px solid hsl(var(--border)); background: hsl(var(--card));`
+   *    (shell-layout.css:216-229) as its FALLBACK. Border is covered by the `--border`
+   *    restatement above; `--card` is only otherwise read as Card's own fallback (moot once
+   *    `--card-background` is set directly above). The Sidebar's own fill and blur knobs are set
+   *    further down and are what render.
+   *
+   *    WHAT IS STILL TRUE, AND IT IS A PLACEMENT FACT RATHER THAN A TOKEN ONE: neither
+   *    `.app-sidebar` nor `.app-topbar` sits inside `.app-main`, and `--gradient-glow` is painted
+   *    only inside `.app-main` (shell-layout.css:403). So both chrome surfaces blur and tint over
+   *    the page's own flat canvas, not over the vivid ground. Glass needs a busy ground BEHIND the
+   *    element wearing it, and AppShell's chrome grid sits outside the one region that has one —
+   *    which is also why the Topbar's Popover was the only overlay on this page that failed AA
+   *    until its fill was moved to the dark end (see the seed layer). */
+
+  /* ── The bar — AND IT IS **ONE** SURFACE, WHICH TOOK A MEASUREMENT TO GET RIGHT (gh#895).
+   *
+   *    There are two elements here and the token names do not say so. `--topbar-gradient` and
+   *    `--app-shell-bar-background` paint `.app-topbar`, the full-width row. `--topbar-background-
+   *    alpha` and `--topbar-backdrop-blur-size` paint `.ui-topbar`, the `<Topbar>` COMPONENT,
+   *    which that row insets by `--app-shell-bar-inset` on each side. Measured at 1440px:
+   *
+   *        .app-topbar   x=256  w=1184     .ui-topbar   x=280  w=1136
+   *
+   *    so this file used to set a 55% dark fill on the inner element while the row underneath
+   *    carried 12% white plus the 120deg gradient — and the 24px gutters showed the row through,
+   *    as two strips of different colour (the gradient runs across them, so one read yellow and
+   *    the other red). Four `--topbar-*` knobs, two elements, and nothing in the names to warn you.
+   *
+   *    The row is the one that reaches the edges, so the row carries the glass. Its FILL needs no
+   *    line here — `.app-topbar` defaults to `hsl(var(--card))`, which this file already set to
+   *    12% white, and that is the correct 0.12 from the standard's §1 recipe. What was missing was
+   *    the BLUR: `--app-shell-bar-backdrop-blur-size` is the knob gh#895 added for the row. The
+   *    sidebar had had one since gh#880; the bar row had none, which is what forced a theme onto
+   *    the inner element in the first place.
+   *
+   *    `.ui-topbar` goes back to being what its own rule calls it, "a layout-only wrapper with no
+   *    fill and no border": both of its knobs are left at `initial`, so each declaration is
+   *    invalid-at-computed-value-time and the property takes its own initial value. NOT `0` and
+   *    NOT `transparent` — a literal `blur(0px)` would still promote it to a backdrop root and
+   *    make it the containing block for its fixed descendants. */
+  --app-shell-bar-backdrop-blur-size: var(--blur-lg);
+
+  /* ── ONE INK RAMP, MEASURED ON THE COMPOSITED GLASS (docs/GLASSMORPHISM-STANDARD.md §3)
+   *    The first pass set no text token at all, so every string kept a default tuned for an
+   *    OPAQUE white card. Sampled on the real composited pixel, the lightest glass ground on the
+   *    page is rgb(172,159,172) — and against it the stock `--muted-foreground` rgb(104,102,94)
+   *    measures 2.28:1, against a 4.5:1 floor. Five separate strings on one card failed.
+   *
+   *    THE RULE THE STANDARD STATES: on glass, "muted" cannot mean LOWER CONTRAST. It means
+   *    smaller, or lighter in weight, at the SAME ratio. So the secondary ink is not a lighter
+   *    grey here — it is the same family, and the hierarchy is carried by size and weight, which
+   *    the components already vary on their own.
+   *
+   *    Solved, not guessed: against that worst ground a neutral ink needs L ≤ 22.5% for 4.5:1 and
+   *    L ≤ 9.5% for 7:1. Body sits at 7:1 (AAA) so it keeps a margin when the backdrop shifts
+   *    under it; secondary sits at 20%, comfortably inside the AA bound with room for the
+   *    gradient to move. */
+  /* ── LIGHT INK, BECAUSE THE GLASS IS DARK. I built this the other way round first and the
+   *    owner's screenshots showed why it could not work: at 42% white the panes were light, so
+   *    the ink went dark — and then the PAGE HEADER, which sits on the bare dark backdrop with no
+   *    pane under it at all, measured 1.63:1 and its subtitle 1.30:1. One ramp cannot serve a
+   *    light pane and a dark ground; §3 of the standard calls that a POLARITY bug and I wrote
+   *    that sentence while still having it.
+   *
+   *    At the spec's 0.12 the panes are dark — white at 12% over a dark backdrop lightens it
+   *    slightly and no more — so light ink is right on the panes AND on the ground, and the
+   *    polarity problem stops existing rather than being worked around. There is no
+   *    `--page-title-color` token; this is why one is not needed.
+   *
+   *    Solved over the three regions the backdrop actually produces, worst case first:
+   *
+   *      region             pane (12% white over it)   off-white ink    bare ground
+   *      blob xanh          rgb(66,110,154)            4.98:1           6.67:1
+   *      blob tím sáng      rgb(112,83,163)            5.66:1           7.69:1
+   *      darkest base       rgb(55,57,70)             10.65:1          15.36:1
+   *
+   *    Every one clears AA 4.5:1, measured against the WORST region rather than a convenient
+   *    sample (§3). Off-white rather than pure white: it keeps a hair of warmth against the cool
+   *    backdrop and still clears 4.98:1 at the worst point. */
+  --foreground: var(--glass-ink);
+  --card-foreground: var(--glass-ink);
+  --popover-foreground: var(--glass-ink);
+  /* "Muted" is SMALLER AND LIGHTER IN WEIGHT, never lower contrast — §3. 82% still measures
+   * 3.49:1 on the worst pane, so it stays at 90% and the hierarchy comes from size. */
+  --muted-foreground: var(--glass-ink-soft);
+  --text-tertiary: 48 10% 93%;
+
+  /* Status ink lightened to match. The hue carries the meaning; the lightness carries the
+   * legibility, and on dark glass those pull in the opposite direction from the light build. */
+  --text-success: 152 60% var(--glass-status-l);
+  --text-warning: 42 90% var(--glass-status-l);
+  --text-info: 210 90% var(--glass-status-l);
+  --text-error: 6 85% var(--glass-status-l);
+
+  /* ── THE CARD WAS NOT CONSISTENT WITH ITS OWN CONTENTS, which is what the owner spotted by eye:
+   *    a translucent Card whose Segmented track stayed opaque `--muted` (measured
+   *    rgb(244,243,240)). This knob EXISTS and the first pass simply never set it — unlike
+   *    `--tabs-list-background` and `--tabs-trigger-active-background`, which do not exist at all
+   *    and are the library half of gh#880. So Segmented is fixed here and Tabs cannot be. */
+  --segmented-track-background-alpha: 10%;
+  --segmented-item-selected-background-alpha: 16%;
+  /* The ITEM ink too — an unselected item measured 2.86:1 because only the track had been
+   * retinted and the label kept its own default. Same ramp as everything else. */
+  /* The table's header strip: both knobs exist, and the first build set neither, so it kept an
+   * opaque `--muted` band with the default dark ink — the same "container is glass, its own parts
+   * are not" defect the owner spotted on the Card's Segmented. */
+  --table-header-background-alpha: 8%;
+  --table-header-foreground: hsl(var(--glass-ink-soft));
+
+  --segmented-item-color: var(--glass-ink-soft);
+  --segmented-item-selected-color: var(--glass-ink);
+
+  /* ── ONE INK RAMP ONLY WORKS IF EVERY GLASS SURFACE SHARES A POLARITY, and that is the part
+   *    §3 of the standard did not say. Card is white glass over a dark canvas; Alert was a toned
+   *    tint — `--surface-*` at 16% over the same dark backdrop — and the same ink measured 1.27:1
+   *    and 1.35:1 on it. Not a contrast bug in the ink: a
+   *    POLARITY bug, two surfaces of opposite value asking one ramp to serve both.
+   *
+   *    Fixed by making the alert a light pane like every other surface, tinted by hue rather
+   *    than darkened by it. The status still reads — the hue is in the border and the icon —
+   *    and the ink stops fighting its own ground. gh#866 shipped these four roles an hour ago;
+   *    this is the first theme to need them. */
+  --surface-success: hsl(152 60% 40% / 0.22);
+  --surface-warning: hsl(42 80% 45% / 0.22);
+  --surface-info: hsl(214 70% 50% / 0.22);
+  --surface-destructive: hsl(0 70% 50% / 0.22);
+
+  /* ══ THE RECIPE, NOW THAT THE KNOBS EXIST (gh#880) ════════════════════════════════════════
+   * namethatui.com, verbatim: background rgba(255,255,255,.12) · backdrop-filter blur(16px) ·
+   * border 1px rgba(255,255,255,.25) · radius 16px. Everything above this block was written when
+   * only ONE surface in the library could take a blur; these 20 lines are what the other eleven
+   * were waiting for.
+   *
+   * BLUR SIZE IS PER SURFACE, SATURATE IS SHARED. `--surface-backdrop-saturate` is one knob
+   * because saturation is a property of the MATERIAL — the per-surface decisions the standard
+   * actually names are the fill alpha and the blur radius. The 160% lives at each call site, so
+   * asking for a blur can never accidentally ask for fog. */
+  /* ── A TRAP THIS FILE FELL INTO, WRITTEN DOWN SO THE NEXT READER DOES NOT.
+   *    This library has TWO token value forms and nothing announces which a given knob takes:
+   *
+   *      HSL COMPONENTS  `--card: 60 33% 99%`      read as `hsl(var(--card))`
+   *      COMPLETE COLOUR `--card-background: …`    read as `var(--card-background)` directly
+   *
+   *    Every one of the 29 knobs gh#880 added is the SECOND kind; every older role token is the
+   *    first. I set fourteen of them in the components form, and the failure is silent: the
+   *    substituted declaration is invalid at computed-value time, so the property takes its own
+   *    initial value or the call-site fallback, and the surface simply keeps the colour it had.
+   *    The table header measured 1.03:1 — light ink on the `--muted` it had fallen back to —
+   *    and looked, from the token file, exactly like a knob that does not work. */
+  /* ── THE PAGE CANVAS MUST BE DARK, and not setting it was the single biggest visual defect.
+   *    `--gradient-glow` paints on `.app-main` ONLY (shell-layout.css:412). Sidebar and Topbar are
+   *    its SIBLINGS, not its children, so nothing of the gradient is behind them — they were
+   *    translucent white over the package's light `--background`, which is why the sidebar read as
+   *    pink and the bar ran pink on the left and blue on the right. Neither is a gap: the canvas
+   *    under the whole shell is `--background`, and a dark-glass theme has to say so.
+   *
+   *    `--foreground` is already the light ink; this is its missing pair. Setting one without the
+   *    other is what produced a light chrome carrying near-white labels. */
+  --background: 230 var(--glass-canvas-sl);
+  --muted: 230 var(--glass-muted-sl);
+  --muted-foreground: var(--glass-ink-soft);
+  --accent: 262 var(--glass-accent-sl);
+  --accent-foreground: var(--glass-ink);
+  --secondary: 230 var(--glass-secondary-sl);
+  --secondary-foreground: var(--glass-ink);
+  --input-alpha: 18%;
+
+  /* ── THE BRAND INK RAMP — the second half of §3, and the half the first build skipped ────────
+   *    `--text-link` / `--text-brand` / `--text-primary` and the per-component actives below all
+   *    derive from `--primary` at the root, where a `var()` substitutes ONCE — so they compute
+   *    against the ROOT's light-theme seed and inherit that frozen dark violet into this dark
+   *    scope. Measured before these lines, on the violet seed alone: the Sidebar's active label
+   *    1.46:1, NavList's 1.39:1, MegaMenu's trigger 1.13:1, the Anchor link and `Button
+   *    variant="link"` 2.44:1, `Text link` 1.85:1. None of it is a contrast bug in the ink: it is
+   *    the `:root` freeze rule (docs/TOKEN-RESOLUTION.md §3) applied to the whole action family.
+   *
+   *    Every one of them has a knob. Restating them here is what a dark theme owes, and the split
+   *    between the two forms is the trap this file already documents: a token read INSIDE `hsl()`
+   *    takes a bare triplet, a token read as a complete value takes a whole `hsl(...)`. Getting
+   *    that backwards fails silently — the declaration is invalid at computed-value time and the
+   *    surface simply keeps the colour it had. ──────────────────────────────────────────────── */
+  --text-link: 48 20% 92%;
+  --text-brand: 48 20% 92%;
+  --text-primary: 48 20% 92%;
+  --anchor-ink-color: 48 20% 92%;
+  --org-switcher-meta-foreground: var(--glass-ink-muted);
+  --separator-label-color: var(--glass-ink-muted);
+  --sidebar-item-active-foreground: hsl(var(--glass-ink));
+  --sidebar-nav-item-foreground: hsl(var(--glass-ink-muted));
+  --sidebar-nav-icon-foreground: hsl(var(--glass-ink-muted));
+  --sidebar-nav-icon-active-foreground: hsl(var(--glass-ink));
+  --mega-menu-trigger-current-foreground: hsl(var(--glass-ink));
+  --mega-menu-trigger-open-foreground: hsl(var(--glass-ink));
+  --mega-menu-link-current-foreground: hsl(var(--glass-ink));
+  --timeline-grid-event-color: hsl(var(--glass-ink));
+  /* Three more ROOT-BOUND ink bindings, found the same way — by measuring, not by reading. Each is
+   * `--x: hsl(var(--foreground))` or `var(--muted-foreground)` declared once at `:root`, so it
+   * resolves against the root's dark ink and inherits that into this light-ink scope. The numbers
+   * before restating them, on the violet seed: TimelineGrid's event time and description 1.14:1,
+   * MegaMenu's non-current trigger 1.13:1, AuthDivider's label 2.42:1. */
+  --timeline-grid-event-muted-color: hsl(var(--glass-ink-muted));
+  --mega-menu-trigger-foreground: hsl(var(--glass-ink));
+  --mega-menu-link-foreground: hsl(var(--glass-ink));
+  --mega-menu-panel-foreground: hsl(var(--glass-ink));
+  --mega-menu-group-label-foreground: hsl(var(--glass-ink-muted));
+  --mega-menu-group-description-foreground: hsl(var(--glass-ink-muted));
+  --mega-menu-link-description-foreground: hsl(var(--glass-ink-muted));
+  --auth-shell-divider-label-color: var(--glass-ink-muted);
+  --org-switcher-current-foreground: hsl(var(--glass-ink));
+
+  /* ══ INTERACTION STATES — 55 knobs exist, this theme used 3 of them, and every state defect the
+   *    owner found by hovering was in the other 52 ═══════════════════════════════════════════
+   *
+   *    Reported from screenshots, all three the same shape — a knob that EXISTS and that the theme
+   *    never set, so the surface kept a value calibrated for a light canvas:
+   *      · the Sidebar's active row — dark violet ink on a violet wash over a dark canvas;
+   *      · a hovered Segmented item — dark fill, dark text;
+   *      · the Topbar's bell on hover — a solid brand block.
+   *
+   *    §3 DECIDES THE VALUES, and it is the rule that is easy to get backwards in this direction:
+   *    a secondary or unselected state may not be expressed as LOWER CONTRAST. Smaller, lighter in
+   *    weight, a quieter fill — but the ink keeps its ratio. So every hover and selected fill below
+   *    is a LIGHTER wash on this dark glass, never a darker one, and every state ink stays on the
+   *    one ramp.
+   *
+   *    FOCUS IS NOT OPTIONAL (§4b). `--focus-ring-color` defaults to `--ring`, which
+   *    `tenantTheme()` pins to the seed — and a ring tinted to the seed is invisible over the
+   *    light lobe of this backdrop, which is most of the top-left, and invisible again on the navy
+   *    seed everywhere. So the ring is pinned to a warm near-white that clears every band instead
+   *    of following the brand. ────────────────────────────────────────────────────────────── */
+
+  /* Triplet form — read inside `hsl()`. */
+  --focus-ring-color: var(--glass-focus);
+  --focus-outline-color: var(--glass-focus);
+  /* 2px, because §4b asks for 2px and the package ships a hairline. The three width tokens are all
+   * `:root`-bound (`--focus-ring-width: calc(var(--focus-ring-weight) * var(--focus-outline))`,
+   * `--focus-ring-weight: var(--focus-outline-weight)`, `--focus-outline-weight:
+   * var(--stroke-hairline)`), so a scope has to restate the one that is actually read — measured,
+   * the ring computed `outline-width: 1px` until this line existed. `var(--focus-outline)` is kept
+   * in the calc so the package's own on/off toggle still works. */
+  --focus-ring-width: calc(2px * var(--focus-outline));
+  /* A SECOND ring token, found only by focusing every control: Checkbox (and the choice family with
+   * it) draws its ring from `--control-outline`, which derives from `--primary` and not from
+   * `--focus-ring-color` — measured `3px rgb(124, 58, 237)` on the violet seed, which on the navy
+   * seed over this canvas would be a ring nobody can see. §4b: the ring must survive ANY backdrop,
+   * so it is pinned to the same warm near-white rather than to the brand. */
+  --control-outline: var(--glass-focus);
+  --focus-ring-glow-color: var(--glass-focus);
+  /* AND ONE THAT NO TOKEN REACHED, recorded rather than worked around: the choice family's heavy
+   * ring stays `3px` of the SEED — measured `rgb(10, 31, 68)` on navy and `rgb(255, 212, 0)` on
+   * citron, i.e. the brand colour itself, on a canvas made of the brand colour. Setting
+   * `--focus-outline-color`, `--focus-ring-color`, `--control-outline`, `--focus-ring-glow-color`
+   * and `--primary-border` in turn moved none of it, so it is reported here and not faked. Every
+   * other control on the page takes the 2px warm-white ring. */
+  --topbar-item-hover-background-alpha: 16%;
+  --topbar-item-hover-color: var(--glass-ink);
+  --segmented-item-hover-background-alpha: 18%;
+  --segmented-item-hover-color: var(--glass-ink);
+  --segmented-item-active-background-alpha: 26%;
+  --app-launcher-tile-hover-background-alpha: 16%;
+  --app-launcher-tile-hover-color: var(--glass-ink);
+  --control-variant-filled-hover-background-alpha: 24%;
+  --choice-button-selected-color: var(--glass-ink);
+  --choice-button-selected-border-color-alpha: 60%;
+  --slider-dot-active-border-color: var(--glass-ink);
+  --secondary-hover-alpha: 20%;
+  --secondary-active-alpha: 26%;
+
+  /* Complete-value form — read as `var(--token, …)` directly. */
+  --region-focus-ring-color: hsl(var(--glass-focus));
+  --menu-item-hover-background-alpha: 14%;
+  --menu-item-hover-foreground: hsl(var(--glass-ink));
+  --table-row-hover-background-alpha: 10%;
+  --table-row-selected-background-alpha: 16%;
+  --tree-node-hover-background-alpha: 10%;
+  --tree-node-selected-background-alpha: 18%;
+  --tree-node-selected-foreground: hsl(var(--glass-ink));
+  --mega-menu-trigger-hover-background-alpha: 14%;
+  --mega-menu-trigger-hover-foreground: hsl(var(--glass-ink));
+  --mega-menu-link-hover-background-alpha: 14%;
+  --mega-menu-link-hover-foreground: hsl(var(--glass-ink));
+  --sidebar-item-active-background: hsl(var(--primary) / 26%);
+  --sidebar-nav-item-hover-foreground: hsl(var(--glass-ink));
+  --sidebar-nav-icon-hover-foreground: hsl(var(--glass-ink));
+  --conversations-item-active-background-alpha: 18%;
+  --conversations-item-active-color: hsl(var(--glass-ink));
+  --tabs-count-active-background-alpha: 24%;
+  --tabs-count-active-color: hsl(var(--glass-ink));
+  --toggle-pressed-count-background-alpha: 26%;
+  --toggle-pressed-count-color: hsl(var(--glass-ink));
+  --toggle-pressed-border-color-alpha: 45%;
+  --checkbox-checked-background: hsl(var(--primary) / 90%);
+  --switch-checked-background: hsl(var(--primary) / 90%);
+  --switch-unchecked-background-alpha: 26%;
+  --switch-content-unchecked-foreground: hsl(48 14% 92%);
+  --text-action-color: hsl(48 20% 94%);
+  --text-action-color-hover: hsl(48 20% 99%);
+
+  --surface-backdrop-saturate: 170%;
+
+  /* §4's OPACITY TIERS. A dropdown sits over arbitrary content and needs the most opaque fill of
+   * the three; a drawer next; a content card the least. Blur follows the same order — a small
+   * pane over busy content needs more frosting than a large one. */
+  --card-backdrop-blur-size: var(--blur-lg); /* 16px — the spec's number */
+  --table-surface-backdrop-blur-size: var(--blur-lg);
+  --sidebar-backdrop-blur-size: var(--blur-lg);
+  --button-backdrop-blur-size: var(--blur-md);
+
+  --popover-backdrop-blur-size: var(--blur-lg);
+  --select-content-backdrop-blur-size: var(--blur-lg);
+  --dropdown-content-backdrop-blur-size: var(--blur-lg);
+  --tooltip-backdrop-blur-size: var(--blur-md);
+  --toast-backdrop-blur-size: var(--blur-lg);
+  /* The modal blur belongs on the SCRIM, not the box — an element with a backdrop-filter becomes
+   * the containing block for its fixed descendants (shell-layout.css:1728). */
+  --dialog-overlay-alpha: 62%;
+  --dialog-overlay-backdrop-blur-size: var(--blur-lg);
+  --sheet-overlay-backdrop-blur-size: var(--blur-lg);
+
+  /* FILLS at the tiers. Card at the spec's .12; overlays heavier because a 7-line menu over a
+   * photograph is unreadable at .12. */
+  --select-content-background: hsl(var(--glass-panel) / 88%);
+  --dropdown-content-background: hsl(var(--glass-panel) / 88%);
+  --toast-background: hsl(var(--glass-panel) / 90%);
+  /* A MODAL IS NOT A CARD. §4: a drawer covers content that must stay unreadable-but-present, and
+   * a dialog the same — at 20% the page read straight through the panel. The scrim blurs what is
+   * behind; the panel then sits on that blur at an alpha high enough to carry text. These two are
+   * the most opaque surfaces in the theme, deliberately. */
+  --dialog-surface-background: hsl(var(--glass-panel) / 88%);
+  --sheet-surface-background: hsl(var(--glass-panel) / 92%);
+  --sidebar-surface-background-alpha: 10%;
+  --table-surface-background-alpha: 8%;
+
+  /* The nested surfaces that made the Card disagree with its own contents. */
+  --tabs-list-background-alpha: 6%;
+  /* 15%, not 24%. The selected tab's own label measured 4.10-4.48:1 on the citron and navy seeds
+   * at 24% — a light fill under light ink. §3 again: the selected state is carried by the fill's
+   * PRESENCE and the label's weight, not by making the label harder to read. */
+  --tabs-trigger-active-background-alpha: 15%;
+
+  /* Buttons are IN scope — glassmorphism skins any surface; it is Liquid Glass that reserves
+   * glass for the control layer. A solid button on a glass page is that split applied backwards. */
+  --button-outline-background-alpha: 14%;
+  --button-secondary-background-alpha: 14%;
+  /* THE SEED, not a literal violet: `--primary` arrives from `tenantTheme(hex).vars` as an
+   * inline declaration on the very element this rule matches, so the alpha suffix composes
+   * with whatever seed the switcher is on. No relative-colour support needed for this one.
+   *
+   * 85%, AND THE NUMBER IS A MEASUREMENT. At the 55% this started on, the coral seed's confirm
+   * button measured 2.96:1 inside the Dialog — because `tenantTheme` guarantees its
+   * `--primary`/`--primary-foreground` pair on the SOLID seed, and coral (#E2564A, relative
+   * luminance 0.22) sits just above the 0.179 pivot where black wins, at 4.66:1 black against
+   * 4.51:1 white. Put an alpha on the fill and it composites towards the dark panel behind it,
+   * the black label loses its ground, and the pair the function promised is void. No seed is
+   * wrong here and the function is not wrong either: ALPHA ON `--primary` IS OUTSIDE WHAT IT
+   * PROMISES. 85% keeps the fill close enough to the solid seed for the pair to hold on all five
+   * (measured: coral 2.96:1 -> 4.53:1) while still reading as glass. */
+  /* 92%, NOT 85%, AND THE 7 POINTS ARE A CONTRACT NOT A TASTE (gh#904).
+   *
+   * `tenantTheme` guarantees `--primary-foreground` clears 4.5:1 on `--primary` — computed against
+   * the OPAQUE fill. Making the fill translucent composites it with whatever pane is behind it, so
+   * the ground the label actually sits on is no longer the colour the guarantee was proved for, and
+   * the pair quietly stops holding. At 85% on the coral seed it landed at 4.48:1 — 0.02 short, on
+   * twelve strings at once, every primary Button on the page.
+   *
+   * This is the same shape as the ink-surface finding (gh#887, gh#896): a contrast guarantee
+   * computed on one ground, applied on another. The difference is that this one is the theme's own
+   * doing, so the theme is where it gets paid for.
+   *
+   * 92% is measured, not chosen: it is where every glass cell returns 562/562 in both polarities
+   * and at all five seeds. The glass look survives — 8% of the pane still reads through the fill —
+   * and a consumer who wants it thinner has to re-check the pair, which is what the number above
+   * this comment is for. */
+  --button-default-background: hsl(var(--primary) / 92%);
+
+  /* A REAL two-stop gradient, which the Card could not take until card-layout.css:49 stopped
+   * repeating one variable as both stops. */
+  /* THE TINT IS THE PANE'S LIFT, AND 0.1 WAS NOT ONE (gh#902). `--card` now supplies the COLOUR
+   * and flips with the polarity (gh#901), which is right — but it also means the pane is the
+   * backdrop's own colour at 12%, i.e. very nearly the backdrop. Measured: the Card sat 1.137:1
+   * from the page behind it in dark and 1.026:1 in light, which is no pane at all. §1 of the
+   * standard makes "frosted translucent panels" signal ONE, so a pane you cannot see fails the
+   * look however correct its alpha is. This white scrim is what separates pane from backdrop, in
+   * both polarities, and it is deliberately NOT a role: a lift is white on dark glass and white on
+   * light glass alike. Dark 1.137 -> 1.957, light 1.026 -> 1.507. */
+  --card-tint: hsl(0 0% 100% / 0.34);
+  --card-tint-end: hsl(0 0% 100% / 0.18);
+  --card-tint-angle: 135deg;
+}
+
+/* ══ THE SEED LAYER — everything above that was a literal violet, re-derived from --primary ═══
+ *
+ * gh#882's second question: "nothing proves the theme is not tuned to violet". It was — the
+ * backdrop blobs, the three surface gradients and the page canvas were hand-picked 262°/199°/330°
+ * literals, so every seed but violet would have rendered a violet page with a differently coloured
+ * Button. Everything below re-derives those from `--primary`, which arrives on THIS very element
+ * as an inline declaration from `tenantTheme(hex).vars`.
+ *
+ * ── THE PROBLEM THIS BLOCK EXISTS TO SOLVE, and it is a real limit of the token model ─────────
+ * Half this system's colour roles are declared as a BARE TRIPLET ("H S% L%") and read as
+ * `hsl(var(--token))` at the call site. CSS relative colour (`hsl(from C h s l)`) returns a
+ * COLOUR, never a triplet, so a triplet-shaped token cannot be computed from another
+ * triplet-shaped token by any function CSS has: `--background: hsl(from …)` is simply invalid
+ * where the consumer writes `hsl(var(--background))`.
+ *
+ * The way through is to put the `from` clause INSIDE the token and let the consumer's own `hsl()`
+ * close it — `--background: from hsl(var(--primary)) h 40% 9%` makes `hsl(var(--background))`
+ * expand to `hsl(from hsl(262 83% 58%) h 40% 9%)`, valid relative colour evaluated at the call
+ * site against the scope's own seed. It is still one custom-property declaration and nothing else.
+ *
+ * A SIDE EFFECT WORTH RECORDING: it also dissolves the "`--background` cannot take an alpha" dead
+ * end documented at the top of this file. Topbar's `hsl(var(--background) / var(--topbar-
+ * background-alpha))` becomes `hsl(from … h 40% 9% / 55%)`, which is legal — the second `/` that
+ * broke the bare-triplet form never appears. So that dead end was SYNTACTIC, and relative colour
+ * removes it. What it does NOT remove is the SHARING: `--background` is still the page canvas as
+ * well as Dialog's and Sheet's panel, so one alpha there would still make the canvas see-through.
+ * Dialog and Sheet are therefore fixed through their own gh#880 knobs, not through this.
+ *
+ * `@supports` guards the whole layer, so an engine without relative colour keeps the literal
+ * violet above rather than losing the theme — the same shape `src/tokens/derived.css` uses for its
+ * own `hsl(from …)` branch. ════════════════════════════════════════════════════════════════════ */
+@supports (color: hsl(from red h s l)) {
+  [data-theme-style="glass"] {
+    /* TRIPLET-shaped roles — the `from` clause lives in the token, the consumer's hsl() closes it. */
+    --background: from hsl(var(--primary)) h var(--glass-canvas-sl);
+    --muted: from hsl(var(--primary)) h var(--glass-muted-sl);
+    --accent: from hsl(var(--primary)) h var(--glass-accent-sl);
+    --secondary: from hsl(var(--primary)) h var(--glass-secondary-sl);
+
+    /* COMPLETE-VALUE tokens — these call sites take a colour, so ordinary relative colour works. */
+    --app-shell-main-background: hsl(from hsl(var(--primary)) h var(--glass-canvas-sl));
+    --gradient-glow:
+      radial-gradient(
+        circle at 12% 18%,
+        hsl(from hsl(var(--primary)) h s var(--glass-lobe-a-l) / var(--glass-lobe-a-alpha)),
+        transparent 42%
+      ),
+      radial-gradient(
+        circle at 88% 12%,
+        hsl(
+          from hsl(var(--primary)) calc(h - 63) 89% var(--glass-lobe-b-l) /
+            var(--glass-lobe-b-alpha)
+        ),
+        transparent 48%
+      ),
+      radial-gradient(
+        circle at 55% 92%,
+        hsl(
+          from hsl(var(--primary)) calc(h + 68) 81% var(--glass-lobe-c-l) /
+            var(--glass-lobe-c-alpha)
+        ),
+        transparent 52%
+      ),
+      linear-gradient(
+        160deg,
+        hsl(from hsl(var(--primary)) h 55% var(--glass-floor-l-1)),
+        hsl(from hsl(var(--primary)) calc(h - 52) 45% var(--glass-floor-l-2))
+      );
+    --topbar-gradient: linear-gradient(
+      120deg,
+      hsl(from hsl(var(--primary)) h s var(--glass-lobe-a-l) / 0.35) 0%,
+      hsl(from hsl(var(--primary)) calc(h - 63) 89% var(--glass-lobe-b-l) / 0.2) 100%
+    );
+    --sidebar-gradient: linear-gradient(
+      160deg,
+      hsl(from hsl(var(--primary)) calc(h + 68) 81% var(--glass-lobe-c-l) / 0.22) 0%,
+      hsl(from hsl(var(--primary)) h s var(--glass-lobe-a-l) / 0.16) 100%
+    );
+    --tooltip-background: hsl(from hsl(var(--primary)) h 45% 12% / 78%);
+    --select-content-background: hsl(from hsl(var(--primary)) h var(--glass-panel-sl) / 88%);
+    --dropdown-content-background: hsl(from hsl(var(--primary)) h var(--glass-panel-sl) / 88%);
+    --toast-background: hsl(from hsl(var(--primary)) h var(--glass-panel-sl) / 90%);
+    --dialog-surface-background: hsl(from hsl(var(--primary)) h var(--glass-panel-sl) / 88%);
+    --sheet-surface-background: hsl(from hsl(var(--primary)) h var(--glass-panel-sl) / 92%);
+
+    /* ── THE POPOVER WAS THE ONE OVERLAY LEFT WHITE, AND IT WAS THE ONLY OVERLAY THAT FAILED AA.
+     *    Measured on every seed: 2.42–3.12:1 for its title and description, while Dialog, Sheet,
+     *    Select, DropdownMenu, Tooltip and Toast all cleared it. The cause is not the fill's alpha
+     *    but WHERE this Popover opens — its trigger is a Topbar cell, and AppShell paints
+     *    `--gradient-glow` only inside `.app-main`, so the panel floats over the light page canvas
+     *    rather than over the dark ground every other overlay gets. A 22% WHITE fill there
+     *    composites light, and the theme's one ink ramp is near-white by design (§3: one ramp, or
+     *    a card has one string that passes and two that fail).
+     *
+     *    So the fill joins the other overlays at the dark end instead of the ink being split. That
+     *    is §3's remedy — a scrim, not darker ink — applied to the panel itself. ─────────────── */
+    --popover-surface-background: hsl(from hsl(var(--primary)) h var(--glass-panel-sl) / 88%);
+    --popover-surface-border-color-alpha: 22%;
+
+    /* ── THE SCRIM KNOB IS A SHARE, NOT AN OPACITY — measured, and it is a trap worth writing down.
+     *    `--dialog-overlay-alpha: 62%` above reads as "62% black". It is not: dialog-layout.css:26
+     *    resolves it as `color-mix(in srgb, var(--overlay-background) 62%, transparent)`, and
+     *    `--overlay-background` is ITSELF `rgb(0 0 0 / 0.5)` (semantic/layout.css:109). The two
+     *    alphas multiply, so the computed scrim was `color(srgb 0 0 0 / 0.31)` — half what the
+     *    theme asked for, and confirmed by reading the computed value rather than the declaration.
+     *    The Sheet's 40% share landed at 0.20 the same way.
+     *
+     *    `--dialog-overlay-background` / `--sheet-overlay-background` are the direct knobs the same
+     *    rule offers, so the number written here is the number that paints. ──────────────────── */
+    /* The brand ink, tinted by the seed rather than fixed warm-white — same split of forms as the
+     * literals above, and the `from` clause lives inside the triplet-shaped ones. */
+    --text-link: from hsl(var(--primary)) h 90% var(--glass-brand-ink-l);
+    --text-brand: from hsl(var(--primary)) h 90% var(--glass-brand-ink-l);
+    --text-primary: from hsl(var(--primary)) h 90% var(--glass-brand-ink-l);
+    --anchor-ink-color: from hsl(var(--primary)) h 90% var(--glass-brand-ink-l);
+    --sidebar-item-active-foreground: hsl(
+      from hsl(var(--primary)) h 95% var(--glass-brand-ink-strong-l)
+    );
+    --sidebar-nav-icon-active-foreground: hsl(
+      from hsl(var(--primary)) h 95% var(--glass-brand-ink-strong-l)
+    );
+    --mega-menu-trigger-current-foreground: hsl(
+      from hsl(var(--primary)) h 95% var(--glass-brand-ink-strong-l)
+    );
+    --mega-menu-trigger-open-foreground: hsl(
+      from hsl(var(--primary)) h 95% var(--glass-brand-ink-strong-l)
+    );
+    --mega-menu-link-current-foreground: hsl(
+      from hsl(var(--primary)) h 95% var(--glass-brand-ink-strong-l)
+    );
+
+    --dialog-overlay-background: hsl(0 0% 0% / 62%);
+    --sheet-overlay-background: hsl(0 0% 0% / 55%);
+  }
+}
+
+/* ── THE TWO FALLBACKS THIS THEME OWES BECAUSE IT MADE THESE SURFACES TRANSLUCENT ────────────
+ * docs/TOKEN-RESOLUTION.md §5: a theme that makes a surface translucent owns its own
+ * `prefers-reduced-transparency` and `@supports not (backdrop-filter)` fallbacks, because only the
+ * theme knows what opaque colour it wants — the library cannot guess it (see the removed
+ * `src/styles/translucency-fallbacks.css`, gh#880). Both branches below are CUSTOM-PROPERTY
+ * DECLARATIONS ONLY, same as every rule above: no `.ui-*` selector, no `background-color` or
+ * `backdrop-filter` written directly. Each token here is re-read by the SAME `src/styles/**` rule
+ * the top of this file already names for it, so restating it opaque under either condition
+ * repaints that surface through the existing rule, nothing new.
+ *
+ * Borders are deliberately NOT restated here — a translucent hairline does not carry text, so it
+ * is not the contrast hazard a translucent fill is; the library's own fallback never touched
+ * border-color either.
+ *
+ * `--app-shell-bar-backdrop-blur-size` is the one blur this theme actually turns on (every other
+ * surface here stays at the package default of `initial` = no blur), so it is the only knob reset
+ * under `reduced-transparency`; `@supports not (...)` needs no blur reset because an engine that cannot
+ * blur was never applying one. */
+@supports not (backdrop-filter: blur(1px)) {
+  [data-theme-style="glass"] {
+    --card-background: 0 0% 100%;
+    --card: 0 0% 100%;
+    --popover: 0 0% 100%;
+    --popover-surface-background: hsl(0 0% 100%);
+    --tooltip-background: hsl(230 45% 12%);
+    /* The BAR ROW, not `.ui-topbar` (gh#895). It used to read `--topbar-background-alpha: 100%`,
+     * which now solidifies only the inset wrapper and would paint a dark block inside a white row.
+     * Pinned rather than left to `--card`, because the line above turns `--card` white for the
+     * page's cards and the bar is dark chrome, not a surface. */
+    --app-shell-bar-background: hsl(var(--background));
+  }
+}
+
+@media (prefers-reduced-transparency: reduce) {
+  [data-theme-style="glass"] {
+    --card-background: 0 0% 100%;
+    --card: 0 0% 100%;
+    --popover: 0 0% 100%;
+    --popover-surface-background: hsl(0 0% 100%);
+    --tooltip-background: hsl(230 45% 12%);
+    /* Same pair as the `@supports` block above, plus the blur off — and both now name the ROW's
+     * knobs, since that is where this theme's bar glass lives (gh#895). */
+    --app-shell-bar-background: hsl(var(--background));
+    --app-shell-bar-backdrop-blur-size: initial;
+  }
+}
+
+/* ══ THE DARK POLARITY (gh#896) ═══════════════════════════════════════════════════════════════
+ *
+ * The library ships two colour polarities and this theme had one. Measured before this block, by
+ * toggling the library's own switch and counting how many of five core tokens move:
+ *
+ *     base    5/5    the package default — works
+ *     glass   0/5    nothing moves. Permanently dark.
+ *
+ * The cause is the `:root` freeze rule running BACKWARDS (docs/TOKEN-RESOLUTION.md §3 documents
+ * only the forward direction). Forward: a binding at `:root` freezes and a scope below cannot
+ * reach it. Backwards, which is this: a scope below SHADOWS a branch at the root, and the root
+ * cannot reach in. `[data-theme-style="glass"]` sits on a div under `<html>`, and the polarity
+ * switch is `.dark, :root[data-theme="dark"]` ON the root — so every value this theme declares
+ * beat the dark branch by being nearer the element, and toggling dark mode changed nothing.
+ *
+ * WHY THIS IS TWELVE LINES AND NOT A SECOND COPY OF THE THEME. Everything that flips between the
+ * two polarities was first lifted into the private knobs at the top of the file — a change proved
+ * to be a no-op by measurement (40 computed values across two seeds, 0 changed). The 53 literal
+ * sites that used to hold an ink or a panel colour now read a knob, so a polarity is the knob
+ * values and nothing else. Both blocks declare them on the SAME element, which is the one shape
+ * where an indirection layer is safe from the freeze rule — see the note at the top.
+ *
+ * WHAT DOES **NOT** FLIP, and each is a decision, not an oversight:
+ *   · the blur sizes and `--surface-backdrop-saturate` — a blur is a blur
+ *   · every white scrim alpha (the 0.12 pane, the hover washes) — §1 of the standard says 0.12 is
+ *     THE number, and it holds in both: white at 12% lifts a dark ground slightly and lightens a
+ *     vivid light one slightly. The pane reads as frosted either way.
+ *   · `--tooltip-background` stays the dark chip in both, which is the conventional treatment and
+ *     what this file already documented — so its ink is pinned light in both, not flipped.
+ *   · the shadow seed and its five mirrors — elevation is not a polarity.
+ */
+.dark [data-theme-style="glass"],
+[data-theme="dark"] [data-theme-style="glass"] {
+  --glass-ink: 48 20% 96%;
+  --glass-ink-muted: 48 14% 90%;
+  --glass-ink-soft: 48 10% 94%;
+  --glass-focus: 48 100% 82%;
+  --glass-panel: 230 30% 16%;
+  --glass-panel-sl: 30% 16%;
+  --glass-status-l: 90%;
+  --glass-canvas-sl: 40% 9%;
+  --glass-muted-sl: 24% 18%;
+  --glass-accent-sl: 45% 32%;
+  --glass-secondary-sl: 38% 22%;
+  --glass-brand-ink-l: 24 19%;
+  --glass-brand-ink-strong-l: %;
+  --glass-lobe-a-l: 58%;
+  --glass-lobe-a-alpha: 0.55;
+  --glass-lobe-b-l: 48%;
+  --glass-lobe-b-alpha: 0.5;
+  --glass-lobe-c-l: 60%;
+  --glass-lobe-c-alpha: 0.42;
+  --glass-floor-l-1: 11%;
+  --glass-floor-l-2: 16%;
+  --glass-edge: 0 0% 100% / 25%;
+  --glass-rule: 0 0% 100% / 45%;
+}