@flyos/design-system 0.0.1-reserved → 1.1.0

package/scss/_business-app-buttons.scss

@@ -0,0 +1,212 @@
+@use 'vos-button-mixins' as *;
+
+// ─── visionOS Button Utility Classes (shared with FlyOS desktop shell) ────────
+// Requires @use 'fly-theme' (or equivalent tokens) before this partial.
+
+@layer designsystem {
+.vos-btn {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  color: var(--label-primary);
+  font-family: var(--font-family);
+  font-weight: var(--btn-font-weight);
+  cursor: pointer;
+  white-space: nowrap;
+  overflow: clip;
+  padding: 0;
+  transition: background 0.15s ease, color 0.15s ease;
+
+  &.sm {
+    height: var(--btn-sm-height);
+    padding: var(--btn-sm-padding);
+    font-size: var(--btn-sm-font-size);
+    line-height: var(--btn-sm-line-height);
+    gap: var(--btn-sm-gap);
+    border-radius: var(--btn-radius-capsule);
+
+    i, .btn-symbol { font-size: var(--btn-sm-symbol-size); }
+  }
+
+  &.reg {
+    height: var(--btn-reg-height);
+    padding: var(--btn-reg-padding);
+    font-size: var(--btn-reg-font-size);
+    line-height: var(--btn-reg-line-height);
+    gap: var(--btn-reg-gap);
+    border-radius: var(--btn-radius-capsule);
+
+    i, .btn-symbol { font-size: var(--btn-reg-symbol-size); }
+  }
+
+  &.lg {
+    height: var(--btn-lg-height);
+    padding: var(--btn-lg-padding);
+    font-size: var(--btn-lg-font-size);
+    line-height: var(--btn-lg-line-height);
+    gap: var(--btn-lg-gap);
+    border-radius: var(--btn-radius-capsule);
+
+    i, .btn-symbol { font-size: var(--btn-lg-symbol-size); }
+  }
+
+  &.rect {
+    &.sm { border-radius: var(--btn-radius-rect-sm); }
+    &.reg { border-radius: var(--btn-radius-rect-sm); }
+    &.lg { border-radius: var(--btn-radius-rect-lg); }
+  }
+
+  &.platter::before {
+    @include vos-platter-layers(inherit);
+  }
+
+  &:hover:not(:disabled, .selected, .active)::before {
+    @include vos-platter-layers(inherit);
+  }
+
+  &.selected,
+  &.active {
+    background: var(--btn-selected-bg);
+    color: var(--btn-selected-text);
+
+    &::before { display: none; }
+  }
+
+  &:disabled, &.disabled {
+    cursor: default;
+    color: var(--btn-disabled-text);
+    pointer-events: none;
+
+    &::before {
+      @include vos-disabled-layers(inherit);
+    }
+  }
+
+  &.danger {
+    color: var(--system-red);
+  }
+
+  &.primary {
+    &.platter::before, &:hover:not(:disabled)::before {
+      background: linear-gradient(var(--primary-color), var(--primary-color));
+      mix-blend-mode: normal;
+      opacity: 0.15;
+    }
+
+    &.selected,
+    &.active {
+      background: var(--primary-color);
+      color: #fff;
+    }
+  }
+}
+
+.vos-btn-symbol {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  color: var(--label-primary);
+  font-family: var(--font-family);
+  font-weight: var(--btn-symbol-font-weight);
+  cursor: pointer;
+  overflow: clip;
+  border-radius: 500px;
+  padding: 0;
+  transition: background 0.15s ease, color 0.15s ease;
+
+  &.mini {
+    width: var(--btn-symbol-mini);
+    height: var(--btn-symbol-mini);
+    font-size: var(--btn-symbol-mini-font);
+    font-weight: var(--btn-font-weight);
+  }
+
+  &.sm {
+    width: var(--btn-symbol-sm);
+    height: var(--btn-symbol-sm);
+    font-size: var(--btn-symbol-sm-font);
+  }
+
+  &.reg {
+    width: var(--btn-symbol-reg);
+    height: var(--btn-symbol-reg);
+    font-size: var(--btn-symbol-reg-font);
+  }
+
+  &.lg {
+    width: var(--btn-symbol-lg);
+    height: var(--btn-symbol-lg);
+    font-size: var(--btn-symbol-lg-font);
+  }
+
+  &.xl {
+    width: var(--btn-symbol-xl);
+    height: var(--btn-symbol-xl);
+    font-size: var(--btn-symbol-xl-font);
+  }
+
+  &.platter::before {
+    @include vos-platter-layers(500px);
+  }
+
+  &:hover:not(:disabled, .selected, .active)::before {
+    @include vos-platter-layers(500px);
+  }
+
+  &.selected,
+  &.active {
+    background: var(--btn-selected-bg);
+    color: var(--btn-selected-text);
+
+    &::before { display: none; }
+  }
+
+  &:disabled, &.disabled {
+    cursor: default;
+    color: var(--btn-disabled-text);
+    pointer-events: none;
+
+    &::before {
+      @include vos-disabled-layers(500px);
+    }
+  }
+
+  &.danger {
+    &:hover:not(:disabled) {
+      background: rgb(255 69 58 / 15%);
+      color: var(--system-red);
+    }
+  }
+}
+
+.vos-link {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  height: var(--link-height);
+  padding: 0 3px;
+  border: none;
+  background: transparent;
+  color: var(--link-color);
+  font-family: var(--font-family);
+  font-weight: var(--btn-font-weight);
+  font-size: var(--link-font-size);
+  cursor: pointer;
+  white-space: nowrap;
+  text-decoration: none;
+  border-radius: var(--btn-radius-capsule);
+  transition: background 0.15s ease;
+
+  &:hover {
+    background: rgb(60 211 254 / 10%);
+    border-radius: var(--btn-radius-rect-sm);
+  }
+}
+
+} // @layer designsystem

