@flyos/design-system 1.6.0 → 1.8.0

package/package.json

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

package/scss/_app-surface-tokens.scss

@@ -47,6 +47,107 @@
 // `_fly-theme.scss`, so `@use 'fly-theme'` is all a consumer needs.
 // ─────────────────────────────────────────────────────────────────────────────
 
+// ── The platform TYPE layer (UX v2, S1.7–S1.10 fallout) ──────────────────────
+// `_tokens.scss` owns `--font-family` / `--font-family-mono` and the `--font-*`
+// role ramp (`--font-footnote`, `--font-caption1`, …). Like the two Nova
+// partials below it was reachable only through `_fly-theme.scss`, i.e. only in
+// the desktop shell.
+
+// The type layer fails harder than the colour layers do, and it fails silently.
+// The Nova form/overlay/content tasks landed 26 declarations across `lib/**` of
+// the form `font: 600 13px/1.3 var(--font-family)` or `font: var(--nova-font-
+// menu-item)`. A `var()` naming an undefined custom property is invalid at
+// computed-value time, and in a SHORTHAND that invalidates the WHOLE
+// declaration — weight, size and line-height all fall back to inherited, not
+// just the family. Standalone that is a 13px control label rendering at the
+// app's 16px body size inside a box hard-sized to 36/30/26px: a `fly-select`
+// trigger, a `fly-form-field` label, a `fly-checkbox` label, a `fly-drawer`
+// title. Nothing reported it because the shell renders every one of them
+// correctly. Before this line the DS had ZERO `var(--font-family)` references
+// in `lib/**`; the guard that now walks those files lives in
+// `app-surface-nova-bridge.spec.ts`.
+
+// Idempotent in the shell for the same reason as the two below: `_fly-theme.scss`
+// already `@use`s `tokens` FIRST, Sass loads a module once per compilation, and
+// the compiled entry is byte-identical either way.
+
+// Standalone it adds 120 greenfield names, of which the three External Apps
+// reference five. Four of those (`--font-title2`, `--system-blue`,
+// `--system-indigo`, `--system-red`) were dangling references that now resolve.
+// The fifth is `--font-family` itself, and it is the one behavioural change in
+// this commit: Circles already loads the DS's own Geist from its
+// `public/ui-fonts/geist.css` and is unaffected, but Thoughts and PPM write
+// `var(--font-family, 'Roboto', …)` on `html, body` while bundling Roboto and
+// NOT Geist. Both must bind `--font-family` to their own stack (or drop the
+// indirection) before taking this DS release, or their body text falls through
+// to a face they do not ship. Recorded here rather than worked around: the
+// alternative — leaving the token undefined so their fallback keeps firing —
+// is what dropped the 26 declarations above.
+@use 'tokens';
+
+// ── The Nova bridge (UX v2, S1.11) ───────────────────────────────────────────
+// `_nova-tokens.scss` carries the Nova vocabulary — the `--w*` ink ramp,
+// `--mat-*`, `--sys-*`, `--tint-*`, the `--glass2-*` quartet. `_fly-theme.scss`
+// loads it, and the desktop shell is the only consumer that loads that entry.
+// The three External Apps do NOT: Circles, Thoughts and PPM each `@use` THIS
+// partial by bare name, and Circles keeps `// @use 'fly-theme';` commented out
+// on line 1 of its `styles.scss` — the same fact this file's header records.
+
+// So without the line below, the Nova names are undefined in precisely the
+// builds that render this family on its own opaque paper. That matters for what
+// comes NEXT rather than for anything today: at the DS 2.0 flip the values in
+// this file are re-pointed at ramp steps (`--ink: var(--w95)`,
+// `--line: var(--w18)`; the whole table is in `.workflow/plans/ux-refresh/
+// notes/S1.11-app-surface-bridge.md`). A `var()` whose token is undefined makes
+// the entire declaration invalid at computed-value time, so that flip would
+// silently unset ink and hairlines for every standalone External App while
+// looking perfect in the shell — the light-mode-only failure that
+// `_shell-embed-bridge.scss` and `_ink-baseline.scss` were each written to end,
+// arriving a third time through a different door.
+
+// It is additive in both directions. In the shell it changes nothing at all:
+// `_fly-theme.scss` already `@use`s `nova-tokens` first, Sass loads a module
+// once per compilation, and the compiled entry is byte-identical either way.
+// Standalone it adds greenfield names only — no Nova name is referenced or
+// declared anywhere in Circles, Thoughts or PPM. It is also invisible to
+// `tools/ds-compat`, which derives the token surface by scanning `src/scss/**`
+// per file, not by compiling this entry.
+
+// `app-surface-nova-bridge.spec.ts` holds the wire in place and proves that
+// every `var()` this file emits still resolves inside the standalone bundle.
+@use 'nova-tokens';
+
+// The same argument, for motion. The app-surface components now reach for the
+// Nova keyframes (`itemIn` / `riseIn` / `appTileIn`) and the `--nova-ease-*` /
+// `--nova-duration-*` tokens, and those live in `_nova-motion.scss` — which,
+// like `_nova-tokens.scss`, was reachable only through `_fly-theme.scss` and so
+// only in the shell. Standalone, an `animation: itemIn …` naming an undefined
+// keyframe is not an error: it silently does nothing, so a list that staggers
+// in for a Core App would appear instantly in an External App with no gate
+// anywhere reporting a difference. Bridging it here is what makes the two
+// builds agree. Same idempotence: the shell already loads this module, so the
+// compiled shell entry is unchanged, and standalone it adds one `:root` block,
+// the keyframe inventory and the single `prefers-reduced-motion` block.
+@use 'nova-motion';
+
+// The same argument again, for the Nova TYPE roles — and the reason `tokens`
+// above is not optional. Half the `--nova-font-*` table SNAPs onto the platform
+// ramp by reference (`--nova-font-menu-item: var(--font-footnote)`,
+// `--nova-font-body`, `--nova-font-tooltip`), so loading this partial without
+// `tokens` would not fix anything: it would move the dangling reference one
+// level down, where a component's `font: var(--nova-font-menu-item)` still
+// resolves to an invalid value and still drops whole. The two travel together
+// or neither is worth loading.
+
+// This is the one `@use` in this file that the partial's own header argues
+// against ("`@use`d exactly once, from `_fly-theme.scss` … never a second
+// time"). That warning is about COMPONENT-level `@use`, which re-emits the
+// `:root` block into each component's compiled stylesheet; this is a global
+// entry, the same role `_fly-theme.scss` plays, and Sass still emits the module
+// exactly once per compilation. Federated it is `_fly-theme.scss`'s copy;
+// standalone it is this one. Never both.
+@use 'nova-type';
+
 :root,
 html.light-theme {
   // ── Neutrals — text ──────────────────────────────────────────────────────

package/scss/_app-surface-utilities.scss

@@ -27,13 +27,18 @@
 // plate ~47px wide) cut every tool's tip off inside its own column, and no z-index could
 // help — clipping is not a stacking question, and `position: fixed` on the pseudo would
 // still be trapped by those plates' `backdrop-filter` containing block.
-//
+
 // `FlyTooltipDirective` now owns the surface for BOTH `[flyTooltip]` and `[data-tooltip]`:
 // a `position: fixed` node parented to `<body>`, so it escapes every clip, flips placement
 // and clamps to the viewport. Components that write `data-tooltip` imperatively (the DS
 // icon button) list the directive in `hostDirectives`; templates with a static or bound
 // `data-tooltip` must IMPORT `FlyTooltipDirective` for the label to appear.
-//
+
+// The surface itself (Nova's `--mat-tip-a`/`-b` material, opaque, no blur) lives entirely
+// in the directive's injected `<style>` — see `fly-tooltip.directive.ts` for the recipe and
+// why it is deliberately NOT a `glass.popover()` thin-blur surface (S1.8). Nothing here
+// draws a tooltip; this selector only keeps the positioning context callers relied on.
+
 // Only the positioning context the attribute implied is kept, since callers may still hang
 // their own absolutely-positioned adornments (badges, dots) off a tooltip'd control.
 [data-tooltip] {

package/scss/_business-app-buttons.scss

@@ -1,9 +1,32 @@
-@use 'vos-button-mixins' as *;
+@use 'fos-button-mixins' as *;
 
-// ─── visionOS Button Utility Classes (shared with FlyOS desktop shell) ────────
+// ─── FlyOS Button Utility Classes (shared with the desktop shell) ─────────────
 // Requires @use 'fly-theme' (or equivalent tokens) before this partial.
 
+// ## The `.vos-` aliases are a deprecation window, not a style
+
+// These three classes are the only PUBLISHED part of the old `vos-` prefix: External
+// Apps write them in their own templates (measured: Circles authors `vos-btn` x21 and
+// `vos-link` x4 across 6 files; Thoughts and PPM use none). Removing the old spelling
+// is therefore a breaking change to this package's CSS surface — and a silent one,
+// because a class that stops matching is not a build error in either repo, it simply
+// renders unstyled.
+
+// **And no gate would have caught it.** ds-compat extracts four things — the TS export
+// surface, CSS CUSTOM PROPERTIES, CSS layers, and peer floors. It has no class-name
+// extractor, so a renamed class is invisible to it: dropping `.vos-btn` outright still
+// reports "federation-safe". The gate protects the token surface, not the class surface,
+// even though the class surface is the one External-App TEMPLATES are written against.
+
+// So `fos-` is canonical and `vos-` rides along as an alias, and the alias is doing the
+// work the gate cannot.
+
+// **Delete the `.vos-` halves at DS 2.0 (plan item S6.1b) — and only AFTER S6.2 lands
+// the Circles migration.** Removing them first breaks Circles with no diagnostic.
+// Verify against a grep of the Circles worktree, not of this repo.
+
 @layer designsystem {
+.fos-btn,
 .vos-btn {
   position: relative;
   display: inline-flex;
@@ -60,11 +83,11 @@
   }
 
   &.platter::before {
-    @include vos-platter-layers(inherit);
+    @include fos-platter-layers(inherit);
   }
 
   &:hover:not(:disabled, .selected, .active)::before {
-    @include vos-platter-layers(inherit);
+    @include fos-platter-layers(inherit);
   }
 
   &.selected,
@@ -81,7 +104,7 @@
     pointer-events: none;
 
     &::before {
-      @include vos-disabled-layers(inherit);
+      @include fos-disabled-layers(inherit);
     }
   }
 
@@ -104,6 +127,8 @@
   }
 }
 
