@motir/design-system 0.1.3 → 0.2.0

package/theme.css

@@ -222,6 +222,35 @@
   --height-input: 44px;
   --height-control: 36px; /* single-line / square small control */
 
+  /* The space the collapsed nav rail puts AROUND its control: its `px-2`
+     gutters (8px a side), its 1px right border, and the 3px of slack the
+     shipped rail has always carried. Not the rail's width — the width is this
+     PLUS one `--height-control` square, composed at the point of use in
+     `components/ui/AppLayout.tsx` so the sum re-resolves under whatever
+     [data-style] is in scope rather than freezing the value `:root` happened
+     to have.
+
+     Calibrated so the DEFAULT style is unchanged: 36px + 20px is the 56px the
+     rail has always been. A denser style now gets a narrower rail and a roomier
+     one a wider rail, which is the density axis working rather than a constant
+     ignoring it. Deliberately NOT overridden per style — a style moves the
+     CONTROL, and the rail follows it (MOTIR-4232). */
+  --width-rail-chrome: 20px;
+
+  /* The inset a FLOATING rail is held away from the frame on all four sides, so
+     the shell canvas reads around it (MOTIR-4253). ZERO here, and that is the
+     point: the rail has a shared right EDGE in ten of the eleven styles, and an
+     edge is flush by definition. Only a style that turns the rail into a panel
+     with a shadow moves it.
+
+     It is composed into `AppLayout`'s two grid columns rather than applied to
+     the rail alone, because the rail FILLS its cell — a margin would shrink the
+     rail inside an unchanged column and take the collapsed rail's content box
+     below one `--height-control` square, which is exactly the invariant
+     MOTIR-4232 established. At `0px` both sums compile to the numbers every
+     other style already had. */
+  --spacing-rail-inset: 0px;
+
   /* ── Interaction ────────────────────────────────────────────────── */
   --transition-duration: 150ms;
   --transition-fast: 100ms;
@@ -349,7 +378,8 @@
 /* ═══════════════════════════════════════════════════════════════════════
    TIER 2 — Named-style overrides ([data-style], Axis 2)
    `warm-editorial` is the base (the Tier-0 defaults above — Notion-sober
-   rectangles), so it needs no override block.
+   rectangles). Its explicit block repeats that shape/feel contract so a nested
+   base-style scope shadows a foreign active style instead of inheriting it.
    `soft-playful` adopts Figma's pill buttons + larger radius + softer shadows
    + roomier spacing + a gentler motion feel. Each later style (Swiss,
    Neo-Brutalism, Glassmorphism, …) adds its own `[data-style='<id>']` block
@@ -357,6 +387,70 @@
    motion / type) — NEVER a colour token (that is the data-palette axis).
    ═══════════════════════════════════════════════════════════════════════ */
 
