@waveso/ui 0.4.1 → 0.6.0

package/dist/styles.css

@@ -6,16 +6,12 @@
  *   @import 'tailwindcss';
  *   @import '@waveso/ui/styles.css';
  *
- * This brings the `tw-animate-css` keyframe utilities the components
- * rely on, the `dark` variant, every theme token (override in your own
- * :root / .dark), motion tokens + recipes, and the `@source` rule. No
- * other library-related imports needed.
+ * This brings the `dark` variant, every theme token (override in your own
+ * :root / .dark), motion tokens + recipes, the few self-hosted keyframe
+ * utilities the components need, and the `@source` rule. No other
+ * library-related imports needed — zero runtime dependencies.
  */
 
-/* Keyframe animation utilities used by popup components
- * (`data-open:animate-in`, `fade-in-0`, `zoom-in-95`, etc.). */
-@import "tw-animate-css";
-
 /* Auto-register component source files so Tailwind generates CSS for all
  * utility classes used by @waveso/ui components. Resolves relative to this
  * file's location in node_modules/@waveso/ui/dist/. */
@@ -29,33 +25,87 @@
  * ------------------------------------------------------------------------- */
 
 :root {
-  /* Core */
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-
-  /* Brand */
-  --primary: oklch(0.488 0.243 264.376);
-  --primary-foreground: oklch(0.97 0.014 254.604);
-  --secondary: oklch(0.967 0.001 286.375);
-  --secondary-foreground: oklch(0.21 0.006 285.885);
-  --accent: oklch(0.488 0.243 264.376);
-  --accent-foreground: oklch(0.97 0.014 254.604);
-
-  /* Neutral */
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
+  /* ========================================================================
+   * Palettes — raw primitives. No `--color-` prefix on purpose: these live in
+   * `:root`, not `@theme`, so they generate NO utilities (no `bg-ion-300`).
+   * They're referenced by the semantic tokens below, never used directly.
+   * ====================================================================== */
+
+  /* Ion — neutral ramp */
+  --ion-50:  #FAFAFB;
+  --ion-100: #F3F3F4;
+  --ion-200: #E5E5E8;
+  --ion-300: #D1D2D7;
+  --ion-400: #ABACB2;
+  --ion-500: #8B8C94;
+  --ion-600: #6C6D76;
+  --ion-700: #4C4D55;
+  --ion-800: #3B3C44;
+  --ion-900: #323339;
+  --ion-950: #2C2D32;
+
+  /* Wave — brand ramp */
+  --wave-50:  #EEF3FF;
+  --wave-100: #DCE6FF;
+  --wave-200: #B8C9FF;
+  --wave-300: #8FA8FF;
+  --wave-400: #6A8DFF;
+  --wave-500: #315FE8;
+  --wave-600: #274FC7;
+  --wave-700: #1C3F96;
+  --wave-800: #142B69;
+  --wave-900: #0D1C46;
+  --wave-950: #061237;
+
+  /* ========================================================================
+   * Semantic tokens — light (default). The spec's `.light` block lives in
+   * `:root` so consumers get the light theme without needing a `.light` class.
+   * ====================================================================== */
+
+  /* Backgrounds = elevation */
+  --foundation: var(--ion-200);
+  --surface: var(--ion-100);
+  --elevated: var(--ion-50);
+
+  /* Contrast = emphasis — highest-contrast text → muted → soft. */
+  --contrast: var(--ion-950);
+  --muted: var(--ion-600);
+  --soft: var(--ion-500);
+
+  /* Inverse — an inverted neutral pair (e.g. the dark tooltip). Aliases, so
+   * they auto-flip with `.dark` (var() re-resolves at the use site). */
+  --surface-inverse: var(--contrast);
+  --contrast-inverse: var(--foundation);
+
+  /* Brand — `primary` wired to the Wave ramp; `secondary` is the neutral fill
+   * (secondary/ghost buttons, hovers, selected) at ion-300; `accent` is the
+   * magenta. No per-fill on-color tokens: text on the saturated fills is
+   * `text-white`, text on the neutral `secondary` is `text-contrast`. */
+  --primary: var(--wave-500);
+  --secondary: var(--ion-300);
+  --accent: #9A466A;
+
+  /* Borders = structure */
+  --line: rgba(44, 45, 50, 0.055);
+  --edge: rgba(44, 45, 50, 0.11);
+  --solid: var(--ion-300);
+
+  /* Rings = brand themed */
+  --focus: var(--primary);
+
+  /* Shadow — two dials for the layered `shadow-*` scale: `--shadow-color` (HSL
+   * components — a deep cool-tinted near-black, never pure #000 which reads
+   * heavy) and `--shadow-strength` (per-layer alpha / intensity). Both resolve
+   * per :root/.dark, so retinting OR dimming every shadow is one token. For a
+   * colored surface set a named tint, e.g. `--shadow-color-primary`. */
+  --shadow-color: 220deg 45% 6%;
+  --shadow-strength: 0.22;
 
   /* Status */
-  --destructive: oklch(0.58 0.22 27);
-  --success: oklch(0.59 0.18 163);
-  --warning: oklch(0.75 0.18 85);
+  --destructive: oklch(0.63 0.22 27);
+  --success: oklch(0.72 0.19 145);
+  --warning: oklch(0.82 0.17 85);
+  --info: oklch(0.62 0.18 250);
 
   /* Charts */
   --chart-1: oklch(0.809 0.105 251.813);
@@ -70,16 +120,6 @@
   --presence-busy: oklch(0.63 0.22 27);
   --presence-invisible: oklch(0.55 0 0);
 
-  /* Sidebar */
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.145 0 0);
-  --sidebar-primary: oklch(0.546 0.245 262.881);
-  --sidebar-primary-foreground: oklch(0.97 0.014 254.604);
-  --sidebar-accent: oklch(0.488 0.243 264.376);
-  --sidebar-accent-foreground: oklch(0.97 0.014 254.604);
-  --sidebar-border: oklch(0.922 0 0);
-  --sidebar-ring: oklch(0.708 0 0);
-
   /* Radius */
   --radius: 0.625rem;
 
