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

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);
@@ -26,17 +26,17 @@
       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-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);
@@ -70,7 +70,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 +91,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,6 +148,24 @@
      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. */
@@ -150,23 +175,58 @@
    --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;
+
+   /* ============================================
+     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 +234,61 @@
    --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.
+     ============================================ */
+   --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);
+   /* 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);
+
    /* 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 +301,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 +399,97 @@
       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));
+   --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));
+
+   /* 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 +500,46 @@
    --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+0+2=18, md:
+      16+4+2=22). pill-px must clear the rounded-full cap so text is not eaten
+      by the curve. */
+   --badge-radius: calc(var(--radius-base) * 0.75);
+   --badge-px-sm: 4px;
+   --badge-px-md: 6px;
+   --badge-py-sm: 0px;
+   --badge-py-md: 2px;
+   --badge-pill-px-sm: 8px;
+   --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 +555,50 @@
    --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 */
+
    /* 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,16 +606,6 @@
    /* 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;
-
    /* Glass effect gradient variables */
    --glass-gradient-outer: linear-gradient(to bottom,
          rgba(250, 250, 250, 0.8) 0%,
@@ -312,10 +616,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,45 +630,8 @@
 
    /* 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);
@@ -377,13 +640,6 @@
    /* 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 +681,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 +870,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);
@@ -620,6 +893,8 @@
       --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
@@ -629,6 +904,7 @@
       --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
@@ -656,7 +932,7 @@
       --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 +1053,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);