@motion-proto/live-tokens 0.1.1 → 0.3.2

package/src/lib/migrations/migrations.test.ts

@@ -0,0 +1,341 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CURRENT_THEME_SCHEMA_VERSION,
+  CURRENT_COMPONENT_SCHEMA_VERSION,
+  runMigrations,
+} from './index';
+
+describe('migration runner — schemaVersion gating', () => {
+  it('CURRENT_*_SCHEMA_VERSION are positive (at least one migration registered each)', () => {
+    expect(CURRENT_THEME_SCHEMA_VERSION).toBeGreaterThan(0);
+    expect(CURRENT_COMPONENT_SCHEMA_VERSION).toBeGreaterThan(0);
+  });
+
+  it('legacy theme (schemaVersion: 0) → bg/canvas + legacy-key renames applied; resaved file matches modern shape', () => {
+    const legacy = {
+      // bg → canvas pattern (exact match + boundary suffix)
+      '--surface-bg': '#fff',
+      '--text-bg': '#000',
+      '--border-bg-strong': '#888',
+      // explicit legacy renames
+      '--empty': '#111',
+      '--empty-attachment': 'fixed',
+      // orphan token (silent drop)
+      '--border-neutral': '#ccc',
+      // unrelated key passes through
+      '--text-primary': '#333',
+    };
+    const migrated = runMigrations('theme', 0, legacy);
+    expect(migrated['--surface-canvas']).toBe('#fff');
+    expect(migrated['--text-canvas']).toBe('#000');
+    expect(migrated['--border-canvas-strong']).toBe('#888');
+    expect(migrated['--page-bg']).toBe('#111');
+    expect(migrated['--page-bg-attachment']).toBe('fixed');
+    expect(migrated['--border-neutral']).toBeUndefined();
+    expect(migrated['--text-primary']).toBe('#333');
+    // The "drop" old keys are gone
+    expect(migrated['--surface-bg']).toBeUndefined();
+    expect(migrated['--empty']).toBeUndefined();
+  });
+
+  it('file already at current theme version → no migrations run (passthrough)', () => {
+    const modern = { '--surface-canvas': '#fff', '--text-primary': '#333' };
+    const out = runMigrations('theme', CURRENT_THEME_SCHEMA_VERSION, modern);
+    expect(out).toEqual(modern);
+    // identity-preserved values
+    expect(out['--surface-canvas']).toBe('#fff');
+  });
+
+  it('legacy component-config (schemaVersion: 0) → prefix + suffix renames; segmentedcontrol option-disabled flatten', () => {
+    const legacy = {
+      // abbreviated prefix
+      '--segment-option-bg': '#eee',
+      // segmentedcontrol option-disabled → disabled flatten
+      '--segmentedcontrol-option-disabled-text': '#999',
+      // selected-disabled is dropped (impossible state)
+      '--segmentedcontrol-selected-disabled-bg': 'red',
+      // selected-hover is dropped
+      '--segmentedcontrol-selected-hover-bg': 'blue',
+      // unrelated key
+      '--segment-track-radius': '4px',
+    };
+    const migrated = runMigrations('component-config', 0, legacy, {
+      component: 'segmentedcontrol',
+    });
+    // Prefix renamed, then option-disabled flattened... actually option-disabled
+    // was already on the long-form name, so it goes through the flatten step.
+    expect(migrated['--segmentedcontrol-option-bg']).toBe('#eee');
+    expect(migrated['--segmentedcontrol-disabled-text']).toBe('#999');
+    expect(migrated['--segmentedcontrol-selected-disabled-bg']).toBeUndefined();
+    expect(migrated['--segmentedcontrol-selected-hover-bg']).toBeUndefined();
+    expect(migrated['--segmentedcontrol-track-radius']).toBe('4px');
+  });
+
+  it('component-config file at version 1 → only the >=1 migrations run (segmentedcontrol flatten only)', () => {
+    const v1 = {
+      // Already on long-form prefix; v1 → v2 step still applies for sc
+      '--segmentedcontrol-option-disabled-text': '#999',
+      // suffix-rename rules from v0→v1 should NOT re-apply; abbreviated keys
+      // present at v1 are user-authored and untouched
+      '--segment-something': 'should-pass-through',
+    };
+    const migrated = runMigrations('component-config', 1, v1, {
+      component: 'segmentedcontrol',
+    });
+    expect(migrated['--segmentedcontrol-disabled-text']).toBe('#999');
+    // v0→v1 prefix rename did NOT re-run
+    expect(migrated['--segment-something']).toBe('should-pass-through');
+    expect(migrated['--segmentedcontrol-something']).toBeUndefined();
+  });
+
+  it('component-config at version 2 → collapsiblesection state tokens namespace into container; v3→v4 cleanup applies on top', () => {
+    const v2 = {
+      '--collapsiblesection-default-surface': '--surface-canvas-high',
+      '--collapsiblesection-hover-icon': '--text-primary',
+      '--collapsiblesection-active-border': '--color-primary-400',
+      '--collapsiblesection-expanded-padding': '--space-4',
+      '--collapsiblesection-default-label-font-family': '--font-sans',
+    };
+    const migrated = runMigrations('component-config', 2, v2, {
+      component: 'collapsiblesection',
+    });
+    // Old, unscoped keys are gone after v2→v3
+    expect(migrated['--collapsiblesection-default-surface']).toBeUndefined();
+    expect(migrated['--collapsiblesection-hover-icon']).toBeUndefined();
+    // Surviving header tokens land in the container namespace
+    expect(migrated['--collapsiblesection-container-default-surface']).toBe('--surface-canvas-high');
+    expect(migrated['--collapsiblesection-container-hover-icon']).toBe('--text-primary');
+    expect(migrated['--collapsiblesection-container-default-label-font-family']).toBe('--font-sans');
+    expect(migrated['--collapsiblesection-container-expanded-padding']).toBe('--space-4');
+    // v3→v4 drops container active-border (frame owns chrome now); the
+    // pre-existing default-surface is also seeded into the new frame namespace.
+    expect(migrated['--collapsiblesection-container-active-border']).toBeUndefined();
+    expect(migrated['--collapsiblesection-container-frame-surface']).toBe('--surface-canvas-high');
+  });
+
+  it('component-config v2 namespace migration only fires for collapsiblesection', () => {
+    const v2 = { '--button-primary-surface': '--surface-success' };
+    const out = runMigrations('component-config', 2, v2, { component: 'button' });
+    expect(out).toEqual(v2);
+  });
+
+  it('component-config at version 3 → collapsiblesection container chrome moves into frame, dead per-state tokens drop', () => {
+    const v3 = {
+      // Container default-state chrome → frame (values preserved).
+      '--collapsiblesection-container-default-surface': '--surface-canvas-high',
+      '--collapsiblesection-container-default-border': '--color-primary-400',
+      '--collapsiblesection-container-default-border-width': '--border-width-3',
+      '--collapsiblesection-container-default-radius': '--radius-md',
+      '--collapsiblesection-container-default-padding': '--space-4',
+      // Container hover/active border tokens drop (frame owns chrome).
+      '--collapsiblesection-container-hover-border': '--color-primary-500',
+      '--collapsiblesection-container-hover-border-width': '--border-width-3',
+      '--collapsiblesection-container-active-radius': '--radius-md',
+      '--collapsiblesection-container-active-surface': '--surface-canvas-low',
+      // Chromeless per-state border / radius drop.
+      '--collapsiblesection-chromeless-default-border': '--color-primary-400',
+      '--collapsiblesection-chromeless-hover-border-width': '--border-width-1',
+      '--collapsiblesection-chromeless-active-radius': '--radius-none',
+      '--collapsiblesection-chromeless-default-padding': '--space-4',
+      // Divider radius drops; divider border-* survives (paints bottom rule).
+      '--collapsiblesection-divider-default-border': '--border-neutral-faint',
+      '--collapsiblesection-divider-default-border-width': '--border-width-1',
+      '--collapsiblesection-divider-default-radius': '--radius-none',
+      // Expanded panel: only padding for chromeless/divider; surface + padding for container.
+      '--collapsiblesection-chromeless-expanded-border': '--color-primary-400',
+      '--collapsiblesection-chromeless-expanded-surface': '--surface-canvas',
+      '--collapsiblesection-chromeless-expanded-padding': '--space-4',
+      '--collapsiblesection-container-expanded-radius': '--radius-md',
+      '--collapsiblesection-container-expanded-surface': '--surface-canvas-low',
+      '--collapsiblesection-container-expanded-padding': '--space-4',
+    };
+    const migrated = runMigrations('component-config', 3, v3, {
+      component: 'collapsiblesection',
+    });
+    // Container frame-* seeded from old default-state tokens. The
+    // v5→v6 primary→brand migration rewrites `--color-primary-*` values
+    // to `--color-brand-*` at the tail of the chain.
+    expect(migrated['--collapsiblesection-container-frame-surface']).toBe('--surface-canvas-high');
+    expect(migrated['--collapsiblesection-container-frame-border']).toBe('--color-brand-400');
+    expect(migrated['--collapsiblesection-container-frame-border-width']).toBe('--border-width-3');
+    expect(migrated['--collapsiblesection-container-frame-radius']).toBe('--radius-md');
+    // Container default-state surface + padding survive (still drive header strip)
+    expect(migrated['--collapsiblesection-container-default-surface']).toBe('--surface-canvas-high');
+    expect(migrated['--collapsiblesection-container-default-padding']).toBe('--space-4');
+    // Container default-state border / radius dropped (frame owns them now)
+    expect(migrated['--collapsiblesection-container-default-border']).toBeUndefined();
+    expect(migrated['--collapsiblesection-container-default-border-width']).toBeUndefined();
+    expect(migrated['--collapsiblesection-container-default-radius']).toBeUndefined();
+    // Container hover/active border tokens dropped
+    expect(migrated['--collapsiblesection-container-hover-border']).toBeUndefined();
+    expect(migrated['--collapsiblesection-container-hover-border-width']).toBeUndefined();
+    expect(migrated['--collapsiblesection-container-active-radius']).toBeUndefined();
+    // Container hover/active surface survives (header strip)
+    expect(migrated['--collapsiblesection-container-active-surface']).toBe('--surface-canvas-low');
+    // Chromeless per-state border / radius dropped; padding stays
+    expect(migrated['--collapsiblesection-chromeless-default-border']).toBeUndefined();
+    expect(migrated['--collapsiblesection-chromeless-hover-border-width']).toBeUndefined();
+    expect(migrated['--collapsiblesection-chromeless-active-radius']).toBeUndefined();
+    expect(migrated['--collapsiblesection-chromeless-default-padding']).toBe('--space-4');
+    // Divider border / border-width survive; radius drops
+    expect(migrated['--collapsiblesection-divider-default-border']).toBe('--border-neutral-faint');
+    expect(migrated['--collapsiblesection-divider-default-border-width']).toBe('--border-width-1');
+    expect(migrated['--collapsiblesection-divider-default-radius']).toBeUndefined();
+    // Expanded panel cleanup
+    expect(migrated['--collapsiblesection-chromeless-expanded-border']).toBeUndefined();
+    expect(migrated['--collapsiblesection-chromeless-expanded-surface']).toBeUndefined();
+    expect(migrated['--collapsiblesection-chromeless-expanded-padding']).toBe('--space-4');
+    expect(migrated['--collapsiblesection-container-expanded-radius']).toBeUndefined();
+    expect(migrated['--collapsiblesection-container-expanded-surface']).toBe('--surface-canvas-low');
+    expect(migrated['--collapsiblesection-container-expanded-padding']).toBe('--space-4');
+  });
+
+  it('component-config at version 4 → sectiondivider gradient stops migrate to angle + stop-{n}-{color,position}', () => {
+    const v4 = {
+      '--sectiondivider-canvas-padding': '--space-16',
+      '--sectiondivider-canvas-gradient-stop-1': '--surface-canvas-highest',
+      '--sectiondivider-canvas-gradient-stop-2': '--surface-canvas-higher',
+      '--sectiondivider-canvas-gradient-stop-3': '--surface-canvas-high',
+      '--sectiondivider-canvas-gradient-stop-4': '--surface-canvas',
+      '--sectiondivider-primary-gradient-stop-1': '--color-primary-300',
+      '--sectiondivider-primary-gradient-stop-2': '--color-primary-500',
+      '--sectiondivider-primary-gradient-stop-4': '--color-primary-800',
+    };
+    const migrated = runMigrations('component-config', 4, v4, { component: 'sectiondivider' });
+    // Old keys gone
+    expect(migrated['--sectiondivider-canvas-gradient-stop-1']).toBeUndefined();
+    expect(migrated['--sectiondivider-canvas-gradient-stop-3']).toBeUndefined();
+    expect(migrated['--sectiondivider-canvas-gradient-stop-4']).toBeUndefined();
+    // Unrelated tokens preserved
+    expect(migrated['--sectiondivider-canvas-padding']).toBe('--space-16');
+    // Canvas: colors mapped from old 1, 2, 4
+    expect(migrated['--sectiondivider-canvas-gradient-angle']).toBe('--gradient-angle-diagonal');
+    expect(migrated['--sectiondivider-canvas-gradient-stop-1-color']).toBe('--surface-canvas-highest');
+    expect(migrated['--sectiondivider-canvas-gradient-stop-1-position']).toBe('--gradient-stop-start');
+    expect(migrated['--sectiondivider-canvas-gradient-stop-2-color']).toBe('--surface-canvas-higher');
+    expect(migrated['--sectiondivider-canvas-gradient-stop-2-position']).toBe('--gradient-stop-mid');
+    expect(migrated['--sectiondivider-canvas-gradient-stop-3-color']).toBe('--surface-canvas');
+    expect(migrated['--sectiondivider-canvas-gradient-stop-3-position']).toBe('--gradient-stop-end');
+    // Primary variant: user-tuned colors carry across; v5→v6 also rewrites
+    // the brand-family value names.
+    expect(migrated['--sectiondivider-primary-gradient-stop-1-color']).toBe('--color-brand-300');
+    expect(migrated['--sectiondivider-primary-gradient-stop-2-color']).toBe('--color-brand-500');
+    expect(migrated['--sectiondivider-primary-gradient-stop-3-color']).toBe('--color-brand-800');
+    // Variants the file didn't set still gain default colors and angle/positions
+    expect(migrated['--sectiondivider-special-gradient-angle']).toBe('--gradient-angle-diagonal');
+    expect(migrated['--sectiondivider-special-gradient-stop-1-color']).toBe('--surface-special-highest');
+    expect(migrated['--sectiondivider-special-gradient-stop-3-position']).toBe('--gradient-stop-end');
+  });
+
+  it('component-config v4 sectiondivider migration only fires for sectiondivider', () => {
+    // Use a value not in the brand-rename map so the v5→v6 step is also a no-op.
+    const v4 = { '--button-primary-gradient-stop-1': '--surface-accent' };
+    const out = runMigrations('component-config', 4, v4, { component: 'button' });
+    expect(out).toEqual(v4);
+  });
+
+  it('component-config v4 sectiondivider migration is idempotent on the new shape', () => {
+    const newShape = {
+      '--sectiondivider-canvas-gradient-angle': '--gradient-angle-horizontal',
+      '--sectiondivider-canvas-gradient-stop-1-color': '--color-primary-200',
+      '--sectiondivider-canvas-gradient-stop-1-position': '10%',
+      '--sectiondivider-canvas-gradient-stop-2-color': '--color-primary-500',
+      '--sectiondivider-canvas-gradient-stop-2-position': '40%',
+      '--sectiondivider-canvas-gradient-stop-3-color': '--color-primary-900',
+      '--sectiondivider-canvas-gradient-stop-3-position': '85%',
+    };
+    const out = runMigrations('component-config', 4, newShape, { component: 'sectiondivider' });
+    // User-tuned values for canvas survive structurally; v5→v6 rewrites
+    // brand-family value names from primary → brand at the tail of the chain.
+    expect(out['--sectiondivider-canvas-gradient-angle']).toBe('--gradient-angle-horizontal');
+    expect(out['--sectiondivider-canvas-gradient-stop-1-color']).toBe('--color-brand-200');
+    expect(out['--sectiondivider-canvas-gradient-stop-1-position']).toBe('10%');
+    expect(out['--sectiondivider-canvas-gradient-stop-2-position']).toBe('40%');
+    expect(out['--sectiondivider-canvas-gradient-stop-3-position']).toBe('85%');
+  });
+
+  it('component-config at current version → no migrations run', () => {
+    const current = { '--button-primary-surface': '--surface-success' };
+    const out = runMigrations(
+      'component-config',
+      CURRENT_COMPONENT_SCHEMA_VERSION,
+      current,
+      { component: 'button' },
+    );
+    expect(out).toEqual(current);
+  });
+
+  it('theme v1 → v2 primary→brand: brand family keys renamed, neutral --text-primary untouched', () => {
+    const v1 = {
+      '--color-primary-100': '#ffe6f9',
+      '--color-primary-500': '#eb0ad4',
+      '--surface-primary': '#55004c',
+      '--surface-primary-high': '#6c0061',
+      '--border-primary': '#b200a0',
+      '--border-primary-strong': '#ff90eb',
+      '--text-primary-color': '#ff8eeb',
+      '--text-primary-secondary': '#fe5be7',
+      // Neutral text ramp — must NOT be touched.
+      '--text-primary': '#fff5f0',
+      '--text-secondary': '#b0a9a4',
+      // Component variant — also must NOT be touched.
+      '--button-primary-surface': '#abc123',
+    };
+    const out = runMigrations('theme', 1, v1);
+    // Brand family renamed.
+    expect(out['--color-brand-100']).toBe('#ffe6f9');
+    expect(out['--color-brand-500']).toBe('#eb0ad4');
+    expect(out['--surface-brand']).toBe('#55004c');
+    expect(out['--surface-brand-high']).toBe('#6c0061');
+    expect(out['--border-brand']).toBe('#b200a0');
+    expect(out['--border-brand-strong']).toBe('#ff90eb');
+    expect(out['--text-brand']).toBe('#ff8eeb');
+    expect(out['--text-brand-secondary']).toBe('#fe5be7');
+    // Old keys gone.
+    expect(out['--color-primary-100']).toBeUndefined();
+    expect(out['--surface-primary']).toBeUndefined();
+    expect(out['--border-primary']).toBeUndefined();
+    expect(out['--text-primary-color']).toBeUndefined();
+    expect(out['--text-primary-secondary']).toBeUndefined();
+    // Neutral text + component variants survive verbatim.
+    expect(out['--text-primary']).toBe('#fff5f0');
+    expect(out['--text-secondary']).toBe('#b0a9a4');
+    expect(out['--button-primary-surface']).toBe('#abc123');
+  });
+
+  it('component-config v5 → v6 primary→brand: rewrites alias keys AND values; component variants untouched', () => {
+    const v5 = {
+      // Brand family on the alias key side (rare but possible).
+      '--text-primary-color': '#fff',
+      // Brand family on the value side (common: component aliases to family token).
+      '--badge-trait-surface': '--surface-primary',
+      '--badge-trait-text': '--text-primary-color',
+      '--badge-trait-border': '--border-primary-medium',
+      // Component variant token — name should NOT change.
+      '--button-primary-surface': '--surface-brand-high',
+      // Neutral text — value should NOT change.
+      '--card-default-title': '--text-primary',
+      // Unrelated key/value pair.
+      '--card-hover-title': '--text-secondary',
+    };
+    const out = runMigrations('component-config', 5, v5, { component: 'badge' });
+    expect(out['--text-brand']).toBe('#fff');
+    expect(out['--text-primary-color']).toBeUndefined();
+    expect(out['--badge-trait-surface']).toBe('--surface-brand');
+    expect(out['--badge-trait-text']).toBe('--text-brand');
+    expect(out['--badge-trait-border']).toBe('--border-brand-medium');
+    // Component variant identifier (LHS) is preserved; its value is not in the
+    // rename map so it passes through.
+    expect(out['--button-primary-surface']).toBe('--surface-brand-high');
+    // Neutral text value preserved.
+    expect(out['--card-default-title']).toBe('--text-primary');
+    expect(out['--card-hover-title']).toBe('--text-secondary');
+  });
+
+  it('runMigrations is pure — does not mutate the input map', () => {
+    const input = { '--surface-bg': '#fff' };
+    const before = { ...input };
+    runMigrations('theme', 0, input);
+    expect(input).toEqual(before);
+  });
+});

