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

package/src/styles/theme.css

@@ -2,17 +2,17 @@
    /* Primary color palette — monochrome: aliased to the neutral scale.
       (Original blue ramp kept for easy revert:
        50 oklch(0.962 0.018 272.314) … 600 oklch(0.511 0.262 276.966) … 950 oklch(0.257 0.09 281.288)) */
-   --color-primary-50: var(--color-neutral-50);
-   --color-primary-100: var(--color-neutral-100);
-   --color-primary-200: var(--color-neutral-200);
-   --color-primary-300: var(--color-neutral-300);
-   --color-primary-400: var(--color-neutral-400);
-   --color-primary-500: var(--color-neutral-500);
-   --color-primary-600: var(--color-neutral-600);
-   --color-primary-700: var(--color-neutral-700);
-   --color-primary-800: var(--color-neutral-800);
-   --color-primary-900: var(--color-neutral-900);
-   --color-primary-950: var(--color-neutral-950);
+   --color-primary-50: var(--color-mono-50);
+   --color-primary-100: var(--color-mono-100);
+   --color-primary-200: var(--color-mono-200);
+   --color-primary-300: var(--color-mono-300);
+   --color-primary-400: var(--color-mono-400);
+   --color-primary-500: var(--color-mono-500);
+   --color-primary-600: var(--color-mono-600);
+   --color-primary-700: var(--color-mono-700);
+   --color-primary-800: var(--color-mono-800);
+   --color-primary-900: var(--color-mono-900);
+   --color-primary-950: var(--color-mono-950);
 
    /* Light mode: dark primary → dark buttons with light text (contrast auto-resolves white). */
    --color-primary: var(--color-primary-900);
@@ -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-neutral-50);
-   --color-secondary-100: var(--color-neutral-100);
-   --color-secondary-200: var(--color-neutral-200);
-   --color-secondary-300: var(--color-neutral-300);
-   --color-secondary-400: var(--color-neutral-400);
-   --color-secondary-500: var(--color-neutral-500);
-   --color-secondary-600: var(--color-neutral-600);
-   --color-secondary-700: var(--color-neutral-700);
-   --color-secondary-800: var(--color-neutral-800);
-   --color-secondary-900: var(--color-neutral-900);
-   --color-secondary-950: var(--color-neutral-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);
@@ -70,7 +50,8 @@
    --color-success-900: oklch(0.386 0.063 188.416);
    --color-success-950: oklch(0.277 0.046 192.524);
 
-   --color-success: var(--color-success-500);
+   /* -600 like danger/warning — white -contrast text passes AA (500 was ~2.7:1) */
+   --color-success: var(--color-success-600);
    --color-success-contrast: oklch(from var(--color-success) clamp(0, (0.85 - l) * 1000, 1) 0 0);
 
    /* Warning color palette - full 50-950 range */
@@ -90,12 +71,18 @@
    --color-warning-contrast: oklch(from var(--color-warning) clamp(0, (0.85 - l) * 1000, 1) 0 0);
 
    /* text color */
-   --color-text-primary: var(--color-neutral-950);
-   --color-text-secondary: var(--color-neutral-700);
-   --color-text-placeholder: var(--color-neutral-400);
-   --color-text-muted: var(--color-neutral-500);
-   --color-text-disabled: var(--color-neutral-400);
-   --color-text-inverse: var(--color-neutral-50);
+   --color-text-primary: var(--color-mono-950);
+   --color-text-secondary: var(--color-mono-700);
+   /* placeholder/muted are ALPHA-DERIVED from text-primary (not ramp rungs):
+      they auto-track any theme's text color in both modes, and translucency
+      composites correctly over any surface. Components must consume these
+      tokens — never point text at neutral rungs (dark:text-[--color-mono-N]
+      bypasses are the theming bug fixed here; same class as Segmented PER-292).
+      Re-derived in .dark below (same reason contrast tokens are). */
+   --color-text-placeholder: color-mix(in oklab, var(--color-text-primary) 40%, transparent);
+   --color-text-muted: color-mix(in oklab, var(--color-text-primary) 57%, transparent);
+   --color-text-disabled: var(--color-mono-400);
+   --color-text-inverse: var(--color-mono-50);
 
    /* generic colors */
    --color-border: oklch(93% 0 0);
@@ -141,32 +128,82 @@
      over ANY surface level — darkens in light, lightens in dark. For hover/active highlights. */
    --color-surface-hover: oklch(0% 0 0 / 0.05);
    --color-chart-track: rgba(0, 0, 0, 0.06);