@@ -96,16 +136,33 @@
    * native / HIG behavior; real links keep their own pointer regardless. */
   --cursor-clickable: pointer;
 
-  /* Motion — tokens consumed by the `motion-*` recipes (see Utilities).
-   * Override any value in your own :root. `prefers-reduced-motion` zeroes
-   * them in one block (bottom of file), so every recipe collapses safely. */
-  --duration: 250ms;
-  --ease: ease-out;                            /* default — fade/blur, no transform */
-  --spring: cubic-bezier(0.34, 1.45, 0.64, 1); /* only with translate/scale */
-  --blur: 2px;      /* enter/exit blur amount     */
-  --scale: 0.97;    /* enter/exit scale-down       */
-  --offset: 4px;    /* enter/exit translate offset */
-  --stagger: 70ms;  /* per-item list delay         */
+  /* Motion — tokens consumed by the `motion-*` recipes (see Utilities). Override
+   * any value in your own :root. `prefers-reduced-motion` zeroes them (bottom of
+   * file), so every recipe collapses safely.
+   *
+   * THE SYSTEM — 5 scalable magnitudes × 3 tiers (sm/md/lg) + 1 fixed signature:
+   *   scalable → --duration · --blur · --scale · --offset · --stagger
+   *   fixed    → --ease (the one curve — never tiered)
+   *   tiers    → sm = controls/icons · md = popups · lg = dialogs
+   * sm/lg zoom in place; md also slides. `--offset`/`--stagger` sm+lg are
+   * defined ahead of use (wired per surface as we build them out). */
+  --ease: cubic-bezier(0.22, 1, 0.36, 1); /* the one curve — never tiered */
+
+  --duration-sm: 150ms;  /* controls, icons */
+  --duration-md: 200ms;  /* popups          */
+  --duration-lg: 250ms;  /* dialogs         */
+  --blur-sm: 2px;
+  --blur-md: 4px;
+  --blur-lg: 8px;
+  --scale-sm: 0.95;
+  --scale-md: 0.9;
+  --scale-lg: 0.85;
+  --offset-sm: 2px;      /* item/icon nudge */
+  --offset-md: 4px;      /* popup slide     */
+  --offset-lg: 8px;
+  --stagger-sm: 30ms;    /* list-item delay */
+  --stagger-md: 60ms;
+  --stagger-lg: 90ms;
 }
 
 /* ---------------------------------------------------------------------------
@@ -113,33 +170,36 @@
  * ------------------------------------------------------------------------- */
 
 .dark {
-  /* Core */
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.205 0 0);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.205 0 0);
-  --popover-foreground: oklch(0.985 0 0);
-
-  /* Brand */
-  --primary: oklch(0.42 0.18 266);
-  --primary-foreground: oklch(0.97 0.014 254.604);
-  --secondary: oklch(0.274 0.006 286.033);
-  --secondary-foreground: oklch(0.985 0 0);
-  --accent: oklch(0.42 0.18 266);
-  --accent-foreground: oklch(0.97 0.014 254.604);
-
-  /* Neutral */
-  --muted: oklch(0.269 0 0);
-  --muted-foreground: oklch(0.708 0 0);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.556 0 0);
+  /* Backgrounds = elevation */
+  --foundation: var(--ion-950);
+  --surface: var(--ion-900);
+  --elevated: var(--ion-800);
+
+  /* Contrast = emphasis */
+  --contrast: var(--ion-100);
+  --muted: var(--ion-400);
+  --soft: var(--ion-600);
+
+  /* Brand — only `secondary` differs from light; mirrored to ion-700 so the
+   * neutral fill stands out against the dark surfaces. primary / accent /
+   * inverse / focus auto-flip or stay constant via the `:root` definitions. */
+  --secondary: var(--ion-700);
+
+  /* Borders = structure */
+  --line: rgba(246, 246, 241, 0.045);
+  --edge: rgba(246, 246, 241, 0.12);
+  --solid: var(--ion-700);
+
+  /* Shadow — darker tint, lower strength: a near-black shadow on a dark
+   * surface reads heavier than on white, so dim it. */
+  --shadow-color: 220deg 40% 3%;
+  --shadow-strength: 0.18;
 
   /* Status */
