@flyos/design-system 1.7.0 → 2.0.0

package/scss/_nova-type.scss

@@ -0,0 +1,188 @@
+// ─── Nova type roles (UX v2) ─────────────────────────────────────────────────
+// Stage 1 task S1.10 of the UX-refresh program.
+// Canon: `skills/desktop-design-language.md` §7, which cites
+// `.workflow/plans/ux-refresh/analysis/D1-home-desktop.md` §6 for the exact
+// numbers below. Never re-derive a value from the `UX/**/*.dc.html`
+// prototypes — the prototypes drift, the skill is the contract.
+
+// This partial is `@use`d exactly once, from `_fly-theme.scss` — it emits
+// GLOBAL CSS (custom properties + two utility classes) and defines NO mixins.
+// That is deliberate, not an omission: `_nova-motion.scss` already hit this
+// exact wall (its own header warns "never `@use` it a second time" because a
+// component-level `@use` re-emits its `:root` block and all 16 `@keyframes`
+// into that component's own compiled stylesheet — harmless in content,
+// wasteful in bytes) and `motion-panel.component.ts` had to replicate
+// `nova-stagger`'s math in TypeScript rather than pay that cost. A role here
+// is therefore exposed ONLY as `var(--nova-font-*)` / `var(--nova-tracking-*)`
+// — plain global custom properties, read directly by any component's own
+// `.scss` exactly the way `--w95` or `--font-title1` already are, with no
+// `@use` of this file required or permitted a second time. Full reasoning for
+// choosing tokens over mixins: `.workflow/plans/ux-refresh/notes/
+// S1.10-typography.md` § "Token vs mixin".
+
+// ── The Display/Text split ───────────────────────────────────────────────────
+// The design distinguishes a Display face (headings ≥ ~13.5px bold) from Text
+// (everything else), but D8 (skill §7, ratified) forbids ever shipping a
+// second face for it — no SF fonts, ever. Geist is ONE family for both; the
+// split rides WEIGHT and LETTER-SPACING only, never `font-family`. Proof
+// point: `--nova-font-menu-item` and `--nova-font-section-title` share the
+// exact same 13.5px SIZE and sit on opposite sides of the split (500/normal
+// Text vs 700/-0.01em Display) — that pairing IS the split in action.
+
+// ── Snap vs mint ─────────────────────────────────────────────────────────────
+// Each role is annotated SNAP (aliases an existing `--font-*` ramp step from
+// `_tokens.scss` verbatim, via `var()`, so a future ramp change propagates) or
+// MINT (a new literal — no ramp step is close enough on size, line-height
+// ratio, weight or letter-spacing to reuse without a visible fidelity loss).
+// The full per-role reasoning lives in the handoff note; the short form
+// travels here as a comment next to each declaration so the two can't drift
+// apart silently.
+
+// ── Letter-spacing rides a SEPARATE token, never the `font` shorthand ───────
+// CSS `font:` cannot carry `letter-spacing` — it is not one of the shorthand's
+// component properties (weight/size/line-height/family only). A role that
+// needs tracking therefore gets a companion `--nova-tracking-<role>` token,
+// and EVERY role gets one — even the ones the design leaves untracked
+// (`normal`) — so a caller always writes the same two-line pattern regardless
+// of role, instead of having to remember which roles carry tracking.
+
+:root {
+  // ── Hero / marquee — bespoke, animated, never reused elsewhere ────────────
+  // MINT. 28px sits between --font-title1 (24px) and --font-large-title
+  // (29px); the closer neighbour (large-title) carries a 38/29 ≈ 1.31 line-
+  // height ratio against this role's specified 1.1 — snapping would make a
+  // compact hero headline read visibly looser than the design. Pair with the
+  // `greetShift` keyframe (`_nova-motion.scss`) for the animated gradient
+  // fill; the fill itself is the caller's concern, not baked in here.
+  --nova-font-page-headline: 700 28px/1.1 var(--font-family);
+  --nova-tracking-page-headline: -0.022em;
+
+  // MINT. Size coincides with --font-title1 (24px), but that step's 32/24 ≈
+  // 1.333 line-height ratio is a third looser than this role's 1.15 — the
+  // assistant's hero greeting would visibly loosen on snap.
+  --nova-font-hero-greeting: 700 24px/1.15 var(--font-family);
+  --nova-tracking-hero-greeting: -0.018em;
+
+  // MINT. No ramp step sits at 26px, and none pairs a semibold (600) weight
+  // with a sub-30px size. Colour/text-shadow (the D1 extraction notes
+  // "#fff + text-shadow") are the caller's concern, not part of the type role.
+  --nova-font-hero-card-name: 600 26px/1.14 var(--font-family);
+  --nova-tracking-hero-card-name: -0.01em;
+
+  // ── Chrome / structural headings (Display) ────────────────────────────────
+  // MINT. --font-headline (17px/700) is the nearest ramp step; its 22/17 ≈
+  // 1.294 line-height ratio is far looser than this role's 1.1, and the ramp
+  // carries no letter-spacing vocabulary at all.
+  --nova-font-drawer-title: 700 16px/1.1 var(--font-family);
+  --nova-tracking-drawer-title: -0.016em;
+
+  // MINT. Nothing in the ramp sits near 14.5px at weight 700.
+  --nova-font-dialog-title: 700 14.5px/1.1 var(--font-family);
+  --nova-tracking-dialog-title: -0.014em;
+
+  // MINT. The design gives a 500-600 WEIGHT RANGE at 14px; --font-footnote
+  // (13px/510) and --font-callout (15px/590) are each 1px off in opposite
+  // directions with no clear winner either way. Minted rather than snapped
+  // because this role lives in the always-visible header chrome — a singular,
+  // high-scrutiny use, not a repeated list primitive — so the vocabulary cost
+  // of one more token buys exact fidelity where it is most seen. Picked 600,
+  // the range's upper bound, for legibility over the translucent header
+  // material.
+  --nova-font-header-context: 600 14px/1.3 var(--font-family);
+  --nova-tracking-header-context: normal;
+
+  // MINT. Explicitly tagged Display in the source, with a tracking value the
+  // ramp has no vocabulary for at all. Shares its 13.5px SIZE with
+  // --nova-font-menu-item below on the opposite side of the Display/Text
+  // split — see the file header.
+  --nova-font-section-title: 700 13.5px/1.2 var(--font-family);
+  --nova-tracking-section-title: -0.01em;
+
+  // ── Workhorse text — repeated everywhere, snapped where fidelity allows ───
+  // SNAP → --font-footnote (510 13px/18px). Δsize 0.5px, Δweight 10 (510 vs
+  // 500) — both imperceptible. No Display tag, no tracking in the source:
+  // plain Text-family, unlike section-title above despite the shared 13.5px
+  // size.
+  --nova-font-menu-item: var(--font-footnote);
+  --nova-tracking-menu-item: normal;
+
+  // SNAP → --font-footnote (510 13px/18px, ratio 1.385). Exact size match.
+  // The source spec asks for weight 400, but every other body-ish ramp step
+  // already uses ~510 as a deliberate on-screen optical correction
+  // (--font-body, --font-caption1/2 all do the same) — reusing --font-footnote
+  // keeps body/chat/input text consistent with that platform-wide convention
+  // instead of introducing a lone literal-400 outlier.
+  --nova-font-body: var(--font-footnote);
+  --nova-tracking-body: normal;
+
+  // MINT. Weight 600 is a real, perceptible step up from every ramp option
+  // near this size (nearest is --font-caption1 at 510) — row labels / tile
+  // names are scannable list-and-grid primitives where that weight jump IS
+  // the point of the role, so snapping would flatten the exact distinction
+  // the design is making.
+  --nova-font-row-label: 600 12.5px/1.3 var(--font-family);
+  --nova-tracking-row-label: normal;
+
+  // MINT. Same weight-fidelity argument as row-label, reinforced by the
+  // skill's own field-kit section (§6) independently ratifying this exact
+  // 600/11.5px/`--w6` pairing as a load-bearing forms convention. Colour is
+  // NOT baked into this token — apply `color: var(--w6)` alongside it, the
+  // same as every other ramp-step colour decision.
+  --nova-font-field-label: 600 11.5px/1.2 var(--font-family);
+  --nova-tracking-field-label: normal;
+
+  // SNAP → --font-caption1 (510 12px/16px, ratio 1.333). Δsize 0.5px, Δweight
+  // 10, Δline-height-ratio ~6.6% against the target 1.25 — all within
+  // tolerance for an ancillary role.
+  --nova-font-tooltip: var(--font-caption1);
+  --nova-tracking-tooltip: normal;
+
+  // MINT. The smallest heading-adjacent role, and the ONLY one with a
+  // POSITIVE tracking direction in the whole table (the ramp has no
+  // letter-spacing vocabulary to snap to regardless). Snapped UP to 11px
+  // rather than the source's 10.5px floor: skill §7's de-facto size floor
+  // reserves 10.5px for the caption-tier exception (timestamps, below), not
+  // eyebrows — 11px is the honest reading of "de-facto floor 11px". Tracking
+  // is the midpoint of the source's 0.02-0.04em range. Colour defaults to
+  // `--w42`; the source also names `--w4` as a context-dependent alternate
+  // with no rule for choosing between them, so that choice stays with the
+  // caller rather than being baked in here.
+  --nova-font-eyebrow: 600 11px/1.3 var(--font-family);
+  --nova-tracking-eyebrow: 0.03em;
+
+  // MINT. The one sanctioned exception to the 11px floor (skill §7:
+  // "10.5px caption-only"). Base weight 400; the source's 400-700 range
+  // covers a bold badge-count variant, applied by the caller with a local
+  // `font-weight: 700` override rather than a second minted role, since size,
+  // tracking and family are identical either way.
+  --nova-font-timestamp: 400 10.5px/1.3 var(--font-family);
+  --nova-tracking-timestamp: normal;
+}
+
+// ── Rule A: tabular numerals (skill §7, mechanical) ─────────────────────────
+// "font-variant-numeric: tabular-nums on every count, timestamp and pagination
+// number." `_app-surface-utilities.scss` already ships `.mono` bundling this
+// same property with a switch to the monospace family; `.nova-tabular-nums`
+// is the tabular-nums-ONLY half, for the proportional-font contexts these
+// roles live in (a row count sitting inside --nova-font-row-label, a
+// timestamp inside --nova-font-timestamp) where switching to Geist Mono is
+// not wanted. One class is the one-liner the rule calls for.
+// Reviewer check: grep the diff for a numeric interpolation — a count binding
+// (`{{ …Count }}`), a date/time pipe, a "page N of M" string — with no
+// `nova-tabular-nums` class alongside it in the same template. That gap IS
+// the violation; there is no way to detect it from the SCSS side alone, since
+// the rule is about which ELEMENTS carry the class, not whether the class
+// itself exists (`nova-type.spec.ts` only guards the latter).
+.nova-tabular-nums {
+  font-variant-numeric: tabular-nums;
+}
+
+// ── Rule B: RTL runs keep embedded Latin its own direction (skill §7) ──────
+// "RTL text runs carry unicode-bidi: plaintext so embedded English keeps its
+// own direction." Same one-class mechanism and the same reviewer check: grep
+// the diff for a translated or mixed-script string (a product name, an email
+// address, a file extension embedded in Arabic/Urdu copy) with no
+// `nova-bidi-plaintext` class in the same template.
+.nova-bidi-plaintext {
+  unicode-bidi: plaintext;
+}