+   /* Categorical chart series palette — 5 fixed slots, independent of the
+      semantic status tokens (primary/success/warning/danger). Series N always
+      maps to slot N; don't reorder or reuse these for status meaning. */
+   --color-chart-1: #3b82f6;
+   /* blue */
+   --color-chart-1-contrast: oklch(from var(--color-chart-1) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+   --color-chart-2: #14b8a6;
+   /* teal */
+   --color-chart-2-contrast: oklch(from var(--color-chart-2) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+   --color-chart-3: #f59e0b;
+   /* amber */
+   --color-chart-3-contrast: oklch(from var(--color-chart-3) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+   --color-chart-4: #8b5cf6;
+   /* violet */
+   --color-chart-4-contrast: oklch(from var(--color-chart-4) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+   --color-chart-5: #ec4899;
+   /* pink */
+   --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-neutral-100);
-
-   --color-neutral-50: oklch(98.5% 0 0);
-   --color-neutral-100: oklch(97% 0 0);
-   --color-neutral-200: oklch(92.2% 0 0);
-   --color-neutral-300: oklch(87% 0 0);
-   --color-neutral-400: oklch(70.8% 0 0);
-   --color-neutral-500: oklch(55.6% 0 0);
-   --color-neutral-600: oklch(43.9% 0 0);
-   --color-neutral-700: oklch(37.1% 0 0);
-   --color-neutral-800: oklch(26.9% 0 0);
-   --color-neutral-900: oklch(20.5% 0 0);
-   --color-neutral-950: oklch(14.5% 0 0);
+   --color-background-disabled: var(--color-mono-100);
+
+   --color-mono-50: oklch(98.5% 0 0);
+   --color-mono-100: oklch(97% 0 0);
+   --color-mono-200: oklch(92.2% 0 0);
+   --color-mono-300: oklch(87% 0 0);
+   --color-mono-400: oklch(70.8% 0 0);
+   --color-mono-500: oklch(55.6% 0 0);
+   --color-mono-600: oklch(43.9% 0 0);
+   --color-mono-700: oklch(37.1% 0 0);
+   --color-mono-800: oklch(26.9% 0 0);
+   --color-mono-900: oklch(20.5% 0 0);
+   --color-mono-950: oklch(14.5% 0 0);
+
+   /* Mono (gray-role) fill default + auto contrast — same machinery as the
+      semantic hues, for FILLED gray surfaces (Button color="mono" etc.): dark
+      ink in light mode, light chip in dark (flipped in .dark below). Lets
+      components write bg-[var(--color-mono)] text-[var(--color-mono-contrast)]
+      instead of hand-picking rungs + hardcoding text-white (§3 foreground rule). */
+   --color-mono: var(--color-mono-900);
+   --color-mono-contrast: oklch(from var(--color-mono) clamp(0, (0.85 - l) * 1000, 1) 0 0);
 
    /* Font family variables */
    --font-family-base: var(--font-sans);
-   --font-cursive: "Birthstone", cursive;
+   /* 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).
+     Tailwind v4 defines each --text-* step as an independent literal, so a
+     smaller "base font size" would otherwise mean redefining every step per
+     theme. Here the ramp is Tailwind's EXACT defaults × --font-scale: at the
+     default 1 every utility is byte-for-byte Tailwind (text-sm = 14px);
+     a theme sets ONE factor (e.g. 0.9375 → 15px-based text) and the whole
+     ramp follows. Line-heights are unitless ratios upstream, so they scale
+     automatically. Text-only: spacing (--spacing is rem) and px geometry
+     tokens are deliberately unaffected. Each step is round()ed to a whole px
+     so scaled sizes stay clean (0.9375 → text-sm 13px, not 13.125px); at
+     scale 1 the rounding is inert (Tailwind's defaults are already integers).
+     ============================================ */
+   --font-scale: 1;
+   --text-xs: round(calc(0.75rem * var(--font-scale)), 1px);
+   --text-sm: round(calc(0.875rem * var(--font-scale)), 1px);
+   --text-base: round(calc(1rem * var(--font-scale)), 1px);
+   --text-lg: round(calc(1.125rem * var(--font-scale)), 1px);
+   --text-xl: round(calc(1.25rem * var(--font-scale)), 1px);
+   --text-2xl: round(calc(1.5rem * var(--font-scale)), 1px);
+   --text-3xl: round(calc(1.875rem * var(--font-scale)), 1px);
+   --text-4xl: round(calc(2.25rem * var(--font-scale)), 1px);
+   --text-5xl: round(calc(3rem * var(--font-scale)), 1px);
+   --text-6xl: round(calc(3.75rem * var(--font-scale)), 1px);
+   --text-7xl: round(calc(4.5rem * var(--font-scale)), 1px);
+   --text-8xl: round(calc(6rem * var(--font-scale)), 1px);
+   --text-9xl: round(calc(8rem * var(--font-scale)), 1px);
    --font-weight-light: 300;
    --font-weight-normal: 400;
    --font-weight-medium: 500;
@@ -174,13 +211,91 @@
    --font-weight-bold: 700;
    --font-weight-extrabold: 800;
 
+   /* ============================================
+     TYPE ROLE SYSTEM — mirrors the two-tier override pattern used by
+     BORDER RADIUS SYSTEM below (--card-radius/--metric-radius etc.): a
+     shared base scale (the --text-* ramp / --font-scale above) that everything derives
+     from by default, plus independently-overridable per-role tokens for the
+     handful of prominent heading/value elements a theme most often wants to
+     differentiate. --font-scale alone can only resize the WHOLE UI
+     uniformly — there was previously no way to make e.g. just Card titles
+     bigger without touching every other text size too.
+
+     Each token below defaults to a specific --text-* rung, so it inherits
+     --font-scale automatically (zero visual change for any theme that
+     doesn't touch these). A theme can override a token two ways:
+       1. Scale-following: --card-title-size: var(--text-lg);
+          (stays pinned to a rung, so it still tracks --font-scale)
+       2. Fixed: --card-title-size: 1.25rem;
+          (a literal opts that one role out of the scale entirely — same
+          escape hatch --card-radius: 20px gives for geometry)
+     This is an ADDITIVE namespace layered on top of --text-* — it does NOT
+     redefine individual --text-* steps, which stays forbidden (see TYPE
+     SCALE above).
+
+     🔴 Consume these via `text-[length:var(--x)]`, NEVER `text-[var(--x)]` —
+     Tailwind's arbitrary text-[...] syntax is ambiguous between color and
+     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. */
+
+   /* Metric/KPI: one token per size variant, not a single shared token — the
+      sm/md/lg values today are deliberate information-density choices, not
+      a formula (e.g. Metric's md and lg are literally identical), so a
+      single token would either collapse that hierarchy or force an
+      arbitrary scaling relationship that doesn't match today's values. */
+   --metric-value-size-sm: var(--text-xl);
+   --metric-value-size-md: var(--text-3xl);
+   --metric-value-size-lg: var(--text-3xl);
+   --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;
    /* h-8 in Tailwind */
-   --form-min-h-md: 40px;
+   --form-min-h-md: 36px;
+   /* h-9 in Tailwind */
+   --form-min-h-lg: 40px;
    /* h-10 in Tailwind */
-   --form-min-h-lg: 48px;
-   /* h-12 in Tailwind */
 
    --form-label-pb: 8px;
    /* pb-2 in Tailwind */
@@ -193,21 +308,97 @@
    /* px-4 in Tailwind */
 
    --form-py-sm: 8px;
-   /* py-1 in Tailwind */
-   --form-py-md: 10px;
    /* py-2 in Tailwind */
+   --form-py-md: 10px;
+   /* py-2.5 in Tailwind */
    --form-py-lg: 12px;
    /* py-3 in Tailwind */
 
+   /* CONTROL TYPE SIZE — the last control-tier axis that was still a raw
+      Tailwind literal baked into the .theme.ts files. Height, padding and
+      radius were already tokens, so a theme could retune a control's box but
+      never its type; same "a library can't hardcode a Tailwind literal and
+      call it themeable" reasoning as the SURFACE PADDING and TYPE ROLE
+      systems below/above. Defaults to a --text-* rung, so --font-scale still
+      applies unless a theme overrides one outright.
+
+      Deliberately TWO rungs across three sizes: 14px is the workhorse control
+      size and dropping sm to 12px is a legibility liability on a 32px-tall
+      primary action — sm/md are separated by box (height + padding), not type.
+      Don't "fix" the repeat into a 12/14/16 ramp without a design pass.
+
+      🔴 Consume as text-[length:var(--…)], never bare text-[var(--…)] —
+      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-md: var(--text-sm);
+   --form-text-size-lg: var(--text-base);
+
+   /* 🔴 Paired line-heights are NOT optional here. A bare `text-sm` utility
+      compiles to font-size AND Tailwind's paired `--text-sm--line-height`
+      (14px/20px); an arbitrary `text-[length:…]` carries font-size ONLY and
+      the element falls back to normal/1.5 (14px/21px). Consuming these
+      tokens without the `/[var(--…-line-height-…)]` modifier therefore
+      silently changes every control's leading — caught in review at exactly
+      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-md: var(--text-sm--line-height);
+   --form-line-height-lg: var(--text-base--line-height);
+
+   /* ============================================
+     OTP SLOT SIZING
+     OTP slots are SQUARE, so this is one size token per rung, not a height +
+     width pair. sm/md/lg ALIAS the form ramp so slots line up with an adjacent
+     Input of the same size — break an alias to size OTP independently (same
+     pattern as --button-min-h-* / --segmented-min-h-*).
+
+     xl is DERIVED, not a literal, and there is deliberately no global
+     --form-min-h-xl: OTP is the only control large enough to want one, and a
+     global rung would ship without its px/py/text siblings. A hardcoded 48px
+     would not track a theme's ramp the way sm/md/lg do — it renders SMALLER
+     than lg in both Jade (36/44/52) and Ember (40/48/56). The 1.2 factor is
+     anchored so the default theme lands on 48px exactly.
+     ============================================ */
+   --otp-slot-size-sm: var(--form-min-h-sm);
+   /* 32px */
+   --otp-slot-size-md: var(--form-min-h-md);
+   /* 36px */
+   --otp-slot-size-lg: var(--form-min-h-lg);
+   /* 40px */
+   --otp-slot-size-xl: calc(var(--form-min-h-lg) * 1.2);
+   /* 48px in the default theme */
+
+   /* The digit runs one rung HOTTER than form body text — it is a display
+      numeral, not label text — so these deliberately do NOT alias
+      --form-text-size-*. Same two-rungs-across-the-low-end shape as the form
+      ramp: sm and md share a rung, lg and xl each step. */
+   --otp-text-size-sm: var(--text-base);
+   --otp-text-size-md: var(--text-base);
+   --otp-text-size-lg: var(--text-lg);
+   --otp-text-size-xl: var(--text-xl);
+
+   /* 🔴 MANDATORY pairing. A bare `text-lg` utility compiles to font-size AND
+      Tailwind's paired --text-lg--line-height; an arbitrary text-[length:…]
+      carries font-size ONLY and falls back to normal/1.5, silently changing
+      the digit's leading. Aliases Tailwind's own pairing vars so --font-scale
+      still flows through. */
+   --otp-line-height-sm: var(--text-base--line-height);
+   --otp-line-height-md: var(--text-base--line-height);
+   --otp-line-height-lg: var(--text-lg--line-height);
+   --otp-line-height-xl: var(--text-xl--line-height);
+
    /* ============================================
      BORDER RADIUS SYSTEM
      Change --radius-base to adjust the entire UI.
      Individual --*-radius variables can be overridden independently.
      ============================================ */
-   --radius-base: 12px;
+   --radius-base: 8px;
    /* Base radius token */
 
-   /* Forms & Controls (1x base = 8px) */
+   /* Forms & Controls (1x base = 12px) */
    --form-radius: var(--radius-base);
 
    /* Checkbox: small absolute box (20–28px), so the radius is CAPPED — a raw
@@ -215,49 +406,119 @@
       base grows. min() keeps it a rounded square at any base. */
    --checkbox-radius: min(calc(var(--radius-base) * 0.5), 6px);
 
-   /* Overlays (1.5x base = 12px) */
-   --dropdown-radius: calc(var(--radius-base) * 1.5);
-   --tooltip-radius: calc(var(--radius-base) / 1);
-   --codeblock-radius: calc(var(--radius-base) * 1.5);
-   --popover-radius: calc(var(--radius-base) * 1.5);
+   /* Surface radius ceilings — every CONTENT-BEARING container (Tooltip,
+      ChartTooltip, Dropdown, CodeBlock, Popover, Alert, Toast, Metric,
+      Message, GanttChart, Card, Modal, Drawer, HeroCard) caps its computed
+      radius at one of these, so a theme chasing pill-shaped controls at a
+      very large --radius-base can never round a padded surface past what
+      its own padding can absorb — the curve would otherwise start visually
+      eating into header text/icons sitting in that padding. Three tiers
+      because containers aren't one size: tiny fixed-padding chips run
+      ~4–12px padding, compact fixed-height surfaces run ~12–20px, spacious
+      freeform ones run ~24px. CONTROLS (Button/Input/Badge/NavItem/
+      Segmented) are the one category deliberately NOT capped below — going
+      fully pill at an extreme --radius-base is the correct, common look
+      there, and CSS itself auto-clamps border-radius to 50% of the box, so
+      a control can never visually break either way. (Tooltip looks like a
+      control at a glance — small, single-purpose — but unlike Button/Badge
+      it's a PADDED content box, not a filled shape with no internal inset,
+      so the padding-collision risk applies to it too; it belongs in the
+      capped camp, not the uncapped one — this was gotten wrong in an
+      earlier pass.) Override any cap per-theme for a more/less rounded
+      ceiling on surfaces specifically (independent of how round the
+      theme's controls are). Every new content-bearing container's radius
+      token MUST derive from one of these three caps — never a bare
+      `calc(var(--radius-base) * N)` — or it silently re-opens this exact gap
+      (see the OfflineIndicator/Message/HeroCard/GanttChart/Tooltip fixes
+      this system replaced). */
+   --surface-radius-cap-xs: 12px;
+   /* tiny/tight-padding chips (~4–12px padding): Tooltip, ChartTooltip */
+   --surface-radius-cap-sm: 24px;
+   /* compact/fixed-height content (~12–20px padding): Dropdown, CodeBlock,
+      Popover, Alert, Toast, Metric, Message, GanttChart */
+   --surface-radius-cap-lg: 32px;
+   /* spacious/freeform containers (~24px padding): Card, Modal, Drawer, HeroCard */
+
+   /* 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));
 
    /* Feedback surfaces */
-   --alert-radius: calc(var(--radius-base) * 1.5);
-   --toast-radius: calc(var(--radius-base) * 1.5);
-   --drawer-radius: calc(var(--radius-base) * 2);
-   --metric-radius: calc(var(--radius-base) * 2);
-
-   /* Surfaces (3x base = 24px) */
-   --card-radius: calc(var(--radius-base) * 1.5);
-   --modal-radius: calc(var(--radius-base) * 1.5);
+   --alert-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-sm));
+   --toast-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-sm));
+   --drawer-radius: min(calc(var(--radius-base) * 2), var(--surface-radius-cap-lg));
+   /* Metric is a compact stat tile, not a Drawer-scale surface — same tier
+      and cap as the other compact containers above, not 2x/lg. */
+   --metric-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-sm));
+   /* Chat bubble: same formula/tier as Alert/Toast/Metric above (compact,
+      padded content) — its own token rather than reusing one of theirs so a
+      theme can dial bubble roundness independently. */
+   --message-bubble-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-sm));
+   /* 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));
+   --modal-radius: min(calc(var(--radius-base) * 1.5), var(--surface-radius-cap-lg));
+   /* HeroCard has no radius token of its own — it's a Card presentation, so
+      it shares --card-radius (overridable per-instance via className, same
+      as every other component). */
 
    /* Special shapes - not part of scale */
    --segmented-radius: var(--form-radius);
    --avatar-radius: 50%;
 