+[data-style='warm-editorial'] {
+  --radius-xs: 4px;
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-xl: 16px;
+  --radius-pill: 9999px;
+  --radius-btn: 8px;
+  --radius-card: 12px;
+  --radius-input: 8px;
+  --radius-modal: 12px;
+  --radius-badge: 9999px;
+  --radius-control: 6px;
+  --radius-kbd: 4px;
+  --shadow-flat: none;
+  --shadow-subtle: 0 1px 2px rgba(15, 15, 15, 0.04);
+  --shadow-card: 0 4px 12px rgba(15, 15, 15, 0.08);
+  --shadow-elevated: 0 8px 24px rgba(15, 15, 15, 0.12);
+  --shadow-modal: 0 16px 48px -8px rgba(15, 15, 15, 0.16);
+  --shadow-hero-mockup: 0 24px 48px -8px rgba(15, 15, 15, 0.2);
+  --spacing-xxs: 4px;
+  --spacing-xs: 8px;
+  --spacing-sm: 12px;
+  --spacing-md: 16px;
+  --spacing-lg: 20px;
+  --spacing-xl: 24px;
+  --spacing-2xl: 32px;
+  --spacing-3xl: 40px;
+  --spacing-section: 64px;
+  --spacing-section-lg: 96px;
+  --spacing-hero: 120px;
+  --spacing-btn-x: 18px;
+  --spacing-btn-y: 10px;
+  --spacing-btn-x-sm: 12px;
+  --spacing-btn-y-sm: 8px;
+  --spacing-input-x: 16px;
+  --spacing-input-y: 12px;
+  --spacing-card-padding: 24px;
+  --spacing-control-x: 10px;
+  --spacing-control-y: 6px;
+  --spacing-icon-btn: 4px;
+  --spacing-chip-x: 10px;
+  --spacing-chip-y: 2px;
+  --spacing-kbd-x: 6px;
+  --spacing-kbd-y: 2px;
+  --spacing-tooltip-x: 8px;
+  --spacing-tooltip-y: 4px;
+  /* The rail keeps its shared edge under this style, so it is flush — the
+     default's mirror of the Tier-0 value, not an override (MOTIR-4253). */
+  --spacing-rail-inset: 0px;
+  --height-btn-sm: 32px;
+  --height-btn-md: 40px;
+  --height-btn-lg: 48px;
+  --height-input: 44px;
+  --height-control: 36px;
+  --transition-duration: 150ms;
+  --transition-fast: 100ms;
+  --transition-slow: 250ms;
+  --hover-scale: 1;
+  --active-scale: 0.98;
+  --focus-ring-width: 2px;
+  --focus-ring-offset: 2px;
+}
+
 [data-style='soft-playful'] {
   /* Figma's pill geometry */
   --radius-btn: 9999px; /* pill */
@@ -548,6 +642,43 @@
    they are NOT the bare [data-style] token block and never carry a hue token
    there — the disjoint-axis token-block test still passes. ───────────────── */
 
+/* ═══════════════════════════════════════════════════════════════════════
+   ⚠️ A STYLE CANVAS IS PAINTED ON `body` AND ON `[data-app-shell]`, FROM ONE
+   RULE (MOTIR-4230 for 3D / Immersive, MOTIR-4234 for the rest)
+   ═══════════════════════════════════════════════════════════════════════
+   Six of the eleven registered styles express part of their identity as a
+   `body`-level CANVAS: glassmorphism's vibrant wash, cybercore's tech grid,
+   aurora's drifting ribbons, 3D / Immersive's atmosphere, neumorphism's
+   moulded field and retrofuturism's synthwave sky. `body` alone covers the
+   anonymous surfaces — auth, the public site, `/tokens` — where nothing is
+   stacked over the canvas. On a SIGNED-IN route it covers nothing at all: the
+   shell root (`components/ui/AppLayout.tsx`, and the platform-admin
+   `AdminShell`) is a `h-dvh overflow-hidden` box carrying `bg-(--el-page-bg)`,
+   an OPAQUE fill over the whole viewport. The canvas was painted and then
+   hidden, so a user who picked one of these styles got the surface treatment
+   on individual panels and a flat frame around them — and glass is the sharpest
+   case, because the thing its frosted rail was blurring was that flat fill
+   rather than the wash the blur exists to refract.
+
+   So each of those rules names TWO members, `body` and the `data-app-shell`
+   hook both shells carry, and the shell repaints the SAME layers over its own
+   page fill. ONE RULE, TWO SELECTORS, DELIBERATELY — a second rule restating a
+   gradient stack is a copy that drifts on the first tune, and the whole defect
+   was the canvas and the frame disagreeing about what the canvas is. Where the
+   body rule fixes `background-attachment`, both members inherit it from the one
+   declaration, which is what makes the two pixel-identical rather than merely
+   similar: each resolves against the viewport instead of against its own box.
+
+   A style that paints NO canvas of its own (`warm-editorial`, `soft-playful`,
+   `swiss-minimal-flat`, `neo-brutalism`, `hand-drawn-indie`) is untouched by
+   all of this and the shell keeps the `--el-page-bg` fill it has always had:
+   the hook is a hook, not a style.
+
+   `tests/theme/styleShellCanvas.test.ts` pins the pairing for EVERY style that
+   paints a canvas — derived from the stylesheet, not from a list — and
+   `tests/e2e/shell-immersive-atmosphere.spec.ts` is the rendered half.
+   ═══════════════════════════════════════════════════════════════════════ */
+
 /* The canvas: the palette's page bg + three soft corner washes. The hue sources
    are the `--el-*` accent roles (NOT Tier-0 `--color-*`), so the washes re-tint
    with the active palette — the `data-palette` axis (7.3.48 / MOTIR-1065)
@@ -555,7 +686,8 @@
    the glass orthogonal to the palette. The gradient is what the frosted panels
    blur — without it, the blur is invisible. */
 @scope ([data-style='glassmorphism']) to ([data-style]) {
-  body {
+  body,
+  [data-app-shell] {
     background-image:
       radial-gradient(
         85% 80% at 6% -12%,
@@ -814,7 +946,8 @@
    renders on it), keeping AA intact. Dark-first — on the dark theme this reads
    as a Tron grid over the near-black canvas. */
 @scope ([data-style='cybercore-y2k']) to ([data-style]) {
-  body {
+  body,
+  [data-app-shell] {
     background-image:
       linear-gradient(color-mix(in srgb, currentColor 6%, transparent) 1px, transparent 1px),
       linear-gradient(90deg, color-mix(in srgb, currentColor 6%, transparent) 1px, transparent 1px);
@@ -918,7 +1051,8 @@
    palette. background-size > 100% gives the gradient room to drift; the whole
    field eases back and forth over `--aurora-drift-duration`. */
 @scope ([data-style='aurora']) to ([data-style]) {
-  body {
+  body,
+  [data-app-shell] {
     background-image:
       radial-gradient(
         58% 75% at 12% 0%,
@@ -964,10 +1098,14 @@
 }
 
 /* Respect a reduced-motion preference — the aurora settles to a still gradient
-   (the identity holds; only the drift stops). */
+   (the identity holds; only the drift stops). BOTH members, for the reason the
+   canvas has two: the shell now carries the same `animation` declaration, so an
+   arm that stilled only `body` would leave a reduced-motion user with a drifting
+   frame around a still page — the defect inverted rather than fixed. */
 @media (prefers-reduced-motion: reduce) {
   @scope ([data-style='aurora']) to ([data-style]) {
-    body {
+    body,
+    [data-app-shell] {
       animation: none;
     }
   }
@@ -1097,6 +1235,13 @@
   --height-control: 40px;
   --height-input: 46px;
 
+  /* The rail FLOATS in this style, so it is held off the frame on all four
+     sides and the immersive atmosphere reads around it (MOTIR-4253). The base
+     layer is `0px`, so this is the only override — every other style's rail
+     stays flush against its shared edge, and both of `AppLayout`'s grid sums
+     compile to the numbers they have today. */
+  --spacing-rail-inset: 10px;
+
   /* Motion — smooth and floaty. A slower ease for the depth to feel weighty.
      The signature INTERACTION is the pointer-parallax TILT below (the standard
      "3D card" effect — cards tip toward the cursor), driven by the
@@ -1115,9 +1260,28 @@
    never a raw hue), so the style/palette axes stay disjoint and the material-
    rule test passes: a palette swap re-tints the atmosphere, a style swap leaves
    hues alone. This is what makes the table/list/board pages (no card surfaces of
-   their own) read as immersive too. */
+   their own) read as immersive too.
+
+   ⚠️ IT IS PAINTED ON THE SHELL CANVAS AS WELL AS ON `body`, AND THAT IS WHY THE
+   SELECTOR LIST HAS TWO MEMBERS (MOTIR-4230). `body` alone covers the anonymous
+   surfaces — auth, the public site, `/tokens` — where nothing is stacked over the
+   canvas. On a SIGNED-IN route the shell root (`components/ui/AppLayout.tsx`, and
+   the platform-admin `AdminShell`) is a `h-dvh` box carrying `bg-(--el-page-bg)`,
+   an OPAQUE fill covering the whole viewport: the body's atmosphere was painted
+   and then hidden behind it, so every card had its 3D tokens while the frame they
+   sit in stayed flat — the style did not read as immersive anywhere a user
+   actually works. The shells therefore carry a `data-app-shell` hook and repaint
+   the SAME layers over their own page fill, which is what the body would have
+   shown. `background-attachment: fixed` on both members is what makes the two
+   pixel-identical: each resolves against the viewport, not against its own box.
+
+   ONE RULE, TWO SELECTORS, DELIBERATELY — a second rule restating this gradient
+   stack is a copy that drifts on the first tune, and the whole defect was the
+   canvas and the frame disagreeing about what the canvas is. `tests/theme/
+   immersiveShellAtmosphere.test.ts` pins the pairing and the hook. */
 @scope ([data-style='3d-immersive']) to ([data-style]) {
-  body {
+  body,
+  [data-app-shell] {
     background-image:
       radial-gradient(
         130% 85% at 50% -15%,
@@ -1585,6 +1749,107 @@
   }
 }
 
+/* 3D / Immersive — THE SHELL CHROME (MOTIR-4253, drawn by MOTIR-4252).
+   docs/styles/3d-immersive.md §4's `shell chrome` row + design/shell/
+   3d-immersive-shell.mock.html, which injects this block verbatim so a frame in
+   the asset cannot flatter a rule the implementation could not write.
+
+   ── The defect this closes ─────────────────────────────────────────────────
+   The plane ladder named ten surfaces and stopped before the FRAME: this block
+   carried no [data-surface='header'] and no [data-surface='sidebar'] rule at
+   all, while both hooks are emitted and five of the eleven styles already use
+   them. So roughly a quarter of every signed-in screen rendered byte-identically
+   to the default style — and §4's own `Quiet control / row` row was left
+   asserting that a sidebar nav link is flat *because the surface it sits in
+   floats*, of a surface no rule made float. §4b is the closure rule that keeps
+   the ladder from going silent about a surface again.
+
+   ── TWO OBJECTS, TWO PLANES, and the ladder says which ─────────────────────
+   How far a surface floats is how far you can see UNDER its edges. The rail has
+   four edges in the scene, so it can be an object at a distance: --shadow-card.
+   The bar has exactly one — its bottom — so the only thing it can express is a
+   CONTACT, which is --shadow-subtle, the ladder's tightest rung. A bar wearing
+   --shadow-card would out-float the panel it frames on the strength of one
+   visible edge.
+
+   Four things here are DECISIONS rather than syntax:
+   1. box-shadow ONLY on the bar, never `position`. hand-drawn-indie carries the
+      same guard explicitly a few hundred lines below — the sticky header is
+      already a containing block and overriding it breaks the sticky — and the
+      pleasing part is that the property is also the MECHANISM: TopNav's
+      `sticky … z-30` is the stacking context that lets the lid's shadow paint
+      over the region beneath it. A static header's downward shadow is painted
+      behind the next sibling's background and is invisible. The constraint and
+      the mechanism are the same line of the component.
+   2. The rail's shared edge goes `border-right-color: transparent`, NOT
+      `border: none`. The 1px stays in the box, so --width-rail-chrome (the
+      rail's px-2 gutters plus that border) is unchanged. A floating panel has a
+      shadow instead of a shared edge; it does not have a different width.
+   3. Both a11y fallbacks restore a LINE the treatment made transparent, and
+      NEITHER MOVES A PIXEL. The rail's hairline comes back as an `outline` at
+      `outline-offset: -1px` — drawn outside the box, follows the radius, costs
+      no layout — and the bar's `border-bottom` already has its width; only its
+      colour was taken away. This is neumorphism's pattern (its own
+      prefers-contrast / forced-colors blocks) applied to a treatment whose
+      structure rests on a shadow.
+   4. --spacing-rail-inset is `0px` in the base layer, so every other style is
+      untouched and AppLayout's two sums compile to today's numbers everywhere
+      else. That is what makes this a style-axis change rather than a shell one.
+
+   Colour: every value is an existing --el-* or an existing style-axis shadow
+   token. The block adds and changes NO colour token, so the style and palette
+   axes stay disjoint. */
+@scope ([data-style='3d-immersive']) to ([data-style]) {
+  /* The RAIL — a floating PANEL, inset from the frame on all four sides so the
+     immersive atmosphere reads around it. */
+  [data-surface='sidebar'] {
+    margin: var(--spacing-rail-inset);
+    height: calc(100% - 2 * var(--spacing-rail-inset));
+    border-radius: var(--radius-card);
+    border-right-color: transparent;
+    box-shadow: var(--shadow-card);
+  }
+}
+@scope ([data-style='3d-immersive']) to ([data-style]) {
+  /* The TOP BAR — the LID. No fill (the atmosphere runs under it), no hairline,
+     and a contact shadow cast down onto the region below. It keeps full-bleed
+     edges and square corners: a bar with a radius and a margin is a second
+     floating slab, not a lid. */
+  [data-surface='header'] {
+    background-color: transparent;
+    border-bottom-color: transparent;
+    box-shadow: var(--shadow-subtle);
+  }
+}
+
+/* Accessibility fallbacks — where STRUCTURE rests on a shadow, restore a solid
+   line. Both are geometry-neutral by construction (see decision 3 above), so a
+   high-contrast or forced-colours user gets the same layout, not a shifted one. */
+@media (prefers-contrast: more) {
+  @scope ([data-style='3d-immersive']) to ([data-style]) {
+    [data-surface='sidebar'] {
+      outline: 1px solid var(--el-border-strong);
+      outline-offset: -1px;
+    }
+    [data-surface='header'] {
+      border-bottom-color: var(--el-border-strong);
+    }
+  }
+}
+@media (forced-colors: active) {
+  @scope ([data-style='3d-immersive']) to ([data-style]) {
+    [data-surface='sidebar'] {
+      outline: 1px solid var(--el-border-strong);
+      outline-offset: -1px;
+      box-shadow: none;
+    }
+    [data-surface='header'] {
+      border-bottom-color: var(--el-border-strong);
+      box-shadow: none;
+    }
+  }
+}
+
 /* ── Hand-Drawn / Indie (data-style="hand-drawn-indie") — Subtask 7.3.41 ─────
    DEFERRED follow-up. A sketchy, friendly, zine-like aesthetic. TWO moves make
    it read as genuinely hand-drawn, not just "softly rounded":
@@ -1890,7 +2155,8 @@
    the canvas and the surfaces below share `var(--el-surface)`, which is the whole
    neumorphic illusion. Palette-derived (no hue of its own). */
 @scope ([data-style='neumorphism']) to ([data-style]) {
-  body {
+  body,
+  [data-app-shell] {
     background-color: var(--el-surface);
   }
 }
@@ -2081,7 +2347,8 @@
    to the palette. Painted as the body's own background (always behind content),
    the proven 3D/Immersive atmosphere approach. */
 @scope ([data-style='retrofuturism']) to ([data-style]) {
-  body {
+  body,
+  [data-app-shell] {
     background-image:
       linear-gradient(
         180deg,
@@ -2105,16 +2372,41 @@
   }
 }
 
+/* ⚠️ THE SHELL BECOMES A STACKING CONTEXT — the one place the shell-canvas
+   pairing needs more than a second selector (MOTIR-4234). The grid floor below
+   is `position: fixed; z-index: -1`, and both shell roots are `relative` with
+   `z-index: auto`, so they establish NO stacking context: a negative-z-index
+   descendant of the shell would be painted into the ROOT stacking context, at
+   the step BEFORE positioned elements — i.e. behind the shell's own background,
+   which is exactly where `body::after` already is and exactly why the floor was
+   invisible on every signed-in route. `isolation: isolate` makes the shell its
+   own context, so its `::after` resolves INSIDE it: above the shell canvas
+   (step 1) and below all shell content (step 3 onwards), which is the
+   disposition the floor is designed for.
+
+   Scoped to retrofuturism, because it is the only style with a canvas LAYER
+   below content; the shell is left alone under every other style. It creates no
+   containing block, so the `position: fixed` floor still resolves against the
+   viewport and the shell's `overflow: hidden` does not clip it. */
+@scope ([data-style='retrofuturism']) to ([data-style]) {
+  [data-app-shell] {
+    isolation: isolate;
+  }
+}
+
 /* The Outrun GRID FLOOR — a receding neon grid below the horizon. A separate
-   fixed layer (`body::after`) so it can be perspective-tilted and masked to fade
+   fixed layer (`body::after`, and `[data-app-shell]::after` for the signed-in
+   shell — the pairing above) so it can be perspective-tilted and masked to fade
    into the horizon; `z-index: -1` keeps it BEHIND all app content (above only the
-   body's own sky background), so it textures the floor without ever covering the
-   UI. Lines are `color-mix()` over `--el-*` accents (palette-derived, no hue of
-   their own); the mask uses the achromatic `black` keyword (no hex). The grid is
-   STATIC depth — like 3D/Immersive's atmosphere it carries the identity, so it is
-   not motion-gated (there is no animation to suppress). */
+   sky background of whichever of the two is painting), so it textures the floor
+   without ever covering the UI. Lines are `color-mix()` over `--el-*` accents
+   (palette-derived, no hue of their own); the mask uses the achromatic `black`
+   keyword (no hex). The grid is STATIC depth — like 3D/Immersive's atmosphere it
+   carries the identity, so it is not motion-gated (there is no animation to
+   suppress). */
 @scope ([data-style='retrofuturism']) to ([data-style]) {
-  body::after {
+  body::after,
+  [data-app-shell]::after {
     content: '';
     position: fixed;
     left: -30%;
@@ -2393,6 +2685,378 @@
   }
 }
 
+/* ─────────────────────────────────────────────────────────────────────────
+   THE HERO AI CONTROL, PER STYLE (drawn by MOTIR-4742, wired by MOTIR-4743).
+
+   The two controls that summon the planning workspace — the header pill
+   (`components/planning/PlanWithAILauncher.tsx`) and the floating M orb
+   (`components/planning/PlanWithAIFab.tsx`) — are the product's headline
+   affordance and the sanctioned exception to the flat-button norm
+   (`design/ai-chat/design-notes.md` § *The hero control is STYLE-AWARE*). Each
+   style gives them its own material. Before this section they rendered
+   byte-identically under all eleven: the hook the design prescribed was emitted
+   nowhere and the fill was painted inline, where no rule can reach it.
+
+   ── TWO ATTRIBUTES, AND THE SECOND IS LOAD-BEARING ─────────────────────────
+   `data-ai-cta` distinguishes the two because they do not share a fill recipe:
+   the orb's `radial-gradient` first stop is `--orb-lit-mix`, a guarded contrast
+   knob (MOTIR-3207, `tests/theme/orb-glyph-contrast.test.ts`), and a shared
+   `background-image` would silently overwrite it. So the shape-agnostic
+   properties — border, outer glow, type, ink — are written on
+   `[data-surface='ai-cta']`, and every FILL under `[data-ai-cta='pill']` or
+   `[data-ai-cta='orb']`.
+
+   ── THE TWO INLINE-DECLARED PROPERTIES TRAVEL ON CUSTOM PROPERTIES ─────────
+   The components declare exactly two things in an inline `style` prop —
+   `background-image` and `box-shadow` — and an inline declaration beats every
+   stylesheet rule. So BOTH are read through a `var()` seam:
+   `background-image: var(--plan-hero-fill, <the base recipe>)` (MOTIR-4743) and
+   `box-shadow: var(--plan-hero-shadow, <the base look>)` (MOTIR-3522), with the
+   orb's twins beside them.
+
+   `design/ai-chat/design-notes.md` § *The CSS, verbatim* writes each treatment
+   as plain `background-image` / `box-shadow` declarations. Both are transcribed
+   here onto those four variables, because written literally they would be
+   **INERT** — which is the very defect this section exists to close, one
+   property over. It is the same mechanism the design's own row 8 relies on and
+   the only one consistent with its "Warm Editorial has no block by design"
+   decision: painting the base in a `warm-editorial` block instead would give the
+   Tier-0 base a second copy of its own recipe to drift from.
+
+   ⚠️ THE SHADOW HALF WAS MEASURED, NOT REASONED. `tests/e2e/hero-ai-control-styles.spec.ts`
+   compares every style against the base in a real browser, and with the shadows
+   written literally exactly ONE control came back byte-identical to the base:
+   the AURORA ORB — the only one whose row sets nothing but a shadow. Every other
+   style also moves a fill, a border or the type, so its rule "worked" while its
+   shadow silently did not. A source-reading review passes that; the render does
+   not.
+
+   A shared `[data-surface='ai-cta']` rule sets BOTH shadow variables, since the
+   design gives the pill and the orb the same shadow and each control reads only
+   its own name. Everything the components do NOT declare inline —
+   `background-color`, `background-size`, `background-position`,
+   `background-repeat`, `border`, `backdrop-filter`, the type properties — is
+   written exactly as the design states it.
+
+   Radius, padding and height are NOT set here: they already flow through
+   `--radius-badge` / `--spacing-btn-x` / `--height-btn-md`, and re-stating them
+   would freeze the one axis that was already working. Palette-derived
+   throughout — `color-mix()` over `--el-*`, no raw hex — so a `data-palette`
+   swap re-tints all eleven treatments. Every label ratio in the design's table
+   was measured on the painted pixel; the tightest is glassmorphism at 4.87:1.
+   ───────────────────────────────────────────────────────────────────────── */
+
+/* 1 · Warm Editorial — NO BLOCK, by design. It is the Tier-0 base, and the
+   components' own `var()` fallbacks ARE its treatment; a block repeating them
+   would be a second copy to drift. */
+
+/* 2 · Soft / Playful — pillowy stacked shadow, no border. */
+@scope ([data-style='soft-playful']) to ([data-style]) {
+  [data-surface='ai-cta'] {
+    font-weight: 800;
+    --plan-hero-shadow:
+      0 7px 0 -1px color-mix(in srgb, var(--el-accent) 22%, var(--el-page-bg)),
+      0 14px 22px -6px color-mix(in srgb, var(--el-accent) 55%, transparent);
+    --plan-orb-shadow:
+      0 7px 0 -1px color-mix(in srgb, var(--el-accent) 22%, var(--el-page-bg)),
+      0 14px 22px -6px color-mix(in srgb, var(--el-accent) 55%, transparent);
+  }
+}
+
+/* 3 · Swiss / Minimal-Flat — flat solid, sharp, uppercase, NO shadow. */
+@scope ([data-style='swiss-minimal-flat']) to ([data-style]) {
+  [data-surface='ai-cta'] {
+    --plan-hero-shadow: none;
+    --plan-orb-shadow: none;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.07em;
+  }
+}
+@scope ([data-style='swiss-minimal-flat']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='pill'] {
+    --plan-hero-fill: none;
+    background-color: var(--el-accent);
+  }
+}
+
+/* 4 · Glassmorphism — frosted translucency over the rim. 86% is a FLOOR, not a
+   preference: white is the lightest backdrop the light theme can put behind it,
+   so 86% accent composited over anything measures >= 4.87:1. */
+@scope ([data-style='glassmorphism']) to ([data-style]) {
+  [data-surface='ai-cta'] {
+    border: 1px solid var(--glass-rim);
+    -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
+    backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
+    --plan-hero-shadow:
+      inset 0 1px 0 var(--glass-rim),
+      0 8px 22px -6px color-mix(in srgb, var(--el-accent) 45%, transparent);
+    --plan-orb-shadow:
+      inset 0 1px 0 var(--glass-rim),
+      0 8px 22px -6px color-mix(in srgb, var(--el-accent) 45%, transparent);
+  }
+}
+@scope ([data-style='glassmorphism']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='pill'] {
+    --plan-hero-fill: none;
+    background-color: color-mix(in srgb, var(--el-accent) 86%, transparent);
+  }
+}
+@scope ([data-style='glassmorphism']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='orb'] {
+    /* Crown-confined: across the whole circle this sheen lightens the 26/56
+       glyph box to 3.17:1 light / 2.67:1 dark and breaks the `--orb-lit-mix`
+       floor the style layer may not touch. Confined, it measures the shipped
+       3.78:1 / 3.10:1 — identical to no sheen at all. */
+    background-size:
+      100% 20%,
+      100% 100%;
+    background-position:
+      top left,
+      top left;
+    background-repeat: no-repeat;
+    --plan-orb-fill:
+      linear-gradient(160deg, var(--glass-sheen), transparent 90%),
+      radial-gradient(
+        circle at 33% 27%,
+        color-mix(in srgb, var(--el-accent-text) var(--orb-lit-mix), var(--el-accent)),
+        var(--el-accent) 56%,
+        color-mix(in srgb, var(--el-accent) 68%, var(--el-highlight))
+      );
+  }
+}
+
+/* 5 · Neo-Brutalism — hard 2px border + zero-blur offset shadow. */
+@scope ([data-style='neo-brutalism']) to ([data-style]) {
+  [data-surface='ai-cta'] {
+    border: 2px solid var(--el-text);
+    --plan-hero-shadow: 4px 4px 0 0 var(--el-text);
+    --plan-orb-shadow: 4px 4px 0 0 var(--el-text);
+    font-weight: 800;
+    text-transform: uppercase;
+  }
+}
+@scope ([data-style='neo-brutalism']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='pill'] {
+    --plan-hero-fill: none;
+    background-color: var(--el-accent);
+  }
+}
+
+/* 6 · Cybercore / Y2K — dark HUD ground, neon halo, mono label. The mixes toward
+   the achromatic `black` KEYWORD are sanctioned by this style's own material
+   layer, which uses them to read as lightness rather than as a hue, so the
+   palette axis stays disjoint. */
+@scope ([data-style='cybercore-y2k']) to ([data-style]) {
+  [data-surface='ai-cta'] {
+    border: 1px solid color-mix(in srgb, var(--el-highlight) 70%, transparent);
+    --plan-hero-shadow:
+      0 0 10px color-mix(in srgb, var(--el-highlight) 60%, transparent),
+      0 0 26px -4px color-mix(in srgb, var(--el-accent) 70%, transparent);
+    --plan-orb-shadow:
+      0 0 10px color-mix(in srgb, var(--el-highlight) 60%, transparent),
+      0 0 26px -4px color-mix(in srgb, var(--el-accent) 70%, transparent);
+    font-family: var(--font-mono);
+    letter-spacing: 0.04em;
+  }
+}
+@scope ([data-style='cybercore-y2k']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='pill'] {
+    --plan-hero-fill: linear-gradient(
+      135deg,
+      color-mix(in srgb, var(--el-accent) 88%, black),
+      color-mix(in srgb, color-mix(in srgb, var(--el-accent) 70%, var(--el-highlight)) 78%, black)
+    );
+  }
+}
+@scope ([data-style='cybercore-y2k']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='orb'] {
+    --plan-orb-fill:
+      linear-gradient(
+        160deg,
+        color-mix(in srgb, var(--el-highlight) 22%, transparent),
+        transparent 55%
+      ),
+      radial-gradient(
+        circle at 33% 27%,
+        color-mix(in srgb, var(--el-accent-text) var(--orb-lit-mix), var(--el-accent)),
+        var(--el-accent) 56%,
+        color-mix(in srgb, var(--el-accent) 68%, var(--el-highlight))
+      );
+  }
+}
+
+/* 7 · Aurora — lit from within, colour halo, no hard shadow. */
+@scope ([data-style='aurora']) to ([data-style]) {
+  [data-surface='ai-cta'] {
+    --plan-hero-shadow:
+      inset 0 1px 0 color-mix(in srgb, var(--el-accent-text) var(--aurora-sheen), transparent),
+      0 0 26px -2px color-mix(in srgb, var(--el-accent) var(--aurora-glow), transparent),
+      0 0 40px -6px color-mix(in srgb, var(--el-highlight) var(--aurora-glow), transparent);
+    --plan-orb-shadow:
+      inset 0 1px 0 color-mix(in srgb, var(--el-accent-text) var(--aurora-sheen), transparent),
+      0 0 26px -2px color-mix(in srgb, var(--el-accent) var(--aurora-glow), transparent),
+      0 0 40px -6px color-mix(in srgb, var(--el-highlight) var(--aurora-glow), transparent);
+  }
+}
+@scope ([data-style='aurora']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='pill'] {
+    background-size:
+      100% 28%,
+      100% 100%;
+    background-position:
+      top left,
+      top left;
+    background-repeat: no-repeat;
+    --plan-hero-fill:
+      linear-gradient(
+        180deg,
+        color-mix(in srgb, var(--el-accent-text) var(--aurora-sheen), transparent),
+        transparent 90%
+      ),
+      linear-gradient(
+        135deg,
+        var(--el-accent),
+        color-mix(in srgb, var(--el-accent) 86%, var(--el-highlight))
+      );
+  }
+}
+
+/* 8 · 3D / Immersive — NOTHING. `--plan-hero-shadow` / `--plan-orb-shadow` own
+   this control's depth and the components read them through a `var()` seam an
+   inline `box-shadow` would otherwise beat (MOTIR-3522). A rule here would
+   either lose to that inline declaration or take a `data-depth="key"` control
+   off the plane ladder it is declared on (docs/styles/3d-immersive.md §4 / §4b).
+   Deliberately empty — recorded so the absence reads as a decision, not an
+   omission. */
+
+/* 9 · Hand-Drawn / Indie — a drawn ink outline + a hand-placed offset.
+   ⚠️ THE `position: relative` IS GUARDED, where the design's transcription
+   states it bare. The orb is `.fixed`, and a fixed element is already a
+   containing block for its own `::after`; re-declaring it `relative` would drop
+   the orb out of fixed positioning entirely. Same `:not(.fixed):not(.absolute)
+   :not(.sticky)` guard this style's own `.border` rule carries, for the same
+   reason it carries it. */
+@scope ([data-style='hand-drawn-indie']) to ([data-style]) {
+  [data-surface='ai-cta']:not(.fixed):not(.absolute):not(.sticky) {
+    position: relative;
+  }
+}
+@scope ([data-style='hand-drawn-indie']) to ([data-style]) {
+  [data-surface='ai-cta'] {
+    font-weight: 700;
+    --plan-hero-shadow: 3px 4px 0 -1px color-mix(in srgb, var(--el-border-strong) 55%, transparent);
+    --plan-orb-shadow: 3px 4px 0 -1px color-mix(in srgb, var(--el-border-strong) 55%, transparent);
+  }
+}
+@scope ([data-style='hand-drawn-indie']) to ([data-style]) {
+  [data-surface='ai-cta']::after {
+    content: '';
+    position: absolute;
+    inset: -1px;
+    pointer-events: none;
+    border: 2px solid var(--el-border-strong);
+    border-radius: inherit;
+    filter: url(#hd-rough);
+  }
+}
+
+/* 10 · Neumorphism — moulded, NOT raised-and-glowing: no gradient, no glow, and
+   the hairline is KEPT (structure never relies on shadow alone). */
+@scope ([data-style='neumorphism']) to ([data-style]) {
+  [data-surface='ai-cta'] {
+    border: 1px solid color-mix(in srgb, var(--el-accent) 70%, var(--el-text));
+    --plan-hero-shadow:
+      var(--neu-distance) var(--neu-distance) var(--neu-blur) var(--neu-shadow),
+      calc(var(--neu-distance) * -1) calc(var(--neu-distance) * -1) var(--neu-blur) var(--neu-light);
+    --plan-orb-shadow:
+      var(--neu-distance) var(--neu-distance) var(--neu-blur) var(--neu-shadow),
+      calc(var(--neu-distance) * -1) calc(var(--neu-distance) * -1) var(--neu-blur) var(--neu-light);
+  }
+}
+@scope ([data-style='neumorphism']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='pill'] {
+    --plan-hero-fill: none;
+    background-color: var(--el-accent);
+  }
+}
+@scope ([data-style='neumorphism']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='orb'] {
+    --plan-orb-fill: none;
+    background-color: var(--el-accent);
+  }
+}
+
+/* 11 · Retrofuturism — a chrome bevel + a CROWN-CONFINED specular streak.
+   ⚠️ THE STREAK IS THE THING THAT HAD TO MOVE, not the bevel. Across the full
+   box the diagonal at `--retro-spec` washes the label to 2.55:1 light / 2.22:1
+   dark, and thinning it does not rescue it (18% still measures 3.67:1 dark, by
+   which point the chrome has stopped reading). Sized to the top band it sits
+   above the cap height, the label sits on the bevel BODY at 6.76:1 / 5.16:1, and
+   the chrome still reads — a machined bevel IS a vertical light-to-dark ramp
+   with a highlight on the crown. The `white` / `black` keywords are this style's
+   own sanctioned lightness mixes, not a hue. */
+@scope ([data-style='retrofuturism']) to ([data-style]) {
+  [data-surface='ai-cta'] {
+    border: 1px solid color-mix(in srgb, var(--el-accent-text) 30%, transparent);
+    --plan-hero-shadow:
+      inset 0 1px 0 color-mix(in srgb, var(--el-accent-text) var(--retro-bevel-light), transparent),
+      0 0 24px -4px color-mix(in srgb, var(--el-accent) var(--retro-glow), transparent);
+    --plan-orb-shadow:
+      inset 0 1px 0 color-mix(in srgb, var(--el-accent-text) var(--retro-bevel-light), transparent),
+      0 0 24px -4px color-mix(in srgb, var(--el-accent) var(--retro-glow), transparent);
+  }
+}
+@scope ([data-style='retrofuturism']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='pill'] {
+    background-size:
+      100% 28%,
+      100% 100%;
+    background-position:
+      top left,
+      top left;
+    background-repeat: no-repeat;
+    --plan-hero-fill:
+      linear-gradient(
+        104deg,
+        transparent 30%,
+        color-mix(in srgb, var(--el-accent-text) var(--retro-spec), transparent) 46%,
+        transparent 62%
+      ),
+      linear-gradient(
+        180deg,
+        color-mix(in srgb, var(--el-accent) 82%, white) 0%,
+        var(--el-accent) 20%,
+        color-mix(in srgb, var(--el-accent) 84%, black) 100%
+      );
+  }
+}
+@scope ([data-style='retrofuturism']) to ([data-style]) {
+  [data-surface='ai-cta'][data-ai-cta='orb'] {
+    /* Crown-confined, for the same reason as glass: unbounded it measures
+       3.34:1 light / 2.78:1 dark inside the glyph box. */
+    background-size:
+      100% 26%,
+      100% 100%;
+    background-position:
+      top left,
+      top left;
+    background-repeat: no-repeat;
+    --plan-orb-fill:
+      linear-gradient(
+        180deg,
+        color-mix(in srgb, var(--el-accent-text) var(--retro-bevel-light), transparent),
+        transparent 90%
+      ),
+      radial-gradient(
+        circle at 33% 27%,
+        color-mix(in srgb, var(--el-accent-text) var(--orb-lit-mix), var(--el-accent)),
+        var(--el-accent) 56%,
+        color-mix(in srgb, var(--el-accent) 68%, var(--el-highlight))
+      );
+  }
+}
+
 /* ─────────────────────────────────────────────────────────────────────────
    Style-preview vignette material canvas (7.3.37 / MOTIR-1050).
    The StyleVignette preview specimen carries its OWN axis attribute on a
@@ -2750,10 +3414,27 @@
   --el-label-4: var(--color-tint-lavender);
   --el-label-5: var(--color-tint-sky);
   --el-label-6: var(--color-tint-yellow);
-  /* Avatar ramp — KEEP the named keys (peach…yellow): lib/projects/avatar.ts persists
-     project.avatarColor ∈ these strings, so numbering them would break stored rows
-     (spec §7.1, rung-2 migration safety). The fallback fixes --el-type-* misuse #2 —
-     the mono initials tile keeps its blue but stops borrowing --el-type-task. */
+  /* Avatar ramp — KEEP the named keys (peach…yellow): they are addressed BY NAME, as
+     literal `bg-(--el-avatar-<key>)` class strings, by
+     `app/(authed)/triage/_components/TriageAvatar.tsx` (a hash of the display name
+     indexes a fixed six-entry array — its ORDER is load-bearing too) and by the
+     `--el-avatar-fallback` initial tiles in
+     `app/(authed)/settings/workspace/_components/gitSettingsPrimitives.tsx` and
+     `app/(authed)/settings/project/code-access/_components/CodeAccessSettings.tsx`.
+     `app/tokens/page.tsx` enumerates all seven. Numbering them would break those
+     lookups, and Tailwind cannot rewrite an arbitrary-value class it never sees.
+     ⚠️ Until MOTIR-4344 this comment reached the same conclusion from MIGRATION
+     safety instead: a module under `lib/projects/` was said to persist a per-project
+     colour column whose values were these key names, so numbering them would break
+     stored rows (spec §7.1, rung-2). Both halves of that warrant went in MOTIR-2680
+     (commit c73fb9112, 2026-08-11, landed in #2046) —
+     `prisma/migrations/20260811223000_drop_project_preset_avatar/migration.sql` drops
+     the column outright ("The values are LOST, deliberately") and the same change
+     deleted the module. The CONCLUSION survived its warrant; the warrant above is the
+     one that is true today. Neither dead address is repeated here on purpose — a
+     citation is only worth as much as the thing it addresses. The fallback fixes
+     --el-type-* misuse #2 — the mono initials tile keeps its blue but stops
+     borrowing --el-type-task. */
   --el-avatar-peach: var(--color-tint-peach);
   --el-avatar-rose: var(--color-tint-rose);
   --el-avatar-mint: var(--color-tint-mint);
@@ -2770,8 +3451,9 @@
   --el-notif-commented: var(--color-info); /* was --el-type-task */
   --el-notif-assigned: var(--color-accent-green); /* was --el-type-story */
   --el-notif-transitioned: var(--color-accent-teal); /* was --el-type-subtask */
-  /* The EXECUTOR badge on a Home row's assignee avatar (Story MOTIR-2649 ·
-     Subtask MOTIR-2653, per design/home/design-notes.md §"The agent state").
+  /* The EXECUTOR badge on a Workbench row's assignee avatar (Story MOTIR-2649 ·
+     Subtask MOTIR-2653, per design/workbench/design-notes.md §"The agent state"
+     — that area was renamed with the surface by MOTIR-4779).
      Same mapping form as --el-notif-mentioned above and for the same reason:
      it resolves to the accent fill today, but owning its own slot means a
      palette can move agent badges without dragging the CTA with them. The
@@ -3113,7 +3795,7 @@
 
    Not part of the Tier-3 layer above and deliberately not named `--el-*`:
    that layer is a COLOUR contract (every member aliases a Tier-0 --color-*
-   and is asserted palette-dependent by tests/theme/paletteTokenCoverage).
+   and is asserted palette-dependent by tests/theme/paletteTokenCoverage.test.ts).
    A knob here is a NUMBER inside a color-mix() — one value for every
    palette and both themes — so it fails both halves of that contract while
    being exactly the thing that has to be expressed once.
@@ -3175,7 +3857,7 @@
    `@layer utilities`; this rule is UNLAYERED, and an unlayered declaration
    outranks a layered one whatever their specificity. That is the whole of the
    mechanism — it does not depend on source order or on this file's position in
-   the `@import` list. Measured, not reasoned: tests/theme/reducedMotionSpinner
+   the `@import` list. Measured, not reasoned: tests/theme/reducedMotionSpinner.test.ts
    reads it back off the COMPILED stylesheet for both consumer shapes.
    ═══════════════════════════════════════════════════════════════════════ */
 @media (prefers-reduced-motion: reduce) {