package/scss/_fly-theme.scss

@@ -0,0 +1,27 @@
+// Entry: tokens + html.light-theme / .dark-theme + OS auto dark.
+// Use from shell or Business Apps:
+//   stylePreprocessorOptions.includePaths → design-system src folder
+//   @use 'scss/fly-theme' or @use 'fly-theme' when scss is on the path.
+@use 'tokens';
+@use 'theme-light';
+@use 'theme-dark';
+
+// The inherited `color` for themed documents. Emits a rule, not tokens, so it
+// lives apart from the theme partials — see its header for why the absence of a
+// baseline was the root cause of the recurring black-ink-on-glass bug.
+@use 'ink-baseline';
+
+// Business-app content surfaces (--ink-*/--bg-*/--line-*, the sp/r/text/z/shadow
+// scales) consumed by the `fly-*` component library. Deliberately a family apart
+// from the shell-chrome tokens above — see the partial's header for why, and for
+// the 12 platform-owned tokens it must never redefine.
+@use 'app-surface-tokens';
+
+// Global CSS the app-surface components rely on: the `[data-tooltip]` hover label
+// (written directly by fly-button / fly-icon-button / fly-status-badge) and the
+// `.mono` tabular-numerals utility. Emits CSS, so it belongs here rather than in
+// the per-component styles.
+@use 'app-surface-utilities';
+@use 'theme-auto';
+@use 'native-select'; // native <select> popups follow the theme's color-scheme (see the partial)
+@use 'menu-anchor'; // the trigger of an open fly-context-menu reads as pressed (see the partial)

package/scss/_ink-baseline.scss

