@flyos/design-system 3.12.0 → 3.13.0

package/package.json

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

package/scss/_nova-tokens.scss

@@ -226,6 +226,33 @@ html.light-theme {
   --w02: rgb(0 0 0 / 2.2%);
   --w015: rgb(0 0 0 / 1.8%);
 
+  // ── Embedded-app plate ─────────────────────────────────────────────────────
+  // The three surface steps `_shell-embed-bridge.scss` hands to a feature app
+  // running inside a shell window (`--bg-2` / `--bg-hover` / `--bg-3`). They are
+  // a token, not a `--w*` pick, because the ramp is the WRONG family here and
+  // only this theme shows it.
+
+  // A `--w*` step is an ink wash on paper the theme already owns. An embedded
+  // app's paper is a TRANSLUCENT window plate over the user's wallpaper — in
+  // this theme `rgb(255 255 255 / 60%)`, which passes a great deal of the
+  // photograph through. Washing 3% black over that does not make a card: it
+  // makes a marginally darker patch of wallpaper, so the card edge disappears
+  // and every accent on it (icon tiles, chips, cover art) competes with whatever
+  // colour the photo happens to put behind it. Measured on the Help Center
+  // guide grid: `--bg-2` resolved to `rgba(0,0,0,0.03)` and the cards read as
+  // wallpaper. Dark mode never showed it because there a 3% WHITE lift sits on
+  // a near-opaque dark plate and reads immediately.
+
+  // So in this theme a lift moves TOWARD the paper's own colour — white — which
+  // both restores the card edge and gives the wallpaper less say in the app's
+  // palette. The dark block keeps the ramp: see the note there.
+
+  // Ordering is `plate < plate-hover < plate-raised`, mirroring the dark
+  // block's `--w03 < --w05 < --w06`.
+  --embed-plate: rgb(255 255 255 / 55%);
+  --embed-plate-hover: rgb(255 255 255 / 68%);
+  --embed-plate-raised: rgb(255 255 255 / 78%);
+
   // ── Materials ──────────────────────────────────────────────────────────────
   // Each material is a two-part token on purpose: a per-material alpha knob and
   // a colour composed from it. `WallpaperGlassService` already samples the
@@ -423,6 +450,16 @@ html.dark-theme {
   --w02: rgb(255 255 255 / 2%);
   --w015: rgb(255 255 255 / 1.5%);
 
+  // ── Embedded-app plate ─────────────────────────────────────────────────────
+  // Aliases the ramp, deliberately. Here the window plate is a near-opaque dark
+  // material, so a white lift IS the canon lift (MainContent.dc.html: a `--w03`
+  // plate with `--w06` header bars and `--w05` row hover) and the wallpaper is
+  // already muted to the point where it cannot colour the app. The light block
+  // carries the rationale for why that reasoning does not survive the flip.
+  --embed-plate: var(--w03);
+  --embed-plate-hover: var(--w05);
+  --embed-plate-raised: var(--w06);
+
   // ── Materials ──────────────────────────────────────────────────────────────
   // Same two-part shape as the light block. The menu gradient stops are opaque
   // in this theme (`#201f25` / `#1a191e`); they are expressed as alpha-1 rgb so

package/scss/_shell-embed-bridge.scss

@@ -44,10 +44,19 @@
   // side-by-side with the design shows. The ramp flips polarity per theme
   // (white-lift on dark glass, ink-wash on light), which is also what the
   // design's own components do — they never branch on theme.
+
+  // CORRECTED: the ramp step is right in DARK and wrong in LIGHT, so the three
+  // lifts now go through `--embed-plate*` (declared per theme in
+  // `_nova-tokens.scss`), which aliases the ramp in dark and moves toward the
+  // plate's own white in light. The reason is written at the light declaration:
+  // an ink wash on a 60%-white translucent plate is a darker patch of WALLPAPER,
+  // not a card, which is what made the Help Center guide grid read as a
+  // photograph in light mode while dark mode looked correct. Same shape of
+  // light-mode-only failure this whole file exists for.
   --bg: transparent;
-  --bg-2: var(--w03);
-  --bg-3: var(--w06);
-  --bg-hover: var(--w05);
+  --bg-2: var(--embed-plate);
+  --bg-3: var(--embed-plate-raised);
+  --bg-hover: var(--embed-plate-hover);
 
   // Hairlines. `--line`/`--line-2` stay on the chrome separators (14% ≈ the
   // design's `--w14` CONTROL border — FormField.dc.html inputs), which is the
@@ -69,33 +78,32 @@
 
   // 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.
+  // `--ink` itself — the primary button.
+
+  // THE FLIP THE NOTE BELOW WARNED ABOUT HAS LANDED, AND THIS LINE IS NOW THE
+  // FIX RATHER THAN THE PREDICTION. `--label-primary` is no longer white in both
+  // themes: `_theme-light.scss` carries `rgb(17 24 39 / 92%)` — dark ink — so
+  // the fixed dark literal this line used to hold made every
+  // `background: var(--ink); color: var(--on-ink)` pair DARK ON DARK in light
+  // mode. Measured live inside `.hc-shell` on `html.light-theme`: fill
+  // `rgba(17,24,39,0.92)` against label `oklch(0.18 0.005 250)` — about 1.05:1,
+  // the same ~1:1 pair this file has now shipped twice, in the opposite
+  // direction. The flip value is the one the note already named.
 
   // `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);
+  // `var(--check-ink)` is 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. Both values are
+  // opaque hex, which is the other half of the contract — a translucent label
+  // composites into its own fill and disappears.
+  --on-ink: var(--check-ink);
 
   // `--ink-inverse` carries the SAME obligation as `--on-ink` and was missed.