-   /* Focus ring styling */
-   --form-focus-ring-width: 2px;
-   --form-focus-ring-offset: -1px;
-   --form-focus-ring-opacity: 0.1;
-
-   /* Outline/border styling */
-   --form-outline-width: 1px;
-   --form-outline-focused-width: 2px;
-
    /* Button variables - inheriting from form variables */
    --button-radius: var(--form-radius);
    --button-min-h-sm: var(--form-min-h-sm);
    --button-min-h-md: var(--form-min-h-md);
    --button-min-h-lg: var(--form-min-h-lg);
 
-   /* Button padding — fixed px */
-   --button-px-sm: 12px;
+   /* Button padding — fixed px. A +2 ramp (10/12/14); py is 0 because the
+      height comes from --button-min-h-* (i.e. --form-min-h-*), not padding. */
+   --button-px-sm: 10px;
    --button-py-sm: 0;
-   --button-px-md: 14px;
+   --button-px-md: 12px;
    --button-py-md: 0;
-   --button-px-lg: 20px;
+   --button-px-lg: 14px;
    --button-py-lg: 0;
 
+   /* Button type size — aliases the form ramp, like --button-min-h-* aliases
+      --form-min-h-*. A theme can break the alias to size button type
+      independently of input type. */
+   --button-text-size-sm: var(--form-text-size-sm);
+   --button-text-size-md: var(--form-text-size-md);
+   --button-text-size-lg: var(--form-text-size-lg);
+   --button-line-height-sm: var(--form-line-height-sm);
+   --button-line-height-md: var(--form-line-height-md);
+   --button-line-height-lg: var(--form-line-height-lg);
+
    /* Button icon-only padding — fixed px */
    --button-icon-p-sm: 6px;
    --button-icon-p-md: 8px;
