@flyos/design-system 1.7.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flyos/design-system",
-  "version": "1.7.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
@@ -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 ──────────────────────────────────────────────────────
@@ -60,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
@@ -105,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
@@ -263,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.
@@ -324,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),
@@ -364,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/_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);
+}