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

package/dist/utils/index.d.ts

@@ -2,7 +2,6 @@ export { cn } from "./cn";
 export { debounce } from "./debounce";
 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.32",
   "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,6 +279,15 @@
    --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;
@@ -435,6 +442,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 +471,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));
@@ -505,17 +534,29 @@
       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 +640,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 +678,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 +725,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 +983,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 +993,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 +1015,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 */

package/src/styles/theme.test.ts

@@ -0,0 +1,119 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+const themeCss = readFileSync(
+  resolve(process.cwd(), "src/styles/theme.css"),
+  "utf8",
+);
+
+/**
+ * CSS comments do NOT nest and are terminated by the FIRST `*​/`. Writing a
+ * token glob like `--button-px-*` immediately before a `/` (e.g. the shorthand
+ * `--button-px-*​/--form-px-*`) therefore closes the comment early: the prose
+ * that follows is parsed as CSS, and it swallows the next declaration up to the
+ * first `;` — silently deleting a token that still *looks* defined in source.
+ *
+ * That is exactly how `--badge-radius` went missing (every non-pill Badge
+ * rendered with square corners, because `border-radius: var(--badge-radius)`
+ * had no definition to resolve). Stripping comments the way a real parser does
+ * — non-greedy, first-terminator-wins — leaves a stray `*​/` behind whenever it
+ * happens, which is what these tests assert on.
+ */
+const stripComments = (css: string) => css.replace(/\/\*[\s\S]*?\*\//g, "");
+
+describe("theme.css", () => {
+  it("has no comment that terminates early", () => {
+    const strays = stripComments(themeCss)
+      .split("\n")
+      .map((line, i) => ({ line: line.trim(), number: i + 1 }))
+      .filter(({ line }) => line.includes("*/"));
+
+    expect(strays).toEqual([]);
+  });
+
+  it("defines every custom property the chip tier consumes", () => {
+    // Split on declaration boundaries and keep only chunks that *start* with a
+    // custom property, the way a parser sees them. Matching `--x:` anywhere
+    // would also match the leaked prose of an early-terminated comment — i.e.
+    // it would report the very token that got swallowed as still defined.
+    const declared = new Set(
+      stripComments(themeCss)
+        .split(/[;{}]/)
+        .map((chunk) => /^\s*(--[a-z0-9-]+)\s*:/.exec(chunk)?.[1])
+        .filter((name): name is string => name !== undefined),
+    );
+
+    // --badge-radius is the token the early-terminated comment ate; the rest
+    // are its immediate neighbours, which pin the boundaries of the damage.
+    for (const token of [
+      "--badge-radius",
+      "--badge-radius-sm",
+      "--badge-radius-md",
+      "--badge-px-sm",
+      "--badge-py-sm",
+      "--badge-pill-px-sm",
+      "--pill-px-sm",
+      "--tag-px-sm",
+      "--kbd-px-sm",
+    ]) {
+      expect(declared).toContain(token);
+    }
+  });
+
+  /**
+   * A named utility like `text-sm` compiles to font-size AND Tailwind's paired
+   * `--text-sm--line-height`. An arbitrary `text-[length:var(--x)]` carries
+   * font-size ONLY — leading silently falls back to normal/1.5. So every
+   * per-role size token must be consumed with the `/[var(--…)]` modifier, or a
+   * theme can resize a title but never re-lead it.
+   *
+   * This scans real source rather than a hardcoded list, so a NEW size token
+   * that ships without its line-height partner fails here immediately.
+   */
+  it("pairs every per-role font-size token with a line-height token", () => {
+    const declared = new Set(
+      stripComments(themeCss)
+        .split(/[;{}]/)
+        .map((chunk) => /^\s*(--[a-z0-9-]+)\s*:/.exec(chunk)?.[1])
+        .filter((name): name is string => name !== undefined),
+    );
+
+    const collectThemeFiles = (dir: string): string[] =>
+      readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) return collectThemeFiles(path);
+        return entry.name.endsWith(".theme.ts") ? [path] : [];
+      });
+
+    const themeFiles = collectThemeFiles(
+      resolve(process.cwd(), "src/components"),
+    );
+
+    const unpaired: string[] = [];
+    const undeclaredLineHeight: string[] = [];
+
+    for (const file of themeFiles) {
+      const source = readFileSync(file, "utf8");
+      // Each `text-[length:var(--x)]` occurrence, plus whatever directly follows,
+      // so we can tell a paired `/[var(--y)]` from a bare size.
+      for (const match of source.matchAll(
+        /text-\[length:var\((--[a-z0-9-]+)\)\](\/\[var\((--[a-z0-9-]+)\)\])?/g,
+      )) {
+        const [, sizeToken, pairing, lineHeightToken] = match;
+        if (!pairing) {
+          unpaired.push(`${file}: ${sizeToken}`);
+          continue;
+        }
+        if (!declared.has(lineHeightToken)) {
+          undeclaredLineHeight.push(`${file}: ${lineHeightToken}`);
+        }
+        expect(declared).toContain(sizeToken);
+      }
+    }
+
+    expect(unpaired).toEqual([]);
+    expect(undeclaredLineHeight).toEqual([]);
+  });
+});