package/src/lib/navLinkTypes.ts

@@ -0,0 +1 @@
+export type NavLink = { path: string; label: string; icon?: string; disabled?: boolean };

package/src/lib/overlayState.ts

@@ -0,0 +1,3 @@
+import { writable } from 'svelte/store';
+
+export const overlayOpen = writable(false);

package/src/lib/paletteDerivation.ts

@@ -0,0 +1,300 @@
+/**
+ * Pure palette → CSS-variable derivation.
+ *
+ * Mirrors the logic that previously lived only inside `PaletteEditor.svelte`'s
+ * reactive emission, but as standalone functions so the editor store can emit
+ * palette-derived vars at boot without requiring any editor component to be
+ * mounted. Without this module the disabled-state preview (and any other
+ * `var(--surface-neutral)` consumer) reads a stale value on reload until the
+ * user opens the LiveEditorOverlay and mounts the PaletteEditors.
+ *
+ * The PaletteEditor still owns *editing* preview (draft hex picked but not
+ * yet committed to overrides). Once committed via the store, this module
+ * derives the same CSS vars from the persisted config.
+ */
+
+import { hexToOklch, oklchToHex, gamutClamp } from './oklch';
+import { type CurveAnchor, sampleCurve, makeAnchor } from '../ui/curveEngine';
+import type { PaletteConfig } from './themeTypes';
+
+export type PaletteMode = 'chromatic' | 'gray';
+
+export interface PaletteSpec {
+  label: string;
+  cssNamespace: string;
+  mode: PaletteMode;
+  emptySelector?: boolean;
+  initialColor: string;
+}
+
+/**
+ * Single source of truth for which palettes exist and how their CSS namespaces
+ * map. Was previously hardcoded inside `VariablesTab.svelte`; centralising it
+ * here lets the store seed boot-time vars without depending on the UI tree.
+ */
+export const PALETTE_SPECS: readonly PaletteSpec[] = [
+  { label: 'Neutral',    cssNamespace: 'neutral',   mode: 'gray',      initialColor: '#808080' },
+  { label: 'Alternate',  cssNamespace: 'alternate', mode: 'gray',      initialColor: '#808080' },
+  { label: 'Background', cssNamespace: 'canvas',    mode: 'chromatic', emptySelector: true, initialColor: '#1a1a2e' },
+  { label: 'Brand',      cssNamespace: 'brand',     mode: 'chromatic', initialColor: '#c93636' },
+  { label: 'Accent',     cssNamespace: 'accent',    mode: 'chromatic', initialColor: '#f49e0b' },
+  { label: 'Special',    cssNamespace: 'special',   mode: 'chromatic', initialColor: '#8b5cf6' },
+  { label: 'Info',       cssNamespace: 'info',      mode: 'chromatic', initialColor: '#3077e8' },
+  { label: 'Success',    cssNamespace: 'success',   mode: 'chromatic', initialColor: '#21c45d' },
+  { label: 'Warning',    cssNamespace: 'warning',   mode: 'chromatic', initialColor: '#e66e1a' },
+  { label: 'Danger',     cssNamespace: 'danger',    mode: 'chromatic', initialColor: '#e8304f' },
+] as const;
+
+const PALETTE_STEPS = [
+  { label: '100' }, { label: '200' }, { label: '300' }, { label: '400' },
+  { label: '500' }, { label: '600' }, { label: '700' }, { label: '800' },
+  { label: '850' }, { label: '900' }, { label: '950' },
+];
+
+const GRAY_STEPS = [
+  { label: '100' }, { label: '200' }, { label: '300' }, { label: '400' },
+  { label: '500' }, { label: '600' }, { label: '700' }, { label: '800' },
+  { label: '850' }, { label: '900' }, { label: '950' },
+];
+
+interface ScaleStep { name: string; position: number; }
+interface Scale { title: string; isText: boolean; steps: ScaleStep[]; }
+
+const SCALES: readonly Scale[] = [
+  {
+    title: 'Surfaces', isText: false,
+    steps: [
+      { name: 'lowest',  position: -1 },
+      { name: 'lower',   position: -2 / 3 },
+      { name: 'low',     position: -1 / 3 },
+      { name: 'default', position: 0 },
+      { name: 'high',    position: 1 / 3 },
+      { name: 'higher',  position: 2 / 3 },
+      { name: 'highest', position: 1 },
+    ],
+  },
+  {
+    title: 'Borders', isText: false,
+    steps: [
+      { name: 'faint',   position: -1 },
+      { name: 'subtle',  position: -0.5 },
+      { name: 'default', position: 0 },
+      { name: 'medium',  position: 0.5 },
+      { name: 'strong',  position: 1 },
+    ],
+  },
+  {
+    title: 'Text', isText: true,
+    steps: [
+      { name: 'primary',   position: 0 },
+      { name: 'secondary', position: 0 },
+      { name: 'tertiary',  position: 0 },
+      { name: 'muted',     position: 0 },
+      { name: 'disabled',  position: 0 },
+    ],
+  },
+];
+
+export const DEFAULT_PALETTE_LIGHTNESS = (): CurveAnchor[] => [makeAnchor(0, 95, 5), makeAnchor(100, 8, 5)];
+export const DEFAULT_PALETTE_SATURATION = (): CurveAnchor[] => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)];
+export const DEFAULT_GRAY_LIGHTNESS = (): CurveAnchor[] => [makeAnchor(0, 92, 5), makeAnchor(100, 3, 5)];
+export const DEFAULT_GRAY_SATURATION = (): CurveAnchor[] => [makeAnchor(0, 20, 30), makeAnchor(100, 20, 30)];
+export const DEFAULT_TINT_CHROMA = 0.04;
+
+export const defaultScaleCurves = {
+  Surfaces: {
+    lightness:  () => [makeAnchor(0, 15, 5),   makeAnchor(100, 47, 5)],
+    saturation: () => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)],
+  },
+  Borders: {
+    lightness:  () => [makeAnchor(0, 25, 5),   makeAnchor(100, 80, 5)],
+    saturation: () => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)],
+  },
+  Text: {
+    lightness:  () => [makeAnchor(0, 120, 30), makeAnchor(100, 55, 30)],
+    saturation: () => [makeAnchor(0, 100, 30), makeAnchor(100, 15, 30)],
+  },
+} as const;
+
+function paletteStepKey(label: string): string { return `Palette-${label}`; }
+function grayStepKey(label: string): string { return `gray-${label}`; }
+function stepKey(scaleTitle: string, stepName: string): string { return `${scaleTitle}-${stepName}`; }
+
+function stepIndexToX(index: number, total: number): number {
+  return total > 1 ? (index / (total - 1)) * 100 : 50;
+}
+
+function computePaletteColor(
+  index: number,
+  base: string,
+  lightnessCurve: CurveAnchor[],
+  saturationCurve: CurveAnchor[],
+  curveOffset: Record<string, number>,
+): string {
+  const { c: baseC, h } = hexToOklch(base);
+  const xPos = stepIndexToX(index, PALETTE_STEPS.length);
+  const targetL = Math.max(0, Math.min(100, sampleCurve(lightnessCurve, xPos) + (curveOffset.lightness ?? 0))) / 100;
+  const satMul = Math.max(0, Math.min(2, (sampleCurve(saturationCurve, xPos) + (curveOffset.saturation ?? 0)) / 100));
+  const targetC = baseC * satMul;
+  const clamped = gamutClamp(targetL, targetC, h);
+  return oklchToHex(clamped.l, clamped.c, clamped.h);
+}
+
+function computeGrayColor(
+  index: number,
+  hue: number,
+  chroma: number,
+  grayLightnessCurve: CurveAnchor[],
+  graySaturationCurve: CurveAnchor[],
+  curveOffset: Record<string, number>,
+): string {
+  const xPos = stepIndexToX(index, GRAY_STEPS.length);
+  const lOff = curveOffset['gray-lightness'] ?? 0;
+  const sOff = curveOffset['gray-saturation'] ?? 0;
+  const targetL = Math.max(0, Math.min(100, sampleCurve(grayLightnessCurve, xPos) + lOff)) / 100;
+  const satMul = Math.max(0, Math.min(2, (sampleCurve(graySaturationCurve, xPos) + sOff) / 100));
+  const targetC = chroma * satMul;
+  const clamped = gamutClamp(targetL, targetC, hue);
+  return oklchToHex(clamped.l, clamped.c, clamped.h);
+}
+
+function computeDerivedColor(
+  step: ScaleStep,
+  base: string,
+  scaleTitle: string,
+  scaleCurves: Record<string, { lightness: CurveAnchor[]; saturation: CurveAnchor[] }>,
+  curveOffset: Record<string, number>,
+): string {
+  const scale = SCALES.find((s) => s.title === scaleTitle)!;
+  const idx = scale.steps.indexOf(step);
+  const xPos = stepIndexToX(idx, scale.steps.length);
+  const defs = defaultScaleCurves[scaleTitle as keyof typeof defaultScaleCurves];
+  const lCurve = scaleCurves[scaleTitle]?.lightness ?? defs.lightness();
+  const sCurve = scaleCurves[scaleTitle]?.saturation ?? defs.saturation();
+  const lOff = curveOffset[`${scaleTitle}-lightness`] ?? 0;
+  const sOff = curveOffset[`${scaleTitle}-saturation`] ?? 0;
+  const { l: baseL, c: baseC, h: baseH } = hexToOklch(base);
+  let targetL: number;
+  if (scale.isText) {
+    const lMul = Math.max(0, Math.min(2, (sampleCurve(lCurve, xPos) + lOff) / 100));
+    targetL = Math.max(0, Math.min(1, baseL * lMul));
+  } else {
+    targetL = Math.max(0, Math.min(100, sampleCurve(lCurve, xPos) + lOff)) / 100;
+  }
+  const satMul = Math.max(0, Math.min(2, (sampleCurve(sCurve, xPos) + sOff) / 100));
+  const targetC = baseC * satMul;
+  const clamped = gamutClamp(targetL, targetC, baseH);
+  return oklchToHex(clamped.l, clamped.c, clamped.h);
+}
+
+export function scaleToCssVar(scaleTitle: string, stepName: string, cssNamespace: string | null): string | null {
+  if (cssNamespace === null) return null;
+  if (scaleTitle === 'Surfaces') {
+    const suffix = stepName === 'default' ? '' : `-${stepName}`;
+    return cssNamespace === 'neutral' ? `--surface-neutral${suffix}` : `--surface-${cssNamespace}${suffix}`;
+  }
+  if (scaleTitle === 'Borders') {
+    const suffix = stepName === 'default' ? '' : `-${stepName}`;
+    return cssNamespace === 'neutral' ? `--border-neutral${suffix}` : `--border-${cssNamespace}${suffix}`;
+  }
+  if (scaleTitle === 'Text') {
+    if (cssNamespace === 'neutral') return `--text-${stepName}`;
+    return stepName === 'primary' ? `--text-${cssNamespace}` : `--text-${cssNamespace}-${stepName}`;
+  }
+  return null;
+}
+
+export function derivePaletteVars(spec: PaletteSpec, config: PaletteConfig | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!config) return out;
+
+  const baseColor = config.baseColor ?? spec.initialColor;
+  const overrides = config.overrides ?? {};
+  const curveOffset = config.curveOffset ?? {};
+  const scaleCurves = config.scaleCurves ?? {};
+
+  let baseForScales: string;
+
+  if (spec.mode === 'gray') {
+    const grayLightnessCurve = config.grayLightnessCurve ?? DEFAULT_GRAY_LIGHTNESS();
+    const graySaturationCurve = config.graySaturationCurve ?? DEFAULT_GRAY_SATURATION();
+    const tintHue = config.tintHue ?? 240;
+    const tintChroma = config.tintChroma ?? DEFAULT_TINT_CHROMA;
+
+    let gray500 = '#808080';
+    GRAY_STEPS.forEach((step, index) => {
+      const k = grayStepKey(step.label);
+      const hex = computeGrayColor(index, tintHue, tintChroma, grayLightnessCurve, graySaturationCurve, curveOffset);
+      const effective = (k in overrides) ? overrides[k] : hex;
+      out[`--color-${spec.cssNamespace}-${step.label}`] = effective;
+      if (step.label === '500') gray500 = hex;
+    });
+    baseForScales = gray500;
+  } else {
+    const lightnessCurve = config.lightnessCurve ?? DEFAULT_PALETTE_LIGHTNESS();
+    const saturationCurve = config.saturationCurve ?? DEFAULT_PALETTE_SATURATION();
+
+    PALETTE_STEPS.forEach((ps, index) => {
+      const k = paletteStepKey(ps.label);
+      const hex = computePaletteColor(index, baseColor, lightnessCurve, saturationCurve, curveOffset);
+      const effective = (k in overrides) ? overrides[k] : hex;
+      out[`--color-${spec.cssNamespace}-${ps.label}`] = effective;
+    });
+    baseForScales = baseColor;
+  }
+
+  for (const scale of SCALES) {
+    for (const step of scale.steps) {
+      const k = stepKey(scale.title, step.name);
+      const hex = (k in overrides)
+        ? overrides[k]
+        : computeDerivedColor(step, baseForScales, scale.title, scaleCurves, curveOffset);
+      const varName = scaleToCssVar(scale.title, step.name, spec.cssNamespace);
+      if (varName) out[varName] = hex;
+    }
+  }
+
+  if (spec.emptySelector) {
+    const emptyMode = config.emptyMode ?? 'solid';
+    const emptyStep = config.emptyStep ?? '850';
+    const gradientStyle = config.gradientStyle ?? 'linear';
+    const gradientAngle = config.gradientAngle ?? 180;
+    const gradientReverse = config.gradientReverse ?? false;
+    const gradientSize = config.gradientSize ?? 'page';
+    const gradientStops = config.gradientStops ?? [
+      { position: 0, paletteLabel: '800' },
+      { position: 100, paletteLabel: '950' },
+    ];
+
+    if (emptyMode === 'solid') {
+      const stepHex = out[`--color-${spec.cssNamespace}-${emptyStep}`];
+      if (stepHex) out['--page-bg'] = stepHex;
+      out['--page-bg-attachment'] = 'scroll';
+    } else {
+      const sortedStops = [...gradientStops].sort((a, b) =>
+        gradientReverse ? b.position - a.position : a.position - b.position,
+      );
+      const stopsCss = sortedStops
+        .map((s) => `${out[`--color-${spec.cssNamespace}-${s.paletteLabel}`] ?? '#000000'} ${s.position}%`)
+        .join(', ');
+      let gradient: string;
+      switch (gradientStyle) {
+        case 'radial': gradient = `radial-gradient(circle, ${stopsCss})`; break;
+        case 'conic':  gradient = `conic-gradient(from ${gradientAngle}deg, ${stopsCss})`; break;
+        default:       gradient = `linear-gradient(${gradientAngle}deg, ${stopsCss})`;
+      }
+      out['--page-bg'] = gradient;
+      out['--page-bg-attachment'] = gradientSize === 'window' ? 'fixed' : 'scroll';
+    }
+  }
+
+  return out;
+}
+
+export function palettesToVars(palettes: Record<string, PaletteConfig>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const spec of PALETTE_SPECS) {
+    Object.assign(out, derivePaletteVars(spec, palettes[spec.label]));
+  }
+  return out;
+}