@@ -0,0 +1,29 @@
+// ─── Inherited-ink baseline ──────────────────────────────────────────────────
+//
+// Establishes the document's inherited `color`. Until this existed, NOTHING in
+// the shell ever set `color` on `html` or `body` — `_theme-light.scss` and
+// `_theme-dark.scss` declare custom properties only. So the inherited colour was
+// the user-agent default, **black**, and every component that says
+// `color: inherit` (fly-tree-nav rows, fly-breadcrumb's current crumb,
+// fly-search-input's typed text, fly-card's meta slot, and any consumer markup
+// that simply doesn't mention colour) rendered black ink on the smoked glass.
+//
+// That is why the "text is invisible in light theme" bug kept coming back app
+// after app: it was never really an app's mistake. There was no baseline to
+// inherit, so *forgetting* to set a colour was the failure mode, and the fix
+// kept being applied one component at a time. `--text-color` is white in BOTH
+// themes since the Liquid-Glass flip, so one declaration settles it everywhere.
+//
+// Scoped to the two theme classes on purpose — NOT `:root`. A business app
+// running STANDALONE renders on its own opaque paper (`--bg`, near-black
+// `--ink`) and does not load `fly-theme` at all; keying on the class means a
+// surface that never opted into a shell theme is never repainted white.
+//
+// A deliberate paper surface inside the shell (the documents editor) still
+// brings its own dark ink locally — a component rule beats this baseline, which
+// is exactly the intended precedence.
+
+html.light-theme,
+html.dark-theme {
+  color: var(--text-color);
+}

package/scss/_menu-anchor.scss

@@ -0,0 +1,22 @@
+// ─── The trigger of an OPEN fly-context-menu ─────────────────────────────────
+// `fly-context-menu` stamps `data-fly-menu-open` on whatever element is passed as its `[anchor]`
+// for as long as the menu is up (it also sets aria-expanded / aria-haspopup — see the component).
+// This paints the matching visual, so a ⋯ button reads as pressed instead of sitting idle while
+// its own menu floats above the page.
+// Imported by `fly-theme`, so the shell and every External App remote get it from the same import
+// that gives them the theme. It has to be global: the anchor lives inside the CONSUMER's
+// encapsulated component, so a DS component stylesheet could never reach it — the same reason
+// `_native-select.scss` lives here. Doing it centrally is the point: the alternative is every
+// caller hand-binding `[class.active]="menuOpen()"`, which is why the indicator was missing
+// everywhere.
+// Specificity: the attribute is repeated to reach (0,3,0). Angular's emulated encapsulation rewrites
+// a component rule like `.btn--ghost { background: transparent }` to `.btn--ghost[_ngcontent-x]`
+// (0,2,0) and injects it into <head> AFTER this stylesheet, so a single `[data-fly-menu-open]`
+// (0,1,0) — or even a doubled one, which ties and then loses on source order — would be silently
+// overridden by the very base style it needs to beat. `!important` would win too, but would also
+// stop a consumer from restyling the state at all; this leaves that door open.
+// `--surface-active` is the DS's selected/active tint and is defined in BOTH themes, so this needs
+// no light/dark pair of its own.
+[data-fly-menu-open][data-fly-menu-open][data-fly-menu-open] {
+  background-color: var(--surface-active);
+}

package/scss/_native-select.scss

@@ -0,0 +1,26 @@
+// ─── Native <select> popup — the ONE fix, platform-wide ──────────────────────
+// Imported by `fly-theme`, so the shell and every External App remote get it from the
+// same import that gives them the theme. Do not copy this rule into an app.
+// THE BUG IT KILLS
+// A themed `<select>` carries a translucent background (the shell's field tokens are glass:
+// `rgb(255 255 255 / 6%)` in dark) and light-on-dark text. That is correct for the CLOSED
+// control. But the OPEN option list is OS chrome: Chromium paints its rows with the select's
+// own `background-color`, composited over a WHITE popup backing. A 6%-white fill over white
+// is white — and the inherited light text lands on it, so the list reads as blank/transparent.
+// The user sees an empty dropdown. It is theme-dependent and easy to miss in light mode.
+// THE FIX
+// Repaint the rows with the `Canvas` / `CanvasText` system pair. Those two are the only colours
+// the native listbox reliably honours, and they FOLLOW `color-scheme` — which the theme already
+// sets on `<html>` (`color-scheme: dark` in `_theme-dark.scss`, `light` in `_theme-light.scss`)
+// and which inherits down to every select. So one rule is automatically correct in both themes,
+// with no per-app pinning.
+// DO NOT pin `color-scheme` on a select to "fix" a popup. Three apps did that independently
+// (dashboard + surveys pinned `light`, settings pinned `dark`) — each one fights the inherited
+// value and is wrong in the opposite theme. Pinning is what this rule replaces.
+// Prefer `<fly-select>` for new work: it renders its own panel, so it has no OS chrome to fight
+// and it can search/multi-select. This rule is the safety net for the native selects that remain.
+option,
+optgroup {
+  background-color: Canvas;
+  color: CanvasText;
+}