@@ -268,8 +529,58 @@
    --button-icon-size-md: var(--form-min-h-md);
    --button-icon-size-lg: var(--form-min-h-lg);
 
-   /* Badge variables */
-   --badge-radius: 6px;
+   /* 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
+      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+2+2=20, md:
+      16+4+2=22). pill-px must clear the rounded-full cap so text is not eaten
+      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: 1px;
+   --badge-py-md: 2px;
+   --badge-pill-px-sm: 10px;
+   --badge-pill-px-md: 10px;
+
+   /* Pill (chip tier) — px/py per size. rounded-full is intrinsic (no radius
+      token needed); a themed --radius-base leaves it pill either way. */
+   --pill-px-sm: 10px;
+   --pill-px-md: 10px;
+   --pill-px-lg: 12px;
+   --pill-py-sm: 2px;
+   --pill-py-md: 2px;
+   --pill-py-lg: 4px;
+
+   /* Tag (chip tier) — rounded-full intrinsic. md carries a slightly larger LEFT
+      inset (--tag-pl-md) so a leading avatar/icon sits right; px-md is the right
+      edge. */
+   --tag-px-sm: 8px;
+   --tag-px-md: 8px;
+   --tag-pl-md: 10px;
+   --tag-py-sm: 2px;
+   --tag-py-md: 2px;
+
+   /* Kbd (chip tier) — px only; height stays the fixed h-5/h-6 keycap size and
+      radius already derives from --radius-base in Kbd.theme.ts. */
+   --kbd-px-sm: 4px;
+   --kbd-px-md: 6px;
 
    /* Segmented variables - now defined in radius system above */
    --segmented-min-h-sm: var(--form-min-h-sm);