-  --destructive: oklch(0.704 0.191 22.216);
-  --success: oklch(0.72 0.17 162);
-  --warning: oklch(0.82 0.17 85);
+  --destructive: oklch(0.65 0.2 27);
+  --success: oklch(0.65 0.17 145);
+  --warning: oklch(0.75 0.15 85);
+  --info: oklch(0.70 0.16 250);
 
   /* Charts */
   --chart-1: oklch(0.75 0.1 252);
@@ -153,52 +213,47 @@
   --presence-away: oklch(0.75 0.15 85);
   --presence-busy: oklch(0.65 0.2 27);
   --presence-invisible: oklch(0.6 0 0);
-
-  /* Sidebar */
-  --sidebar: oklch(0.205 0 0);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.623 0.214 259.815);
-  --sidebar-primary-foreground: oklch(0.97 0.014 254.604);
-  --sidebar-accent: oklch(0.42 0.18 266);
-  --sidebar-accent-foreground: oklch(0.97 0.014 254.604);
-  --sidebar-border: oklch(1 0 0 / 10%);
-  --sidebar-ring: oklch(0.556 0 0);
 }
 
 /* ---------------------------------------------------------------------------
  * Tailwind v4 theme mapping — maps CSS variables to Tailwind color tokens.
  * Consumers MUST include this for Tailwind classes like `bg-primary`,
- * `text-muted-foreground`, `border-sidebar-border` etc. to work.
+ * `text-muted`, `border-line` etc. to work.
  * ------------------------------------------------------------------------- */
 
 @theme inline {
-  /* Core */
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-
-  /* Brand */
+  /* Surfaces */
+  --color-foundation: var(--foundation);
+  --color-surface: var(--surface);
+  --color-elevated: var(--elevated);
+
+  /* Contrast / text — `contrast` (highest emphasis) → `muted` → `soft`. */
+  --color-contrast: var(--contrast);
+  --color-muted: var(--muted);
+  --color-soft: var(--soft);
+
+  /* Inverse — maps the `:root` inverse aliases to utilities. */
+  --color-surface-inverse: var(--surface-inverse);
+  --color-contrast-inverse: var(--contrast-inverse);
+
+  /* Brand — saturated fills use `text-white`, the neutral `secondary` uses
+   * `text-contrast`. No per-fill on-color tokens. */
   --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
   --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
   --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
 
-  /* Neutral */
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
+  /* Structure — `line` (faint divider), `edge` (input border), `solid` (opaque
+   * border), `focus` (brand-themed ring = primary). */
+  --color-line: var(--line);
+  --color-edge: var(--edge);
+  --color-solid: var(--solid);
+  --color-focus: var(--focus);
 
   /* Status */
   --color-destructive: var(--destructive);
   --color-success: var(--success);
   --color-warning: var(--warning);
+  --color-info: var(--info);
 
   /* Charts */
   --color-chart-1: var(--chart-1);
@@ -213,33 +268,45 @@
   --color-presence-busy: var(--presence-busy);
   --color-presence-invisible: var(--presence-invisible);
 
-  /* Sidebar */
-  --color-sidebar: var(--sidebar);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-ring: var(--sidebar-ring);
-
-  /* Radius */
-  --radius-xs: calc(var(--radius) - 6px);
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-  --radius-2xl: calc(var(--radius) + 8px);
-  --radius-3xl: calc(var(--radius) + 12px);
-  --radius-4xl: calc(var(--radius) + 16px);
+  /* Radius — 3-tier scale, spacing-aligned + concentric (outer = inner + one
+   * --spacing); synced 1:1 with the motion sm/md/lg tiers. `--spacing` is
+   * Tailwind-provided (0.25rem = 4px). */
+  --radius-sm: calc(var(--radius) - var(--spacing)); /* 6px  — small controls */
+  --radius-md: var(--radius);                        /* 10px — default (buttons, inputs, menus, popovers) */
+  --radius-lg: calc(var(--radius) + var(--spacing)); /* 14px — large surfaces (dialogs, drawers, cards) */
 
   /* Typography — passthroughs so consumers' `--font-sans` /
-   * `--font-geist-mono` flow through to Tailwind's `font-sans` /
+   * `--font-mono` flow through to Tailwind's `font-sans` /
    * `font-mono` utilities. */
   --font-sans: var(--font-sans);
   --font-mono: var(--font-mono);
 }
 