package/scss/_shell-embed-bridge.scss

@@ -0,0 +1,81 @@
+// ─── Shell-embed bridge — app-surface tokens re-tinted onto shell glass ──────
+// MIXIN ONLY. This partial emits no CSS on import; it exists so the mapping
+// below lives in ONE place instead of being retyped per feature app.
+//
+// WHY IT IS NEEDED
+// The DS carries two token families on purpose (see `_app-surface-tokens.scss`'s
+// header). `--ink-*`/`--bg-*`/`--line-*` dress BUSINESS-APP CONTENT: an opaque
+// reading surface, dark ink on white in light mode. `--label-*`/`--surface-*`
+// dress SHELL CHROME: white ink on translucent glass over the user's wallpaper.
+//
+// A desktop-shell feature app renders inside a glass window, so its chrome is
+// necessarily the second family — but the moment it mounts a component from the
+// `fly-*` app-surface kit (or `@flyos/design-system-board`), that component
+// themes itself from the FIRST family and paints an opaque white slab with
+// near-black ink. One region, two families: the app's own header ink is white,
+// the slab beneath it is white, and the header goes invisible.
+//
+// That is not hypothetical. It shipped in canvas-boards and was measured live:
+// `.cbe__export-btn` computed `color: rgb(255,255,255)` sitting on a board whose
+// `--_surface` resolved to `oklch(100% 0 0deg)`. `core/theme/feature-app-surface-tokens.ts`
+// documents the same class of trap ("a dark-mode-only review passes while light
+// mode renders a white slab") — and note the failure is LIGHT-mode-only, because
+// in dark mode both families happen to agree on light-ink-on-dark.
+//
+// THE FIX is the seam the tokens file already names: an app that embeds in the
+// shell re-tints the content family onto glass. help-center (`.hc-shell`) and
+// dashboard-app hand-rolled identical copies of this map before it lived here.
+//
+// ALIASES ONLY — every value is another token, never a literal, so the whole map
+// follows the shell's theme automatically. The ONE exception is `--on-ink`, and
+// its reason is written at the declaration.
+@mixin app-surface-on-glass {
+  // Surfaces: the window chrome supplies the material, so the app's own page
+  // background is nothing at all; cards/tracks are lifts ON that plate.
+  --bg: transparent;
+  --bg-2: var(--surface-card);
+  --bg-3: var(--fill-tertiary);
+  --bg-hover: var(--surface-active);
+
+  // Hairlines.
+  --line: var(--separator);
+  --line-2: var(--surface-border);
+  --line-3: var(--separator);
+
+  // Ink — opaque label tokens, never a surface token. Aliasing a translucent
+  // surface onto an ink slot is what turns a control into an empty coloured
+  // square (see the note in help-center.component.scss).
+  --ink: var(--label-primary);
+  --ink-2: var(--label-secondary);
+  --ink-3: var(--label-secondary);
+  --ink-4: var(--label-tertiary);
+
+  // CONTRACT (`_app-surface-tokens.scss`): anything that redefines `--ink` MUST
+  // redefine `--on-ink`, and it must be OPAQUE. `--on-ink` labels a fill of
+  // `--ink` itself — the primary button. Above we pin `--ink` to the shell's
+  // white label ink in BOTH themes, so its counter-ink is a fixed DARK value in
+  // both. It cannot alias a shell token: the shell is glass and owns no
+  // dark-opaque ink. This literal is the same value `--ink` carries in the
+  // app-surface light theme, i.e. the colour a white pill is designed to label.
+  //
+  // `app-surface-conventions.spec.ts` can only police the DS token file itself;
+  // its doc says consumers that remap `--ink` "carry the same obligation".
+  // Routing every consumer through this mixin is how that obligation is met.
+  --on-ink: oklch(18% 0.005 250deg);
+
+  // `--ink-inverse` carries the SAME obligation as `--on-ink` and was missed.
+  //
+  // The app-surface family defines it once, as "text on dark / gradient fills" — near-white, which
+  // is correct while `--ink` is near-black. This mixin flips `--ink` to the shell's WHITE label ink
+  // and updated `--on-ink` accordingly, but left `--ink-inverse` at its near-white resting value.
+  // Every `background: var(--ink); color: var(--ink-inverse)` pair inside an embedded app therefore
+  // became WHITE ON WHITE at a contrast ratio of about 1:1.
+  //
+  // That is not hypothetical: it is what made `[data-tooltip]` (the CSS tooltip behind every
+  // `fly-icon-button`'s `tooltipKey`) invisible across the board editor — measured live at
+  // background rgb(255,255,255) with colour oklch(0.99 0 0). The same pair is used by the button,
+  // icon-button, checkbox and card components, so this was never a Boards-only bug.
+  //
+  // Pinned to `--on-ink` rather than restated, so the two counter-inks cannot drift apart again.
+  --ink-inverse: var(--on-ink);
+}

