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

package/src/styles/theme.css

@@ -0,0 +1,838 @@
+@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-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);
+
+   /* 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-neutral-50);
+   --color-secondary-100: var(--color-neutral-100);
+   --color-secondary-200: var(--color-neutral-200);
+   --color-secondary-300: var(--color-neutral-300);
+   --color-secondary-400: var(--color-neutral-400);
+   --color-secondary-500: var(--color-neutral-500);
+   --color-secondary-600: var(--color-neutral-600);
+   --color-secondary-700: var(--color-neutral-700);
+   --color-secondary-800: var(--color-neutral-800);
+   --color-secondary-900: var(--color-neutral-900);
+   --color-secondary-950: var(--color-neutral-950);
+
+   --color-secondary: var(--color-secondary-600);
+   --color-secondary-contrast: oklch(from var(--color-secondary) clamp(0, (0.85 - l) * 1000, 1) 0 0);
+
+   /* Danger/Error color palette - full 50-950 range */
+   --color-danger-50: oklch(0.971 0.013 17.38);
+   --color-danger-100: oklch(0.936 0.032 17.717);
+   --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);
+
+   --color-success: var(--color-success-500);
+   --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-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);
+
+   /* 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);
+   --color-background: var(--surface-1);
+   /* near-white page canvas (rung 1) — white cards lift via the shadow ring */
+   /* DEPRECATED (remove next major): alias of --color-surface. Use the surface ladder. */
+   --color-background-secondary: var(--color-surface);
+   /* DEPRECATED (remove next major): recessed/subtle fills. Migrate per-usage to --color-surface-sunken
+     (dark values below are inverted vs. a correct sunken token, so no blind alias). */
+   --color-background-tertiary: oklch(90% 0.002 247.839);
+   --color-background-quaternary: oklch(85% 0.002 247.839);
+   --color-background-quinary: oklch(80% 0.002 247.839);
+   --color-background-disabled: var(--color-neutral-100);
+
+   --color-neutral-50: oklch(98.5% 0 0);
+   --color-neutral-100: oklch(97% 0 0);
+   --color-neutral-200: oklch(92.2% 0 0);
+   --color-neutral-300: oklch(87% 0 0);
+   --color-neutral-400: oklch(70.8% 0 0);
+   --color-neutral-500: oklch(55.6% 0 0);
+   --color-neutral-600: oklch(43.9% 0 0);
+   --color-neutral-700: oklch(37.1% 0 0);
+   --color-neutral-800: oklch(26.9% 0 0);
+   --color-neutral-900: oklch(20.5% 0 0);
+   --color-neutral-950: oklch(14.5% 0 0);
+
+   /* Font family variables */
+   --font-family-base: var(--font-sans);
+   --font-cursive: "Birthstone", cursive;
+   --font-weight-light: 300;
+   --font-weight-normal: 400;
+   --font-weight-medium: 500;
+   --font-weight-semibold: 600;
+   --font-weight-bold: 700;
+   --font-weight-extrabold: 800;
+
+   /* 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;
+   /* h-10 in Tailwind */
+   --form-min-h-lg: 48px;
+   /* h-12 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-1 in Tailwind */
+   --form-py-md: 10px;
+   /* py-2 in Tailwind */
+   --form-py-lg: 12px;
+   /* py-3 in Tailwind */
+
+   /* ============================================
+     BORDER RADIUS SYSTEM
+     Change --radius-base to adjust the entire UI.
+     Individual --*-radius variables can be overridden independently.
+     ============================================ */
+   --radius-base: 12px;
+   /* Base radius token */
+
+   /* Forms & Controls (1x base = 8px) */
+   --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);
+
+   /* 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);
+
+   /* 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);
+
+   /* 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-py-sm: 0;
+   --button-px-md: 14px;
+   --button-py-md: 0;
+   --button-px-lg: 20px;
+   --button-py-lg: 0;
+
+   /* 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 */
+   --badge-radius: 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 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);
+
+   /* 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%,
+         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%);
+
+   /* 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 */
+   --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 */
+
+   /* 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 */
+   --nav-item-radius: var(--radius-base);
+   --nav-item-min-h: 40px;
+   /* h-10 in Tailwind */
+
+   /* NavItem padding — fixed px */
+   --nav-item-px: 12px;
+   /* px-3 in Tailwind */
+   --nav-item-py: 10px;
+   /* py-2.5 in Tailwind */
+
+   /* Modal and Drawer */
+   --overlay-bg: rgba(0, 0, 0, 0.65);
+   --overlay-blur: 8px;
+   --color-scale-background: oklch(0% 0 0);
+   /* backdrop behind scaled content */
+   /* Modal radius - now defined in radius system above */
+
+   /* Shadow color presets for utility generation */
+   --shadow-color-primary: var(--color-primary);
+   --shadow-color-success: var(--color-success);
+   --shadow-color-warning: var(--color-warning);
+   --shadow-color-danger: var(--color-danger);
+   --shadow-color-secondary: var(--color-secondary);
+
+   /* Neumorphic tokens — light mode (multi-layer realistic) */
+   --neu-raised-shadow:
+      1px 1px 2px rgba(0, 0, 0, 0.04), 3px 3px 6px rgba(0, 0, 0, 0.06),
+      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%);
+}
+
+/* ============================================
+   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-neutral-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);
+
+      /* 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);
+
+      /* 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);
+
+      /* 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-neutral-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);
+
+      /* Glass effect gradients - dark mode */
+      --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%);
+      --glass-gradient-inner: linear-gradient(to bottom,
+            var(--color-background-secondary) 0%,
+            var(--color-background) 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%);
+   }
+}