@flyos/design-system 1.8.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flyos/design-system",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "description": "FlyOS design system — shared components, directives, pipes, services, and models for Business App developers.",
   "keywords": [
     "flyos",

package/scss/_app-surface-tokens.scss

@@ -23,11 +23,11 @@
 // ADDITIVE ONLY. `tools/ds-compat` classifies re-valuing an existing theme
 // token as MAJOR (it forks the Native Federation shared singleton for every
 // remote), so nothing here may redefine a token another DS partial owns.
-//
+
 // Three tokens are deliberately ABSENT — they are the consuming app's BRAND and
 // every app already sets them in its own theme file:
 // --accent --accent-soft --focus-ring
-//
+
 // The other nine platform tokens (--danger* --warning* --purple --scrim
 // --glass-blur) USED to be absent too, on the assumption that the platform layer
 // supplies them. That assumption only holds when an app runs FEDERATED, where
@@ -36,7 +36,7 @@
 // commented out in both Circles and Thoughts — so `var(--danger)` resolved to
 // nothing and error text rendered colourless. Confirmed in a live browser, not
 // inferred: 9 of the 12 computed to the empty string on Thoughts standalone.
-//
+
 // They are now mirrored below at the SAME values `_theme-light/dark.scss` uses.
 // Mirroring (rather than picking new values) is what makes this safe under the
 // cascade: this file's `:root, html.light-theme` selector can tie with the
@@ -161,7 +161,7 @@ html.light-theme {
   // Label for a fill of `--ink` itself (the primary button). Distinct from
   // `--ink-inverse`, which is a FIXED near-white for coloured/gradient fills and
   // therefore wrong here: `--ink` flips per theme, so its label must flip too.
-  //
+
   // CONTRACT — anything that redefines `--ink` MUST redefine `--on-ink`.
   // It must also be OPAQUE. The shell-embed glass remaps in Circles and Thoughts
   // set `--ink` to white and every surface token to a translucent veil; a
@@ -206,14 +206,22 @@ html.light-theme {
   --on-accent-soft: var(--ink);
 
   //  2. --accent-fill is a SOLID plate we own outright, so its ink is knowable
-  //     regardless of backdrop — always white. Badges/chips use this pair, so
-  //     their contrast cannot be broken by a host token override.
+  //     regardless of backdrop — knowable FROM THE PLATE, not "always white".
+  //     Badges/chips use this pair, so their contrast cannot be broken by a
+  //     host token override.
   --accent-fill: var(--accent);
 
-  // Aliased, not a second copy of the same white: "ink on a solid accent plate"
-  // and "ink on a dark/gradient fill" are the same requirement, so they must
-  // move together if the inverse ink is ever re-tuned.
-  --on-accent-fill: var(--ink-inverse);
+  // FALLBACK RUNG ONLY. The accent-aware derivation at the foot of this file
+  // overrides this wherever relative colour syntax parses; this is what an
+  // older engine gets, and Nova's theme-invariant `--on-accent` (#fff) is the
+  // right answer for the platform violet in both themes.
+
+  // It is deliberately NOT an alias of `--ink-inverse` any more. Two tokens that
+  // happen to agree today are not the same requirement: "ink on a dark/gradient
+  // fill" is a constant, "ink on the accent plate" is a function of the accent.
+  // Aliasing them made the second one's contrast depend on a token that is not
+  // the plate. See the foot of the file for what it depends on now.
+  --on-accent-fill: var(--on-accent);
 
   // ── Interaction state layers ─────────────────────────────────────────────
   // Translucent veils layered OVER a surface for hover/press/selected instead
@@ -364,6 +372,7 @@ html.dark-theme {
   --ink-3: oklch(62% 0.005 250deg);
   --ink-4: oklch(45% 0.005 250deg);
   --ink-hover: oklch(85% 0.005 250deg);
+
   // Flips with --ink above: the primary button is a near-white pill here, so its
   // label goes near-black. Aliased to --bg (the darkest opaque surface in this
   // theme) rather than repeating its literal — see the contract on the :root decl.
@@ -425,17 +434,17 @@ html.dark-theme {
 // and each reference carries a hardcoded literal fallback, e.g.
 // `var(--label-primary, #1d1d1f)` or `var(--surface-card, #fff)`. 211 such
 // fallbacks exist across the library.
-//
+
 // Those literals are theme-BLIND: a single constant picked by whoever wrote the
 // component. Federated that never shows, because the desktop shell defines the
 // whole chrome family. Standalone, no one does — so a business app got whatever
 // constant each component happened to hardcode, in BOTH light and dark.
-//
+
 // Aliasing the chrome names onto the app-surface family fixes all 211 sites at
 // once, without touching a single component: the var() resolves through the
 // token and never reaches its literal. The targets are theme-aware, so these
 // follow light/dark automatically.
-//
+
 // SELECTOR IS LOAD-BEARING: this block is `:root` ALONE — deliberately not
 // `:root, html.light-theme` like the blocks above. The shell declares every one
 // of these under `html.light-theme` / `html.dark-theme` (specificity 0,1,1),
@@ -465,3 +474,108 @@ html.dark-theme {
   --surface-hover: var(--bg-hover);
   --surface-active: var(--state-selected);
 }
+
+// ── Plate ink, derived from the plate (UX v2, S7.1a) ─────────────────────────
+// `--on-accent-fill` labels a SOLID `--accent-fill` plate: `fly-detail-shell`'s
+// active tab, `badge()`'s default, `fly-pagination`'s current-page pill.
+
+// THE FAILURE IS THE EXTERNAL-APP ACCENT, NOT THE EMBED. A fixed near-white is
+// right for the platform violet (5.25:1) and for the 2.0 `--accent-hi`
+// (8.33:1), and catastrophic for an External App that remaps `--accent` to a
+// light brand colour: white on a pale gold #F5C542 measures 1.58:1, on a cyan
+// #22D3EE 1.76:1. Three tokens are deliberately absent from this file precisely
+// because the accent is the consuming app's to choose (see the header), so this
+// is not a hypothetical — it is what the seam is for. The label has to follow
+// the plate's LUMINANCE, which means the plate is what it is computed from.
+
+// WHAT S1.11 RECORDED HERE WAS WRONG, and the correction is the reason this is
+// a derivation rather than the one-line repoint that note proposed. The claim
+// was that `app-surface-on-glass` pinning `--ink-inverse` to a dark literal
+// dragged `--on-accent-fill` (then an alias of it) down to ~2.5:1 on #9333EA.
+// It never did. A custom property is substituted at the element that DECLARES
+// it: `--on-accent-fill: var(--ink-inverse)` resolves at `:root`, and the
+// resolved value is what inherits. Every shipped `app-surface-on-glass` call
+// site is a component host far below `:root`, so it re-values `--ink-inverse`
+// for its own subtree and cannot reach an `--on-accent-fill` that was computed
+// above it. Measured in Chromium against the real compiled mixin: inside the
+// mixin `--ink-inverse` is `oklch(18% 0.005 250deg)` while `--on-accent-fill`
+// is still `oklch(99% 0 0deg)`, rendering 5.25:1 — identical to outside it.
+// The same rule is why there is no generic `--on-plate` token; see below.
+
+// WHY A LIVE `var()` CHAIN AND NOT A BUILD-TIME COMPUTATION. Sass cannot see
+// the input. `--accent` is a runtime knob: `FlyThemeService.applyAccent` writes
+// it as an INLINE style on `<html>` from tenant/user branding, and
+// `isAccentColor` admits anything `CSS.supports('color', …)` does. Any value
+// resolved at compile time is answering a question about a colour that does not
+// exist yet. Same reason `--shadow-accent` is a `color-mix` and not a hex.
+
+// MECHANISMS REJECTED.
+//  · `contrast-color(var(--accent-fill))` is CSS Color 5 and is literally this
+//    feature, but it is not yet carried widely enough to be the only rung — and
+//    it splits black/white on the same WCAG luminance the expression below
+//    computes, so it would buy a dependency rather than an answer.
+//  · `light-dark()` pairs on the THEME. An accent's lightness is independent of
+//    the theme (an app may set a pale accent in dark mode), so it answers a
+//    different question and fails on exactly the case that motivates this.
+//  · `color-mix(… var(--accent) N%, white)` scales lightness monotonically; it
+//    cannot invert polarity, so it cannot cross the light/dark accent boundary.
+//  · "External Apps override the token" moves the defect into every integrator,
+//    silently — nothing can gate an app that forgets. The token stays
+//    overridable as an escape hatch; it is not the contract.
+
+// THE EXPRESSION. Relative colour syntax in `srgb-linear` exposes `r`/`g`/`b`
+// as exactly the linearised channels WCAG's relative-luminance formula takes,
+// so `0.2126r + 0.7152g + 0.0722b` IS that luminance — no approximation. An
+// oklch-`l` split is the tempting one-channel version and it is not safe: `l`
+// and WCAG luminance disagree by up to ~0.04 on saturated hues, which near the
+// boundary picks the wrong pole and ships a ~3.7:1 label. `(0.1791 - Y) *
+// infinity` clamped to 0..1 is a step function: 1 (white) below the threshold,
+// 0 (black) above. 0.1791 is where white and black contrast a background
+// EQUALLY, so the worst case over the entire sRGB cube is 4.58:1 — the AA floor
+// here is arithmetic, not a review. The explicit `/ 100%` is load-bearing:
+// relative colour syntax inherits the ORIGIN's alpha when the slot is omitted,
+// and this file's header requires a counter-ink to be OPAQUE or it composites
+// into its own fill. A tenant accent may legitimately carry one — `isAccentColor`
+// admits any value `CSS.supports('color', …)` accepts.
+
+// TWO RUNGS. Relative colour syntax is Baseline since Firefox 128 (2024-07);
+// anything older keeps the `--on-accent` white declared above, i.e. today's
+// platform-correct behaviour. `@supports` is what makes that a fallback at all:
+// a custom property accepts almost any token sequence at PARSE time, so the
+// usual declare-it-twice ladder does not work here — the later declaration
+// always wins and the failure surfaces at the consumer as an unset `color`.
+// The `infinity` keyword needs no rung of its own; every engine with relative
+// colour syntax predates its own support for it.
+
+// THERE IS NO GENERIC `--on-plate` TOKEN, and the substitution rule above is
+// why. A plate that is not the accent — `-board`'s presence chips carry a
+// per-user colour from `presenceColorFor`, bound inline per element — cannot be
+// served by a `:root` token, because a `:root` declaration substitutes `:root`'s
+// input, not the chip's. Tried and measured: with an `--on-plate` token declared
+// here and its input set on the chip, every chip resolved to the `:root`
+// fallback and nothing changed. A plate the DS cannot know has to be derived in the
+// CONSUMING declaration, on the element that paints it, which is what
+// `canvas-diagram` / `canvas-fishbone` now do. `$_plate-ink` is the one
+// statement of the formula; `plate-ink.spec.ts` holds those copies to it, and
+// evaluates this one at both accent poles rather than pattern-matching it.
+
+// Both theme classes are listed rather than leaning on `:root` alone: a future
+// redeclaration of `--on-accent-fill` inside `html.dark-theme` (0,1,1) would
+// otherwise silently outrank a bare `:root` (0,1,0) override.
+
+// A Sass-private string, interpolated once per channel: all three take the SAME
+// switch, and written inline Sass would try to evaluate `0.2126 * r` as
+// arithmetic and fail. So this is both the escape hatch and the single place
+// the formula exists — it cannot drift between the channels or the tokens.
+$_plate-ink: 'clamp(0, (0.1791 - (0.2126 * r + 0.7152 * g + 0.0722 * b)) * infinity, 1)';
+
+// The probe colour is `rgb(0 0 0)`, not a hex, so the identical prelude can be
+// copied verbatim into `design-system-board` — whose own gate bans bare colour
+// literals anywhere in a component stylesheet, prelude and comments included.
+@supports (color: color(from rgb(0 0 0) srgb-linear r g b)) {
+  :root,
+  html.light-theme,
+  html.dark-theme {
+    --on-accent-fill: color(from var(--accent-fill) srgb-linear #{$_plate-ink} #{$_plate-ink} #{$_plate-ink} / 100%);
+  }
+}

package/scss/_ink-baseline.scss

@@ -1,5 +1,5 @@
 // ─── 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
@@ -7,18 +7,18 @@
 // `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 vibrancy 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.

package/scss/_nova-glass.scss

@@ -134,12 +134,20 @@
     // `.workflow/plans/ux-refresh/notes/S1-review-fixes-surfaces.md`.
     @return $glow, $sheen, linear-gradient(180deg, var(--mat-menu-a), var(--mat-menu-b));
   } @else if $surface == agent {
-    // The agent aside keeps its own lighter fill (skill §2 ⚠). No token exists
-    // for this pair; it is a ratified literal, allow-listed in the spec.
-    @return $glow, $sheen, linear-gradient(rgb(56 54 60 / 52%), rgb(56 54 60 / 65%));
+    // The agent aside's own fill — the panel hue on a slightly wider alpha ramp,
+    // top-to-bottom. Same two-stop shape as `menu`, for the same reason: the pair
+    // IS a gradient.
+
+    // This used to be the literal `rgb(56 54 60 / 52%) → 65%`, described as "a
+    // ratified literal, allow-listed in the spec". That colour is byte-identical to
+    // the DARK `--mat-panel`, so the aside painted the dark panel in BOTH themes and
+    // was the one surface here that could not flip — while `panel` and `menu` right
+    // above it both resolved through theme-aware tokens. The dark values are carried
+    // over unchanged, so this is a light-theme fix with no dark-theme delta.
+    @return $glow, $sheen, linear-gradient(180deg, var(--mat-agent-a), var(--mat-agent-b));
   }
 
-  @error 'nova-glass: unknown surface `#{$surface}`. Declare one of `chrome` (ratified --glass2-bg fill; the canon default, but unreadable under a light-theme FLOATING menu — see the note on the branch), `menu` (--mat-menu-a/-b, the design\'s menu material, for menus/listboxes/action menus), `panel` (--mat-panel fill, for a surface inside the content panel), `agent` (the agent aside\'s lighter fill).';
+  @error 'nova-glass: unknown surface `#{$surface}`. Declare one of `chrome` (ratified --glass2-bg fill; the canon default, but unreadable under a light-theme FLOATING menu — see the note on the branch), `menu` (--mat-menu-a/-b, the design\'s menu material, for menus/listboxes/action menus), `panel` (--mat-panel fill, for a surface inside the content panel), `agent` (--mat-agent-a/-b, the agent aside\'s own fill).';
 }
 
 // ── The degradation ladder (skill §4 — non-negotiable) ───────────────────────
@@ -291,12 +299,30 @@
   @include _degrade;
 }
 
-// ── Light "vibrancy" material — OPT-IN, shell chrome only ────────────────
-// The light-theme refractive layer (skill §4): a 1px gradient rim ring
-// (`::before`, mask-composite exclude) and a drifting specular sheen (`::after`,
-// `glassSheen` 22s, opacity .5) over a white-gradient fill.
-// This is NOT the default glass, and it must be hard to reach by accident. Two
-// locks, both mechanical:
+// ── Light "vibrancy" material — RETIRED IN PLACE, no production callers ──────
+// DO NOT ADOPT THIS. S6.-1 reversed the ruling that motivated it: the light
+// theme is conventional dark-ink-on-pale-plate, and the white-ink-on-smoke
+// vibrancy model is gone. `window/_nova-vibrancy.scss` — which this docblock
+// used to name as the live precedent for how to include it — WAS DELETED, along
+// with its `styles.scss` include. The only remaining callers anywhere are the
+// design-lab `glass-recipes-panel` exhibit and this file's own spec.
+// ---
+// It is kept rather than deleted at 2.0.0 because removing it is not the
+// one-line edit it looks like, and none of what it costs is worth buying here:
+//   · `glassSheen` is a RATIFIED motion-canon keyframe (`nova-motion.spec.ts`)
+//     with no other consumer, so deleting the material either strands a canon
+//     animation or drags a second ratified removal along with it.
+//   · The design lab's reduced-motion simulation uses this material as its only
+//     vehicle — the sheen is the one thing on any recipe that reduced-motion has
+//     to switch off — so it would need re-vehicling, not just deleting.
+//   · ds-compat does NOT extract Sass mixins (it covers TS exports, custom
+//     properties, `@layer` names, peer floors and, since S6.1c, CSS classes), so
+//     removing a published mixin is a SILENT break with no gate — the same blind
+//     spot S6.1c closed for classes, still open for this surface.
+// Leaving it costs nothing behavioural: it is unreachable by accident (below),
+// and no shipped stylesheet includes it.
+// ---
+// It must stay hard to reach by accident. Two locks, both mechanical:
 //   · `$surface` has NO DEFAULT and is checked against a closed six-name list of
 //     REAL shell surfaces. `@include glass.material()` is a compile error, and
 //     there is no honest value for a feature-app component to pass.
@@ -306,9 +332,7 @@
 //     Including this from a component stylesheet is a review-blocker: under
 //     emulated encapsulation `html.light-theme &` is dead (skill §9 rule 1), so
 //     the material would apply in DARK theme too and paint white gradients over
-//     dark chrome. The shell already sets this precedent — `window/
-//     _nova-vibrancy.scss` is included once from `styles.scss` under
-//     `html.light-theme`, never from a component.
+//     dark chrome.
 // The variant follows from the surface; a caller cannot mismatch them. The four
 // `regular`/`chrome` names are the design's four `[data-material]` surfaces; the
 // two `thin` names are the light thin controls §4 lists alongside them.

package/scss/_nova-tokens.scss

@@ -61,6 +61,32 @@ html.light-theme {
   // `--sys-red-txt` exists because `--sys-red` fails AA as dark-theme text
   // (4.16:1). No `-txt` variant exists yet for blue/orange/teal; those fixes
   // land centrally at S7.1, never improvised per component.
+  // ---
+  // S6.1w re-measured the family after making dark's chrome plate adaptive, to
+  // decide whether BLUE needed a `-txt` variant. It does not, for two separate
+  // reasons — the second is the load-bearing one.
+  // ---
+  // 1. Blue is never TEXT. Its only path to the DOM is `nova-priority-tone
+  //    ('normal')` -> `.status-dot--normal`, a filled circle painted with
+  //    `background: currentcolor` — a non-text graphical object (WCAG 1.4.11,
+  //    3:1), not body copy. The hues that ARE painted as text (red, green,
+  //    orange, and `--sys-red-txt`) live on the alpha-1 dark `--mat-menu-*`
+  //    (action-menu, magic-actions) and the opaque `--surface-overlay`, where
+  //    nothing varies with the wallpaper: red 4.80 / 4.82, green 8.96 / 8.99.
+  // 2. A `-txt` variant is not the mechanism anyway. Where these colours DO
+  //    measure badly is on TRANSLUCENT plates over a bright wallpaper —
+  //    `--glass-bg-elevated` at 82% gives red 2.83, blue 2.64, purple 3.40 over
+  //    the brightest backdrop — and that is a PLATE defect of exactly the kind
+  //    S6.1w fixed for the chrome, not a palette one. The proof: the EXISTING
+  //    `--sys-red-txt` measures 3.42 on that same plate and fails too. Clearing
+  //    4.5 there needs an ink of luminance >= 0.44 — near-pastel, no longer
+  //    reading as the system colour, and washed out over the 22-of-26 dark
+  //    wallpapers where the plain token already sits at 4.74–5.07.
+  // ---
+  // So the real fix is to bring `--glass-bg-elevated` (`_theme-dark.scss`, NOT
+  // this file) into the adaptive set. Minting `--sys-blue-txt` would spend a
+  // token to improve one number while every other hue on that plate still
+  // failed — the "improvised per component" move this comment already forbids.
   --sys-red: #C2263A;
   --sys-red-txt: #B32436;
   --sys-orange: #9A5A0F;
@@ -158,6 +184,25 @@ html.light-theme {
   --mat-menu-a: rgb(238 242 247 / calc(var(--mat-menu-a-alpha) * 100%));
   --mat-menu-b-alpha: 0.64;
   --mat-menu-b: rgb(222 229 238 / calc(var(--mat-menu-b-alpha) * 100%));
+
+  // The agent aside — the PANEL hue on its own alpha ramp, top-to-bottom. It was a
+  // hardcoded literal inside `_nova-glass.scss`'s `agent` branch, and that literal
+  // was `rgb(56 54 60)` — byte-identical to the DARK `--mat-panel`, so the aside
+  // painted the dark panel colour in both themes and could never flip. Every sibling
+  // branch (`panel`, `menu`) already routed through a theme-aware token; this pair is
+  // that same shape, so the aside stops being the one surface outside the system.
+  // 0.52 -> 0.60 (S6.-1 fan-in ruling). The aside is painted straight against the
+  // WALLPAPER, exactly like `--window-bg`, and 22 of the 26 shipped wallpapers are
+  // dark: at 0.52 the top stop composited to 4.06:1 for body ink over the darkest
+  // one — sub-AA, and measured as such by `theme-contrast.spec`. The window plate
+  // solves this with the adaptive `--fly-glass-alpha` knob; this pair is not in that
+  // set, so it takes the static equivalent instead. 0.60 is not arbitrary: it leaves
+  // 40% transmission, the same as the window plate's ratified floor, so the aside
+  // and the window beside it now let the wallpaper through by the same amount.
+  --mat-agent-a-alpha: 0.6;
+  --mat-agent-a: rgb(230 236 243 / calc(var(--mat-agent-a-alpha) * 100%));
+  --mat-agent-b-alpha: 0.65;
+  --mat-agent-b: rgb(230 236 243 / calc(var(--mat-agent-b-alpha) * 100%));
   --mat-tip-a-alpha: 0.8;
   --mat-tip-a: rgb(238 241 245 / calc(var(--mat-tip-a-alpha) * 100%));
   --mat-tip-b-alpha: 0.86;
@@ -274,6 +319,22 @@ html.dark-theme {
   --mat-menu-a: rgb(32 31 37 / calc(var(--mat-menu-a-alpha) * 100%));
   --mat-menu-b-alpha: 1;
   --mat-menu-b: rgb(26 25 30 / calc(var(--mat-menu-b-alpha) * 100%));
+
+  // Re-valued by S6W (agent-panel sweep). The carried-over literal was
+  // rgb(56 54 60) at 0.52→0.65 — warm-hued AND translucent, so over a warm
+  // wallpaper the aside composited into muddy brown while the account-menu
+  // popover beside it stayed crisp on the alpha-1 `--mat-menu-*` pair. These
+  // are now that same menu pair's stops at alpha 1: crisp, wallpaper-immune,
+  // and cool-neutral like every other dark floating surface.
+  // Alternatives weighed (final call is perceptual, at fan-in):
+  //   · alpha→1 on the old hue rgb(56 54 60) — crisp but noticeably lighter
+  //     and warmer than the menu material next to it;
+  //   · ~0.85 alpha on either hue — still lets a warm wallpaper tint the
+  //     plate, i.e. a smaller dose of the same defect.
+  --mat-agent-a-alpha: 1;
+  --mat-agent-a: rgb(32 31 37 / calc(var(--mat-agent-a-alpha) * 100%));
+  --mat-agent-b-alpha: 1;
+  --mat-agent-b: rgb(26 25 30 / calc(var(--mat-agent-b-alpha) * 100%));
   --mat-tip-a-alpha: 0.82;
   --mat-tip-a: rgb(46 44 52 / calc(var(--mat-tip-a-alpha) * 100%));
   --mat-tip-b-alpha: 0.86;

package/scss/_shell-embed-bridge.scss

@@ -1,31 +1,31 @@
 // ─── 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.
@@ -57,7 +57,7 @@
   // 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.
@@ -81,33 +81,40 @@
   --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.
 
-  // KNOWN COLLATERAL, recorded not fixed (S1.11 — the fix is a token re-value, and DS 1.x is
-  // additive-only). `_app-surface-tokens.scss` aliases `--on-accent-fill: var(--ink-inverse)`,
-  // so this pin also re-points the label on a SOLID ACCENT plate from near-white to near-black
-  // wherever the mixin applies. That contradicts the guarantee its header gives — "--accent-fill
-  // is a SOLID plate we own outright, so its ink is knowable regardless of backdrop — always
-  // white … their contrast cannot be broken by a host token override" — and this mixin is such
-  // an override. Live example inside the DS itself: `detail-shell.component.scss` paints
-  // `.ds__tab--active` as `background: var(--accent-fill); color: var(--on-accent-fill)`, which
-  // under the bridge is oklch(18%) ink on `#9333EA`, roughly 2.5:1. Also reached by
-  // `_mixins.scss`'s `badge()` default and `-board`'s canvas-diagram / canvas-fishbone.
-
-  // The 2.0 fix is one line in `_app-surface-tokens.scss` — `--on-accent-fill: var(--on-accent)`,
-  // Nova's theme-invariant `#fff` — which also makes the pair immune to any future host remap of
-  // `--ink-inverse`, rather than immune only to the remaps that exist today.
+  // 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

@@ -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%);
@@ -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;