@flikk/ui 1.0.0-beta.31 → 1.0.0-beta.33

package/dist/utils/composeEventHandlers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Compose a component's own event handler with the consumer's.
+ *
+ * 🔴 §9: a prop the component also sets is MERGED, never clobbered. Spreading
+ * `{...rest}` before the element's own `onKeyUp` drops the consumer's handler
+ * silently; spreading it after lets the consumer silently replace load-bearing
+ * internal machinery. Composition is the only option that serves both.
+ *
+ * **Ours runs first**, so consumer code observes settled internal state.
+ *
+ * 🔴 **Both handlers ALWAYS run.** A `preventDefault()` in either does NOT skip
+ * the other — a consumer that cares reads `event.defaultPrevented`. Dropping the
+ * second handler conditionally would reintroduce the invisible-drop bug this
+ * helper exists to remove.
+ *
+ * @example
+ * <div onKeyUp={composeEventHandlers(syncFormatting, onKeyUpProp)} />
+ */
+export declare function composeEventHandlers<E>(ours: ((event: E) => void) | undefined, theirs: ((event: E) => void) | undefined): (event: E) => void;

package/dist/utils/composeEventHandlers.js

@@ -0,0 +1,26 @@
+/**
+ * Compose a component's own event handler with the consumer's.
+ *
+ * 🔴 §9: a prop the component also sets is MERGED, never clobbered. Spreading
+ * `{...rest}` before the element's own `onKeyUp` drops the consumer's handler
+ * silently; spreading it after lets the consumer silently replace load-bearing
+ * internal machinery. Composition is the only option that serves both.
+ *
+ * **Ours runs first**, so consumer code observes settled internal state.
+ *
+ * 🔴 **Both handlers ALWAYS run.** A `preventDefault()` in either does NOT skip
+ * the other — a consumer that cares reads `event.defaultPrevented`. Dropping the
+ * second handler conditionally would reintroduce the invisible-drop bug this
+ * helper exists to remove.
+ *
+ * @example
+ * <div onKeyUp={composeEventHandlers(syncFormatting, onKeyUpProp)} />
+ */
+function composeEventHandlers(ours, theirs) {
+    return (event) => {
+        ours === null || ours === void 0 ? void 0 : ours(event);
+        theirs === null || theirs === void 0 ? void 0 : theirs(event);
+    };
+}
+
+export { composeEventHandlers };

package/dist/utils/composeEventHandlers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/index.d.ts

@@ -1,8 +1,8 @@
 export { cn } from "./cn";
 export { debounce } from "./debounce";
+export { composeEventHandlers } from "./composeEventHandlers";
 export { formatTimestamp, formatDate, formatTime, formatDateCustom, formatRelativeTime, isToday, isYesterday, isThisWeek, getLastNDays, getThisWeek, getLastWeek, getThisMonth, getLastMonth, getThisYear, getLastYear, toDate, addDays, isSameDay, isWeekend, getDaysBetween, getWeekNumber, type DateInput, type TimestampOptions, type DateRange, } from "./dateUtils";
 export { findNextMatchingOption, isValidTypeaheadChar, TYPEAHEAD_TIMEOUT_MS, type TypeaheadOption, type FindNextMatchingOptionParams, } from "./typeaheadUtils";
-export { timeToMinutes, minutesToTime, getEventDuration, getTotalTimeSlots, getTimeSlotIndex, getTimeSlotForIndex, calculateEventPosition, calculateEventHeight, eventsOverlap, findOverlappingEvents, groupOverlappingEvents, resolveOverlappingEvents, generateTimeGrid, filterEventsByDate, sortEventsByStartTime, separateAllDayEvents, isValidTimeFormat, isValidDateFormat, validateEvent, DEFAULT_GRID_CONFIGS, type CalendarEvent, type GridConfig, type EventPosition, type EventLayout, type TimeSlot, } from "./calendarUtils";
 export { parseOpenAI, parseAnthropic, parseGemini, parseSSELine, SSE_PARSERS, type SSEFormat, type SSEParser, } from "./sseFormatParsers";
 export { StreamingNetworkError, StreamingTimeoutError, StreamingParseError, StreamingAbortError, StreamingServerError, normalizeError, type StreamingError, } from "./streamingErrors";
 export { calculateRetryDelay, shouldRetry, type RetryConfig, } from "./retryUtils";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flikk/ui",