package/scss/_shell-embed-bridge.scss

@@ -1,81 +1,120 @@
-// ─── 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);
-}
+// ─── 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.
+  // (`app-surface-nova-bridge.spec.ts` extends that gate to THIS file.)
+
+  // AT THE DS 2.0 FLIP THIS LINE MUST CHANGE — it is the one value in this mixin
+  // that does not follow the shell automatically. The premise above ("`--ink` is
+  // the shell's white label ink in BOTH themes") holds only while light chrome is
+  // the vibrancy smoked plate. Nova's light chrome is genuinely light with
+  // DARK ink (`--chrome-ink: #353537`; design `--ink` light `#000`, folded into
+  // `--label-primary` per D1), so post-flip `--ink` flips per theme here too and
+  // a single dark literal is wrong in light mode — the same white-slab failure,
+  // arriving from the opposite side.
+
+  // The flip value is `var(--check-ink)`: Nova's only counter-ink that flips the
+  // right way (`#fff` light, `#0f1013` dark), which is exactly "the ink on a
+  // plate that carries the theme's own primary ink". Do NOT reach for a `--w*`
+  // step — the ramp flips polarity (`--w95` is 95% black in light, 95% WHITE in
+  // dark), so no step is a counter-ink in both themes; and do NOT reach for
+  // `--on-accent`, which is `#fff` in both and therefore right only in light.
+  --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.
+
+  // THE "KNOWN COLLATERAL" THIS NOTE USED TO RECORD DOES NOT EXIST (corrected at 2.0.0). S1.11
+  // claimed that because `_app-surface-tokens.scss` aliased `--on-accent-fill: var(--ink-inverse)`,
+  // the pin below also dragged the label on a SOLID ACCENT plate to near-black — `.ds__tab--active`
+  // cited at roughly 2.5:1 on `#9333EA`. It never could. A custom property is substituted at the
+  // element that DECLARES it: that alias resolved at `:root`, against `:root`'s `--ink-inverse`,
+  // and it is the RESOLVED value that inherits. Re-valuing `--ink-inverse` for a subtree cannot
+  // reach a property already computed above it.
+
+  // That is a structural fact, not a browser quirk, and it holds for every shipped call site
+  // because all of them are component-level — `.hc-shell`, `.fly-app-surface-on-glass` on a
+  // `<div>`, and the strategies / dashboard / canvas-boards feature hosts. None is `:root` or
+  // `html`. Measured in Chromium inside the real compiled mixin: `--ink-inverse` is
+  // `oklch(18% 0.005 250deg)` there while `--on-accent-fill` is still `oklch(99% 0 0deg)`,
+  // rendering 5.25:1 — identical to outside it. Applying this mixin AT `:root` would break that
+  // reasoning, which is one more reason it belongs on an embedded app's own subtree.
+
+  // The token was still wrong, for an unrelated reason S1.11 half-saw: a FIXED ink on a plate the
+  // consuming app may remap. `--on-accent-fill` is now derived from `--accent-fill`'s own
+  // luminance (see the foot of `_app-surface-tokens.scss`), so it is immune both to a host
+  // re-value of `--ink-inverse` and to an External App choosing a pale accent — white on
+  // `#F5C542` measured 1.58:1 before that change.
+  --ink-inverse: var(--on-ink);
+}