+/* Shadow scale — layered, tinted by `--shadow-color` and dimmed by
+ * `--shadow-strength` (both resolve per :root/.dark, so retinting or dimming
+ * every shadow is one token). Tiers differ by layer count + spread, not alpha.
+ * Overrides Tailwind's shadow-sm/md/lg. */
+@theme {
+  --shadow-sm:
+    0px 0.5px 0.7px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 0.8px 1px -1.2px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 2px 2.5px -2.5px hsl(var(--shadow-color) / var(--shadow-strength));
+  --shadow-md:
+    0px 0.5px 0.7px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 1.6px 2px -0.8px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 4.1px 5.2px -1.7px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 10px 12.6px -2.5px hsl(var(--shadow-color) / var(--shadow-strength));
+  --shadow-lg:
+    0px 0.5px 0.7px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 2.9px 3.7px -0.4px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 5.4px 6.8px -0.7px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 8.9px 11.2px -1.1px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 14.3px 18px -1.4px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 22.3px 28.1px -1.8px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 33.9px 42.7px -2.1px hsl(var(--shadow-color) / var(--shadow-strength)),
+    0px 50px 62.9px -2.5px hsl(var(--shadow-color) / var(--shadow-strength));
+}
+
 /* ---------------------------------------------------------------------------
  * Utilities
  * ------------------------------------------------------------------------- */
@@ -251,60 +318,256 @@
   cursor: var(--cursor-clickable);
 }
 