-  "version": "1.0.0-beta.31",
+  "version": "1.0.0-beta.33",
   "description": "A modern React component library built with TypeScript, Tailwind CSS v4, and Framer Motion. Follows the shadcn philosophy with complete className override support.",
   "type": "module",
   "packageManager": "yarn@1.22.22",
@@ -58,6 +58,10 @@
       "types": "./dist/components/generative/index.d.ts",
       "import": "./dist/components/generative/index.js"
     },
+    "./generative/ai-sdk": {
+      "types": "./dist/components/generative/ai-sdk/index.d.ts",
+      "import": "./dist/components/generative/ai-sdk/index.js"
+    },
     "./components/*": {
       "import": "./dist/components/*.js",
       "types": "./dist/components/*.d.ts"
@@ -99,6 +103,19 @@
     "watch": "rollup -c -w",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",
+    "verify": "node scripts/verify.mjs",
+    "verify:fast": "node scripts/verify.mjs --fast",
+    "verify:full": "node scripts/verify.mjs --full",
+    "verify:pack": "node scripts/smoke-package.mjs",
+    "test:stories": "node scripts/test-stories.mjs",
+    "test-storybook": "test-storybook",
+    "verify:drift": "yarn build:generative && yarn build:inventory && git diff --exit-code src/components/generative/schema.generated.ts && git diff --exit-code CLAUDE.md",
+    "prepare": "git config core.hooksPath .githooks || true",
+    "chromatic": "chromatic --build-script-name build-storybook --only-changed",
+    "changeset": "changeset",
+    "release:status": "changeset status --verbose",
+    "release:version": "changeset version && node scripts/normalize-changelog.mjs && yarn build:inventory",
+    "release:publish": "changeset publish",
     "clean": "rimraf dist",
     "prepublishOnly": "npm run clean && npm run test && npm run build",
     "dev": "concurrently \"npm run watch:css:dev\" \"storybook dev -p 6006\" \"npm --prefix apps/docs run dev\"",
@@ -131,9 +148,11 @@
     "npm": ">=10.0.0"
   },
   "peerDependencies": {
+    "@ai-sdk/react": ">=4.0.0",
     "@phosphor-icons/react": ">=2.1.0",
     "@react-three/drei": ">=10.0.0",
     "@react-three/fiber": ">=9.0.0",
+    "ai": ">=7.0.0",
     "motion": ">=12.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
@@ -144,6 +163,12 @@
     "three": ">=0.170.0"
   },
   "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "@ai-sdk/react": {
+      "optional": true
+    },
     "react-markdown": {
       "optional": true
     },