package/scss/_theme-auto.scss

@@ -0,0 +1,6 @@
+// ─── Automatic dark mode via OS preference (when user hasn't chosen) ─────────
+@media (prefers-color-scheme: dark) {
+  html:not(.light-theme, .dark-theme) {
+    color-scheme: dark;
+  }
+}

package/scss/_theme-dark-vars.scss

@@ -0,0 +1,56 @@
+// ─── Dark Theme Variables (shared mixin to avoid duplication) ────────────────
+// NOTE: this mixin is currently never @include-d — it is a leftover. Kept in sync with
+// _theme-dark.scss anyway so it cannot resurrect the brand orange if someone wires it up.
+@mixin dark-theme-vars {
+  --primary-light: color-mix(in srgb, var(--accent) 18%, transparent);
+  --surface-ground: #0e0e10;
+  --surface-section: rgb(28 28 30 / 85%);
+  --surface-card: rgb(28 28 30 / 70%);
+  --surface-border: rgb(255 255 255 / 10%);
+  --surface-hover: rgb(255 255 255 / 8%);
+  --text-color: #f2f2f7;
+  --text-color-secondary: rgb(242 242 247 / 65%);
+  --glass-bg: rgb(25 25 28 / 72%);
+  --glass-bg-elevated: rgb(38 38 42 / 82%);
+
+  // Ink for text ON `--glass-bg-elevated` — see `_theme-light.scss` for why this is its own pair.
+  --glass-ink-elevated: rgb(242 242 247 / 96%);
+  --glass-ink-elevated-secondary: rgb(242 242 247 / 65%);
+  --glass-border: rgb(255 255 255 / 12%);
+  --glass-shadow: 0 8px 40px rgb(0 0 0 / 35%);
+  --glass-inner-glow: inset 0 1px 0 rgb(255 255 255 / 8%);
+  --window-bg: rgb(22 22 24 / 55%);
+  --window-radius: 46px;
+  --window-shadow: 0 24px 80px rgb(0 0 0 / 40%);
+  --window-border: rgb(255 255 255 / 12%);
+  --titlebar-bg: transparent;
+  --dock-bg: rgb(20 20 20 / 24%);
+  --dock-border: 1px solid rgb(255 255 255 / 8%);
+  --dock-blur: 40px;
+  --dock-shadow: 0 8px 32px rgb(0 0 0 / 60%),
+    inset 0 1px 0 rgb(255 255 255 / 5%);
+  --menubar-bg: rgb(14 14 16 / 60%);
+  --menubar-border: rgb(255 255 255 / 6%);
+  --menubar-text: rgb(242 242 247 / 100%);
+  --sidebar-bg: rgb(20 20 22 / 60%);
+  --sidebar-border: rgb(255 255 255 / 8%);
+  --focus-ring: color-mix(in srgb, var(--accent) 60%, transparent);
+
+  // Opaque Business App surfaces (mirror light-theme semantic set for embeds).
+  --label-primary: var(--text-color);
+  --label-secondary: var(--text-color-secondary);
+  --label-tertiary: rgb(242 242 247 / 42%);
+  --separator-primary: rgb(255 255 255 / 14%);
+  --separator: var(--separator-primary);
+  --fill-secondary: rgb(255 255 255 / 10%);
+  --fill-tertiary: rgb(255 255 255 / 6%);
+  --material-glass: rgb(28 28 30 / 92%);
+  --fly-color-surface: rgb(28 28 30 / 95%);
+  --fly-color-surface-alt: rgb(38 38 42 / 90%);
+  --fly-color-border: rgb(255 255 255 / 12%);
+  --fly-color-text-muted: var(--text-color-secondary);
+  --fly-color-primary: var(--primary-color);
+  --fly-color-primary-hover: var(--primary-hover);
+  --fly-color-danger: var(--system-red);
+  --fly-shadow-md: 0 4px 16px rgb(0 0 0 / 35%);
+}

