@flyos/design-system 1.0.0 → 1.2.0

package/package.json

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

package/scss/_app-surface-utilities.scss

@@ -2,6 +2,16 @@
 // UI library global utilities (generic). EMITS CSS — import once from the
 // global stylesheet, after _tokens.scss.
 // ─────────────────────────────────────────────────────────────────────────────
+@use 'shell-embed-bridge';
+
+// Class form of the app-surface → shell-glass bridge, for consumers that cannot
+// reach the mixin: a component with INLINE `styles:` (no SCSS pipeline), or a
+// subtree portalled out of its app's stylesheet scope. Prefer the mixin in a
+// real `.scss` file; this exists so the map is never retyped by hand. See
+// `_shell-embed-bridge.scss` for why the bridge is needed at all.
+.fly-app-surface-on-glass {
+  @include shell-embed-bridge.app-surface-on-glass;
+}
 
 // Tabular numerals / code — reusable in templates without restyling a component.
 .mono {

package/scss/_ink-baseline.scss

@@ -1,29 +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);
-}
+// ─── 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/_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-dark.scss

@@ -102,6 +102,14 @@ html.dark-theme {
   --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%);

package/scss/_theme-light.scss

@@ -97,6 +97,23 @@ html.light-theme {
   --glass-bg: rgb(255 255 255 / 60%);
   --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
+  // at `:root`, so under a dark wallpaper it becomes a 54 %-alpha DARK plate even while the shell
+  // 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.
+  --tooltip-bg: #1f2430;
+  --tooltip-ink: #fff;
+  --tooltip-border: rgb(255 255 255 / 14%);
+
   // Ink for text sitting ON `--glass-bg-elevated`. This pair was already correct when the rest
   // of the theme was not, so it became the model the `--label-*` / `--text-color-*` families
   // were rebuilt against. It now agrees with them rather than compensating for them; the

package/scss/_vos-button-mixins.scss

@@ -1,28 +1,28 @@
-// visionOS button pseudo-element layers (used by _business-app-buttons.scss).
-// Kept separate from desktop-app glass mixins so Business Apps only pull button-related SCSS.
-
-@mixin vos-platter-layers($radius) {
-  content: '';
-  position: absolute;
-  inset: 0;
-  border-radius: $radius;
-  pointer-events: none;
-  background:
-    linear-gradient(var(--btn-platter-lighten), var(--btn-platter-lighten)),
-    linear-gradient(var(--btn-platter-dodge), var(--btn-platter-dodge));
-  background-blend-mode: lighten, color-dodge;
-  mix-blend-mode: screen;
-}
-
-@mixin vos-disabled-layers($radius) {
-  content: '';
-  position: absolute;
-  inset: 0;
-  border-radius: $radius;
-  pointer-events: none;
-  background:
-    linear-gradient(var(--btn-disabled-lighten), var(--btn-disabled-lighten)),
-    linear-gradient(var(--btn-disabled-dodge), var(--btn-disabled-dodge));
-  background-blend-mode: lighten, color-dodge;
-  mix-blend-mode: screen;
-}
+// visionOS button pseudo-element layers (used by _business-app-buttons.scss).
+// Kept separate from desktop-app glass mixins so Business Apps only pull button-related SCSS.
+
+@mixin vos-platter-layers($radius) {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: $radius;
+  pointer-events: none;
+  background:
+    linear-gradient(var(--btn-platter-lighten), var(--btn-platter-lighten)),
+    linear-gradient(var(--btn-platter-dodge), var(--btn-platter-dodge));
+  background-blend-mode: lighten, color-dodge;
+  mix-blend-mode: screen;
+}
+
+@mixin vos-disabled-layers($radius) {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: $radius;
+  pointer-events: none;
+  background:
+    linear-gradient(var(--btn-disabled-lighten), var(--btn-disabled-lighten)),
+    linear-gradient(var(--btn-disabled-dodge), var(--btn-disabled-dodge));
+  background-blend-mode: lighten, color-dodge;
+  mix-blend-mode: screen;
+}