@@ -285,6 +596,81 @@
    --segmented-py-md: var(--form-py-md);
    --segmented-py-lg: var(--form-py-lg);
 
+   /* Segmented type size — aliases the form ramp like every other Segmented
+      box token. Previously Segmented was text-sm at ALL THREE sizes while
+      Button/Input both stepped up at lg, despite --segmented-min-h-* being a
+      straight alias of --form-min-h-*: lg grew its box but not its type. */
+   --segmented-text-size-sm: var(--form-text-size-sm);
+   --segmented-text-size-md: var(--form-text-size-md);
+   --segmented-text-size-lg: var(--form-text-size-lg);
+   --segmented-line-height-sm: var(--form-line-height-sm);
+   --segmented-line-height-md: var(--form-line-height-md);
+   --segmented-line-height-lg: var(--form-line-height-lg);
+
+   /* ============================================
+     SURFACE PADDING SYSTEM — same idea as BORDER RADIUS SYSTEM/TYPE ROLE
+     SYSTEM above: a library can't bake a Tailwind literal (p-6, p-4) into a
+     .theme.ts file and call it themeable — a consumer's theme has no lever
+     to reach it. These are the "brand-visible container weight" surfaces a
+     theme author would actually want to dial roomier/tighter (e.g. the
+     spacious-dialog look), not every padded box in the library — denser/
+     data-oriented chrome (Alert, Toast, Popover, Message, Tooltip,
+     ChartTooltip, GanttChart, CommandPalette, Table, etc.) is deliberately
+     out of scope for now. HeroCard is also deliberately excluded — it's a
+     custom/override presentation of Card, not a foundational container, and
+     keeps its hardcoded p-10.
+     Each token defaults to today's exact px value — zero visual change for
+     any theme that doesn't override these. */
+   --card-px: 24px;
+   --card-py: 24px;
+   /* from p-6 */
+   --modal-px: 16px;
+   --modal-py: 16px;
+   /* from p-4 */
+   --drawer-px: 16px;
+   --drawer-py: 16px;
+   /* from p-4 */
+
+   /* Metric: uniform (not split px/py) — matches its existing non-split
+     contentPaddingSizes shape and the --metric-value-size-* naming. */
+   --metric-content-p-sm: 12px;
+   /* from p-3 */
+   --metric-content-p-md: 16px;
+   /* from p-4 */
+   --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. */
@@ -292,15 +678,24 @@
    /* 2px */
    --segmented-inner-radius: calc(var(--segmented-radius) - var(--segmented-padding) - 1px);
 