+/* `motion-color` — interaction-state transition for controls: smoothly
+ * animates color / background / border / ring (box-shadow) on hover, focus,
+ * pressed, checked, etc. Runs at the `sm` tier (controls are small + fast). A
+ * plain layered `@utility`, so the unlayered enter/exit recipes below win over
+ * it when both land on one element (e.g. a button that also carries `motion-scale-sm`). */
+@utility motion-color {
+  transition: color var(--duration-sm) var(--ease),
+              background-color var(--duration-sm) var(--ease),
+              border-color var(--duration-sm) var(--ease),
+              box-shadow var(--duration-sm) var(--ease);
+}
+
 /* Motion recipes — Base UI primitives emit `data-starting-style` (enter)
- * and `data-ending-style` (exit). Each recipe declares its `transition`,
- * resting state, and enter/exit state in one `@utility` (the `utilities`
- * layer) so `group-has` overrides (also utilities) win over the resting
- * state by normal cascade order. Co-locating `transition` here is only safe
- * because the library ships no `transition-all` — nothing else in the
- * utilities layer sets `transition` on a recipe-bearing element and clobbers
- * it. (If `transition-all` ever returns, these break; keep them specific.)
+ * and `data-ending-style` (exit). Each recipe's resting + enter/exit state
+ * lives in `@utility` (the `utilities` layer) so `group-has` overrides (also
+ * utilities) win over the resting state by normal cascade order.
+ *
+ * The `transition` is declared UNLAYERED (right after these blocks), NOT
+ * inside `@utility`. Recipes routinely sit on elements that ALSO carry a
+ * Tailwind `transition-*` utility — e.g. the combobox chevron is an
+ * `InputGroupButton`, i.e. a `Button` with `transition-[color,…]`. Both set
+ * the `transition` property; in the SAME layer the Button's wins and the
+ * recipe animates instantly (no transition — the bug this guards against).
+ * An unlayered declaration beats ANY layered `transition-*` per the CSS
+ * cascade, with NO `!important` (banned — see feedback_security). The
+ * resting/enter/exit declarations stay layered so `group-has` still wins.
  *
  * `0.001px` resting blur defeats Lightning CSS's `blur(0) → blur()`
  * minification (which emits invalid CSS); it is visually equivalent to 0. */
 
-/* `motion-fade` — opacity + blur. For simple show/hide on small surfaces. */
-@utility motion-fade {
-  transition: opacity var(--duration) var(--ease),
-              filter var(--duration) var(--ease);
-  filter: blur(0.001px);
+/* `motion-scrim` — opacity only, no blur. For full-screen backdrops: animating
+ * blur across the whole viewport janks (a flat dim shows none anyway). The
+ * scrim only fades its dim — the frosted-glass look comes from a STATIC
+ * `backdrop-filter` on the backdrop, faded by this opacity (not an animated
+ * `filter`, which is what would jank). */
+@utility motion-scrim {
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
-    filter: blur(var(--blur));
   }
 }
 
