@devalok/shilp-sutra 0.36.1 → 0.37.0-next.1

package/dist/tokens/semantic.css

@@ -1,337 +1,475 @@
+/* ═══════════════════════════════════════════════════════════════════
+   SEMANTIC TOKENS (TW4 native)
+
+   This file expresses the design system's PUBLIC token surface as
+   Tailwind 4 `@theme` variables. Every `@theme` variable below maps
+   to an auto-generated utility class:
+
+     --color-accent-9       → bg-accent-9, text-accent-9, border-accent-9, ...
+     --spacing-ds-03        → p-ds-03, m-ds-03, gap-ds-03, w-ds-03, ...
+     --text-ds-md           → text-ds-md
+     --leading-ds-relaxed   → leading-ds-relaxed
+     --radius-ds-md         → rounded-ds-md
+     --shadow-raised        → shadow-raised
+     --ease-productive-standard → ease-productive-standard
+     --breakpoint-md        → md:* variant
+     --animate-skeleton-shimmer → animate-skeleton-shimmer
+
+   Declared in @theme but utilities generated by explicit @utility blocks
+   in tokens/utilities.css (TW4 has no auto-namespace for these):
+     --z-popover            → z-popover (via @utility)
+     --duration-moderate-01 → duration-moderate-01 (via @utility)
+
+   INTERNAL tokens (not utility-generating) stay in plain `:root { }`:
+     - --action-*-opacity    (consumed by `opacity-action-*` via preset — moving
+                               these to theme would pollute the `opacity-*` namespace)
+     - --shadow-color, --shadow-strength, --shadow-xs/sm/md/lg internals
+     - --size-*, --icon-*, --border-width-*, --border-focus-*
+     - --max-width*, --shadow-transition, --shadow-kbd
+     - --chart-*              (consumed via var() in chart components, not utility)
+     - --gradient-brand-*     (consumed via var() in DevalokGrain)
+     - --color-inset-glow*, --color-text-shadow, --color-overlay*
+       (consumed via var() in internal effect layers)
+
+   The `.dark { }` block below overrides theme variables for dark mode.
+   TW4 supports this cascade: an `@theme` variable re-declared under a
+   scoped selector is honored at runtime.
+   ═══════════════════════════════════════════════════════════════════ */
+
 :root {
   color-scheme: light;
+}
 