-   /* Segmented sliding background */
-   --segmented-active-bg: #ffffff;
-   --segmented-active-shadow:
-      0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
-
-   /* Glass effect variables */
-   --glass-layer-padding: 0.5px;
-   --glass-layer-border-width: 0.5px;
-   --glass-layer-inner-offset: 1.5px;
+   /* 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,
@@ -312,10 +707,6 @@
          rgba(242, 242, 242, 0.8) 0%,
          rgba(250, 250, 250, 0.8) 100%);
 
-   /* Chat message variables */
-   --chat-bubble-border-sender: rgba(255, 255, 255, 0.4);
-   --chat-bubble-border-receiver: rgba(255, 255, 255, 1);
-
    /* Avatar variables — fixed px */
    --avatar-size-xs: 24px;
    /* size-6 in Tailwind */
@@ -330,60 +721,16 @@
 
    /* Avatar radius - now defined in radius system above */
 
-   /* Carousel Variables */
-   --carousel-container-width: 100%;
-   /* Full width container */
-   --carousel-slide-width: 66vw;
-   /* Default slide width - can be overridden */
-   --carousel-slide-height: 44rem;
-   /* 384px = h-96 */
-   --carousel-slide-gap: 16px;
-   /* gap between slides */
-   --carousel-controls-size: 48px;
-   /* control button size */
-   --carousel-controls-offset: 16px;
-   /* distance from edge */
-
-   /* Popover variables - radius now defined in radius system above */
-   --popover-shadow:
-      0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
-   --popover-border-width: 1px;
-   --popover-backdrop-opacity: 0.5;
-   --popover-offset-sm: 8px;
-   --popover-offset-md: 8px;
-   --popover-offset-lg: 12px;
-   --popover-max-width-sm: 256px;
-   --popover-max-width-md: 384px;
-   --popover-max-width-lg: 512px;
-   --popover-padding-sm: 12px;
-   --popover-padding-md: 12px;
-   --popover-padding-lg: 16px;
-
-   /* NavItem variables */
+   /* NavItem variables — radius only (padding/height live in NavItem.theme.ts) */
    --nav-item-radius: var(--radius-base);