package/tailwind.preset.cjs

@@ -9,6 +9,11 @@
  * components paint, and follows the active theme + dark mode automatically:
  * the monochrome base theme aliases --color-primary -> -900, a colored theme
  * (e.g. iris) sets it -> -600. Numbered utilities (bg-primary-600) are unchanged.
+ *
+ * `contrast` on each semantic color is the auto-derived foreground for a FILLED
+ * surface of that color (text-primary-contrast on bg-primary) — see CLAUDE.md §3.
+ * It is derived in pure CSS from the live base var, so it tracks any theme and
+ * both modes; never substitute a hardcoded text-white.
  */
 
 module.exports = {
@@ -27,7 +32,8 @@ module.exports = {
           800: 'var(--color-primary-800)',
           900: 'var(--color-primary-900)',
           950: 'var(--color-primary-950)',
-          DEFAULT: 'var(--color-primary)'
+          DEFAULT: 'var(--color-primary)',
+          contrast: 'var(--color-primary-contrast)'
         },
         danger: {
           50: 'var(--color-danger-50)',
@@ -41,7 +47,8 @@ module.exports = {
           800: 'var(--color-danger-800)',
           900: 'var(--color-danger-900)',
           950: 'var(--color-danger-950)',
-          DEFAULT: 'var(--color-danger)'
+          DEFAULT: 'var(--color-danger)',
+          contrast: 'var(--color-danger-contrast)'
         },
         success: {
           50: 'var(--color-success-50)',
@@ -55,7 +62,8 @@ module.exports = {
           800: 'var(--color-success-800)',
           900: 'var(--color-success-900)',
           950: 'var(--color-success-950)',
-          DEFAULT: 'var(--color-success)'
+          DEFAULT: 'var(--color-success)',
+          contrast: 'var(--color-success-contrast)'
         },
         warning: {
           50: 'var(--color-warning-50)',
@@ -69,7 +77,8 @@ module.exports = {
           800: 'var(--color-warning-800)',
           900: 'var(--color-warning-900)',
           950: 'var(--color-warning-950)',
-          DEFAULT: 'var(--color-warning)'
+          DEFAULT: 'var(--color-warning)',
+          contrast: 'var(--color-warning-contrast)'
         },
         // The gray/neutral role. Named `mono` (not `neutral`) on purpose:
         // mapping `neutral` here would override Tailwind's own built-in neutral
@@ -87,22 +96,8 @@ module.exports = {
           800: 'var(--color-mono-800)',
           900: 'var(--color-mono-900)',
           950: 'var(--color-mono-950)',
-          DEFAULT: 'var(--color-mono)'
-        },
-        // DEPRECATED (remove next major): alias of the gray scale. Prefer `mono`.
-        secondary: {
-          50: 'var(--color-secondary-50)',
-          100: 'var(--color-secondary-100)',
-          200: 'var(--color-secondary-200)',
-          300: 'var(--color-secondary-300)',
-          400: 'var(--color-secondary-400)',
-          500: 'var(--color-secondary-500)',
-          600: 'var(--color-secondary-600)',
-          700: 'var(--color-secondary-700)',
-          800: 'var(--color-secondary-800)',
-          900: 'var(--color-secondary-900)',
-          950: 'var(--color-secondary-950)',
-          DEFAULT: 'var(--color-secondary)'
+          DEFAULT: 'var(--color-mono)',
+          contrast: 'var(--color-mono-contrast)'
         },
         text: {
           primary: 'var(--color-text-primary)',
@@ -127,6 +122,21 @@ module.exports = {
           secondary: 'var(--color-border-secondary)',
           hover: 'var(--color-border-hover)'
         },
+        // Categorical chart series palette + the unfilled-track color, for consumers
+        // building their own visuals alongside @flikk/ui/charts (charts themselves are
+        // `config`-driven and never take a className — see CLAUDE.md §19).
+        // NOTE: the matching --color-chart-N-contrast tokens are deliberately NOT mapped
+        // here — they are declared in @theme and unreferenced by library source, so
+        // Tailwind prunes them from the light block of the shipped styles.css and they
+        // resolve only under .dark. Map them once they are defined outside @theme.
+        chart: {
+          1: 'var(--color-chart-1)',
+          2: 'var(--color-chart-2)',
+          3: 'var(--color-chart-3)',
+          4: 'var(--color-chart-4)',
+          5: 'var(--color-chart-5)',
+          track: 'var(--color-chart-track)'
+        },
         dark: 'var(--color-mono-950)'
       },
       fontFamily: {