@@ -167,6 +192,8 @@
     }
   },
   "devDependencies": {
+    "@ai-sdk/react": "^4.0.50",
+    "@changesets/cli": "^2.31.1",
     "@chromatic-com/storybook": "^5.0.0",
     "@emotion/is-prop-valid": "^1.4.0",
     "@eslint/js": "^9",
@@ -184,6 +211,7 @@
     "@storybook/addon-themes": "^10.2.3",
     "@storybook/addon-webpack5-compiler-swc": "^4.0.2",
     "@storybook/react-webpack5": "^10.2.3",
+    "@storybook/test-runner": "^0.24.4",
     "@tailwindcss/cli": "^4.1.18",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
@@ -195,7 +223,9 @@
     "@types/react-syntax-highlighter": "^15.5.11",
     "@types/three": "^0.182.0",
     "@vitejs/plugin-react": "^5.2.0",
+    "ai": "^7.0.47",
     "autoprefixer": "^10.4.24",
+    "chromatic": "^18.1.0",
     "concurrently": "^9.2.1",
     "eslint": "^9",
     "eslint-plugin-react-hooks": "^5.2.0",

package/src/global.scss

@@ -822,6 +822,12 @@ body {
   -moz-osx-font-smoothing: grayscale;
 }
 
+@layer base {
+  h1, h2, h3, h4, h5, h6 {
+    font-family: var(--font-heading);
+  }
+}
+
 /* Auto-fill input styling resets - fixes border-radius issues with auto-populated inputs */
 @layer base {
   /* Webkit browsers (Chrome, Safari, Edge) */
@@ -896,34 +902,6 @@ body {
   }
 }
 
-/* Heatmap flicker animation */
-@keyframes flicker {
-  0% {
-    opacity: 0;
-    transform: scale(1.05);
-  }
-  20% {
-    opacity: 0.3;
-    transform: scale(1.02);
-  }
-  40% {
-    opacity: 0.1;
-    transform: scale(1.03);
-  }
-  60% {
-    opacity: 0.7;
-    transform: scale(1.01);
-  }
-  80% {
-    opacity: 0.4;
-    transform: scale(1.02);
-  }
-  100% {
-    transform: scale(1);
-    /* No opacity at 100% - let inline styles control final opacity */
-  }
-}
-
 /* Loader shimmer animation for indeterminate linear progress */
 @keyframes shimmer {
   0% {
@@ -1023,3 +1001,18 @@ body {
     width: 33%;
   }
 }
+
+/*
+ * Segmented Progress indeterminate animation. Each cell runs the same pulse
+ * with a staggered animation-delay, which reads as a lit band travelling along
+ * the row — the discrete equivalent of the sweep above.
+ */
+@keyframes progress-segment-chase {
+  0%,
+  100% {
+    opacity: 0.15;
+  }
+  50% {
+    opacity: 1;
+  }
+}

package/src/styles/theme.css

@@ -21,26 +21,6 @@
       the live --color-primary, so a raw override (even white) self-corrects. */
    --color-primary-contrast: oklch(from var(--color-primary) clamp(0, (0.85 - l) * 1000, 1) 0 0);
 
-   /* DEPRECATED: the `secondary` semantic color was removed (it overlapped
-      `neutral` and was ambiguous — see CLAUDE.md §8). These vars are now aliased
-      to the neutral scale so any stray/consumer CSS still resolves. Remove next
-      major. Original Tailwind-gray ramp kept for reference:
-      50 oklch(0.984 0.003 247.858) … 600 oklch(0.446 0.043 257.281) … 950 oklch(0.129 0.042 264.695). */
-   --color-secondary-50: var(--color-mono-50);
-   --color-secondary-100: var(--color-mono-100);
-   --color-secondary-200: var(--color-mono-200);
-   --color-secondary-300: var(--color-mono-300);
-   --color-secondary-400: var(--color-mono-400);
-   --color-secondary-500: var(--color-mono-500);
-   --color-secondary-600: var(--color-mono-600);
-   --color-secondary-700: var(--color-mono-700);
-   --color-secondary-800: var(--color-mono-800);
-   --color-secondary-900: var(--color-mono-900);
-   --color-secondary-950: var(--color-mono-950);
-
-   --color-secondary: var(--color-secondary-600);
-   --color-secondary-contrast: oklch(from var(--color-secondary) clamp(0, (0.85 - l) * 1000, 1) 0 0);
-
    /* Danger/Error color palette - full 50-950 range */
    --color-danger-50: oklch(0.971 0.013 17.38);
    --color-danger-100: oklch(0.936 0.032 17.717);
@@ -168,13 +148,6 @@
    --color-chart-5-contrast: oklch(from var(--color-chart-5) clamp(0, (0.85 - l) * 1000, 1) 0 0);
    --color-background: var(--surface-1);
    /* near-white page canvas (rung 1) — white cards lift via the shadow ring */
-   /* DEPRECATED (remove next major): alias of --color-surface. Use the surface ladder. */
-   --color-background-secondary: var(--color-surface);
-   /* DEPRECATED (remove next major): recessed/subtle fills. Migrate per-usage to --color-surface-sunken
-     (dark values below are inverted vs. a correct sunken token, so no blind alias). */
-   --color-background-tertiary: oklch(90% 0.002 247.839);
-   --color-background-quaternary: oklch(85% 0.002 247.839);
-   --color-background-quinary: oklch(80% 0.002 247.839);
    --color-background-disabled: var(--color-mono-100);
 
    --color-mono-50: oklch(98.5% 0 0);
@@ -199,6 +172,10 @@
 
    /* Font family variables */
    --font-family-base: var(--font-sans);
+   /* Heading font — defaults to the body font so the default render is
+      unchanged; themes override it independently (e.g. display face for
+      headings, workhorse for body). */
+   --font-heading: var(--font-family-base);
 
    /* ============================================
      TYPE SCALE — one --font-scale knob (like --radius-base).
@@ -261,12 +238,33 @@
      font-size, and a bare var() value resolves to the COLOR branch (silently
      dropping the font-size change, no error). The `length:` type hint forces
      the correct branch.
+
+     🔴 Every size token below has a PAIRED --*-line-height token, consumed via
+     the `/[var(--…)]` modifier: `text-[length:var(--x-size)]/[var(--x-line-height)]`.
+     This is the same rule CONTROL TYPE SIZE states for --form-text-size-*, and it
+     is mandatory for the same reason. A named utility like `text-sm` compiles to
+     font-size AND Tailwind's paired --text-sm--line-height; an arbitrary
+     `text-[length:…]` carries font-size ONLY and silently falls back to
+     normal/1.5. These roles previously pinned the gap shut with hardcoded
+     literals (leading-[1.4], leading-6, leading-none), which meant a theme could
+     resize a title but never re-lead it — and a theme raising --card-title-size
+     got a title that stayed locked at line-height 1. Defaults below are the exact
+     values those literals resolved to, so this is a zero-visual-change addition.
      ============================================ */
    --card-title-size: var(--text-base);
    --modal-title-size: var(--text-base);
    --drawer-title-size: var(--text-base);
    --page-heading-title-size: var(--text-xl);
    --section-title-size: var(--text-base);
+   /* Unitless where the old literal was unitless (1.4/1.5 scale with the font),
+      and 1.5rem where it was leading-6 (a fixed 6 x --spacing step, which did
+      NOT scale with the title size) — preserving each role's existing behaviour
+      rather than silently converting one model into the other. */
+   --card-title-line-height: 1;
+   --modal-title-line-height: 1.5rem;
+   --drawer-title-line-height: 1.5rem;
+   --page-heading-title-line-height: 1.4;
+   --section-title-line-height: 1.5;
    /* AlertDialog has no title style of its own — it renders Modal.Title
       directly, so it already inherits --modal-title-size above. */
 
@@ -281,9 +279,18 @@
    --kpi-value-size-sm: var(--text-xl);
    --kpi-value-size-md: var(--text-2xl);
    --kpi-value-size-lg: var(--text-3xl);
+   /* Paired leading, per the rule above. Unitless so a themed value-size still
+      leads proportionally — these are big display numerals where a fixed rem
+      leading would clip descenders the moment a theme scaled the size up. */
+   --metric-value-line-height-sm: 1.4;
+   --metric-value-line-height-md: 1.2;
+   --metric-value-line-height-lg: 1.2;
+   --kpi-value-line-height-sm: 1.4;
+   --kpi-value-line-height-md: 1.333;
+   --kpi-value-line-height-lg: 1.2;
 
    /* Form element variables — fixed px so they don't scale with root font-size */
-   --form-min-h-sm: 32px;
+   --form-min-h-sm: 28px;
    /* h-8 in Tailwind */
    --form-min-h-md: 36px;
    /* h-9 in Tailwind */
@@ -300,8 +307,9 @@
    --form-px-lg: 16px;
    /* px-4 in Tailwind */
 
-   --form-py-sm: 8px;
-   /* py-2 in Tailwind */
+   --form-py-sm: 6px;
+   /* 6px, not py-2's 8px: the sm rung is a 28px box around a 12px/16px line,
+      so 8px left a 12px content box for a 16px line. */
    --form-py-md: 10px;
    /* py-2.5 in Tailwind */
    --form-py-lg: 12px;
@@ -324,7 +332,7 @@
       Tailwind's arbitrary text-[…] syntax is ambiguous between colour and
       font-size and a bare var() resolves to the COLOUR branch, silently
       no-oping the size (see TYPE ROLE SYSTEM). */
-   --form-text-size-sm: var(--text-sm);
+   --form-text-size-sm: var(--text-xs);
    --form-text-size-md: var(--text-sm);
    --form-text-size-lg: var(--text-base);
 
@@ -337,10 +345,30 @@
       that 20px→21px step. Values alias Tailwind's own pairing vars so the
       ramp stays byte-identical and --font-scale still flows through (the
       pairings are unitless ratios). */
-   --form-line-height-sm: var(--text-sm--line-height);
+   --form-line-height-sm: var(--text-xs--line-height);
    --form-line-height-md: var(--text-sm--line-height);
    --form-line-height-lg: var(--text-base--line-height);
 
+   /* CONTROL ICON SIZE — the GLYPH inside a field (chevron, clock, search,
+      check), NOT any button square.
+
+      🔴 Do not confuse with --button-icon-square-* , which is the icon-only
+      BUTTON's box (aliased to --form-min-h-*). This family is the drawn icon.
+
+      Icons were the one axis of a field's geometry that was NOT themeable: a
+      preset could retune height, padding, radius and type, and every decorator
+      stayed a hardcoded size-4/size-5. So a scaled-up theme got 16px chevrons
+      rattling around a 48px field. The ramp is deliberately gentler than the
+      type ramp (12/14/16 against 14/14/16) — an icon carries more optical mass
+      per px than a glyph of text, so matching type 1:1 reads heavy at sm.
+
+      Consumed as size-[var(--form-icon-size-…)] via formsBaseTheme.iconStyles.sizes.
+      Unlike --form-text-size-*, there is no line-height partner to pair — an
+      icon is a box, not a line of text. */
+   --form-icon-size-sm: 12px;
+   --form-icon-size-md: 14px;
+   --form-icon-size-lg: 16px;
+
    /* ============================================
      OTP SLOT SIZING
      OTP slots are SQUARE, so this is one size token per rung, not a height +
@@ -435,6 +463,17 @@
    /* Overlays (1.5x base = 18px, capped; tooltip stays 1x but is now ALSO
       capped — same 1x multiplier as before, just no longer unbounded) */
    --dropdown-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-sm));