-   --nav-item-min-h: 40px;
-   /* h-10 in Tailwind */
-
-   /* NavItem padding — fixed px */
-   --nav-item-px: 12px;
-   /* px-3 in Tailwind */
-   --nav-item-py: 10px;
-   /* py-2.5 in Tailwind */
 
    /* 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 */
    /* Modal radius - now defined in radius system above */
 
-   /* Shadow color presets for utility generation */
-   --shadow-color-primary: var(--color-primary);
-   --shadow-color-success: var(--color-success);
-   --shadow-color-warning: var(--color-warning);
-   --shadow-color-danger: var(--color-danger);
-   --shadow-color-secondary: var(--color-secondary);
-
    /* Neumorphic tokens — light mode (multi-layer realistic) */
    --neu-raised-shadow:
       1px 1px 2px rgba(0, 0, 0, 0.04), 3px 3px 6px rgba(0, 0, 0, 0.06),
@@ -425,6 +772,17 @@
          rgba(255, 255, 255, 0.5) 100%);
 }
 
+/* NOTE on --color-neutral-*: the gray ROLE was renamed to `mono`
+   (--color-mono-* / color="mono") so it stops colliding with Tailwind's own
+   `neutral`. We deliberately do NOT re-alias --color-neutral-* here: in a
+   Tailwind build those names already resolve to Tailwind's real neutral
+   palette (emitted into styles.css alongside slate/zinc/stone, which the
+   RichTextEditor swatches rely on), and re-aliasing them to mono would
+   re-shadow Tailwind's neutral — exactly what this rename removes. Raw-var
+   consumers who used var(--color-neutral-*) for the role should migrate to
+   var(--color-mono-*); the old name now yields Tailwind's neutral (a near-
+   identical gray in the default theme). See CHANGELOG. */
+
 /* ============================================
    DARK MODE OVERRIDES
    Add .dark class to <html> or a parent container
@@ -603,12 +961,18 @@
 
       /* Neutral text ramp (Linear's text reads essentially neutral off-white;
        slate was too blue against the low-chroma surfaces). */