+// `.vos-btn-symbol` alias: see the deprecation note at the top of this file.
+.fos-btn-symbol,
 .vos-btn-symbol {
   position: relative;
   display: inline-flex;
@@ -152,11 +177,11 @@
   }
 
   &.platter::before {
-    @include vos-platter-layers(500px);
+    @include fos-platter-layers(500px);
   }
 
   &:hover:not(:disabled, .selected, .active)::before {
-    @include vos-platter-layers(500px);
+    @include fos-platter-layers(500px);
   }
 
   &.selected,
@@ -173,7 +198,7 @@
     pointer-events: none;
 
     &::before {
-      @include vos-disabled-layers(500px);
+      @include fos-disabled-layers(500px);
     }
   }
 
@@ -185,6 +210,8 @@
   }
 }
 
+// `.vos-link` alias: see the deprecation note at the top of this file.
+.fos-link,
 .vos-link {
   display: inline-flex;
   align-items: center;

package/scss/_fly-theme.scss

@@ -6,6 +6,15 @@
 @use 'theme-light';
 @use 'theme-dark';
 
+// ── Nova (UX v2) design language ─────────────────────────────────────────────
+// Additive layer: new vocabulary only, nothing here re-values a token the three
+// partials above already define (the colliding glass quartet is renamed
+// `--glass2-*` per the D1 ruling). Canon: `skills/desktop-design-language.md`.
+// `nova-glass` is mixins-only and is @used by components, not from here.
+@use 'nova-tokens';
+@use 'nova-motion';
+@use 'nova-type';
+
 // The inherited `color` for themed documents. Emits a rule, not tokens, so it
 // lives apart from the theme partials — see its header for why the absence of a
 // baseline was the root cause of the recurring black-ink-on-glass bug.

package/scss/{_vos-button-mixins.scss → _fos-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;
-}
+// FlyOS 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 fos-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 fos-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;
+}

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 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.
+
+html.light-theme,
+html.dark-theme {
+  color: var(--text-color);
+}