+   /* The form listbox panel (Select/Combobox/InputTag/Mention) is the same kind of
+     anchored menu panel as the one above — Mention literally renders MenuItem rows
+     in it — so it ALIASES --dropdown-radius rather than restating the formula. An
+     alias, not a copy: `precision.css` overrides --dropdown-radius alone, and two
+     parallel formulas would have left form listboxes at a different radius than the
+     menus they sit beside. Override this token to deliberately split the two.
+     🔴 It used to paint --form-radius, which is `var(--radius-base)`: the UNCAPPED
+     CONTROL token, on a padded content container — the exact bypass the caps above
+     exist to prevent (on `ember`, base 24px, a 24px curve against 4px of padding).
+     Never route a panel through a control token. */
+   --form-dropdown-radius: var(--dropdown-radius);
    --tooltip-radius: min(var(--radius-base), var(--surface-radius-cap-xs));
    --codeblock-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-sm));
    --popover-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-sm));
@@ -453,6 +492,17 @@
    /* Owns its own border/bg/shadow with compact (~12-20px) paddings, closer
       to Alert/Dropdown's profile than Card's, despite living in data-display. */
    --gantt-chart-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-sm));
+   /* AgentRequest: the composer-slot panel. Compact chrome (~14px padding), so
+      it takes the sm cap like Dropdown/Popover/Toast — NOT --card-radius. It
+      used to borrow that token, but Card earns the lg cap by having 24px of
+      padding to absorb the curve; at 14px the same 32px radius visibly crowds
+      the header row (ember, --radius-base: 24px). */
+   --agent-request-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-sm));
+   /* The payload well INSIDE that panel (the command/diff being approved) has
+      only ~10px of padding, so it needs the tight xs cap — same formula and
+      reasoning as --tooltip-radius, one tier below its own container. A bare
+      var(--radius-base) here rendered a 24px curve on a 10px-padded box. */
+   --agent-request-well-radius: min(var(--radius-base), var(--surface-radius-cap-xs));
 
    /* Surfaces (1.5x base = 18px, capped) */
    --card-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-lg));