-      --color-text-primary: var(--color-neutral-50);
+      --color-text-primary: var(--color-mono-50);
       --color-text-secondary: oklch(80% 0 0);
-      --color-text-placeholder: var(--color-neutral-600);
-      --color-text-muted: var(--color-neutral-600);
-      --color-text-disabled: var(--color-neutral-400);
-      --color-text-inverse: var(--color-neutral-950);
+      /* Re-derived (same formulas as :root) so the mix picks up the dark
+         text-primary even when .dark is scoped to a subtree — mirrors the
+         contrast-token re-declaration below. 40% of near-white over the dark
+         surfaces lands at the neutral-500 lightness the components used. */
+      --color-text-placeholder: color-mix(in oklab, var(--color-text-primary) 40%, transparent);
+      --color-text-muted: color-mix(in oklab, var(--color-text-primary) 50%, transparent);
+      /* neutral-600, not -400: the value every date/time picker bypassed to —
+         encoded here so components don't need dark: overrides */
+      --color-text-disabled: var(--color-mono-600);
+      --color-text-inverse: var(--color-mono-950);
 
       /* Shimmer surface sweep — dim the white streak on the near-black floor. */
       --shimmer-surface-highlight: color-mix(in srgb, #fff 8%, transparent);
@@ -619,7 +983,8 @@
       --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);
 
       /* Contrast colors for filled variants on semantic backgrounds.
          Auto-derived (same formula as :root) — recomputes against the dark-mode
@@ -628,7 +993,7 @@
       --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 */
       /* Surface ladder — faithful Fluid Functionalism dark palette. 8 rungs step up neutrally
@@ -650,13 +1015,7 @@
       --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-neutral-800);
+      --color-background-disabled: var(--color-mono-800);
 
       /* Scale backdrop — sits behind scaled content, darker than the #171717 floor */
       --color-scale-background: #0a0a0a;
@@ -777,20 +1136,32 @@
          inset 0 20px 40px -8px rgba(0, 0, 0, 0.36),
          inset 0 -1px 0 rgba(255, 255, 255, 0.12);
       --color-chart-track: rgba(255, 255, 255, 0.05);
-
-      /* Glass effect gradients - dark mode */
+      --color-chart-1: #60a5fa;
+      --color-chart-1-contrast: oklch(from var(--color-chart-1) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+      --color-chart-2: #2dd4bf;
+      --color-chart-2-contrast: oklch(from var(--color-chart-2) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+      --color-chart-3: #fbbf24;
+      --color-chart-3-contrast: oklch(from var(--color-chart-3) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+      --color-chart-4: #a78bfa;
+      --color-chart-4-contrast: oklch(from var(--color-chart-4) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+      --color-chart-5: #f472b6;
+      --color-chart-5-contrast: oklch(from var(--color-chart-5) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+
+      /* Glass effect gradients - dark mode. Surface-ladder rungs, NOT the deprecated
+       --color-background-* aliases (removed next major); values match the old ones
+       (tertiary oklch 22% ≈ surface-4, secondary = surface-3, background = surface-1). */
       --glass-gradient-outer: linear-gradient(135deg,
-            var(--color-background-tertiary) 0%,
-            var(--color-background-secondary) 30%,
-            var(--color-background) 70%,
-            var(--color-background-tertiary) 100%);
+            var(--surface-4) 0%,
+            var(--surface-3) 30%,
+            var(--surface-1) 70%,
+            var(--surface-4) 100%);
       --glass-gradient-inner: linear-gradient(to bottom,
-            var(--color-background-secondary) 0%,
-            var(--color-background) 100%);
+            var(--surface-3) 0%,
+            var(--surface-1) 100%);
 
       /* Scrollbar - dark mode */
       --ui-scrollbar-thumb-rest: rgba(75, 85, 99, 0.3);
-      --ui-scrollbar-thumb-active: rgb(75 85 99, 0.75);
+      --ui-scrollbar-thumb-active: rgb(75 85 99 / 0.75);
       --ui-scrollbar-track-rest: transparent;
       --ui-scrollbar-track-active: rgba(55, 65, 81, 0.1);