package/scss/_theme-dark.scss

@@ -0,0 +1,204 @@
+// ─── Dark theme (`html.dark-theme`, persisted `dark`) ────────────────────────
+// Shell Appearance label "Dark" / i18n `settings.theme.dark`.
+// VisionOS-style translucent dark glass: semi-transparent surfaces + backdrop blur.
+html.dark-theme {
+  /* Native selects / scrollbars follow OS form appearance; keep in sync with light-on-glass labels. */
+  color-scheme: dark;
+
+  --primary-light: color-mix(in srgb, var(--accent) 20%, transparent);
+
+  // ── FlyOS platform accent ────────────────────────────────────────────────
+  // Platform-owned accent palette (violet). Theme-agnostic — same values as
+  // the light theme. App-specific token remaps live in each External App's
+  // own remote stylesheet (e.g. Circles' circles-shell-overrides.scss), NOT
+  // here.
+  // NOTE: --focus-ring is also platform-owned; its authoritative value is the
+  // orange declaration near the end of this block (a later declaration in the
+  // same block always wins, so a second definition here would be dead code).
+  --purple:      #9333EA;
+
+  // ── THE accent knob ────────────────────────────────────────────────────────
+  // The one value that defines the platform's accent. Everything else derives from it
+  // (--primary-color, --accent-soft, --focus-ring, the fly-context-menu gradient, …), so a tenant
+  // or user override is a single write: FlyThemeService.applyAccent('#0aa') re-skins the platform.
+  // Never copy this hex elsewhere — a copy silently stops tracking the override.
+  --accent:      #9333EA;
+
+  // Alias of --accent, NOT a second brand colour. It was referenced ~163 times across the DS
+  // and shell and defined nowhere, so every `var(--primary-color)` silently shipped
+  // its orange fallback — that fallback WAS the platform's accent in practice. Defining it
+  // here turns all of those purple at once. An app may still scope its own (dashboard-app
+  // pins blue); a local override wins inside its subtree, as before.
+  --primary-color: var(--accent);
+
+  // DERIVED, never a copy. A hardcoded rgba(147,51,234,…) here would not follow a runtime
+  // accent override (see FlyThemeService.applyAccent) — you would get the new accent with
+  // the old tint beside it. Every accent-derived value must color-mix off --accent.
+  --accent-soft: color-mix(in srgb, var(--accent) 18%, transparent);
+
+  // Scrim — deeper veil for drawers / dialogs over translucent glass
+  --scrim: rgb(0 0 0 / 50%);
+
+  // Semantic feedback — bright fg on translucent bg
+  --danger:      #ff6b6b;
+  --danger-bg:   rgb(255 59 48 / 20%);
+  --danger-line: rgb(255 59 48 / 40%);
+  --warning:     #FEBC2E;
+  --warning-bg:  rgb(254 188 46 / 18%);
+  --warning-fg:  rgb(255 255 255 / 96%);
+
+  // ── Material glass primitives ───────────────────────────────────────────────
+  --material-glass: rgb(28 28 31 / 65%);
+  --material-glass-blur: 40px;
+  --material-glass-stroke: rgb(255 255 255 / 16%);
+  --material-glass-specular: inset 0 1px 0 rgb(255 255 255 / 10%),
+                              inset 0 -1px 0 rgb(255 255 255 / 5%);
+
+  // ── Surfaces ────────────────────────────────────────────────────────────────
+  --app-content-plate: transparent;
+  --surface-ground: #0e0e10;
+  --surface-section: rgb(22 22 26 / 78%);
+  --surface-card: rgb(28 28 32 / 55%);
+
+  // Opaque surface for floating overlays that sit ABOVE content and must stay
+  // fully legible — popovers, menus, tooltips. Unlike the translucent glass
+  // --surface-card (which reads whatever is behind it), this is solid.
+  --surface-overlay: #1f1f24;
+  --surface-border: rgb(255 255 255 / 14%);
+  --surface-hover: rgb(255 255 255 / 8%);
+
+  // Selected/active row tint — one step stronger than hover. Composited over an opaque panel, so a
+  // translucent tint is safe (unlike the glass surfaces above it needs no reduced-transparency pair).
+  --surface-active: rgb(255 255 255 / 14%);
+
+  // ── Labels & text ───────────────────────────────────────────────────────────
+
+  /* `:root` / `html.light-theme` set dark `--label-*`; dark shell must force light-on-dark. */
+  // Steps 96 / 72 / 48, mirroring the light theme's 92 / 72 / 55. Secondary and tertiary were
+  // 65%/42%, which missed AA on the plate once a BRIGHT wallpaper (`alpine-lake`) tinted it
+  // through the glass — the dark theme's mirror image of the light-theme bug, just milder.
+  // Raised here rather than by thickening `--glass-bg` further, to keep the glass translucent.
+  --label-primary: rgb(255 255 255 / 96%);
+  --label-secondary: rgb(255 255 255 / 72%);
+  --label-tertiary: rgb(255 255 255 / 50%);
+  --separator-primary: rgb(255 255 255 / 14%);
+  --separator: var(--separator-primary);
+  --fill-secondary: rgb(255 255 255 / 10%);
+  --fill-tertiary: rgb(255 255 255 / 6%);
+  --text-color: var(--label-primary);
+  --text-color-secondary: var(--label-secondary);
+
+  // ── Fly alias tokens ────────────────────────────────────────────────────────
+  --fly-color-surface: #1c1c1f;
+  --fly-color-surface-alt: #242428;
+  --fly-color-border: rgb(255 255 255 / 14%);
+  --fly-color-text-muted: var(--text-color-secondary);
+  --fly-color-primary: var(--primary-color);
+  --fly-color-primary-hover: var(--primary-hover);
+  --fly-color-danger: var(--system-red);
+  --fly-shadow-md: 0 4px 16px rgb(0 0 0 / 42%);
+
+  // ── Glass system ────────────────────────────────────────────────────────────
+  --glass-bg: rgb(22 22 26 / 72%);
+  --glass-bg-elevated: rgb(30 30 36 / 82%);
+
+  // Tooltip surface — OPAQUE, and not a glass token. See the light theme for the full reasoning
+  // (a body-parented overlay can appear over any backdrop, so it cannot inherit a translucent,
+  // wallpaper-adaptive surface). Lifted slightly here so the plate still separates from a dark
+  // page, while keeping the same white ink and therefore the same contrast guarantee.
+  --tooltip-bg: #2c313c;
+  --tooltip-ink: #fff;
+  --tooltip-border: rgb(255 255 255 / 16%);
+
+  // Ink for text ON `--glass-bg-elevated` — see the light theme for why this is its own pair.
+  --glass-ink-elevated: rgb(255 255 255 / 96%);
+  --glass-ink-elevated-secondary: rgb(255 255 255 / 65%);
+  --glass-blur: 40px;
+  --glass-border: var(--material-glass-stroke);
+  --glass-shadow: 0 16px 60px rgb(0 0 0 / 50%);
+  --glass-inner-glow: var(--material-glass-specular);
+
+  // ── Layout metrics (size, not color — same as light) ────────────────────────
+  --card-radius: 16px;
+  --card-padding: 20px;
+  --card-gap: 14px;
+
+  // ── Apps launcher card tokens — dark glass variant ──────────────────────────
+  --launcher-card-bg: rgb(28 28 32 / 45%);
+  --launcher-card-border: rgb(255 255 255 / 12%);
+  --launcher-card-blur: 50px;
+  --launcher-card-radius: 16px;
+  --launcher-card-icon-bg: rgb(255 255 255 / 8%);
+  --launcher-card-icon-border: rgb(255 255 255 / 14%);
+  --launcher-card-icon-blur: 4px;
+  --launcher-card-title: rgb(255 255 255 / 92%);
+  --launcher-card-desc: rgb(255 255 255 / 58%);
+
+  // ── Window chrome ───────────────────────────────────────────────────────────
+  // 42% was too thin to be a dependable substrate: over the brightest shipped wallpapers
+  // (`alpine-lake`, `cherry-blossom`) the plate stayed light enough that white body text fell
+  // to ~2.9:1. Raised to match `--glass-bg`, which is the same surface one layer out.
+  --window-bg: rgb(20 20 24 / 70%);
+  --window-radius: 24px;
+  --window-blur: 30px;
+  --window-backdrop-saturate: 160%;
+  --window-shadow: 0 36px 120px rgb(0 0 0 / 52%);
+  --window-border: var(--material-glass-stroke);
+  --window-specular: inset 0 1px 0 rgb(255 255 255 / 12%),
+                     inset 0 -1px 0 rgb(255 255 255 / 6%);
+  --window-content-scrim: transparent;
+
+  // ── Titlebar ────────────────────────────────────────────────────────────────
+  --titlebar-bg: transparent;
+  --titlebar-height: 44px;
+  --titlebar-padding: 0 14px;
+
+  // ── Dock ────────────────────────────────────────────────────────────────────
+  --dock-bg: rgb(18 18 22 / 60%);
+  --dock-border: var(--material-glass-stroke);
+  --dock-blur: 50px;
+
+  // ── Menubar ─────────────────────────────────────────────────────────────────
+  --menubar-bg: rgb(14 14 18 / 80%);
+  --menubar-border: var(--material-glass-stroke);
+  --menubar-text: var(--label-primary);
+  --menubar-blur: 40px;
+  --menubar-radius: 24px;
+
+  // ── Sidebar ─────────────────────────────────────────────────────────────────
+  --sidebar-bg: rgb(18 18 22 / 72%);
+  --sidebar-border: var(--material-glass-stroke);
+  --sidebar-width: 60px;
+  --sidebar-icon-size: 36px;
+  --sidebar-radius: 28px;
+  --focus-ring: color-mix(in srgb, var(--accent) 60%, transparent);
+
+  // ── Button selected state — white-tint pill on dark surface ─────────────────
+  --btn-selected-bg: rgb(255 255 255 / 15%);
+  --btn-selected-text: #fff;
+}
+
+// ── Reduced-transparency fallback — restore fully opaque / zero-blur values ──
+@media (prefers-reduced-transparency: reduce) {
+  html.dark-theme {
+    --material-glass: #1c1c1f;
+    --material-glass-blur: 0px;
+    --app-content-plate: #121214;
+    --surface-section: #161618;
+    --surface-card: #1c1c1f;
+    --surface-overlay: #1c1c1f;
+    --glass-bg: #161618;
+    --glass-bg-elevated: #1e1e22;
+    --glass-blur: 0px;
+    --window-bg: #141416;
+    --window-blur: 0px;
+    --window-backdrop-saturate: 100%;
+    --dock-bg: #121214;
+    --dock-blur: 0px;
+    --menubar-bg: #0e0e10;
+    --menubar-blur: 0px;
+    --sidebar-bg: #121214;
+    --launcher-card-bg: #1c1c1f;
+    --launcher-card-blur: 0px;
+  }
+}