-/* `motion-scale` — opacity + blur + scale-down. For icon-sized targets. */
-@utility motion-scale {
-  transition: opacity var(--duration) var(--ease),
-              filter var(--duration) var(--ease),
-              scale var(--duration) var(--ease);
+/* Enter/exit recipes — THREE idioms, each tiered sm/md/lg.
+ *   `motion-scale-*` ZOOMs (opacity + blur + scale) — icons (sm), dialogs (lg).
+ *   `motion-slide-*` SLIDES (opacity + blur + directional translate) — popups (md).
+ *   `motion-fade-*`  FADES in place (opacity + blur, no transform).
+ * Tiers: sm = controls/icons · md = popups · lg = dialogs. Pick ONE idiom +
+ * tier per surface (don't compose — each declares its own unlayered transition).
+ * Companion idioms: `motion-color` (controls) and `motion-scrim` (backdrops). */
+@utility motion-scale-sm {
+  filter: blur(0.001px);
+  scale: 1;
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    filter: blur(var(--blur-sm));
+    scale: var(--scale-sm);
+  }
+}
+@utility motion-scale-md {
+  filter: blur(0.001px);
+  scale: 1;
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    filter: blur(var(--blur-md));
+    scale: var(--scale-md);
+  }
+}
+@utility motion-scale-lg {
   filter: blur(0.001px);
   scale: 1;
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
-    filter: blur(var(--blur));
-    scale: var(--scale);
+    filter: blur(var(--blur-lg));
+    scale: var(--scale-lg);
+  }
+}
+
+/* `motion-slide-*` — directional slide: the surface starts offset AWAY from its
+ * trigger's `data-[side]` (Base UI sets it) and settles toward it; default /
+ * side=bottom rises up. Opacity + blur + translate (`--offset-*`), NO scale. */
+@utility motion-slide-sm {
+  filter: blur(0.001px);
+  translate: 0;
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    filter: blur(var(--blur-sm));
+    translate: 0 var(--offset-sm);
+  }
+  &[data-side=top][data-starting-style],
+  &[data-side=top][data-ending-style] { translate: 0 calc(var(--offset-sm) * -1); }
+  &[data-side=left][data-starting-style],
+  &[data-side=left][data-ending-style],
+  &[data-side=inline-start][data-starting-style],
+  &[data-side=inline-start][data-ending-style] { translate: calc(var(--offset-sm) * -1) 0; }
+  &[data-side=right][data-starting-style],
+  &[data-side=right][data-ending-style],
+  &[data-side=inline-end][data-starting-style],
+  &[data-side=inline-end][data-ending-style] { translate: var(--offset-sm) 0; }
+}
+@utility motion-slide-md {
+  filter: blur(0.001px);
+  translate: 0;
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    filter: blur(var(--blur-md));
+    translate: 0 var(--offset-md); /* default + side=bottom: start lower, rise up */
+  }
+  &[data-side=top][data-starting-style],
+  &[data-side=top][data-ending-style] { translate: 0 calc(var(--offset-md) * -1); }
+  &[data-side=left][data-starting-style],
+  &[data-side=left][data-ending-style],
+  &[data-side=inline-start][data-starting-style],
+  &[data-side=inline-start][data-ending-style] { translate: calc(var(--offset-md) * -1) 0; }
+  &[data-side=right][data-starting-style],
+  &[data-side=right][data-ending-style],
+  &[data-side=inline-end][data-starting-style],
+  &[data-side=inline-end][data-ending-style] { translate: var(--offset-md) 0; }
+}
+@utility motion-slide-lg {
+  filter: blur(0.001px);
+  translate: 0;
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    filter: blur(var(--blur-lg));
+    translate: 0 var(--offset-lg);
+  }
+  &[data-side=top][data-starting-style],
+  &[data-side=top][data-ending-style] { translate: 0 calc(var(--offset-lg) * -1); }
+  &[data-side=left][data-starting-style],
+  &[data-side=left][data-ending-style],
+  &[data-side=inline-start][data-starting-style],
+  &[data-side=inline-start][data-ending-style] { translate: calc(var(--offset-lg) * -1) 0; }
+  &[data-side=right][data-starting-style],
+  &[data-side=right][data-ending-style],
+  &[data-side=inline-end][data-starting-style],
+  &[data-side=inline-end][data-ending-style] { translate: var(--offset-lg) 0; }
+}
+
+/* `motion-fade-*` — fade in place: opacity + blur, no transform. The signature
+ * blur-fade for content that should appear without moving or scaling. */
+@utility motion-fade-sm {
+  filter: blur(0.001px);
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    filter: blur(var(--blur-sm));
+  }
+}
+@utility motion-fade-md {
+  filter: blur(0.001px);
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    filter: blur(var(--blur-md));
+  }
+}
+@utility motion-fade-lg {
+  filter: blur(0.001px);
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    filter: blur(var(--blur-lg));
   }
 }
 