@@ -495,27 +545,42 @@
    --button-icon-p-md: 8px;
    --button-icon-p-lg: 10px;
 
-   /* Button icon-only sizes */
-   --button-icon-size-sm: var(--form-min-h-sm);
-   --button-icon-size-md: var(--form-min-h-md);
-   --button-icon-size-lg: var(--form-min-h-lg);
+   /* Icon-only Button SQUARE — the button's box, aliased to the form height so
+      an icon button lines up with the field beside it. Named `-square-`, not
+      `-size-`: it is not the size of the icon (that is --form-icon-size-*, and
+      two tokens both called `icon-size` meaning different things is a trap). */
+   --button-icon-square-sm: var(--form-min-h-sm);
+   --button-icon-square-md: var(--form-min-h-md);
+   --button-icon-square-lg: var(--form-min-h-lg);
 
    /* Badge variables.
       Radius derives from --radius-base like every other CONTROL (Button/Input/
       Segmented) — 0.75x = 6px at the 8px base, and now it tracks a themed base
       (was a hardcoded 6px literal that silently ignored --radius-base). Uncapped:
       a large base takes Badge fully pill, which CSS auto-clamps to 50%.
-      Paddings are fixed px (like --button-px-*/--form-px-*), overridable per theme
+      Paddings are fixed px (like --button-px-* / --form-px-*), overridable per theme
       so a spacious theme can grow the chip tier alongside its controls. py drives
