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

package/src/styles/theme.css

@@ -0,0 +1,1126 @@
+@theme {
+   /* 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-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);
+   /* Auto-derived: dark text on light/white primaries, white text on dark ones.
+      Crossover at oklch L 0.85 — see CLAUDE.md §3. The relative-color syntax reads
+      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);
+   --color-danger-200: oklch(0.885 0.062 18.334);
+   --color-danger-300: oklch(0.808 0.114 19.571);
+   --color-danger-400: oklch(0.704 0.191 22.216);
+   --color-danger-500: oklch(0.637 0.237 25.331);
+   --color-danger-600: oklch(0.577 0.245 27.325);
+   --color-danger-700: oklch(0.505 0.213 27.518);
+   --color-danger-800: oklch(0.444 0.177 26.899);
+   --color-danger-900: oklch(0.396 0.141 25.723);
+   --color-danger-950: oklch(0.258 0.092 26.042);
+
+   --color-danger: var(--color-danger-600);
+   --color-danger-contrast: oklch(from var(--color-danger) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+
+   /* Success color palette - Tailwind v4 teal */
+   --color-success-50: oklch(0.984 0.014 180.72);
+   --color-success-100: oklch(0.953 0.051 180.801);
+   --color-success-200: oklch(0.91 0.096 180.426);
+   --color-success-300: oklch(0.855 0.138 181.071);
+   --color-success-400: oklch(0.777 0.152 181.912);
+   --color-success-500: oklch(0.704 0.14 182.503);
+   --color-success-600: oklch(0.6 0.118 184.704);
+   --color-success-700: oklch(0.511 0.096 186.391);
+   --color-success-800: oklch(0.437 0.078 188.216);
+   --color-success-900: oklch(0.386 0.063 188.416);
+   --color-success-950: oklch(0.277 0.046 192.524);
+
+   /* -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 */
+   --color-warning-50: oklch(0.987 0.022 95.277);
+   --color-warning-100: oklch(0.962 0.059 95.617);
+   --color-warning-200: oklch(0.924 0.12 95.746);
+   --color-warning-300: oklch(0.879 0.169 91.605);
+   --color-warning-400: oklch(0.828 0.189 84.429);
+   --color-warning-500: oklch(0.769 0.188 70.08);
+   --color-warning-600: oklch(0.666 0.179 58.318);
+   --color-warning-700: oklch(0.555 0.163 48.998);
+   --color-warning-800: oklch(0.473 0.137 46.201);
+   --color-warning-900: oklch(0.414 0.112 45.904);
+   --color-warning-950: oklch(0.279 0.077 45.635);
+
+   --color-warning: var(--color-warning-600);
+   --color-warning-contrast: oklch(from var(--color-warning) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+
+   /* text color */
+   --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);
+   --color-border-secondary: oklch(87% 0 0);
+   /* Interaction border (hover/focus-adjacent) — darkens in light for a clear
+     edge, mirror of --color-surface-hover but on the border axis. */
+   --color-border-hover: oklch(80% 0 0);
+   /* ============================================
+     SURFACE ELEVATION LADDER — Fluid Functionalism (https://www.fluidfunctionalism.com/docs/surfaces)
+     8 numbered rungs are the ENGINE source of truth; the semantic tokens below are ALIASES onto fixed
+     rungs (existing theme files keep using --color-surface-overlay etc. unchanged). The relative-
+     elevation engine (src/theme/SurfaceContext) paints a deeper rung at runtime when a surface is nested.
+     Named --surface-N (NOT --color-surface-N) on purpose — keeps the bg-[var(--surface-N)] arbitrary-
+     value convention and avoids Tailwind auto-generating a colliding `surface-N` color utility.
+     Light: NEAR-WHITE floor (1=#FAFAFA), then WHITE ceiling (3–8 all #FFFFFF) — depth above the card is
+     carried by the doubling shadow ladder, NOT luminance. ============================================ */
+   --surface-1: #fafafa;
+   --surface-2: #fcfcfc;
+   --surface-3: #ffffff;
+   --surface-4: #ffffff;
+   --surface-5: #ffffff;
+   --surface-6: #ffffff;
+   --surface-7: #ffffff;
+   --surface-8: #ffffff;
+
+   /* Semantic aliases onto the rungs. */
+   --color-surface: var(--surface-3);
+   /* card — Card, KPI, Table, Sidebar… lift off the near-white floor via the shadow ring */
+   --color-surface-raised: var(--surface-4);
+   /* Modal/Drawer; pop via shadow + dimmed backdrop */
+   --color-surface-overlay: var(--surface-5);
+   /* Dropdown/Popover/Tooltip; pop via shadow */
+   /* sunken stays STANDALONE (a recess INSIDE a card — code, table zebra, tracks — not an
+     elevation rung), so it is not aliased to the ladder. */
+   --color-surface-sunken: #f4f4f4;
+   /* Input/field fill — the surface a text field paints. Defaults to the card surface (rung 3); the
+     relative-elevation engine raises it to ONE RUNG ABOVE the host (surfaceClasses publishes
+     `--field-fill = surface(level+1)` on each surface element, which inputs inherit via the CSS
+     cascade), so a field lifts a step out of its card/modal/overlay in dark. In light, rungs 3–8 are
+     all white, so this resolves to white = unchanged from a plain surface fill. */
+   --field-fill: var(--color-surface);
+   /* Interaction fill (the one tokenized state): translucent tint so it composites correctly
+     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-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);
+
+   /* ============================================
+     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;
+   --font-weight-semibold: 600;
+   --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: 36px;
+   /* h-9 in Tailwind */
+   --form-min-h-lg: 40px;
+   /* h-10 in Tailwind */
+
+   --form-label-pb: 8px;
+   /* pb-2 in Tailwind */
+
+   --form-px-sm: 12px;
+   /* px-3 in Tailwind */
+   --form-px-md: 14px;
+   /* px-3.5 in Tailwind */
+   --form-px-lg: 16px;
+   /* px-4 in Tailwind */
+
+   --form-py-sm: 8px;
+   /* 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: 8px;
+   /* Base radius token */
+
+   /* Forms & Controls (1x base = 12px) */
+   --form-radius: var(--radius-base);
+
+   /* Checkbox: small absolute box (20–28px), so the radius is CAPPED — a raw
+      multiple of --radius-base rounds the sm variant into a circle once the
+      base grows. min() keeps it a rounded square at any base. */
+   --checkbox-radius: min(calc(var(--radius-base) * 0.5), 6px);
+
+   /* 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: 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%;
+
+   /* 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. 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: 12px;
+   --button-py-md: 0;
+   --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;
+   --button-icon-p-lg: 10px;
+
+   /* Button icon-only sizes */
+   --button-icon-size-sm: var(--form-min-h-sm);
+   --button-icon-size-md: var(--form-min-h-md);
+   --button-icon-size-lg: var(--form-min-h-lg);
+
+   /* 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);
+   --segmented-min-h-md: var(--form-min-h-md);
+   --segmented-min-h-lg: var(--form-min-h-lg);
+
+   /* Segmented padding */
+   --segmented-px-sm: 8px;
+   --segmented-px-md: 10px;
+   --segmented-px-lg: 12px;
+
+   --segmented-py-sm: var(--form-py-sm);
+   --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. */
+   --segmented-padding: 0.125rem;
+   /* 2px */
+   --segmented-inner-radius: calc(var(--segmented-radius) - var(--segmented-padding) - 1px);
+
+   /* Glass effect gradient variables */
+   --glass-gradient-outer: linear-gradient(to bottom,
+         rgba(250, 250, 250, 0.8) 0%,
+         rgba(229, 229, 229, 0.8) 30%,
+         rgba(242, 242, 242, 0.8) 70%,
+         rgba(250, 250, 250, 0.8) 100%);
+   --glass-gradient-inner: linear-gradient(to bottom,
+         rgba(242, 242, 242, 0.8) 0%,
+         rgba(250, 250, 250, 0.8) 100%);
+
+   /* Avatar variables — fixed px */
+   --avatar-size-xs: 24px;
+   /* size-6 in Tailwind */
+   --avatar-size-sm: 32px;
+   /* size-8 in Tailwind */
+   --avatar-size-md: 40px;
+   /* size-10 in Tailwind */
+   --avatar-size-lg: 48px;
+   /* size-12 in Tailwind */
+   --avatar-size-xl: 64px;
+   /* size-16 in Tailwind */
+
+   /* Avatar radius - now defined in radius system above */
+
+   /* NavItem variables — radius only (padding/height live in NavItem.theme.ts) */
+   --nav-item-radius: var(--radius-base);
+
+   /* Modal and Drawer */
+   --overlay-bg: rgba(0, 0, 0, 0.65);
+   --overlay-blur: 8px;
+   --color-scale-background: oklch(0% 0 0);
+   /* backdrop behind scaled content */
+   /* Modal radius - now defined in radius system above */
+
+   /* 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),
+      6px 6px 14px rgba(0, 0, 0, 0.08), 12px 12px 28px rgba(0, 0, 0, 0.04),
+      -1px -1px 2px rgba(255, 255, 255, 0.5),
+      -3px -3px 6px rgba(255, 255, 255, 0.5),
+      -6px -6px 14px rgba(255, 255, 255, 0.3),
+      inset 0 1px 0 rgba(255, 255, 255, 0.6), inset 0 -1px 0 rgba(0, 0, 0, 0.04);
+   --neu-inset-shadow:
+      inset 1px 1px 2px rgba(0, 0, 0, 0.06),
+      inset 2px 2px 4px rgba(0, 0, 0, 0.06),
+      inset 4px 4px 8px rgba(0, 0, 0, 0.05),
+      inset 8px 8px 16px rgba(0, 0, 0, 0.03),
+      inset -1px -1px 2px rgba(255, 255, 255, 0.5),
+      inset -3px -3px 6px rgba(255, 255, 255, 0.4),
+      inset -6px -6px 12px rgba(255, 255, 255, 0.2),
+      0 1px 0 rgba(255, 255, 255, 0.5);
+   --neu-circle-groove-shadow:
+      inset 0.5px 0.5px 1px rgba(0, 0, 0, 0.08),
+      inset 1px 1px 3px rgba(0, 0, 0, 0.08),
+      inset 2px 2px 5px rgba(0, 0, 0, 0.04), 0.5px 0.5px 1px rgba(0, 0, 0, 0.4),
+      1px 1px 2px rgba(0, 0, 0, 0.3);
+   --neu-circle-disc-shadow:
+      inset 0.5px 0.5px 1px rgba(0, 0, 0, 0.05),
+      inset 1px 1px 3px rgba(0, 0, 0, 0.04),
+      inset -0.5px -0.5px 1px rgba(255, 255, 255, 0.4),
+      inset -1px -1px 2px rgba(255, 255, 255, 0.3), 0 1px 2px rgba(0, 0, 0, 0.06),
+      0 2px 4px rgba(0, 0, 0, 0.04);
+   --neu-raised-border: linear-gradient(145deg,
+         rgba(255, 255, 255, 0.7) 0%,
+         rgba(255, 255, 255, 0.35) 30%,
+         transparent 50%,
+         rgba(0, 0, 0, 0.06) 100%);
+   --neu-inset-border: linear-gradient(180deg,
+         rgba(0, 0, 0, 0.1) 0%,
+         rgba(0, 0, 0, 0.04) 25%,
+         rgba(255, 255, 255, 0.15) 50%,
+         rgba(255, 255, 255, 0.35) 75%,
+         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
+   to enable dark mode. All CSS variable-based
+   components will automatically adapt.
+
+   IMPORTANT: Dark mode overrides MUST be in @layer theme
+   (not @layer base) for proper cascade priority in Tailwind v4.
+   This ensures CSS variable overrides take precedence over
+   Tailwind's generated theme styles.
+   ============================================ */
+@layer theme {
+
+   /* Scrollbar - light mode defaults.
+     These MUST live in @layer theme (not @layer base) alongside the .dark
+     override below. The layer order is `theme, base, ...`, so values in
+     @layer base win over @layer theme — if these defaults sat in base, the
+     .dark override here would never apply and the scrollbar would render with
+     the light (bright) thumb in dark mode. Keeping both in @layer theme means
+     the .dark block (later source order, equal specificity) wins. */
+   :root {
+      /* Tell the UA which palette to paint native chrome (scrollbars, form
+       controls, etc.). Our custom `::-webkit-scrollbar` track/thumb are mostly
+       transparent, so without this the browser composites its *default light*
+       scrollbar underneath — in dark mode the visible (active) track then reads
+       as an opaque white bar showing through the faint dark tint. `.dark` flips
+       this to `dark` below so the UA scrollbar matches the surface. */
+      color-scheme: light;
+      --ui-scrollbar-size: 4px;
+      --ui-scrollbar-thumb-rest: rgba(209, 213, 219, 0.3);
+      --ui-scrollbar-thumb-active: rgb(209 213 219);
+      --ui-scrollbar-track-rest: transparent;
+      --ui-scrollbar-track-active: rgba(209, 213, 219, 0.1);
+
+      /* Shimmer effect (effects/Shimmer) — light defaults.
+       Text shimmer adapts to dark for free via --color-text-* tokens; only the
+       surface sweep streak needs a .dark override (a strong white streak is too
+       loud on the near-black floor) — see the .dark block below. Both default
+       and override live in @layer theme so the .dark value wins the cascade. */
+      --shimmer-color: var(--color-text-muted);
+      --shimmer-highlight: var(--color-text-primary);
+      --shimmer-duration: 2s;
+      --shimmer-spread: 20%;
+      --shimmer-surface-highlight: color-mix(in srgb, #fff 60%, transparent);
+   }
+
+   /* Realistic layered elevation shadows — light mode (source of truth).
+     Consumed by `@utility shadow-real-*` / `shadow-inner-real-*` in global.scss.
+     Tokenized here (NOT inline in the utility) so the `.dark` block below can
+     swap them — faint multi-layer black reads on light surfaces but is invisible
+     on the near-black dark floor, so dark gets a depth-pool + top-rim treatment.
+     🔴 Named --elevation-* on purpose, NOT --shadow-*: a `--shadow-*` theme
+     property makes Tailwind v4 auto-generate a colliding `shadow-*` utility. */
+   :root {
+      /* Doubling shadow ladder (Fluid Functionalism) — one faint color, offsets/blur double every
+       step, each layer a matching negative spread, plus a 0 0 0 1px hairline ring that carries the
+       surface edge. The 8 numbered --elevation-surface-N are the CANONICAL per-rung shadows (consumed
+       by @utility shadow-surface-N and the SurfaceContext engine); --elevation-real-{sm…3xl} below
+       are named ALIASES of rungs 2…7 (one source of truth, two name schemes). Each rung = the full
+       cumulative stack up to its level (rung 1 = ring only; rung 8 adds the 96px layer). */
+      --elevation-shadow-color: rgb(0 0 0 / 0.06);
+      --elevation-surface-1: 0 0 0 1px var(--elevation-shadow-color);
+      --elevation-surface-2:
+         0 0 0 1px var(--elevation-shadow-color),
+         0 1px 1px -0.5px var(--elevation-shadow-color);
+      --elevation-surface-3:
+         0 0 0 1px var(--elevation-shadow-color),
+         0 1px 1px -0.5px var(--elevation-shadow-color),
+         0 3px 3px -1.5px var(--elevation-shadow-color);
+      --elevation-surface-4:
+         0 0 0 1px var(--elevation-shadow-color),
+         0 1px 1px -0.5px var(--elevation-shadow-color),
+         0 3px 3px -1.5px var(--elevation-shadow-color),
+         0 6px 6px -3px var(--elevation-shadow-color);
+      --elevation-surface-5:
+         0 0 0 1px var(--elevation-shadow-color),
+         0 1px 1px -0.5px var(--elevation-shadow-color),
+         0 3px 3px -1.5px var(--elevation-shadow-color),
+         0 6px 6px -3px var(--elevation-shadow-color),
+         0 12px 12px -6px var(--elevation-shadow-color);
+      --elevation-surface-6:
+         0 0 0 1px var(--elevation-shadow-color),
+         0 1px 1px -0.5px var(--elevation-shadow-color),
+         0 3px 3px -1.5px var(--elevation-shadow-color),
+         0 6px 6px -3px var(--elevation-shadow-color),
+         0 12px 12px -6px var(--elevation-shadow-color),
+         0 24px 24px -12px var(--elevation-shadow-color);
+      --elevation-surface-7:
+         0 0 0 1px var(--elevation-shadow-color),
+         0 1px 1px -0.5px var(--elevation-shadow-color),
+         0 3px 3px -1.5px var(--elevation-shadow-color),
+         0 6px 6px -3px var(--elevation-shadow-color),
+         0 12px 12px -6px var(--elevation-shadow-color),
+         0 24px 24px -12px var(--elevation-shadow-color),
+         0 48px 48px -24px var(--elevation-shadow-color);
+      --elevation-surface-8:
+         0 0 0 1px var(--elevation-shadow-color),
+         0 1px 1px -0.5px var(--elevation-shadow-color),
+         0 3px 3px -1.5px var(--elevation-shadow-color),
+         0 6px 6px -3px var(--elevation-shadow-color),
+         0 12px 12px -6px var(--elevation-shadow-color),
+         0 24px 24px -12px var(--elevation-shadow-color),
+         0 48px 48px -24px var(--elevation-shadow-color),
+         0 96px 96px -48px var(--elevation-shadow-color);
+      /* Named aliases (sm…3xl = rungs 2…7) — keep for ad-hoc shadow-real-* utility use. */
+      --elevation-real-sm: var(--elevation-surface-2);
+      --elevation-real-md: var(--elevation-surface-3);
+      --elevation-real-lg: var(--elevation-surface-4);
+      --elevation-real-xl: var(--elevation-surface-5);
+      --elevation-real-2xl: var(--elevation-surface-6);
+      --elevation-real-3xl: var(--elevation-surface-7);
+
+      --elevation-inner-real-sm:
+         inset 0px 0.9px 0.8px rgba(0, 0, 0, 0.04),
+         inset 0px 3.6px 3.2px -1.5px rgba(0, 0, 0, 0.08);
+      --elevation-inner-real-md:
+         inset 0px 0.9px 0.8px rgba(0, 0, 0, 0.04),
+         inset 0px 3.7px 3.3px -2px rgba(0, 0, 0, 0.09),
+         inset 0px 18.2px 16.2px -4.1px rgba(0, 0, 0, 0.06);
+      --elevation-inner-real-lg:
+         inset 0px 0.9px 0.8px rgba(0, 0, 0, 0.04),
+         inset 0px 3.6px 3.2px -0.8px rgba(0, 0, 0, 0.06),
+         inset 0px 9.5px 8.5px -1.6px rgba(0, 0, 0, 0.06),
+         inset 0px 22.6px 20.2px -2.4px rgba(0, 0, 0, 0.05),
+         inset 0px 47.3px 42.2px -3.2px rgba(0, 0, 0, 0.04),
+         inset 0px 87.7px 78.3px -4.1px rgba(0, 0, 0, 0.03);
+      --elevation-inner-real-xl:
+         inset 0px 0.9px 0.8px rgba(0, 0, 0, 0.04),
+         inset 0px 4.8px 4.3px -0.5px rgba(0, 0, 0, 0.06),
+         inset 0px 11.2px 10px -1px rgba(0, 0, 0, 0.06),
+         inset 0px 21.3px 19px -1.5px rgba(0, 0, 0, 0.05),
+         inset 0px 38.4px 34.3px -2px rgba(0, 0, 0, 0.05),
+         inset 0px 64.6px 57.7px -2.5px rgba(0, 0, 0, 0.04),
+         inset 0px 102.1px 91.2px -3px rgba(0, 0, 0, 0.03),
+         inset 0px 154.3px 137.8px -3.5px rgba(0, 0, 0, 0.03),
+         inset 0px 222.5px 198.7px -4.1px rgba(0, 0, 0, 0.02);
+      --elevation-inner-real-2xl:
+         inset 0px 0.9px 0.8px rgba(0, 0, 0, 0.04),
+         inset 0px 6.2px 5.5px -0.3px rgba(0, 0, 0, 0.06),
+         inset 0px 14.8px 13.2px -0.6px rgba(0, 0, 0, 0.06),
+         inset 0px 27.1px 24.2px -0.9px rgba(0, 0, 0, 0.06),
+         inset 0px 45.2px 40.4px -1.2px rgba(0, 0, 0, 0.05),
+         inset 0px 70.3px 62.8px -1.5px rgba(0, 0, 0, 0.05),
+         inset 0px 104.2px 93.1px -1.8px rgba(0, 0, 0, 0.04),
+         inset 0px 148.9px 133px -2.1px rgba(0, 0, 0, 0.04),
+         inset 0px 207.4px 185.3px -2.4px rgba(0, 0, 0, 0.03),
+         inset 0px 283.8px 253.5px -2.7px rgba(0, 0, 0, 0.03),
+         inset 0px 381.6px 340.9px -3px rgba(0, 0, 0, 0.02),
+         inset 0px 503.7px 450px -3.3px rgba(0, 0, 0, 0.02);
+      --elevation-inner-real-3xl:
+         inset 0px 0.9px 0.8px rgba(0, 0, 0, 0.04),
+         inset 0px 8.1px 7.2px -0.2px rgba(0, 0, 0, 0.06),
+         inset 0px 19.3px 17.2px -0.4px rgba(0, 0, 0, 0.06),
+         inset 0px 34.8px 31.1px -0.6px rgba(0, 0, 0, 0.06),
+         inset 0px 55.2px 49.3px -0.8px rgba(0, 0, 0, 0.06),
+         inset 0px 81.7px 73px -1px rgba(0, 0, 0, 0.05),
+         inset 0px 115.8px 103.4px -1.2px rgba(0, 0, 0, 0.05),
+         inset 0px 158.9px 142px -1.4px rgba(0, 0, 0, 0.05),
+         inset 0px 212.4px 189.7px -1.6px rgba(0, 0, 0, 0.04),
+         inset 0px 278.8px 249.1px -1.8px rgba(0, 0, 0, 0.04),
+         inset 0px 360.5px 322.1px -2px rgba(0, 0, 0, 0.03),
+         inset 0px 460.1px 411px -2.2px rgba(0, 0, 0, 0.03),
+         inset 0px 579.9px 518px -2.4px rgba(0, 0, 0, 0.02),
+         inset 0px 722.4px 645.3px -2.6px rgba(0, 0, 0, 0.02),
+         inset 0px 890.8px 796px -2.8px rgba(0, 0, 0, 0.02);
+   }
+
+   .dark {
+      /* Paint native UA chrome (scrollbars, form controls) with the dark palette.
+       Pairs with `color-scheme: light` on :root — fixes the white native
+       scrollbar track that showed through our transparent custom track in dark
+       mode (Select, RichTextEditor dropdowns, any native-overflow surface). */
+      color-scheme: dark;
+
+      /* Text colors - inverted for dark backgrounds */
+
+      /* 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-mono-50);
+      --color-text-secondary: oklch(80% 0 0);
+      /* 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);
+
+      /* Base theme colors */
+      /* Dark mode: light primary → light buttons with dark text (contrast auto-resolves dark). */
+      --color-primary: var(--color-primary-100);
+      --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
+         base steps (-500/-400) overridden just above. See CLAUDE.md §3. */
+      --color-primary-contrast: oklch(from var(--color-primary) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+      --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
+       (no tint) from the #171717 floor; semantic tokens alias the same rungs as in light. The
+       engine paints deeper rungs (6–8) when surfaces nest. */
+      --surface-1: #171717;
+      --surface-2: #1e1e1e;
+      --surface-3: #252525;
+      --surface-4: #2c2c2c;
+      --surface-5: #333333;
+      --surface-6: #3a3a3a;
+      --surface-7: #414141;
+      --surface-8: #484848;
+      --color-surface: var(--surface-3);
+      --color-surface-raised: var(--surface-4);
+      --color-surface-overlay: var(--surface-5);
+      /* sunken stays standalone — recessed inside cards (≈ rung 2, but it's a well, not a lift) */
+      --color-surface-sunken: #1e1e1e;
+      --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 */
+      --color-scale-background: #0a0a0a;
+
+      /* Border - Linear-style subtle light hairline (a faint lift that catches
+       light on the dark surface, rather than a flat mid-gray line). */
+      --color-border: oklch(100% 0.01 255 / 0.05);
+      --color-border-secondary: oklch(100% 0.01 255 / 0.10);
+      /* Interaction border — lightens in dark (higher alpha) so an edge "lifts"
+       on hover, matching the --color-surface-hover lighten-in-dark behavior. */
+      --color-border-hover: oklch(100% 0.01 255 / 0.18);
+
+      /* Realistic elevation shadows — dark mode (Fluid Functionalism doubling ladder).
+       Faint black is invisible on the dark floor, so each level layers: a scaling inset
+       white TOP RIM (dm-hi, the lit top edge — the primary "raised panel" cue in dark
+       UIs), a scaling inset ring (dm-ring), a scaling black 0 0 0 1px outline, and the
+       same doubling black drop ladder (dm-drop) used in light. Mirrors their shadow-2…7. */
+      --dm-hi-base: rgba(255, 255, 255, 0.01);
+      --dm-hi-mid: rgba(255, 255, 255, 0.02);
+      --dm-hi-high: rgba(255, 255, 255, 0.04);
+      --dm-hi-peak: rgba(255, 255, 255, 0.06);
+      --dm-ring-base: rgba(255, 255, 255, 0.02);
+      --dm-ring-mid: rgba(255, 255, 255, 0.04);
+      --dm-ring-high: rgba(255, 255, 255, 0.06);
+      --dm-drop: rgba(0, 0, 0, 0.18);
+      /* Canonical per-rung dark shadows (1 = inset ring only; 8 adds the 96px layer). */
+      --elevation-surface-1:
+         inset 0 0 0 1px var(--dm-ring-base);
+      --elevation-surface-2:
+         inset 0 1px 0 0 var(--dm-hi-base),
+         inset 0 0 0 1px var(--dm-ring-base),
+         0 1px 1px -0.5px var(--dm-drop);
+      --elevation-surface-3:
+         inset 0 1px 0 0 var(--dm-hi-mid),
+         inset 0 0 0 1px var(--dm-ring-base),
+         0 0 0 1px rgba(0, 0, 0, 0.12),
+         0 1px 1px -0.5px var(--dm-drop),
+         0 3px 3px -1.5px var(--dm-drop);
+      --elevation-surface-4:
+         inset 0 1px 0 0 var(--dm-hi-mid),
+         inset 0 0 0 1px var(--dm-ring-mid),
+         0 0 0 1px rgba(0, 0, 0, 0.14),
+         0 1px 1px -0.5px var(--dm-drop),
+         0 3px 3px -1.5px var(--dm-drop),
+         0 6px 6px -3px var(--dm-drop);
+      --elevation-surface-5:
+         inset 0 1px 0 0 var(--dm-hi-high),
+         inset 0 0 0 1px var(--dm-ring-mid),
+         0 0 0 1px rgba(0, 0, 0, 0.16),
+         0 1px 1px -0.5px var(--dm-drop),
+         0 3px 3px -1.5px var(--dm-drop),
+         0 6px 6px -3px var(--dm-drop),
+         0 12px 12px -6px var(--dm-drop);
+      --elevation-surface-6:
+         inset 0 1px 0 0 var(--dm-hi-high),
+         inset 0 0 0 1px var(--dm-ring-high),
+         0 0 0 1px rgba(0, 0, 0, 0.18),
+         0 1px 1px -0.5px var(--dm-drop),
+         0 3px 3px -1.5px var(--dm-drop),
+         0 6px 6px -3px var(--dm-drop),
+         0 12px 12px -6px var(--dm-drop),
+         0 24px 24px -12px var(--dm-drop);
+      --elevation-surface-7:
+         inset 0 1px 0 0 var(--dm-hi-peak),
+         inset 0 0 0 1px var(--dm-ring-high),
+         0 0 0 1px rgba(0, 0, 0, 0.20),
+         0 1px 1px -0.5px var(--dm-drop),
+         0 3px 3px -1.5px var(--dm-drop),
+         0 6px 6px -3px var(--dm-drop),
+         0 12px 12px -6px var(--dm-drop),
+         0 24px 24px -12px var(--dm-drop),
+         0 48px 48px -24px var(--dm-drop);
+      --elevation-surface-8:
+         inset 0 1px 0 0 var(--dm-hi-peak),
+         inset 0 0 0 1px var(--dm-ring-high),
+         0 0 0 1px rgba(0, 0, 0, 0.22),
+         0 1px 1px -0.5px var(--dm-drop),
+         0 3px 3px -1.5px var(--dm-drop),
+         0 6px 6px -3px var(--dm-drop),
+         0 12px 12px -6px var(--dm-drop),
+         0 24px 24px -12px var(--dm-drop),
+         0 48px 48px -24px var(--dm-drop),
+         0 96px 96px -48px var(--dm-drop);
+      --elevation-real-sm: var(--elevation-surface-2);
+      --elevation-real-md: var(--elevation-surface-3);
+      --elevation-real-lg: var(--elevation-surface-4);
+      --elevation-real-xl: var(--elevation-surface-5);
+      --elevation-real-2xl: var(--elevation-surface-6);
+      --elevation-real-3xl: var(--elevation-surface-7);
+
+      /* Inset/recessed in dark: a black inset barely shows on the near-black floor
+       (same reason outer shadows fail), so the recess is carried by the WHITE
+       BOTTOM LIP — light pooling on the well's lower inner edge is the readable
+       "carved" cue in dark (inverse of the outer set's top rim). The white lip is
+       the primary signal here, NOT the black; the black inset only adds in-card
+       depth where the well sits on a lighter card. */
+      --elevation-inner-real-sm:
+         inset 0 1px 2px rgba(0, 0, 0, 0.30),
+         inset 0 -1px 0 rgba(255, 255, 255, 0.09);
+      --elevation-inner-real-md:
+         inset 0 1px 2px rgba(0, 0, 0, 0.30),
+         inset 0 3px 6px -1px rgba(0, 0, 0, 0.30),
+         inset 0 -1px 0 rgba(255, 255, 255, 0.10);
+      --elevation-inner-real-lg:
+         inset 0 2px 4px rgba(0, 0, 0, 0.32),
+         inset 0 6px 12px -2px rgba(0, 0, 0, 0.30),
+         inset 0 -1px 0 rgba(255, 255, 255, 0.10);
+      --elevation-inner-real-xl:
+         inset 0 2px 5px rgba(0, 0, 0, 0.35),
+         inset 0 10px 20px -4px rgba(0, 0, 0, 0.32),
+         inset 0 -1px 0 rgba(255, 255, 255, 0.11);
+      --elevation-inner-real-2xl:
+         inset 0 3px 6px rgba(0, 0, 0, 0.38),
+         inset 0 14px 28px -6px rgba(0, 0, 0, 0.34),
+         inset 0 -1px 0 rgba(255, 255, 255, 0.11);
+      --elevation-inner-real-3xl:
+         inset 0 3px 8px rgba(0, 0, 0, 0.40),
+         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);
+      --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(--surface-4) 0%,
+            var(--surface-3) 30%,
+            var(--surface-1) 70%,
+            var(--surface-4) 100%);
+      --glass-gradient-inner: linear-gradient(to bottom,
+            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-track-rest: transparent;
+      --ui-scrollbar-track-active: rgba(55, 65, 81, 0.1);
+
+      /* Neumorphic tokens — dark mode (multi-layer realistic) */
+      --neu-raised-shadow:
+         1px 1px 2px rgba(0, 0, 0, 0.2), 3px 3px 6px rgba(0, 0, 0, 0.25),
+         6px 6px 14px rgba(0, 0, 0, 0.2), 12px 12px 28px rgba(0, 0, 0, 0.1),
+         -1px -1px 2px rgba(255, 255, 255, 0.02),
+         -3px -3px 6px rgba(255, 255, 255, 0.015),
+         -6px -6px 14px rgba(255, 255, 255, 0.01),
+         inset 0 1px 0 rgba(255, 255, 255, 0.04),
+         inset 0 -1px 0 rgba(0, 0, 0, 0.15);
+      --neu-inset-shadow:
+         inset 1px 1px 2px rgba(0, 0, 0, 0.3),
+         inset 2px 2px 4px rgba(0, 0, 0, 0.25),
+         inset 4px 4px 8px rgba(0, 0, 0, 0.2),
+         inset 8px 8px 16px rgba(0, 0, 0, 0.1),
+         inset -1px -1px 2px rgba(255, 255, 255, 0.02),
+         inset -3px -3px 6px rgba(255, 255, 255, 0.015),
+         0 1px 0 rgba(255, 255, 255, 0.04);
+      --neu-circle-groove-shadow:
+         inset 0.5px 0.5px 1px rgba(0, 0, 0, 0.4),
+         inset 1px 1px 2px rgba(0, 0, 0, 0.35),
+         inset 2px 2px 5px rgba(0, 0, 0, 0.2),
+         0.5px 0.5px 1px rgba(255, 255, 255, 0.04),
+         1px 1px 2px rgba(255, 255, 255, 0.03);
+      --neu-circle-disc-shadow:
+         inset 0.5px 0.5px 1px rgba(0, 0, 0, 0.2),
+         inset 1px 1px 3px rgba(0, 0, 0, 0.15),
+         inset -0.5px -0.5px 1px rgba(255, 255, 255, 0.04),
+         inset -1px -1px 2px rgba(255, 255, 255, 0.03),
+         0 1px 2px rgba(0, 0, 0, 0.25), 0 2px 4px rgba(0, 0, 0, 0.2);
+      --neu-raised-border: linear-gradient(145deg,
+            rgba(255, 255, 255, 0.2) 0%,
+            rgba(255, 255, 255, 0.08) 30%,
+            transparent 50%,
+            rgba(0, 0, 0, 0.12) 100%);
+      --neu-inset-border: linear-gradient(180deg,
+            rgba(0, 0, 0, 0.4) 0%,
+            rgba(0, 0, 0, 0.15) 25%,
+            rgba(255, 255, 255, 0.03) 50%,
+            rgba(255, 255, 255, 0.08) 75%,
+            rgba(255, 255, 255, 0.12) 100%);
+   }
+}