-/* `motion-rise` — opacity + blur + translate-y, spring ease. For larger
- * content surfaces (alerts, menus, cards) — spring overshoot only reads
- * with translate. */
-@utility motion-rise {
-  transition: opacity var(--duration) var(--spring),
-              filter var(--duration) var(--spring),
-              translate var(--duration) var(--spring);
+/* `motion-pop-md` — COMBINED idiom: scale + slide together (dropdowns "pop up
+ * while zooming"). The one surface that wants two idioms — so it's a single
+ * recipe with one transition. Don't try `motion-scale-md motion-slide-md`: their
+ * transitions collide and scale won't animate. md only (no sm/lg consumer). */
+@utility motion-pop-md {
   filter: blur(0.001px);
+  scale: 1;
   translate: 0;
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
-    filter: blur(var(--blur));
-    translate: 0 var(--offset);
+    filter: blur(var(--blur-md));
+    scale: var(--scale-md);
+    translate: 0 var(--offset-md); /* default + side=bottom: start lower, rise up */
   }
+  &[data-side=top][data-starting-style],
+  &[data-side=top][data-ending-style] { translate: 0 calc(var(--offset-md) * -1); }
+  &[data-side=left][data-starting-style],
+  &[data-side=left][data-ending-style],
+  &[data-side=inline-start][data-starting-style],
+  &[data-side=inline-start][data-ending-style] { translate: calc(var(--offset-md) * -1) 0; }
+  &[data-side=right][data-starting-style],
+  &[data-side=right][data-ending-style],
+  &[data-side=inline-end][data-starting-style],
+  &[data-side=inline-end][data-ending-style] { translate: var(--offset-md) 0; }
+}
+
+/* Recipe transitions — UNLAYERED on purpose (see note above): beats any
+ * layered `transition-*` utility on the same element without `!important`. */
+.motion-scrim {
+  transition: opacity var(--duration-lg) var(--ease);
+}
+.motion-scale-sm {
+  transition: opacity var(--duration-sm) var(--ease),
+              filter var(--duration-sm) var(--ease),
+              scale var(--duration-sm) var(--ease);
+}
+.motion-scale-md {
+  transition: opacity var(--duration-md) var(--ease),
+              filter var(--duration-md) var(--ease),
+              scale var(--duration-md) var(--ease);
+}
+.motion-scale-lg {
+  transition: opacity var(--duration-lg) var(--ease),
+              filter var(--duration-lg) var(--ease),
+              scale var(--duration-lg) var(--ease);
+}
+.motion-slide-sm {
+  transition: opacity var(--duration-sm) var(--ease),
+              filter var(--duration-sm) var(--ease),
+              translate var(--duration-sm) var(--ease);
+}
+.motion-slide-md {
+  transition: opacity var(--duration-md) var(--ease),
+              filter var(--duration-md) var(--ease),
+              translate var(--duration-md) var(--ease);
+}
+.motion-slide-lg {
+  transition: opacity var(--duration-lg) var(--ease),
+              filter var(--duration-lg) var(--ease),
+              translate var(--duration-lg) var(--ease);
+}
+.motion-fade-sm {
+  transition: opacity var(--duration-sm) var(--ease),
+              filter var(--duration-sm) var(--ease);
+}
+.motion-fade-md {
+  transition: opacity var(--duration-md) var(--ease),
+              filter var(--duration-md) var(--ease);
+}
+.motion-fade-lg {
+  transition: opacity var(--duration-lg) var(--ease),
+              filter var(--duration-lg) var(--ease);
+}
+.motion-pop-md {
+  transition: opacity   var(--duration-md) var(--ease),
+              filter    var(--duration-md) var(--ease),
+              scale     var(--duration-md) var(--ease),
+              translate var(--duration-md) var(--ease);
 }
 
 /* ---------------------------------------------------------------------------
@@ -312,10 +575,37 @@
  * ------------------------------------------------------------------------- */
 @media (prefers-reduced-motion: reduce) {
   :root {
-    --duration: 0ms;
-    --blur: 0px;
-    --scale: 1;
-    --offset: 0px;
-    --stagger: 0ms;
+    --duration-sm: 0ms; --duration-md: 0ms; --duration-lg: 0ms;
+    --blur-sm: 0px; --blur-md: 0px; --blur-lg: 0px;
+    --scale-sm: 1; --scale-md: 1; --scale-lg: 1;
+    --offset-sm: 0px; --offset-md: 0px; --offset-lg: 0px;
+    --stagger-sm: 0ms; --stagger-md: 0ms; --stagger-lg: 0ms;
   }
 }
+
+/* ---------------------------------------------------------------------------
+ * Keyframe utilities — self-hosted (replaces the former `tw-animate-css` dep,
+ * now removed). Only the three the library actually uses; `animate-spin` /
+ * `animate-pulse` come from Tailwind core. Registering via `@theme` generates
+ * the `animate-accordion-down` / `animate-accordion-up` / `animate-caret-blink`
+ * utilities. Accordion height runs on our motion tokens (`md` tier + the curve)
+ * and uses Base UI's `--accordion-panel-height` (the Radix var tw-animate
+ * targeted is never set under Base UI). Collapses under reduced motion via
+ * `--duration-md`. */
+@theme {
+  --animate-accordion-down: accordion-down var(--duration-md) var(--ease);
+  --animate-accordion-up: accordion-up var(--duration-md) var(--ease);
+  --animate-caret-blink: caret-blink 1.25s ease-out infinite;
+}
+@keyframes accordion-down {
+  from { height: 0; }
+  to { height: var(--accordion-panel-height); }
+}
+@keyframes accordion-up {
+  from { height: var(--accordion-panel-height); }
+  to { height: 0; }
+}
+@keyframes caret-blink {
+  0%, 70%, 100% { opacity: 1; }
+  20%, 50% { opacity: 0; }
+}