-      height together with the text line-height + 1px border (sm: 16+0+2=18, md:
+      height together with the text line-height + 1px border (sm: 16+2+2=20, md:
       16+4+2=22). pill-px must clear the rounded-full cap so text is not eaten
-      by the curve. */
+      by the curve.
+
+      RADIUS IS PER SIZE. A single shared radius does not survive down the ramp:
+      the curve starts `radius` in from each edge while text starts `px + border`
+      in, so the smaller box — which has LESS padding to absorb the curve — is the
+      one whose glyphs end up sitting inside it. At the shared 0.75x (6px) sm's
+      text started at 5px against a 6px curve; 0.5x (4px) clears it. Same
+      curve-vs-padding collision the --surface-radius-cap-* ceilings solve for
+      containers, one tier down. Both still derive from --radius-base so a themed
+      base scales them; --badge-radius stays the md value (and the name a theme
+      already overrides), with --badge-radius-md aliasing it. */
    --badge-radius: calc(var(--radius-base) * 0.75);
+   --badge-radius-sm: calc(var(--radius-base) * 0.5);
+   --badge-radius-md: var(--badge-radius);
    --badge-px-sm: 4px;
    --badge-px-md: 6px;
-   --badge-py-sm: 0px;
+   --badge-py-sm: 1px;
    --badge-py-md: 2px;
-   --badge-pill-px-sm: 8px;
+   --badge-pill-px-sm: 10px;
    --badge-pill-px-md: 10px;
 
    /* Pill (chip tier) — px/py per size. rounded-full is intrinsic (no radius
@@ -599,6 +664,37 @@
    --metric-content-p-lg: 20px;
    /* from p-5 */
 
+   /* ============================================
+     MOTION SYSTEM — the transition-duration tier, tokenised.
+
+     Unlike the type utilities, Tailwind's duration-* does NOT route through a
+     theme variable: `duration-200` compiles to a literal `transition-duration:
+     .2s`, so a theme had no way to make the whole UI quicker or calmer. These
+     five tokens cover every duration the library actually uses; consume them as
+     `duration-[var(--motion-duration-base)]`.
+
+     🔴 Values are the EXACT literals they replace — this is a tokenisation, not
+     a retune. The names label the existing tiers rather than proposing new
+     timings, so a theme opts into a different feel by overriding a token; the
+     default rendering is byte-identical.
+
+     🔴 There is deliberately NO --motion-ease-* family. Easing ALREADY routes
+     through overridable variables — `ease-out` compiles to
+     `transition-timing-function: var(--ease-out)`, same as `tracking-tight` ->
+     var(--tracking-tight). A theme retunes --ease-out/--ease-in/--ease-in-out
+     directly; adding a parallel --motion-ease-* namespace would give the same
+     property two competing knobs.
+
+     🔴 Scope is CSS transitions only. motion/react animations take durations as
+     JS numbers (seconds) in .animations.ts and cannot read a CSS variable — see
+     interaction.animations.ts for the shared press/hover springs, which stay the
+     single source of truth for those. Don't mirror these tokens into JS. */
+   --motion-duration-fast: 150ms;
+   --motion-duration-base: 200ms;
+   --motion-duration-slow: 300ms;
+   --motion-duration-slower: 400ms;
+   --motion-duration-slowest: 500ms;
+
    /* Segmented inner offset — drives wrapper padding AND inner radius so
      the sliding background + items stay concentric with the outer shell.
      border (1px) + padding (--segmented-padding) = total inset. */
@@ -606,6 +702,25 @@
    /* 2px */
    --segmented-inner-radius: calc(var(--segmented-radius) - var(--segmented-padding) - 1px);
 
+   /* Menu panel inner offset — same model as --segmented-* above: one padding
+     token drives BOTH the panel's own padding AND the outer corner radius of
+     its first/last row, so the rows stay concentric with the panel instead of
+     bulging past its curve. border (1px) + padding (--dropdown-padding) = total
+     inset. Consumed by Dropdown's menu, ContextMenu's body + submenu body, and
+     MenuItem's first:/last: rules — change the padding here, never at a call
+     site, or the two drift apart. Interior rows keep their own flat radius;
+     only the two rows that meet the panel's corners take this one. */
+   --dropdown-padding: 0.25rem;
+   /* 4px */
+   --dropdown-inner-radius: calc(var(--dropdown-radius) - var(--dropdown-padding) - 1px);
+
+   /* Same pair for the FORM listbox panel, aliasing the menu's by default (see
+     --form-dropdown-radius). Named separately so a theme CAN split the two — and so
+     the inner radius always derives from the panel it actually sits in, whichever
+     way that goes. */
+   --form-dropdown-padding: var(--dropdown-padding);
+   --form-dropdown-inner-radius: calc(var(--form-dropdown-radius) - var(--form-dropdown-padding) - 1px);
+
    /* Glass effect gradient variables */
    --glass-gradient-outer: linear-gradient(to bottom,
          rgba(250, 250, 250, 0.8) 0%,
@@ -634,7 +749,7 @@
    --nav-item-radius: var(--radius-base);
 
    /* Modal and Drawer */
-   --overlay-bg: rgba(0, 0, 0, 0.65);
+   --overlay-bg: rgba(0, 0, 0, 0.75);
    --overlay-blur: 8px;
    --color-scale-background: oklch(0% 0 0);
    /* backdrop behind scaled content */
@@ -892,7 +1007,6 @@
       --color-success: var(--color-success-400);
       --color-warning: var(--color-warning-400);
       --color-danger: var(--color-danger-400);
-      --color-secondary: var(--color-secondary-400);
       /* Neutral fill flips to a light chip (dark ink text via auto contrast) */
       --color-mono: var(--color-mono-200);
 
@@ -903,7 +1017,6 @@
       --color-danger-contrast: oklch(from var(--color-danger) clamp(0, (0.85 - l) * 1000, 1) 0 0);
       --color-success-contrast: oklch(from var(--color-success) clamp(0, (0.85 - l) * 1000, 1) 0 0);
       --color-warning-contrast: oklch(from var(--color-warning) clamp(0, (0.85 - l) * 1000, 1) 0 0);
-      --color-secondary-contrast: oklch(from var(--color-secondary) clamp(0, (0.85 - l) * 1000, 1) 0 0);
       --color-mono-contrast: oklch(from var(--color-mono) clamp(0, (0.85 - l) * 1000, 1) 0 0);
 
       /* Background colors - dark equivalents */
@@ -926,12 +1039,6 @@
       --color-surface-hover: oklch(100% 0 0 / 0.07);
       --color-background: var(--surface-1);
       /* rung 1 — dark floor */
-      /* DEPRECATED (remove next major): alias of --color-surface. */
-      --color-background-secondary: var(--color-surface);
-      /* DEPRECATED (remove next major): migrate per-usage to --color-surface-sunken / surface ladder. */
-      --color-background-tertiary: oklch(22% 0 0);
-      --color-background-quaternary: oklch(26% 0 0);
-      --color-background-quinary: oklch(30% 0 0);
       --color-background-disabled: var(--color-mono-800);
 
       /* Scale backdrop — sits behind scaled content, darker than the #171717 floor */