-  /* ═══════════════════════════════════════════════════════════
-     TYPOGRAPHY
-     ═══════════════════════════════════════════════════════════ */
+/* ═══════════════════════════════════════════════════════════════════
+   PUBLIC TOKENS (utility-generating)
+   ═══════════════════════════════════════════════════════════════════ */
+@theme {
+  /* ───────────────────────────────────────────────────────────
+     TYPOGRAPHY — font families, weights, sizes, leading, tracking
+     ─────────────────────────────────────────────────────────── */
 
-  /* Font families — override these with next/font CSS variables */
+  /* Font families — consumers override with next/font CSS variables.
+     TW4 namespace: --font-* → font-* utility */
   --font-sans: "Inter", system-ui, sans-serif;
   --font-display: "Inter", system-ui, sans-serif;
   --font-body: "Inter", system-ui, sans-serif;
   --font-accent: Ranade, sans-serif;
   --font-mono: "SF Mono", "Fira Code", monospace;
 
-  /* ── Font Weights ──────────────────────────── */
+  /* Font weights — TW4 namespace: --font-weight-* → font-* (semibold, bold, etc.) */
   --font-weight-light: 300;
   --font-weight-regular: 400;
   --font-weight-medium: 500;
   --font-weight-semibold: 600;
   --font-weight-bold: 700;
 
-  /* ── Type Scale (rem) ──────────────────────── */
-  /* Base: 16px = 1rem (browser default)          */
-  --font-size-xs: 0.625rem;
-  /* 10px */
-  --font-size-sm: 0.75rem;
-  /* 12px */
-  --font-size-md: 0.875rem;
-  /* 14px */
-  --font-size-base: 1rem;
-  /* 16px */
-  --font-size-lg: 1.125rem;
-  /* 18px */
-  --font-size-xl: 1.25rem;
-  /* 20px */
-  --font-size-2xl: 1.5rem;
-  /* 24px */
-  --font-size-3xl: clamp(1.5rem, 1.125rem + 1.25vw, 2rem);
-  /* 24px → 32px fluid */
-  --font-size-4xl: clamp(1.75rem, 1.25rem + 1.5vw, 2.25rem);
-  /* 28px → 36px fluid */
-  --font-size-5xl: clamp(2rem, 1.25rem + 2.5vw, 3rem);
-  /* 32px → 48px fluid */
-  --font-size-6xl: clamp(2.25rem, 1.5rem + 3vw, 3.75rem);
-  /* 36px → 60px fluid */
-
-  /* ── Line Heights ──────────────────────────── */
-  --line-height-none: 1;
-  --line-height-tight: 1.15;
-  --line-height-snug: 1.25;
-  --line-height-normal: 1.4;
-  --line-height-relaxed: 1.5;
-  --line-height-loose: 1.6;
-
-  /* ── Letter Spacing ────────────────────────── */
-  --tracking-tighter: -0.05em;
-  --tracking-tight: -0.025em;
-  --tracking-normal: 0;
-  --tracking-wide: 0.025em;
-  --tracking-wider: 0.05em;
-  --tracking-widest: 0.1em;
-
-  /* ═══════════════════════════════════════════════════════════
+  /* Type scale (rem). Base: 16px = 1rem.
+     TW4 namespace: --text-* → text-* utility.
+     We use the `ds-` prefix to avoid collision with consumer's own
+     text sizes (TW4 default supplies text-xs, text-sm, etc.). */
+  --text-ds-xs:   0.625rem;   /* 10px */
+  --text-ds-sm:   0.75rem;    /* 12px */
+  --text-ds-md:   0.875rem;   /* 14px */
+  --text-ds-base: 1rem;       /* 16px */
+  --text-ds-lg:   1.125rem;   /* 18px */
+  --text-ds-xl:   1.25rem;    /* 20px */
+  --text-ds-2xl:  1.5rem;     /* 24px */
+  --text-ds-3xl:  clamp(1.5rem, 1.125rem + 1.25vw, 2rem);   /* 24→32 fluid */
+  --text-ds-4xl:  clamp(1.75rem, 1.25rem + 1.5vw, 2.25rem); /* 28→36 fluid */
+  --text-ds-5xl:  clamp(2rem, 1.25rem + 2.5vw, 3rem);       /* 32→48 fluid */
+  --text-ds-6xl:  clamp(2.25rem, 1.5rem + 3vw, 3.75rem);    /* 36→60 fluid */
+
+  /* Line heights — TW4 namespace: --leading-* → leading-* utility.
+     `ds-` prefix to namespace our scale, not collide with TW4 defaults. */
+  --leading-ds-none:    1;
+  --leading-ds-tight:   1.15;
+  --leading-ds-snug:    1.25;
+  --leading-ds-normal:  1.4;
+  --leading-ds-relaxed: 1.5;
+  --leading-ds-loose:   1.6;
+
+  /* Letter spacing — TW4 namespace: --tracking-* → tracking-* utility.
+     `ds-` prefix preserves TW4 defaults (tracking-tight, tracking-wide, etc.) */
+  --tracking-ds-tighter: -0.05em;
+  --tracking-ds-tight:   -0.025em;
+  --tracking-ds-normal:  0;
+  --tracking-ds-wide:    0.025em;
+  --tracking-ds-wider:   0.05em;
+  --tracking-ds-widest:  0.1em;
+
+  /* ───────────────────────────────────────────────────────────
      ACCENT (swappable — consumers override these to rebrand)
-     ═══════════════════════════════════════════════════════════ */
-  --color-accent-1: var(--pink-1);
-  --color-accent-2: var(--pink-2);
-  --color-accent-3: var(--pink-3);
-  --color-accent-4: var(--pink-4);
-  --color-accent-5: var(--pink-5);
-  --color-accent-6: var(--pink-6);
-  --color-accent-7: var(--pink-7);
-  --color-accent-8: var(--pink-8);
-  --color-accent-9: var(--pink-9);
+     ─────────────────────────────────────────────────────────── */
+  --color-accent-1:  var(--pink-1);
+  --color-accent-2:  var(--pink-2);
+  --color-accent-3:  var(--pink-3);
+  --color-accent-4:  var(--pink-4);
+  --color-accent-5:  var(--pink-5);
+  --color-accent-6:  var(--pink-6);
+  --color-accent-7:  var(--pink-7);
+  --color-accent-8:  var(--pink-8);
+  --color-accent-9:  var(--pink-9);
   --color-accent-10: var(--pink-10);
   --color-accent-11: var(--pink-11);
   --color-accent-12: var(--pink-12);
   --color-accent-fg: var(--neutral-1);
 
-  /* ═══════════════════════════════════════════════════════════
+  /* ───────────────────────────────────────────────────────────
      SECONDARY ACCENT
-     ═══════════════════════════════════════════════════════════ */
-  --color-secondary-1: var(--purple-1);
-  --color-secondary-2: var(--purple-2);
-  --color-secondary-3: var(--purple-3);
-  --color-secondary-4: var(--purple-4);
-  --color-secondary-5: var(--purple-5);
-  --color-secondary-6: var(--purple-6);
-  --color-secondary-7: var(--purple-7);
-  --color-secondary-8: var(--purple-8);
-  --color-secondary-9: var(--purple-9);
+     ─────────────────────────────────────────────────────────── */
+  --color-secondary-1:  var(--purple-1);
+  --color-secondary-2:  var(--purple-2);
+  --color-secondary-3:  var(--purple-3);
+  --color-secondary-4:  var(--purple-4);
+  --color-secondary-5:  var(--purple-5);
+  --color-secondary-6:  var(--purple-6);
+  --color-secondary-7:  var(--purple-7);
+  --color-secondary-8:  var(--purple-8);
+  --color-secondary-9:  var(--purple-9);
   --color-secondary-10: var(--purple-10);
   --color-secondary-11: var(--purple-11);
   --color-secondary-12: var(--purple-12);
   --color-secondary-fg: var(--neutral-1);
 
-  /* ═══════════════════════════════════════════════════════════
+  /* ───────────────────────────────────────────────────────────
+     NEUTRAL (primitive → @theme alias)
+     Bridges `:root`-declared `--neutral-*` primitives into the
+     TW4 `--color-*` namespace so `bg-neutral-5`, `border-neutral-7`,
+     `text-neutral-11`, etc. actually emit utilities. Without this,
+     every CVA referencing bg-neutral-* silently renders unstyled.
+     ─────────────────────────────────────────────────────────── */
+  --color-neutral-1:  var(--neutral-1);
+  --color-neutral-2:  var(--neutral-2);
+  --color-neutral-3:  var(--neutral-3);
+  --color-neutral-4:  var(--neutral-4);
+  --color-neutral-5:  var(--neutral-5);
+  --color-neutral-6:  var(--neutral-6);
+  --color-neutral-7:  var(--neutral-7);
+  --color-neutral-8:  var(--neutral-8);
+  --color-neutral-9:  var(--neutral-9);
+  --color-neutral-10: var(--neutral-10);
+  --color-neutral-11: var(--neutral-11);
+  --color-neutral-12: var(--neutral-12);
+
+  /* ───────────────────────────────────────────────────────────
      SURFACE
-     ═══════════════════════════════════════════════════════════ */
-  /* Semantic surface tokens */
-  --color-surface-base: var(--neutral-2);    /* 0.97L — slightly grey page (Stripe/Linear pattern) */
-  --color-surface-sunken: var(--color-surface-0);
-  --color-surface-raised: var(--neutral-1);  /* 0.99L — white cards float above the page */
-  --color-surface-overlay: var(--neutral-1); /* same as raised — floating elements are white */
-  --color-surface-raised-hover: var(--neutral-3);
+     ─────────────────────────────────────────────────────────── */
+  /* Numeric layering aliases — canonical per CLAUDE.md surface rule.
+     Consumers and stories use bg-surface-1..4; without these @theme
+     entries TW4 emits zero rules for them. */
+  --color-surface-1: var(--neutral-1);
+  --color-surface-2: var(--neutral-2);
+  --color-surface-3: var(--neutral-3);
+  --color-surface-4: var(--neutral-4);
+
+  --color-surface-base:          var(--neutral-2);
+  --color-surface-sunken:        var(--color-surface-0);
+  --color-surface-raised:        var(--neutral-1);
+  --color-surface-overlay:       var(--neutral-1);
+  --color-surface-raised-hover:  var(--neutral-3);
   --color-surface-raised-active: var(--neutral-4);
-  --color-surface-inverted: var(--neutral-12);
-  --color-surface-inverted-fg: var(--neutral-1);
-  --color-surface-disabled: var(--neutral-2);
-  --color-surface-fg-disabled: var(--neutral-8);
-
-  --color-surface-fg: var(--neutral-12);
-  --color-surface-fg-muted: var(--neutral-11);
-  --color-surface-fg-subtle: var(--neutral-9);  /* was neutral-8; darkened for WCAG AA 4.5:1 contrast */
-  --color-surface-border: var(--neutral-6);         /* was neutral-5; bumped for WCAG 1.4.11 non-text contrast */
-  --color-surface-border-strong: var(--neutral-7);   /* was neutral-6 */
-  --color-surface-border-subtle: var(--neutral-5);   /* was neutral-4 */
-  --color-backdrop: oklch(0 0 0 / 0.4);
-
-  /* ═══════════════════════════════════════════════════════════
+  --color-surface-inverted:      var(--neutral-12);
+  --color-surface-inverted-fg:   var(--neutral-1);
+  --color-surface-disabled:      var(--neutral-2);
+  --color-surface-fg-disabled:   var(--neutral-8);
+  --color-surface-fg:            var(--neutral-12);
+  --color-surface-fg-muted:      var(--neutral-11);
+  --color-surface-fg-subtle:     var(--neutral-9);  /* darkened for WCAG AA 4.5:1 */
+  --color-surface-border:        var(--neutral-6);  /* bumped for WCAG 1.4.11 */
+  --color-surface-border-strong: var(--neutral-7);
+  --color-surface-border-subtle: var(--neutral-5);
+  --color-backdrop:              oklch(0 0 0 / 0.4);
+
+  /* Overlay + disabled — promoted from internal :root into @theme so
+     `bg-overlay`, `text-overlay`, `bg-disabled`, `text-disabled` emit. */
+  --color-overlay:  oklch(0 0 0 / 0.50);
+  --color-disabled: var(--neutral-5);
+
+  /* ───────────────────────────────────────────────────────────
      STATUS — Error
-     ═══════════════════════════════════════════════════════════ */
-  --color-error-2: var(--red-2);
-  --color-error-3: var(--red-3);
-  --color-error-4: var(--red-4);
-  --color-error-5: var(--red-5);
-  --color-error-7: var(--red-7);
-  --color-error-9: var(--red-9);
+     Full step subset: 2, 3, 4, 5, 6, 7, 9, 10, 11.
+     Step 6 added in 0.37.0-next.1 (missed in original migration)
+     — SplitButton soft variants and status-dot muted tones use it.
+     ─────────────────────────────────────────────────────────── */
+  --color-error-2:  var(--red-2);
+  --color-error-3:  var(--red-3);
+  --color-error-4:  var(--red-4);
+  --color-error-5:  var(--red-5);
+  --color-error-6:  var(--red-6);
+  --color-error-7:  var(--red-7);
+  --color-error-9:  var(--red-9);
   --color-error-10: var(--red-10);
   --color-error-11: var(--red-11);
   --color-error-fg: var(--neutral-1);
 
-  /* ═══ Status — Success ═══ */
-  --color-success-2: var(--green-2);
-  --color-success-3: var(--green-3);
-  --color-success-4: var(--green-4);
-  --color-success-5: var(--green-5);
-  --color-success-7: var(--green-7);
-  --color-success-9: var(--green-9);
+  /* ─── Status — Success ─── */
+  --color-success-2:  var(--green-2);
+  --color-success-3:  var(--green-3);
+  --color-success-4:  var(--green-4);
+  --color-success-5:  var(--green-5);
+  --color-success-6:  var(--green-6);
+  --color-success-7:  var(--green-7);
+  --color-success-9:  var(--green-9);
   --color-success-10: var(--green-10);
   --color-success-11: var(--green-11);
   --color-success-fg: var(--neutral-1);
 
-  /* ═══ Status — Warning (amber-bright — lightness-corrected) ═══ */
+  /* ─── Status — Warning (amber-bright, lightness-corrected) ─── */
   --color-warning-2:  var(--amber-bright-2);
   --color-warning-3:  var(--amber-bright-3);
   --color-warning-4:  var(--amber-bright-4);
   --color-warning-5:  var(--amber-bright-5);
+  --color-warning-6:  var(--amber-bright-6);
   --color-warning-7:  var(--amber-bright-7);
   --color-warning-9:  var(--amber-bright-9);
   --color-warning-10: var(--amber-bright-10);
   --color-warning-11: var(--amber-bright-11);
   --color-warning-fg: oklch(0.25 0.01 55);
 
-  /* ═══ Status — Info ═══ */
-  --color-info-2: var(--blue-2);
-  --color-info-3: var(--blue-3);
-  --color-info-4: var(--blue-4);
-  --color-info-5: var(--blue-5);
-  --color-info-7: var(--blue-7);
-  --color-info-9: var(--blue-9);
+  /* ─── Status — Info ─── */
+  --color-info-2:  var(--blue-2);
+  --color-info-3:  var(--blue-3);
+  --color-info-4:  var(--blue-4);
+  --color-info-5:  var(--blue-5);
+  --color-info-6:  var(--blue-6);
+  --color-info-7:  var(--blue-7);
+  --color-info-9:  var(--blue-9);
   --color-info-10: var(--blue-10);
   --color-info-11: var(--blue-11);
   --color-info-fg: var(--neutral-1);
 
-  /* ═══════════════════════════════════════════════════════════
+  /* ───────────────────────────────────────────────────────────
      LINK COLORS
-     ═══════════════════════════════════════════════════════════ */
-  --color-link: var(--color-accent-11);           /* default link text — high-contrast accent */
-  --color-link-hover: var(--color-accent-12);     /* hover — darker for clear feedback */
-  --color-link-visited: var(--purple-11);          /* visited — distinct from unvisited, uses secondary hue */
+     ─────────────────────────────────────────────────────────── */
+  --color-link:         var(--color-accent-11);
+  --color-link-hover:   var(--color-accent-12);
+  --color-link-visited: var(--purple-11);
 
-  /* ═══════════════════════════════════════════════════════════
+  /* ───────────────────────────────────────────────────────────
      CATEGORY COLORS (Sapta Varna — step subsets)
-     ═══════════════════════════════════════════════════════════ */
-  --color-category-teal-3: var(--teal-3);
-  --color-category-teal-7: var(--teal-7);
-  --color-category-teal-9: var(--teal-9);
-  --color-category-teal-11: var(--teal-11);
-
-  --color-category-amber-3: var(--amber-3);
-  --color-category-amber-7: var(--amber-7);
-  --color-category-amber-9: var(--amber-9);
-  --color-category-amber-11: var(--amber-11);
-
-  --color-category-slate-3: var(--slate-3);
-  --color-category-slate-7: var(--slate-7);
-  --color-category-slate-9: var(--slate-9);
-  --color-category-slate-11: var(--slate-11);
-
-  --color-category-indigo-3: var(--indigo-3);
-  --color-category-indigo-7: var(--indigo-7);
-  --color-category-indigo-9: var(--indigo-9);
-  --color-category-indigo-11: var(--indigo-11);
-
-  --color-category-cyan-3: var(--cyan-3);
-  --color-category-cyan-7: var(--cyan-7);
-  --color-category-cyan-9: var(--cyan-9);
-  --color-category-cyan-11: var(--cyan-11);
-
-  --color-category-orange-3: var(--orange-3);
-  --color-category-orange-7: var(--orange-7);
-  --color-category-orange-9: var(--orange-9);
-  --color-category-orange-11: var(--orange-11);
-
-  --color-category-emerald-3: var(--emerald-3);
-  --color-category-emerald-7: var(--emerald-7);
-  --color-category-emerald-9: var(--emerald-9);
+     ─────────────────────────────────────────────────────────── */
+  --color-category-teal-3:     var(--teal-3);
+  --color-category-teal-7:     var(--teal-7);
+  --color-category-teal-9:     var(--teal-9);
+  --color-category-teal-11:    var(--teal-11);
+
+  --color-category-amber-3:    var(--amber-3);
+  --color-category-amber-7:    var(--amber-7);
+  --color-category-amber-9:    var(--amber-9);
+  --color-category-amber-11:   var(--amber-11);
+
+  --color-category-slate-3:    var(--slate-3);
+  --color-category-slate-7:    var(--slate-7);
+  --color-category-slate-9:    var(--slate-9);
+  --color-category-slate-11:   var(--slate-11);
+
+  --color-category-indigo-3:   var(--indigo-3);
+  --color-category-indigo-7:   var(--indigo-7);
+  --color-category-indigo-9:   var(--indigo-9);
+  --color-category-indigo-11:  var(--indigo-11);
+
+  --color-category-cyan-3:     var(--cyan-3);
+  --color-category-cyan-7:     var(--cyan-7);
+  --color-category-cyan-9:     var(--cyan-9);
+  --color-category-cyan-11:    var(--cyan-11);
+
+  --color-category-orange-3:   var(--orange-3);
+  --color-category-orange-7:   var(--orange-7);
+  --color-category-orange-9:   var(--orange-9);
+  --color-category-orange-11:  var(--orange-11);
+
+  --color-category-emerald-3:  var(--emerald-3);
+  --color-category-emerald-7:  var(--emerald-7);
+  --color-category-emerald-9:  var(--emerald-9);
   --color-category-emerald-11: var(--emerald-11);
 
-  /* ═══════════════════════════════════════════════════════════
+  /* ───────────────────────────────────────────────────────────
      SKELETON
-     ═══════════════════════════════════════════════════════════ */
-  --color-skeleton-base: var(--neutral-3);
+     ─────────────────────────────────────────────────────────── */
+  --color-skeleton-base:    var(--neutral-3);
   --color-skeleton-shimmer: var(--neutral-2);
 
-  /* ═══════════════════════════════════════════════════════════
-     UTILITY TOKENS (not step-based, but semantically needed)
-     ═══════════════════════════════════════════════════════════ */
-  --color-overlay: oklch(0 0 0 / 0.50);
-  --color-disabled: var(--neutral-5);
-
-  /* ═══════════════════════════════════════════════════════════
-     ACTION STATE OPACITIES
-     ═══════════════════════════════════════════════════════════ */
-  --action-hover-opacity: 0.04;
-  --action-selected-opacity: 0.08;
-  --action-disabled-opacity: 0.38;
-  --action-focus-opacity: 0.12;
-  --action-active-opacity: 0.12;
-
-  /* ═══════════════════════════════════════════════════════════
-     SPACING
-     ═══════════════════════════════════════════════════════════ */
-  --spacing-01: 2px;
-  --spacing-02: 4px;
-  --spacing-02b: 6px;
-  --spacing-03: 8px;
-  --spacing-04: 12px;
-  --spacing-05: 16px;
-  --spacing-05b: 20px;
-  --spacing-06: 24px;
-  --spacing-06b: 28px;
-  --spacing-07: 32px;
-  --spacing-08: 40px;
-  --spacing-09: 48px;
-  --spacing-10: 64px;
-  --spacing-11: 80px;
-  --spacing-12: 96px;
-  --spacing-13: 160px;
-
-  /* ── Layout Spacing (semantic page/section-level) ──
-     These reference the base spacing scale but provide responsive overrides
-     via @media queries below. Components like Container use these instead
-     of hardcoding a single spacing token. */
-  --spacing-page-x: var(--spacing-05);            /* 16px — horizontal page padding */
-  --spacing-page-y: var(--spacing-07);            /* 32px — vertical page padding */
-  --spacing-section-gap: var(--spacing-08);       /* 40px — between major page sections */
-  --spacing-card-gap: var(--spacing-05);          /* 16px — between cards in a grid */
-  --spacing-stack-gap: var(--spacing-06);         /* 24px — between stacked content blocks */
-
-  /* ═══════════════════════════════════════════════════════════
+  /* ───────────────────────────────────────────────────────────
+     SPACING — numeric scale
+     Generates p-ds-* / m-ds-* / gap-ds-* / w-ds-* / h-ds-* / etc.
+     ─────────────────────────────────────────────────────────── */
+  --spacing-ds-01:  2px;
+  --spacing-ds-02:  4px;
+  --spacing-ds-02b: 6px;
+  --spacing-ds-03:  8px;
+  --spacing-ds-04:  12px;
+  --spacing-ds-05:  16px;
+  --spacing-ds-05b: 20px;
+  --spacing-ds-06:  24px;
+  --spacing-ds-06b: 28px;
+  --spacing-ds-07:  32px;
+  --spacing-ds-08:  40px;
+  --spacing-ds-09:  48px;
+  --spacing-ds-10:  64px;
+  --spacing-ds-11:  80px;
+  --spacing-ds-12:  96px;
+  --spacing-ds-13:  160px;
+
+  /* Named component sizes — drive w-ds-{xs|sm|md|lg|xl}, h-ds-*, min-w-ds-*, min-h-ds-*.
+     These are the heights of Avatar, Button, Input, IconButton, etc.
+     In TW4, spacing-namespaced tokens ALSO emit w-/h-/min-w/min-h/max-* utilities,
+     so one `--spacing-ds-<name>` entry covers all sizing utilities. */
+  --spacing-ds-xs:      24px;
+  --spacing-ds-xs-plus: 28px;
+  --spacing-ds-sm:      32px;
+  --spacing-ds-sm-plus: 36px;
+  --spacing-ds-md:      40px;
+  --spacing-ds-lg:      48px;
+  --spacing-ds-xl:      56px;
+
+  /* Icon sizes — drive w-ico-{sm|md|lg|xl}, h-ico-*. Same spacing-namespace
+     rule applies: one var emits both w- and h- utilities. */
+  --spacing-ico-sm: 16px;
+  --spacing-ico-md: 20px;
+  --spacing-ico-lg: 24px;
+  --spacing-ico-xl: 32px;
+
+  /* Layout spacing (responsive via @media in :root below).
+     Generates p-page-x, p-page-y, gap-section-gap, gap-card-gap, gap-stack-gap. */
+  --spacing-page-x:      var(--spacing-ds-05);
+  --spacing-page-y:      var(--spacing-ds-07);
+  --spacing-section-gap: var(--spacing-ds-08);
+  --spacing-card-gap:    var(--spacing-ds-05);
+  --spacing-stack-gap:   var(--spacing-ds-06);
+
+  /* ───────────────────────────────────────────────────────────
      RADIUS
-     ═══════════════════════════════════════════════════════════ */
-  --radius-none: 0;
-  --radius-sm: 2px;
-  --radius-default: 4px;
-  --radius-md: 6px;
-  --radius-lg: 10px;
-  --radius-xl: 16px;
-  --radius-2xl: 24px;
-  --radius-full: 9999px;
-
-  /* ═══════════════════════════════════════════════════════════
-     MOTION
-     ═══════════════════════════════════════════════════════════ */
-
-  /* ── Motion: Durations (Carbon-inspired scale) ── */
-  --duration-instant: 0ms;
-  --duration-fast-01: 70ms;
-  --duration-fast-02: 110ms;
-  --duration-moderate-01: 150ms;
-  --duration-moderate-01b: 200ms;  /* accordion, collapsible, layout transitions — most-used gap */
-  --duration-moderate-02: 240ms;
-  --duration-slow-01: 400ms;
-  --duration-slow-02: 700ms;
-
-  /* ── Motion: Easing — Productive (task-focused, utilitarian) ── */
+     ─────────────────────────────────────────────────────────── */
+  --radius:        4px;     /* bare `rounded` class — TW4 default namespace */
+  --radius-ds-none: 0;
+  --radius-ds-sm:   2px;
+  --radius-ds-md:   6px;
+  --radius-ds-lg:   10px;
+  --radius-ds-xl:   16px;
+  --radius-ds-2xl:  24px;
+  --radius-ds-full: 9999px;
+
+  /* ───────────────────────────────────────────────────────────
+     DURATION (Carbon-inspired scale)
+     ─────────────────────────────────────────────────────────── */
+  --duration-instant:      0ms;
+  --duration-fast-01:      70ms;
+  --duration-fast-02:      110ms;
+  --duration-moderate-01:  150ms;
+  --duration-moderate-01b: 200ms;
+  --duration-moderate-02:  240ms;
+  --duration-slow-01:      400ms;
+  --duration-slow-02:      700ms;
+
+  /* ───────────────────────────────────────────────────────────
+     EASING
+     ─────────────────────────────────────────────────────────── */
+  /* Productive (task-focused, utilitarian) */
   --ease-productive-standard: cubic-bezier(0.2, 0, 0.38, 0.9);
   --ease-productive-entrance: cubic-bezier(0, 0, 0.38, 0.9);
-  --ease-productive-exit: cubic-bezier(0.2, 0, 1, 0.9);
-
-  /* ── Motion: Easing — Expressive (attention-grabbing, dramatic) ── */
+  --ease-productive-exit:     cubic-bezier(0.2, 0, 1, 0.9);
+  /* Expressive (attention-grabbing, dramatic) */
   --ease-expressive-standard: cubic-bezier(0.4, 0.14, 0.3, 1);
   --ease-expressive-entrance: cubic-bezier(0, 0, 0.3, 1);
-  --ease-expressive-exit: cubic-bezier(0.4, 0.14, 1, 1);
-
-  /* ── Motion: Easing — Utility ── */
+  --ease-expressive-exit:     cubic-bezier(0.4, 0.14, 1, 1);
+  /* Utility */
   --ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
   --ease-linear: linear;
 
-  /* ═══════════════════════════════════════════════════════════
-     SHADOWS
-     ═══════════════════════════════════════════════════════════ */
+  /* ───────────────────────────────────────────────────────────
+     SHADOW (semantic elevation — public API)
+     ─────────────────────────────────────────────────────────── */
+  --shadow-raised:       var(--shadow-xs-internal);
+  --shadow-raised-hover: var(--shadow-sm-internal);
+  --shadow-floating:     var(--shadow-md-internal);
+  --shadow-overlay:      var(--shadow-lg-internal);
 
-  /* Shadow color: cool blue tint for natural depth */
-  --shadow-color: 0.15 0.015 260;
-  --shadow-strength: 1;
+  /* Effect shadows */
+  --shadow-brand:   0 2px 8px oklch(0.55 0.19 360 / 0.20), 0 6px 20px oklch(0.55 0.19 360 / 0.15);
+  --shadow-glow:    0 0 0 1.5px oklch(0.55 0.19 360 / 0.20), 0 0 7px oklch(0.55 0.19 360 / 0.12);
+  --shadow-inset:   inset 0 1px 2px oklch(var(--shadow-color) / calc(0.08 * var(--shadow-strength))), inset 0 2px 5px oklch(var(--shadow-color) / calc(0.06 * var(--shadow-strength)));
+  --shadow-ring-sm: 0 0 0 1px var(--color-surface-border);
+  --shadow-ring:    0 0 0 2px oklch(0.55 0.19 360 / 0.30);
 
-  /* Shadow transition */
-  --shadow-transition: box-shadow var(--duration-fast-02) var(--ease-productive-standard);
+  --shadow-raised-inner: inset 0 1px 0 oklch(1 0 0 / 0.10), inset 0 -1px 0 oklch(0 0 0 / 0.06);
+  --shadow-pressed: 0 0 0 1px oklch(var(--shadow-color) / calc(0.04 * var(--shadow-strength)));
+  --shadow-success: 0 2px 8px oklch(0.55 0.14 145 / 0.20), 0 6px 20px oklch(0.55 0.14 145 / 0.15);
+  --shadow-error:   0 2px 8px oklch(0.55 0.18 25 / 0.20),  0 6px 20px oklch(0.55 0.18 25 / 0.15);
+  --shadow-warning: 0 2px 8px oklch(0.78 0.16 65 / 0.22),  0 6px 20px oklch(0.78 0.16 65 / 0.15);
 
   /* Keyboard shortcut badge shadow */
   --shadow-kbd: inset 0 -1px 0 oklch(0 0 0 / 0.1);
 
-  /* Shadow primitives (internal) */
-  --shadow-xs:
+  /* ───────────────────────────────────────────────────────────
+     Z-INDEX
+     TW4 does NOT auto-generate utilities from --z-*. These vars
+     exist as named CSS custom properties; the z-base/z-raised/etc.
+     utilities are declared explicitly in tokens/utilities.css via
+     @utility blocks that reference these names.
+     ─────────────────────────────────────────────────────────── */
+  --z-base:     0;
+  --z-raised:   10;
+  --z-dropdown: 1000;
+  --z-sticky:   1100;
+  --z-overlay:  1200;
+  --z-modal:    1300;
+  --z-popover:  1400;
+  --z-toast:    1500;
+  --z-tooltip:  1600;
+
+  /* ───────────────────────────────────────────────────────────
+     BREAKPOINTS (TW4 namespace: --breakpoint-* → variant)
+     ─────────────────────────────────────────────────────────── */
+  --breakpoint-sm:  640px;
+  --breakpoint-md:  768px;
+  --breakpoint-lg:  1024px;
+  --breakpoint-xl:  1280px;
+  --breakpoint-2xl: 1536px;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   INTERNAL / META TOKENS (not utility-generating, consumed via var())
+   ═══════════════════════════════════════════════════════════════════ */
+:root {
+  /* Action state opacities (reflected by preset `opacity-action-*` util) */
+  --action-hover-opacity:    0.04;
+  --action-selected-opacity: 0.08;
+  --action-disabled-opacity: 0.38;
+  --action-focus-opacity:    0.12;
+  --action-active-opacity:   0.12;
+
+  /* NOTE: --color-overlay and --color-disabled have been promoted to
+     @theme above (so TW4 emits `bg-overlay`, `text-disabled`, etc.).
+     The dark-mode override below and forced-colors override further
+     down still work because TW4 honors scoped redeclarations of
+     @theme vars. */
+
+  /* Shadow internals — the `--shadow-xs-internal` etc. are composed into
+     the public `--shadow-raised`/`--shadow-floating` @theme values above.
+     They depend on `--shadow-color` (a runtime var) so they cannot live
+     in @theme (TW4 may statically-inline theme values). */
+  --shadow-color:    0.15 0.015 260;   /* cool blue tint */
+  --shadow-strength: 1;
+  --shadow-transition: box-shadow var(--duration-fast-02) var(--ease-productive-standard);
+
+  --shadow-xs-internal:
     0 0 0 1px oklch(var(--shadow-color) / calc(0.035 * var(--shadow-strength))),
     0 0.5px 1px -0.5px oklch(var(--shadow-color) / calc(0.045 * var(--shadow-strength))),
     0 1.5px 3px -1px oklch(var(--shadow-color) / calc(0.04 * var(--shadow-strength))),
     0 3px 7px -2px oklch(var(--shadow-color) / calc(0.03 * var(--shadow-strength)));
-  --shadow-sm:
+  --shadow-sm-internal:
     0 0 0 1px oklch(var(--shadow-color) / calc(0.035 * var(--shadow-strength))),
     0 0.5px 1px -0.5px oklch(var(--shadow-color) / calc(0.04 * var(--shadow-strength))),
     0 2px 4px -1.5px oklch(var(--shadow-color) / calc(0.045 * var(--shadow-strength))),
     0 6px 12px -3px oklch(var(--shadow-color) / calc(0.035 * var(--shadow-strength))),
     0 14px 28px -8px oklch(var(--shadow-color) / calc(0.025 * var(--shadow-strength)));
-  --shadow-md:
+  --shadow-md-internal:
     0 0 0 1px oklch(var(--shadow-color) / calc(0.04 * var(--shadow-strength))),
     0 1px 2px -1px oklch(var(--shadow-color) / calc(0.05 * var(--shadow-strength))),
     0 4px 8px -2px oklch(var(--shadow-color) / calc(0.04 * var(--shadow-strength))),
     0 10px 20px -5px oklch(var(--shadow-color) / calc(0.035 * var(--shadow-strength))),
     0 24px 44px -12px oklch(var(--shadow-color) / calc(0.025 * var(--shadow-strength)));
-  --shadow-lg:
+  --shadow-lg-internal:
     0 0 0 1px oklch(var(--shadow-color) / calc(0.04 * var(--shadow-strength))),
     0 1px 2px -1px oklch(var(--shadow-color) / calc(0.05 * var(--shadow-strength))),
     0 3px 6px -2px oklch(var(--shadow-color) / calc(0.045 * var(--shadow-strength))),
@@ -339,36 +477,14 @@
     0 18px 34px -8px oklch(var(--shadow-color) / calc(0.03 * var(--shadow-strength))),
     0 40px 64px -16px oklch(var(--shadow-color) / calc(0.025 * var(--shadow-strength)));
 
-  /* Semantic elevation shadows (public API) */
-  --shadow-raised: var(--shadow-xs);
-  --shadow-raised-hover: var(--shadow-sm);
-  --shadow-floating: var(--shadow-md);
-  --shadow-overlay: var(--shadow-lg);
-
-  /* Effect shadows */
-  --shadow-brand: 0 2px 8px oklch(0.55 0.19 360 / 0.20), 0 6px 20px oklch(0.55 0.19 360 / 0.15);
-  --shadow-glow: 0 0 0 1.5px oklch(0.55 0.19 360 / 0.20), 0 0 7px oklch(0.55 0.19 360 / 0.12);
-  --shadow-inset: inset 0 1px 2px oklch(var(--shadow-color) / calc(0.08 * var(--shadow-strength))), inset 0 2px 5px oklch(var(--shadow-color) / calc(0.06 * var(--shadow-strength)));
-  --shadow-ring-sm: 0 0 0 1px var(--color-surface-border);
-  --shadow-ring: 0 0 0 2px oklch(0.55 0.19 360 / 0.30);
-
-  /* Status & state effect shadows */
-  --shadow-raised-inner: inset 0 1px 0 oklch(1 0 0 / 0.10), inset 0 -1px 0 oklch(0 0 0 / 0.06);
-  --shadow-pressed: 0 0 0 1px oklch(var(--shadow-color) / calc(0.04 * var(--shadow-strength)));
-  --shadow-success: 0 2px 8px oklch(0.55 0.14 145 / 0.20), 0 6px 20px oklch(0.55 0.14 145 / 0.15);
-  --shadow-error:   0 2px 8px oklch(0.55 0.18 25 / 0.20),  0 6px 20px oklch(0.55 0.18 25 / 0.15);
-  --shadow-warning: 0 2px 8px oklch(0.78 0.16 65 / 0.22),  0 6px 20px oklch(0.78 0.16 65 / 0.15);
-
-  /* ═══════════════════════════════════════════════════════════
-     SIZES
-     ═══════════════════════════════════════════════════════════ */
-  --size-xs: 24px;
+  /* Component sizes (consumed via w-ds-/h-ds- manual preset mappings) */
+  --size-xs:      24px;
   --size-xs-plus: 28px;
-  --size-sm: 32px;
+  --size-sm:      32px;
   --size-sm-plus: 36px;
-  --size-md: 40px;
-  --size-lg: 48px;
-  --size-xl: 56px;
+  --size-md:      40px;
+  --size-lg:      48px;
+  --size-xl:      56px;
   --icon-sm: 16px;
   --icon-md: 20px;
   --icon-lg: 24px;
@@ -376,42 +492,18 @@
   --border-width-sm: 1px;
   --border-width-md: 2px;
   --border-width-lg: 3px;
-  --border-focus-width: 2px;
+  --border-focus-width:  2px;
   --border-focus-offset: 2px;
 
-  /* ═══════════════════════════════════════════════════════════
-     Z-INDEX
-     ═══════════════════════════════════════════════════════════ */
-  --z-base: 0;
-  --z-raised: 10;
-  --z-dropdown: 1000;
-  --z-sticky: 1100;
-  --z-overlay: 1200;
-  --z-modal: 1300;
-  --z-popover: 1400;
-  --z-toast: 1500;
-  --z-tooltip: 1600;
-
-  /* ── Layout ─────────────────────────────────── */
-  --max-width: 1280px;
+  /* Layout */
+  --max-width:      1280px;
   --max-width-body: 960px;
 
-  /* ── Breakpoints ───────────────────────────── */
-  --breakpoint-sm: 640px;
-  --breakpoint-md: 768px;
-  --breakpoint-lg: 1024px;
-  --breakpoint-xl: 1280px;
-  --breakpoint-2xl: 1536px;
-
-  /* ═══════════════════════════════════════════════════════════
-     GRADIENTS
-     ═══════════════════════════════════════════════════════════ */
+  /* Gradients (consumed via var() in DevalokGrain, not as utilities) */
   --gradient-brand-light: linear-gradient(135deg, var(--pink-7), var(--purple-9));
-  --gradient-brand-dark: linear-gradient(135deg, var(--pink-8), var(--purple-10));
+  --gradient-brand-dark:  linear-gradient(135deg, var(--pink-8), var(--purple-10));
 
-  /* ═══════════════════════════════════════════════════════════
-     CHART PALETTE
-     ═══════════════════════════════════════════════════════════ */
+  /* Chart palette (consumed via var() in chart components) */
   --chart-1: var(--pink-9);
   --chart-2: var(--purple-9);
   --chart-3: var(--blue-9);
@@ -421,31 +513,30 @@
   --chart-7: var(--cyan-9);
   --chart-8: var(--orange-9);
 
-  /* ═══════════════════════════════════════════════════════════
-     INSET GLOW & OVERLAY
-     ═══════════════════════════════════════════════════════════ */
-  --color-inset-glow: oklch(1 0 0 / 0.25);
-  --color-inset-glow-strong: oklch(1 0 0 / 0.16);
-  --color-inset-glow-subtle: oklch(1 0 0 / 0.10);
+  /* Inset glow & overlay (internal effect layers) */
+  --color-inset-glow:           oklch(1 0 0 / 0.25);
+  --color-inset-glow-strong:    oklch(1 0 0 / 0.16);
+  --color-inset-glow-subtle:    oklch(1 0 0 / 0.10);
   --color-surface-overlay-light: oklch(1 0 0 / 0.20);
-  --color-surface-overlay-dark: oklch(0 0 0 / 0.12);
-  --color-text-shadow: oklch(0 0 0 / 0.15);
+  --color-surface-overlay-dark:  oklch(0 0 0 / 0.12);
+  --color-text-shadow:          oklch(0 0 0 / 0.15);
 }
 
-/* ═══════════════════════════════════════════════════════════
+/* ═══════════════════════════════════════════════════════════════════
    DARK MODE
-   ═══════════════════════════════════════════════════════════ */
+   TW4 supports overriding @theme variables in scoped selectors.
+   ═══════════════════════════════════════════════════════════════════ */
 .dark {
   color-scheme: dark;
 
-  /* Foreground on solid accent/status backgrounds — pure white on brand colors */
-  --color-accent-fg: var(--neutral-0);
+  /* Foreground on solid accent/status backgrounds — pure white in dark mode */
+  --color-accent-fg:    var(--neutral-0);
   --color-secondary-fg: var(--neutral-0);
-  --color-error-fg: var(--neutral-0);
-  --color-success-fg: var(--neutral-0);
-  --color-info-fg: var(--neutral-0);
+  --color-error-fg:     var(--neutral-0);
+  --color-success-fg:   var(--neutral-0);
+  --color-info-fg:      var(--neutral-0);
 
-  /* Warning: amber-bright dark ramp for dark mode */
+  /* Warning: amber-bright dark ramp */
   --color-warning-2:  var(--amber-bright-2);
   --color-warning-3:  var(--amber-bright-3);
   --color-warning-4:  var(--amber-bright-4);
@@ -456,50 +547,44 @@
   --color-warning-11: var(--amber-bright-11);
   --color-warning-fg: var(--neutral-0);
 
-  /* Link colors — accent-11/12 already flip via semantic layer;
-     visited uses purple-11 which also flips via primitives dark block */
-
-  /* Dark mode borders need lower contrast — bright borders look harsh.
-     Drop to step 3/4 for subtle resting borders that don't overpower surfaces */
-  /* Dark mode: restore base/raised to original direction (raised = lighter than base) */
-  --color-surface-base: var(--neutral-1);     /* 0.11L — dark page */
-  --color-surface-raised: var(--neutral-2);   /* 0.17L — lighter cards */
-
-  --color-surface-border: var(--neutral-4);         /* was neutral-3; bumped for contrast */
-  --color-surface-border-strong: var(--neutral-5);   /* was neutral-4 */
-  --color-surface-overlay: oklch(0.13 0.0002 350);
-  --color-surface-border-subtle: var(--neutral-3); /* was neutral-2 = same as raised = invisible (1:1) */
-  --color-backdrop: oklch(0 0 0 / 0.6);
+  /* Surface — dark page, lighter cards */
+  --color-surface-base:          var(--neutral-1);  /* 0.11L */
+  --color-surface-raised:        var(--neutral-2);  /* 0.17L */
+  --color-surface-border:        var(--neutral-4);
+  --color-surface-border-strong: var(--neutral-5);
+  --color-surface-overlay:       oklch(0.13 0.0002 350);
+  --color-surface-border-subtle: var(--neutral-3);
+  --color-backdrop:              oklch(0 0 0 / 0.6);
 
   /* Overlay */
   --color-overlay: oklch(0 0 0 / 0.70);
 
-  /* Action State Opacities (higher in dark mode) */
-  --action-hover-opacity: 0.08;
+  /* Action state opacities (higher in dark mode) */
+  --action-hover-opacity:    0.08;
   --action-selected-opacity: 0.12;
   --action-disabled-opacity: 0.38;
-  --action-focus-opacity: 0.12;
-  --action-active-opacity: 0.16;
+  --action-focus-opacity:    0.12;
+  --action-active-opacity:   0.16;
 
   /* Skeleton */
-  --color-skeleton-base: var(--neutral-4);
+  --color-skeleton-base:    var(--neutral-4);
   --color-skeleton-shimmer: var(--neutral-3);
 
   /* Shadows (heavier in dark mode) */
   --shadow-strength: 2.5;
-  --shadow-brand: 0 2px 8px oklch(0.55 0.19 360 / 0.30), 0 6px 20px oklch(0.55 0.19 360 / 0.20);
-  --shadow-glow: 0 0 0 1.5px oklch(0.55 0.19 360 / 0.35), 0 0 10px oklch(0.55 0.19 360 / 0.20);
-  --shadow-ring: 0 0 0 2px oklch(0.55 0.19 360 / 0.45);
+  --shadow-brand:    0 2px 8px oklch(0.55 0.19 360 / 0.30), 0 6px 20px oklch(0.55 0.19 360 / 0.20);
+  --shadow-glow:     0 0 0 1.5px oklch(0.55 0.19 360 / 0.35), 0 0 10px oklch(0.55 0.19 360 / 0.20);
+  --shadow-ring:     0 0 0 2px oklch(0.55 0.19 360 / 0.45);
   --shadow-raised-inner: inset 0 1px 0 oklch(1 0 0 / 0.06), inset 0 -1px 0 oklch(0 0 0 / 0.12);
-  --shadow-success: 0 2px 8px oklch(0.6 0.14 145 / 0.30), 0 6px 20px oklch(0.6 0.14 145 / 0.20);
-  --shadow-error:   0 2px 8px oklch(0.6 0.18 25 / 0.30),  0 6px 20px oklch(0.6 0.18 25 / 0.20);
-  --shadow-warning: 0 2px 8px oklch(0.78 0.16 65 / 0.30), 0 6px 20px oklch(0.78 0.16 65 / 0.20);
+  --shadow-success:  0 2px 8px oklch(0.6 0.14 145 / 0.30), 0 6px 20px oklch(0.6 0.14 145 / 0.20);
+  --shadow-error:    0 2px 8px oklch(0.6 0.18 25 / 0.30),  0 6px 20px oklch(0.6 0.18 25 / 0.20);
+  --shadow-warning:  0 2px 8px oklch(0.78 0.16 65 / 0.30), 0 6px 20px oklch(0.78 0.16 65 / 0.20);
 
   /* Gradients */
   --gradient-brand-light: linear-gradient(135deg, var(--pink-9), var(--purple-9));
-  --gradient-brand-dark: linear-gradient(135deg, var(--pink-10), var(--purple-10));
+  --gradient-brand-dark:  linear-gradient(135deg, var(--pink-10), var(--purple-10));
 
-  /* Chart Palette (dark — use step 9 which is brighter in dark) */
+  /* Chart palette (dark — step 9 brighter) */
   --chart-1: var(--pink-9);
   --chart-2: var(--purple-9);
   --chart-3: var(--blue-9);
@@ -509,68 +594,47 @@
   --chart-7: var(--cyan-9);
   --chart-8: var(--orange-9);
 
-  /* Inset Glow & Overlay */
-  --color-inset-glow: oklch(1 0 0 / 0.10);
-  --color-inset-glow-strong: oklch(1 0 0 / 0.08);
-  --color-inset-glow-subtle: oklch(1 0 0 / 0.05);
+  /* Inset glow & overlay */
+  --color-inset-glow:            oklch(1 0 0 / 0.10);
+  --color-inset-glow-strong:     oklch(1 0 0 / 0.08);
+  --color-inset-glow-subtle:     oklch(1 0 0 / 0.05);
   --color-surface-overlay-light: oklch(1 0 0 / 0.08);
-  --color-surface-overlay-dark: oklch(0 0 0 / 0.25);
-  --color-text-shadow: oklch(0 0 0 / 0.40);
+  --color-surface-overlay-dark:  oklch(0 0 0 / 0.25);
+  --color-text-shadow:           oklch(0 0 0 / 0.40);
 }
 
-/* Ensure Radix popper content (Select, Combobox, Popover, etc.)
-   renders above Sheet/Dialog overlays */
+/* ═══════════════════════════════════════════════════════════════════
+   Ensure Radix popper content (Select, Combobox, Popover, etc.)
+   renders above Sheet/Dialog overlays.
+   ═══════════════════════════════════════════════════════════════════ */
 [data-radix-popper-content-wrapper] {
   z-index: var(--z-popover) !important;
 }
 
-/* ── Responsive Layout Spacing ──────────────────────── */
+/* ═══════════════════════════════════════════════════════════════════
+   Responsive layout spacing — overrides @theme values at breakpoints.
+   TW4 permits re-declaring @theme vars under @media scope.
+   ═══════════════════════════════════════════════════════════════════ */
 @media (min-width: 768px) {
   :root {
-    --spacing-page-x: var(--spacing-06);          /* 24px on tablet+ */
-    --spacing-section-gap: var(--spacing-10);     /* 64px on tablet+ */
+    --spacing-page-x:      var(--spacing-ds-06);
+    --spacing-section-gap: var(--spacing-ds-10);
   }
 }
 
 @media (min-width: 1280px) {
   :root {
-    --spacing-page-x: var(--spacing-08);          /* 40px on desktop+ */
+    --spacing-ds-page-x: var(--spacing-ds-08);
   }
 }
 
-/* ── Reduced Motion ──────────────────────────────────── */
-/* ═══════════════════════════════════════════════════════════
-   PROCESSING ANIMATIONS
-   ═══════════════════════════════════════════════════════════ */
-
-@property --border-angle {
-  syntax: "<angle>";
-  initial-value: 0deg;
-  inherits: false;
-}
-
-@keyframes processing-ants-rotate {
-  to {
-    --border-angle: 360deg;
-  }
-}
-
-@keyframes processing-ants-march {
-  to {
-    background-position: 16px 0, 100% 16px, calc(100% - 16px) 100%, 0 calc(100% - 16px);
-  }
-}
-
-@keyframes processing-ants-svg {
-  to {
-    stroke-dashoffset: -10;
-  }
-}
-
-/* ═══════════════════════════════════════════════════════════ */
+/* ═══════════════════════════════════════════════════════════════════
+   REDUCED MOTION
 
+   @property --border-angle and @keyframes definitions moved to
+   base.css and animations.css respectively (Phase 2 of 0.37 migration).
+   ═══════════════════════════════════════════════════════════════════ */
 @media (prefers-reduced-motion: reduce) {
-
   *,
   *::before,
   *::after {
@@ -581,85 +645,68 @@
   }
 }
 
-/* ═══════════════════════════════════════════════════════════
+/* ═══════════════════════════════════════════════════════════════════
    FORCED COLORS (Windows High Contrast, etc.)
-   ───────────────────────────────────────────────────────────
+
    When the OS forces a color scheme, browsers strip our custom
-   palette and remap to a small set of system keywords. We opt
-   into this by default (forced-color-adjust: auto is the
-   default) and only *explicitly map* our semantic tokens to
-   system colors where the remapping would otherwise be lossy
-   or ambiguous.
-
-   Applies to BOTH light and dark themes — forced-colors is
-   orthogonal to theme. We override both :root and .dark.
-
-   Testing: Chrome DevTools → Rendering → "Emulate CSS media
-   feature forced-colors: active". Or Windows Settings → High
-   Contrast.
-   ═══════════════════════════════════════════════════════════ */
+   palette and remap to a small set of system keywords. Opt in
+   explicitly so the DS degrades legibly.
+   Applies to BOTH light and dark themes.
+   Test: Chrome DevTools → Rendering → "Emulate CSS media feature
+   forced-colors: active".
+   ═══════════════════════════════════════════════════════════════════ */
 @media (forced-colors: active) {
   :root,
   .dark {
-    /* ── Surface ── */
-    --color-surface-fg: CanvasText;
-    --color-surface-fg-muted: CanvasText;     /* Muted merges with fg; rely on weight/position for hierarchy */
-    --color-surface-fg-subtle: GrayText;
-    --color-surface-fg-disabled: GrayText;
-    --color-surface-base: Canvas;
-    --color-surface-sunken: Canvas;
-    --color-surface-raised: Canvas;
-    --color-surface-raised-hover: Canvas;      /* System handles hover via :hover + Highlight */
+    /* Surface */
+    --color-surface-fg:           CanvasText;
+    --color-surface-fg-muted:     CanvasText;
+    --color-surface-fg-subtle:    GrayText;
+    --color-surface-fg-disabled:  GrayText;
+    --color-surface-base:         Canvas;
+    --color-surface-sunken:       Canvas;
+    --color-surface-raised:       Canvas;
+    --color-surface-raised-hover: Canvas;
     --color-surface-raised-active: Canvas;
-    --color-surface-overlay: Canvas;
-    --color-surface-disabled: Canvas;
-    --color-surface-inverted: CanvasText;
-    --color-surface-inverted-fg: Canvas;
-    --color-surface-border: CanvasText;
-    --color-surface-border-strong: CanvasText;
-    --color-surface-border-subtle: GrayText;
+    --color-surface-overlay:      Canvas;
+    --color-surface-disabled:     Canvas;
+    --color-surface-inverted:     CanvasText;
+    --color-surface-inverted-fg:  Canvas;
+    --color-surface-border:         CanvasText;
+    --color-surface-border-strong:  CanvasText;
+    --color-surface-border-subtle:  GrayText;
     --color-backdrop: Canvas;
-    --color-overlay: Canvas;
+    --color-overlay:  Canvas;
     --color-disabled: GrayText;
 
-    /* ── Accent ──
-       Step 9/10 (solid backgrounds) → Highlight (system selected color).
-       Step 11 (text) → LinkText for emphasis / interactive text runs.
-       Step 3-5 (hover/subtle bg) collapse to Canvas — hover is expressed
-       by system Highlight on :hover automatically. */
+    /* Accent */
     --color-accent-1: Canvas;
     --color-accent-2: Canvas;
     --color-accent-3: Canvas;
     --color-accent-4: Canvas;
     --color-accent-5: Canvas;
     --color-accent-6: Canvas;
-    --color-accent-7: Highlight;
-    --color-accent-8: Highlight;
-    --color-accent-9: Highlight;
+    --color-accent-7:  Highlight;
+    --color-accent-8:  Highlight;
+    --color-accent-9:  Highlight;
     --color-accent-10: Highlight;
     --color-accent-11: LinkText;
     --color-accent-12: LinkText;
     --color-accent-fg: HighlightText;
 
-    /* ── Secondary accent ── (same pattern) */
-    --color-secondary-9: Highlight;
+    /* Secondary */
+    --color-secondary-9:  Highlight;
     --color-secondary-10: Highlight;
     --color-secondary-11: LinkText;
     --color-secondary-12: LinkText;
     --color-secondary-fg: HighlightText;
 
-    /* ── Status colors ──
-       Forced-colors has no distinct error/success/warning/info slots.
-       Step-11 text → CanvasText (still readable). Step-9 solid → Mark
-       (often highlighted/annotated color in system themes) for error
-       since errors are the most distinguishable need; others use
-       Highlight to stay legible. Meaning MUST be carried by iconography
-       + text, not color, under forced-colors. */
+    /* Status (meaning carried by iconography + text, not color) */
     --color-error-3: Canvas;
     --color-error-4: Canvas;
     --color-error-5: Canvas;
     --color-error-7: CanvasText;
-    --color-error-9: Mark;
+    --color-error-9:  Mark;
     --color-error-10: Mark;
     --color-error-11: CanvasText;
     --color-error-fg: CanvasText;
@@ -668,7 +715,7 @@
     --color-success-4: Canvas;
     --color-success-5: Canvas;
     --color-success-7: CanvasText;
-    --color-success-9: Highlight;
+    --color-success-9:  Highlight;
     --color-success-10: Highlight;
     --color-success-11: CanvasText;
     --color-success-fg: HighlightText;
@@ -677,7 +724,7 @@
     --color-warning-4: Canvas;
     --color-warning-5: Canvas;
     --color-warning-7: CanvasText;
-    --color-warning-9: Highlight;
+    --color-warning-9:  Highlight;
     --color-warning-10: Highlight;
     --color-warning-11: CanvasText;
     --color-warning-fg: HighlightText;
@@ -686,36 +733,28 @@
     --color-info-4: Canvas;
     --color-info-5: Canvas;
     --color-info-7: CanvasText;
-    --color-info-9: Highlight;
+    --color-info-9:  Highlight;
     --color-info-10: Highlight;
     --color-info-11: CanvasText;
     --color-info-fg: HighlightText;
 
-    /* ── Links ──
-       VisitedText falls back to LinkText on browsers that don't
-       implement it; both render visibly. */
-    --color-link: LinkText;
-    --color-link-hover: LinkText;
+    /* Links */
+    --color-link:         LinkText;
+    --color-link-hover:   LinkText;
     --color-link-visited: VisitedText;
 
-    /* ── Skeleton ── collapse to Canvas; shimmer animation still runs */
-    --color-skeleton-base: GrayText;
+    /* Skeleton collapses */
+    --color-skeleton-base:    GrayText;
     --color-skeleton-shimmer: Canvas;
   }
 
-  /* Focus ring — Tailwind's `ring-*` utility compiles to box-shadow, which
-     CAN be stripped by some UAs under forced-colors. Belt-and-suspenders:
-     enforce an `outline` too so focus is *always* visible. */
+  /* Focus ring — enforce via outline so it's never stripped */
   *:focus-visible {
     outline: 2px solid Highlight !important;
     outline-offset: 2px !important;
   }
 
-  /* Interactive elements need a visible border even when their resting
-     background is transparent (ghost/link buttons, bare inputs). Canvas +
-     no background = invisible interactive area. Use ButtonText for
-     buttons, CanvasText for inputs — the system keywords closest in
-     intent. */
+  /* Interactive elements need a visible border even when bg collapses */
   button,
   [role="button"],
   [role="menuitem"],
@@ -730,13 +769,9 @@
     border: 1px solid CanvasText;
   }
 
-  /* Decorative texture layers are pure noise in high-contrast mode. */
-  [data-grain] {
-    display: none;
-  }
+  /* Decorative grain is pure noise in high-contrast */
+  [data-grain] { display: none; }
 
-  /* Skeleton shimmer can feel alarming in high-contrast; keep static. */
-  [data-skeleton] {
-    animation: none !important;
-  }
+  /* Skeleton shimmer can feel alarming in HC; keep static */
+  [data-skeleton] { animation: none !important; }
 }