@flyos/design-system 1.7.0 → 2.0.0

package/scss/_nova-glass.scss

@@ -0,0 +1,451 @@
+// ─── Nova glass recipes (UX v2) ──────────────────────────────────────────────
+// Stage 1 task S1.2 of the UX-refresh program. Canon: `skills/desktop-design-
+// language.md` §4, which cites `.workflow/plans/ux-refresh/analysis/
+// D1-home-desktop.md` §4 and `D3-styleguide-tokens.md` §1.6.
+
+// Mixins only — this partial emits NO CSS when merely `@use`d, so components can
+// `@use` it freely without duplicating rules. That is also why `_fly-theme.scss`
+// does NOT `@use` it: there would be nothing to emit.
+
+// ── Canonical import ─────────────────────────────────────────────────────────
+//   @use 'nova-glass' as glass;
+//   .fly-menu     { @include glass.popover; }
+//   .fly-drawer   { @include glass.popover($shadow: drawer, $surface: panel); }
+//   .app-panel    { @include glass.panel; }
+//   .shell-header { @include glass.chrome; }
+// Note the argumentless form has no parentheses — stylelint's
+// `scss/at-mixin-argumentless-call-parentheses` rejects `popover()`.
+
+// Members are namespaced rather than `nova-`-prefixed (the sibling
+// `_nova-motion.scss` prefixes because `@keyframes` names are GLOBAL and can
+// genuinely collide; Sass mixin names are module-scoped and cannot). Read the
+// call site, not the definition: `glass.popover` already says everything
+// `nova-glass-popover` would, and the namespace is what a reviewer sees.
+
+// ── The one rule this file exists to enforce ─────────────────────────────────
+// NEVER hand-compose glass (skill §9 rule 10). Per-component gradient stacks are
+// the drift this program exists to kill. Every sanctioned surface is one of the
+// four public mixins below; there is deliberately NO public way to pass a raw
+// blur radius, a raw shadow, or a fill of your own.
+
+// ── backdrop-filter is not a paint-only property (READ THIS) ─────────────────
+// A non-`none` `backdrop-filter` does three structural things to the element,
+// only the first of which is obvious:
+//   1. it creates a STACKING CONTEXT (hence the shell's z-ladder: the header
+//      must out-rank content, skill §6);
+//   2. it makes the element a CONTAINING BLOCK for every descendant, including
+//      `position: fixed` ones. A descendant that uses `fixed` to escape to the
+//      viewport is instead trapped inside the glass surface, and any coordinates
+//      computed from `getBoundingClientRect()` land in the wrong place;
+//   3. it makes the element a BACKDROP ROOT. A nested `backdrop-filter` then
+//      samples only what is painted INSIDE this element — not the wallpaper — so
+//      glass-inside-glass reads flat and muddy. (The shell already knew this:
+//      `window/_nova-vibrancy.scss` invented `--surface-overlay-strong` for
+//      exactly this case. `$nested: true` below is that knowledge, generalised.)
+
+// (2) is load-bearing exactly once — the `material()` rim and sheen are absolute
+// pseudo-elements that resolve against the glass surface without it needing
+// `position: relative`. Everywhere else it is a hazard: see the handoff note
+// `.workflow/plans/ux-refresh/notes/S1.2-glass-mixins.md` §"Containing block"
+// for the full inventory of what may and may not be nested under glass.
+
+// ── Vocabulary shared by the recipes ─────────────────────────────────────────
+// Private (Sass makes a leading `_` member inaccessible from other modules), so
+// no consumer can reach a half-recipe: the ONLY way to get `backdrop-filter` out
+// of this file is through a public mixin, and every public mixin carries the
+// full degradation ladder. That is the mechanism, not a convention.
+
+// The leading underscore IS that mechanism — it is the only privacy marker Sass
+// has — and it is what the kebab-case rules below reject. Scoped off for the
+// three private members only, then back on for the public API.
+// These are Sass line comments, NOT `/* */`: a CSS comment would survive into the
+// compiled output, and this partial's whole contract is that it emits nothing.
+// stylelint-disable scss/at-mixin-pattern, scss/at-function-pattern
+
+// The three sanctioned blur tiers (skill §4) — chrome 36 / content panel 72 /
+// thin 16. Selected BY NAME; a fourth tier would have to be added here, in the
+// open, where `nova-glass.spec.ts` counts them.
+@mixin _backdrop($tier) {
+  @if $tier == chrome {
+    -webkit-backdrop-filter: blur(36px) saturate(180%);
+    backdrop-filter: blur(36px) saturate(180%);
+  } @else if $tier == panel {
+    -webkit-backdrop-filter: blur(72px) saturate(180%);
+    backdrop-filter: blur(72px) saturate(180%);
+  } @else if $tier == thin {
+    // The ratified quartet value: blur(16px) saturate(180%) brightness(.95).
+    -webkit-backdrop-filter: var(--glass2-blur);
+    backdrop-filter: var(--glass2-blur);
+  } @else {
+    @error 'nova-glass: unknown blur tier `#{$tier}`. The three sanctioned tiers are `chrome` (36px), `panel` (72px), `thin` (16px) — skill §4 says do not invent a fourth.';
+  }
+}
+
+// The surface-context seam (skill §2 ⚠, §10).
+// The ratified light `--glass2-bg` carries the DARK near-opaque fill, so a light
+// popover anchored in the header renders as dark glass. In the mock only ONE
+// region escaped that, via a `#dc-root > div > div > div:nth-child(2) > section`
+// structural selector — which is exactly the fragile thing this argument
+// replaces: a caller DECLARES which surface it is and gets the right fill.
+// This is the seam the open UX ruling lands on. If UX rules the light fill is a
+// bug, the fix is one value in `_nova-tokens.scss` and `chrome` inherits it with
+// no change here. Nothing in this file second-guesses the ratified token.
+
+// READ THIS BEFORE PICKING `chrome`. As of the S1 review fixes NO shipping
+// component passes it: `fly-context-menu`, `fly-action-menu` and the
+// `fly-select` listbox moved to `menu`, and `fly-drawer` / `fly-modal` /
+// `fly-confirm-dialog` were already on `panel`. Only `/design-lab`'s Glass
+// Recipes preview and `nova-glass.spec.ts` still compile it. It is kept as the
+// DEFAULT on purpose — it is the canon's popover fill (skill §4) and the branch
+// the light-`--glass2-bg` ruling lands on — so the next genuine chrome-anchored
+// popover is the first caller that will feel that ruling, and it should. What it
+// must NOT be used for again is a floating menu in light theme: that pairing put
+// 95 % black ink on a near-opaque #38363C plate at 1.66–1.99:1.
+@function _fill($surface) {
+  @if $surface == chrome {
+    @return var(--glass2-bg);
+  }
+
+  // `panel`, `menu` and `agent` keep the quartet's two upper layers (bottom
+  // radial glow + top sheen, both composed from ramp steps) and swap ONLY the
+  // fill layer.
+  $glow: radial-gradient(70% 60% at 50% 100%, var(--w07), transparent 70%);
+  $sheen: linear-gradient(180deg, var(--w08), transparent 20%);
+
+  @if $surface == panel {
+    // Theme-aware translucency — the fill the light theme's `--mat-panel` was
+    // picked for and, today, the only place those values are used at all.
+    @return $glow, $sheen, linear-gradient(var(--mat-panel), var(--mat-panel));
+  } @else if $surface == menu {
+    // The design's own MENU material, ratified in both themes (skill §2) and
+    // consumed by nothing until the S1 review fixes — `_nova-tokens.scss` says
+    // as much in its ⚠, where the unused `--mat-menu-*` values are listed as
+    // collateral of the light `--glass2-bg` anomaly. A two-stop vertical
+    // gradient because the pair IS a gradient (`-a` top, `-b` bottom), the same
+    // shape `--mat-tip-a`/`-b` carry for tooltips.
+
+    // This branch exists because a floating menu is neither chrome nor a panel.
+    // `chrome` is unreadable in light theme (above). `panel` fixes light but is
+    // translucent in BOTH themes, so it inherits its backdrop: a dark-theme menu
+    // over a light wallpaper falls to 3.23:1 — AA failure for primary ink on the
+    // three most-used overlays in the system. `--mat-menu-*` is ALPHA-1 in dark,
+    // so this fill does not vary with the wallpaper there at all (14.85:1), and
+    // light lands at 17.44:1. Measured table:
+    // `.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'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` (--mat-agent-a/-b, the agent aside\'s own fill).';
+}
+
+// ── The degradation ladder (skill §4 — non-negotiable) ───────────────────────
+// Every public recipe ends with this. A component must never have to remember an
+// accessibility fallback, so the ladder ships WITH the glass or the glass does
+// not ship. `nova-glass.spec.ts` fails the build if a recipe is added without
+// it — that is the rule that stops the ladder rotting as recipes multiply.
+// The reduced-transparency flat fills are theme-dependent (`#2c2c2e` dark /
+// `#eef2f8` light) and are resolved with `light-dark()`, NOT a theme selector.
+// `html.light-theme` / `html.dark-theme` each set `color-scheme` (see
+// `_theme-light.scss` / `_theme-dark.scss`, and `native-select.spec.ts` which
+// forbids re-pinning it locally), so `light-dark()` follows the APP theme rather
+// than the OS. It is also the only mechanism that survives Angular's emulated
+// encapsulation: `html.dark-theme &` compiles to `html.dark-theme[_ngcontent-x]`
+// and is dead, and a component-local theme branch is banned outright (skill §9
+// rule 4). One value, no selector, correct in both themes.
+@mixin _degrade {
+  // Transparency off: a flat, fully opaque plate. Killing only the blur would
+  // leave the translucent fill, which is the thing that hurts.
+  @media (prefers-reduced-transparency: reduce) {
+    & {
+      border-color: transparent;
+      background-color: light-dark(#eef2f8, #2c2c2e);
+      background-image: none;
+      box-shadow: none;
+      -webkit-backdrop-filter: none;
+      backdrop-filter: none;
+    }
+
+    // The refractive rim and specular sheen ARE the transparency effect.
+    &::before,
+    &::after {
+      display: none;
+    }
+  }
+
+  // The glass hairline is decorative-contrast at best (`--w18` measures 1.79:1
+  // against the panel — D3 §contrast). This is the ratified bump.
+  @media (prefers-contrast: more) {
+    & {
+      border-color: var(--w6);
+    }
+  }
+
+  // The sheen is the only animation this file starts, and `::after` is the only
+  // pseudo it animates. `_nova-motion.scss` already zeroes every animation
+  // globally under this query; this block makes the recipe self-sufficient for
+  // any consumer that pulls the mixin without the motion partial.
+  @media (prefers-reduced-motion: reduce) {
+    &::after {
+      animation: none;
+    }
+  }
+}
+// stylelint-enable scss/at-mixin-pattern, scss/at-function-pattern
+
+// ── Popover composite ────────────────────────────────────────────────────────
+// Menus, listboxes, dialogs, drawers, filter panels — the four-token quartet
+// (skill §4). Thin blur tier, always: a popover's tier is a property of the
+// recipe, not a caller's choice.
+
+// $shadow  `menu` (default) — menus/listboxes/dialogs/content-panel/agent-aside
+//          `drawer`        — the directional, direction-AWARE drawer shadow
+// $surface `chrome` (default) / `menu` / `panel` / `agent` — see `_fill()`.
+//          A FLOATING MENU takes `menu`, not the default: `chrome` is the
+//          ratified quartet fill and carries the dark plate in BOTH themes.
+// $nested  `true` when this surface sits INSIDE another glass surface. Drops
+//          `backdrop-filter` entirely, because a nested backdrop root samples
+//          its parent instead of the wallpaper and reads as flat mud (hazard 3
+//          in the header). The near-opaque `chrome` fill then carries the
+//          surface on its own — which is why `$nested` and a translucent
+//          `$surface` are refused rather than silently rendered see-through.
+@mixin popover($shadow: menu, $surface: chrome, $nested: false) {
+  @if $nested and $surface != chrome {
+    @error 'nova-glass: popover($nested: true) needs the near-opaque `chrome` fill — a nested surface has no backdrop-filter to separate it from the glass beneath, so a translucent `#{$surface}` fill renders see-through. Drop $surface, or drop $nested and accept the muddy double-blur.';
+  }
+
+  border: 1px solid var(--glass2-border);
+  background-image: _fill($surface);
+
+  @if $shadow == menu {
+    box-shadow:
+      0 16px 40px rgb(0 0 0 / 20%),
+      0 4px 10px rgb(0 0 0 / 10%),
+      var(--glass2-inset);
+  } @else if $shadow == drawer {
+    // A drawer's shadow travels AWAY from the edge it is anchored to, so it
+    // mirrors under RTL. `box-shadow` has no logical-offset form, so the offset
+    // rides a custom property flipped by `:dir(rtl)` — a compound on the element
+    // ITSELF, which is why it survives emulated encapsulation where the
+    // `[dir='rtl'] &` descendant combinator is dead (skill §9 rule 1). On an
+    // engine without `:dir()` the rule drops whole and the shadow stays on the
+    // LTR side: cosmetic, never a layout break.
+    --nova-glass-drawer-shadow-x: -30px;
+
+    box-shadow:
+      var(--nova-glass-drawer-shadow-x) 0 70px rgb(0 0 0 / 34%),
+      0 4px 10px rgb(0 0 0 / 10%),
+      var(--glass2-inset);
+  } @else {
+    @error 'nova-glass: unknown $shadow `#{$shadow}`. Use `menu` (menus/listboxes/dialogs/content panel/agent aside) or `drawer`.';
+  }
+
+  @if not $nested {
+    @include _backdrop(thin);
+  }
+
+  @if $shadow == drawer {
+    &:dir(rtl) {
+      --nova-glass-drawer-shadow-x: 30px;
+    }
+  }
+
+  @include _degrade;
+}
+
+// ── Chrome ───────────────────────────────────────────────────────────────────
+// Header + nav rail. Explicitly NOT the quartet (skill §4): a flat `--mat-rail`
+// fill, a `--w16` hairline, its own three-part shadow, and the 36px tier.
+// `--mat-header` exists and is deliberately unused here — the design's own
+// header draws `--mat-rail` too, and the skill says not to "clean that up".
+// Note the inset step is `--w2` (0.20), NOT `--w22` (0.22) as the quartet's
+// `--glass2-inset` uses. The digits are the decimal fraction (skill §3.3) and
+// these are two different ratified steps, not a typo.
+@mixin chrome {
+  border: 1px solid var(--w16);
+  background: var(--mat-rail);
+  box-shadow:
+    0 6px 16px rgb(0 0 0 / 16%),
+    0 1px 4px rgb(0 0 0 / 10%),
+    inset 0 0.5px 0 var(--w2);
+
+  @include _backdrop(chrome);
+  @include _degrade;
+}
+
+// ── Content panel ────────────────────────────────────────────────────────────
+// The surface holding app content — the strongest blur in the language (72px),
+// on the quartet's layer stack with the `--mat-panel` fill.
+@mixin panel {
+  border: 1px solid var(--w18);
+  background-image: _fill(panel);
+  box-shadow:
+    0 16px 40px rgb(0 0 0 / 20%),
+    0 4px 10px rgb(0 0 0 / 10%),
+    var(--glass2-inset);
+
+  @include _backdrop(panel);
+  @include _degrade;
+}
+
+// ── 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.
+//   · The light/dark gate is the CALLER's selector scope, and the only scope
+//     where a theme gate actually works is a GLOBAL stylesheet:
+//       html.light-theme .fly-header { @include glass.material($surface: header); }
+//     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 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.
+@mixin material($surface) {
+  $variant: null;
+
+  @if $surface == header or $surface == rail {
+    $variant: chrome;
+  } @else if $surface == content-panel or $surface == agent-aside {
+    $variant: regular;
+  } @else if $surface == toolbar or $surface == tablist {
+    $variant: thin;
+  } @else {
+    @error 'nova-glass: material($surface: #{$surface}) is not a shell surface. This layer is opt-in for shell chrome ONLY — pass `header`, `rail`, `content-panel`, `agent-aside` (the four [data-material] surfaces), or `toolbar` / `tablist` (the thin light controls). A feature-app component must not apply this layer at all; use popover() / panel() instead.';
+  }
+
+  // The rim and sheen are `z-index: -1` pseudo-elements: they paint above this
+  // element's own background but below its content. `isolation` keeps them from
+  // falling through to an ancestor's background. No `position` is set on
+  // purpose — the `backdrop-filter` below already makes this element a
+  // containing block for absolutely positioned descendants (hazard 2 in the
+  // header, load-bearing exactly here), so forcing `position: relative` would
+  // buy nothing and would silently break a `fixed` or `sticky` caller.
+  isolation: isolate;
+  border-color: transparent;
+
+  @if $variant == regular {
+    background-image: linear-gradient(
+      180deg,
+      rgb(255 255 255 / 50%),
+      rgb(255 255 255 / 10%) 46%,
+      rgb(255 255 255 / 22%) 100%
+    );
+    box-shadow:
+      inset 0 0.5px 0 rgb(255 255 255 / 70%),
+      inset 0 -0.5px 0 rgb(148 170 200 / 20%),
+      inset 0 0 26px rgb(255 255 255 / 16%),
+      0 10px 26px rgb(71 90 120 / 8%),
+      0 2px 5px rgb(71 90 120 / 5%);
+    -webkit-backdrop-filter: blur(34px) saturate(165%) brightness(1.04);
+    backdrop-filter: blur(34px) saturate(165%) brightness(1.04);
+  } @else if $variant == chrome {
+    background-image: linear-gradient(
+      168deg,
+      rgb(255 255 255 / 72%) 0%,
+      rgb(248 251 255 / 36%) 34%,
+      rgb(232 240 252 / 24%) 72%,
+      rgb(255 255 255 / 46%) 100%
+    );
+    box-shadow:
+      inset 0 1px 0 rgb(255 255 255 / 98%),
+      inset 0 -0.5px 0 rgb(120 145 180 / 22%),
+      inset 0 0 0 0.5px rgb(255 255 255 / 50%),
+      0 8px 22px rgb(60 80 115 / 10%),
+      0 2px 5px rgb(60 80 115 / 6%);
+    -webkit-backdrop-filter: blur(30px) saturate(180%) brightness(1.07);
+    backdrop-filter: blur(30px) saturate(180%) brightness(1.07);
+  } @else {
+    background-image: linear-gradient(180deg, rgb(255 255 255 / 66%), rgb(240 246 255 / 24%));
+    box-shadow:
+      inset 0 0.5px 0 rgb(255 255 255 / 80%),
+      inset 0 -0.5px 0 rgb(148 170 200 / 16%),
+      inset 0 0 0 0.5px rgb(255 255 255 / 34%),
+      0 1px 3px rgb(71 90 120 / 5%);
+    -webkit-backdrop-filter: blur(16px) saturate(160%) brightness(1.05);
+    backdrop-filter: blur(16px) saturate(160%) brightness(1.05);
+  }
+
+  // Refractive rim — light bending through the edge of the glass. A 1px padding
+  // box masked against its own content box leaves only the ring.
+  &::before {
+    content: '';
+    position: absolute;
+    z-index: -1;
+    inset: 0;
+    padding: 1px;
+    border-radius: inherit;
+    background: linear-gradient(
+      140deg,
+      rgb(255 255 255 / 60%),
+      rgb(255 255 255 / 8%) 34%,
+      rgb(190 210 240 / 16%) 64%,
+      rgb(255 255 255 / 42%)
+    );
+    pointer-events: none;
+    -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+    mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+    -webkit-mask-composite: xor;
+    mask-composite: exclude;
+  }
+
+  // Specular sheen drifting across the surface. `background-size` is
+  // load-bearing, not decoration: `glassSheen` animates background-POSITION, and
+  // a background no wider than its box has nowhere to travel — at 100% the
+  // animation runs and nothing moves.
+  &::after {
+    content: '';
+    position: absolute;
+    z-index: -1;
+    inset: 0;
+    border-radius: inherit;
+    background: linear-gradient(
+      100deg,
+      transparent 22%,
+      rgb(255 255 255 / 22%) 46%,
+      rgb(255 255 255 / 7%) 54%,
+      transparent 76%
+    );
+    background-size: 260% 100%;
+    opacity: 0.5;
+    animation: glassSheen 22s ease-in-out infinite;
+    pointer-events: none;
+  }
+
+  @include _degrade;
+}

package/scss/_nova-motion-mixins.scss

@@ -0,0 +1,42 @@
+// ─── Nova motion — MIXINS ONLY ───────────────────────────────────────────────
+// The companion to `_nova-motion.scss`, split out at the S1 review (F4).
+// `_nova-motion.scss` is the EMISSION entry: `@use`-ing it writes the `:root`
+// token block, the `[dir='rtl']` flip, all 16 `@keyframes` and the global
+// `prefers-reduced-motion` block into whatever compiled it. Because every
+// Angular component stylesheet compiles as its own Sass entry, that made the
+// partial's one useful Sass-level construct — the `nova-stagger` mixin —
+// unreachable from a component without paying for a second copy of ~200 lines
+// of global CSS. The result was predictable and did happen: two callers
+// hand-copied the mixin's nth-child math rather than `@use` it, and a third
+// `@use`d it anyway and re-emitted everything.
+// This file is the fix, in the shape `_nova-glass.scss` already proved: it
+// declares mixins and emits NOTHING, so any component may `@use` it freely. It
+// is the single home of the stagger math; `_nova-motion.scss` re-exports it via
+// `@forward` so an existing `@use 'nova-motion'` caller keeps working.
+// Referencing a keyframe NAME (`animation: itemIn …`) or a `var(--nova-*)` token
+// needs no `@use` at all — both are plain global CSS, emitted once through
+// `_fly-theme.scss`. Only the nth-child loop is a Sass construct, which is why
+// it is the only thing here.
+
+// ── Stagger utility ──────────────────────────────────────────────────────────
+// Emits an `:nth-child` animation-delay chain so no component hand-writes one.
+// $step matches the context: 40ms toolbar actions/items, 55ms cards, 20ms app
+// tiles (skill §5). Capped at $max (default 12 — every shipped stagger set in
+// the design is well under this) because emitting hundreds of nth-child rules
+// for an unbounded list is worse than the duplication this mixin replaces. Items
+// past the cap hold at the LAST step's delay rather than snapping to a bare 0,
+// so a long list's tail doesn't visibly un-stagger.
+// `:nth-child` counts ALL element siblings, not just the ones this selector
+// matches — a caller must keep the staggered element's parent homogeneous, or
+// insert non-staggered siblings only AFTER the last staggered one.
+@mixin nova-stagger($step: 40ms, $max: 12) {
+  @for $i from 0 through ($max - 1) {
+    &:nth-child(#{$i + 1}) {
+      animation-delay: $i * $step;
+    }
+  }
+
+  &:nth-child(n + #{$max + 1}) {
+    animation-delay: ($max - 1) * $step;
+  }
+}