package/scss/_theme-dark.scss

@@ -1,6 +1,6 @@
 // ─── 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.
+// 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;
@@ -64,6 +64,15 @@ html.dark-theme {
   // fully legible — popovers, menus, tooltips. Unlike the translucent glass
   // --surface-card (which reads whatever is behind it), this is solid.
   --surface-overlay: #1f1f24;
+
+  // A surface nested INSIDE another overlay — a listbox in a drawer, an emoji grid
+  // in a popover. `window/_nova-vibrancy.scss` invented this token for the light
+  // vibrancy theme (where stacking two translucent glasses reads as see-through)
+  // but never defined it here, so every consumer painting it had NO background in
+  // dark theme. It must resolve in every theme or the contract "opt in by painting
+  // this instead of `--surface-overlay`" is a trap. Dark's overlays are already
+  // opaque, so this is simply one step lifted, to separate the nested plate.
+  --surface-overlay-strong: #26262c;
   --surface-border: rgb(255 255 255 / 14%);
   --surface-hover: rgb(255 255 255 / 8%);
 
@@ -187,6 +196,7 @@ html.dark-theme {
     --surface-section: #161618;
     --surface-card: #1c1c1f;
     --surface-overlay: #1c1c1f;
+    --surface-overlay-strong: #232327;
     --glass-bg: #161618;
     --glass-bg-elevated: #1e1e22;
     --glass-blur: 0px;

package/scss/_theme-light.scss

@@ -70,17 +70,32 @@ html.light-theme {
   // theme's dark secondary ink disappeared into it.
 
   // They now carry real opacity, in line with the dark theme's long-standing 72%/55%. The
-  // window still reads as glass — 72% white lets the wallpaper tint through and the 50px
-  // backdrop blur still does its work — but text no longer sits on a bare photo.
+  // window still reads as glass — 60% white lets the wallpaper tint through and the backdrop
+  // blur still does its work — but text no longer sits on a bare photo.
   // Contract pinned by `src/app/core/theme/theme-contrast.spec.ts`.
   // `--surface-card` / `--surface-section` are a LIFT on top of the window plate, not a second
   // full substrate — stacking two thick layers is what reads as frosted plastic.
   --surface-section: rgb(255 255 255 / 35%);
   --surface-card: rgb(255 255 255 / 20%);
 
+  // The substrate plate alpha — ONE knob, three consumers (`--window-bg`, `--glass-bg`,
+  // `--dock-bg`). 0.6 is the ratified static plate; `WallpaperGlassService` overrides it at
+  // runtime with the thinnest alpha in [0.6, 0.7] that keeps the WEAKEST substrate body ink
+  // (`--text-color-secondary`, 78%) at AA over the ACTIVE wallpaper. Over bright and mid rooms
+  // that is 0.6 itself; over a starfield-dark room it steps to 0.62 (0.6 measures 4.51:1 there —
+  // above the 4.5 line but with no margin at all, which is why the knob exists). The service and
+  // `theme-contrast.ts` reconstruct the same scan; their specs fail if the two ever disagree.
+  --fly-glass-alpha: 0.6;
+
   // Opaque surface for floating overlays (popovers, menus, tooltips) that must
   // stay fully legible above content — see the dark theme for the rationale.
   --surface-overlay: #fff;
+
+  // Nested-overlay surface — see the dark theme for why this must exist in every
+  // theme. It equals `--surface-overlay` here on purpose: the problem it solves is
+  // two TRANSLUCENT glasses stacking into transparency, and this theme's overlays
+  // are already opaque white, where separation is the border's job, not the fill's.
+  --surface-overlay-strong: #fff;
   --surface-border: rgb(0 0 0 / 6%);
   --surface-hover: rgb(0 0 0 / 4%);
 
@@ -94,11 +109,14 @@ html.light-theme {
   // and for opposite reasons. Both now follow the `--glass-ink-elevated` model below.
   --text-color: rgb(17 24 39 / 92%);
   --text-color-secondary: rgb(17 24 39 / 78%);
-  --glass-bg: rgb(255 255 255 / 60%);
+
+  // Composes the adaptive knob above over a WHITE base — the same two-part shape as the
+  // `--mat-*` materials, so the service adapts a NUMBER and never rewrites a colour string.
+  --glass-bg: rgb(255 255 255 / calc(var(--fly-glass-alpha) * 100%));
   --glass-bg-elevated: rgb(255 255 255 / 88%);
 
   // Tooltip surface. OPAQUE and deliberately NOT a glass token.
-  //
+
   // A tooltip is body-parented and floats over whatever happens to be underneath — a light app
   // surface, a dark board canvas, the wallpaper. The glass family is TRANSLUCENT and, at runtime,
   // wallpaper-adaptive: the shell recomputes `--glass-bg-elevated` from the wallpaper and writes it
@@ -106,7 +124,7 @@ html.light-theme {
   // is in `light-theme`. Composited over a light page that resolves to roughly rgb(143,141,140),
   // and the matching white ink lands at about 2.8:1 — the "tooltips are white on white" report.
   // An overlay that can appear anywhere cannot inherit a surface tuned for one backdrop.
-  //
+
   // Dark plate + white ink in BOTH themes is the classic tooltip treatment (macOS, Material,
   // Bootstrap) and is exactly what this directive's own comment always claimed it fell back to —
   // it just never actually did, because the `var()`s carried no fallback.
@@ -149,8 +167,9 @@ html.light-theme {
   // Window chrome — light frosted glass similar to Figma spec (soft white plate,
   // strong background blur, subtle luminous border).
   // The app window plate. At 6% this was the single biggest cause of the reported failure:
-  // every app's body text was effectively painted on the wallpaper. Raised to match `--glass-bg`.
-  --window-bg: rgb(255 255 255 / 60%);
+  // every app's body text was effectively painted on the wallpaper. Matches `--glass-bg`,
+  // including its adaptive-knob composition.
+  --window-bg: rgb(255 255 255 / calc(var(--fly-glass-alpha) * 100%));
   --window-radius: 24px;
   --window-blur: 24px;
   --window-backdrop-saturate: 175%;
@@ -166,7 +185,8 @@ html.light-theme {
 
   // Backs BOTH the dock and the top Finder bar (`.topbar-glass`), which is why it needs a real
   // substrate: at 15% the bar's labels and icons sat on the wallpaper like everything else.
-  --dock-bg: rgb(255 255 255 / 60%);
+  // Same plate as the window, same adaptive knob.
+  --dock-bg: rgb(255 255 255 / calc(var(--fly-glass-alpha) * 100%));
   --dock-border: rgb(17 24 39 / 12%);
   --dock-blur:50px;
   --menubar-bg: rgb(255 255 255 / 60%);
@@ -181,7 +201,7 @@ html.light-theme {
   --sidebar-radius: 28px;
   --focus-ring: color-mix(in srgb, var(--accent) 50%, transparent);
 
-  // Segmented `.vos-btn.selected` / `.active` (Settings theme row, clock, weather, etc.): dark pill on light UI.
+  // Segmented `.fos-btn.selected` / `.active` (Settings theme row, clock, weather, etc.): dark pill on light UI.
   --btn-selected-bg: #111827;
   --btn-selected-text: #fff;
 
@@ -207,7 +227,7 @@ html.light-theme {
   --material-glass-specular: inset 0 1px 0 rgb(255 255 255 / 60%),
                               inset 0 -1px 0 rgb(17 24 39 / 4%);
 
-  // Aliases used by some Business App SCSS (not part of core visionOS tokens).
+  // Aliases used by some Business App SCSS (not part of core FlyOS tokens).
   --fly-color-surface: #fff;
   --fly-color-surface-alt: #f3f4f6;
   --fly-color-border: #e5e7eb;
@@ -231,6 +251,7 @@ html.light-theme {
     --surface-section: #fff;
     --surface-card: #fff;
     --surface-overlay: #fff;
+    --surface-overlay-strong: #fff;
     --glass-bg: #f7f8fa;
     --glass-bg-elevated: #fff;
     --glass-blur: 0px;

package/scss/_tokens.scss

@@ -1,4 +1,4 @@
-// ─── visionOS System Colors & Design Tokens ─────────────────────────────────
+// ─── FlyOS System Colors & Design Tokens ─────────────────────────────────
 :root {
   --system-red: #FF453A;
   --system-orange: #FF9F0A;
@@ -21,11 +21,19 @@
   --status-info: var(--system-blue);
   --status-pending: var(--system-yellow);
 
-  // ── visionOS Typography ──
-  // Geist is the primary face (self-hosted, see styles/_geist-fonts.scss).
-  // SF Pro / Inter / system fonts remain as fallbacks; the cascade also picks
-  // them up for scripts Geist doesn't cover (ar / ur).
-  --font-family: 'Geist', 'SF Pro Display', 'SF Pro', 'Inter', -apple-system, blinkmacsystemfont, 'Segoe UI', sans-serif;
+  // ── FlyOS Typography ──
+  // Geist is the primary face (self-hosted, see styles/_geist-fonts.scss). Inter and the
+  // system stack are the fallbacks, and the cascade also picks them up for scripts Geist
+  // doesn't cover (ar / ur).
+  // ---
+  // 2.0.0 removed 'SF Pro Display' / 'SF Pro' — D8 (no SF fonts, ever, for licensing). The
+  // repo had been SHIPPING them: 9 self-hosted woff2 faces, preloaded from index.html.
+  // Removing them changes NOTHING for ar/ur, contrary to the comment that used to sit here
+  // and to the one in `_geist-fonts.scss`: measured in the live shell, Arabic and Urdu
+  // render byte-identically with and without SF Pro in the stack (its @font-face rules carry
+  // no unicode-range, and it supplies no Arabic glyphs at all — the apparent width delta was
+  // one SPACE character). Those scripts have always resolved to the system Arabic face.
+  --font-family: 'Geist', 'Inter', -apple-system, blinkmacsystemfont, 'Segoe UI', sans-serif;
   --font-family-mono: 'Geist Mono', ui-monospace, 'SF Mono', menlo, monospace;
   --font-xl-title1: 700 48px/56px var(--font-family);
   --font-xl-title2: 700 38px/46px var(--font-family);
@@ -41,12 +49,12 @@
   --font-caption1: 510 12px/16px var(--font-family);
   --font-caption2: 510 12px/16px var(--font-family);
 
-  // ── visionOS Label Colors ──
+  // ── FlyOS Label Colors ──
   --label-primary: rgb(255 255 255 / 96%);
   --label-secondary: rgb(255 255 255 / 56%);
   --label-tertiary: rgb(255 255 255 / 36%);
 
-  // ── visionOS Materials ──
+  // ── FlyOS Materials ──
   --material-glass: rgb(128 128 128 / 30%);
   --material-glass-blur: 50px;
   --material-glass-stroke: rgb(255 255 255 / 40%);
@@ -70,7 +78,7 @@
   --separator: rgb(255 255 255 / 12%);
   --blur-shadow-small: 0 2px 4px rgb(0 0 0 / 10%);
 
-  // ── visionOS Button Tokens ──
+  // ── FlyOS Button Tokens ──
   --btn-font-weight: 590;
   --btn-symbol-font-weight: 510;
   --btn-radius-capsule: 500px;