@motion-proto/live-tokens 0.40.0 → 0.41.0

package/src/editor/core/themes/migrations/2026-06-05-palette-unification.ts

@@ -19,23 +19,25 @@
  */
 
 import { type CurveAnchor, sampleCurve } from '../../../ui/curveEngine';
-import { hexToOklch, oklchToHex, gamutClamp } from '../../palettes/oklch';
+import { oklchToHex, gamutClamp } from '../../palettes/oklch';
 import { DEFAULT_PALETTE_SATURATION } from '../../palettes/paletteDerivation';
-import type { PaletteConfig } from '../themeTypes';
+import type { PreOklchPaletteConfig } from './2026-07-21-palette-oklch-basis';
 
 const NEUTRAL_LABELS = new Set(['Neutral', 'Alternate']);
 
 const GRAY_STEP_COUNT = 11;
 const GRAY_500_X = (4 / (GRAY_STEP_COUNT - 1)) * 100;
 
-/** Legacy shape: the gray fields union'd onto every saved palette config. */
+/** Legacy shape: the gray fields union'd onto every saved palette config. This
+ *  migration runs before the OKLCH-basis conversion, so color channels here are
+ *  still hex strings. */
 type LegacyGrayFields = {
   tintHue?: number;
   tintChroma?: number;
   grayLightnessCurve?: CurveAnchor[];
   graySaturationCurve?: CurveAnchor[];
 };
-type LegacyPaletteConfig = PaletteConfig & LegacyGrayFields;
+type LegacyPaletteConfig = PreOklchPaletteConfig & LegacyGrayFields;
 
 /** Reproduces the deleted `computeGrayColor` at step 500. */
 function effectiveGray500(cfg: LegacyPaletteConfig): string {
@@ -51,13 +53,13 @@ function effectiveGray500(cfg: LegacyPaletteConfig): string {
   return oklchToHex(clamped.l, clamped.c, clamped.h);
 }
 
-function stripGrayFields(cfg: LegacyPaletteConfig): PaletteConfig {
+function stripGrayFields(cfg: LegacyPaletteConfig): PreOklchPaletteConfig {
   const { tintHue, tintChroma, grayLightnessCurve, graySaturationCurve, ...rest } = cfg;
   return rest;
 }
 
 /** Precondition: `cfg.grayLightnessCurve` is defined (caller-guarded). */
-function unifyNeutral(cfg: LegacyPaletteConfig): PaletteConfig {
+function unifyNeutral(cfg: LegacyPaletteConfig): PreOklchPaletteConfig {
   const {
     'gray-lightness': grayLightnessOffset,
     'gray-saturation': _graySaturationOffset,
@@ -77,9 +79,9 @@ function unifyNeutral(cfg: LegacyPaletteConfig): PaletteConfig {
 }
 
 export function unifyGrayPalettes(
-  editorConfigs: Record<string, PaletteConfig>,
-): Record<string, PaletteConfig> {
-  const out: Record<string, PaletteConfig> = {};
+  editorConfigs: Record<string, PreOklchPaletteConfig>,
+): Record<string, PreOklchPaletteConfig> {
+  const out: Record<string, PreOklchPaletteConfig> = {};
   for (const [label, cfg] of Object.entries(editorConfigs)) {
     const legacy = cfg as LegacyPaletteConfig;
     out[label] = NEUTRAL_LABELS.has(label) && legacy.grayLightnessCurve !== undefined

package/src/editor/core/themes/migrations/2026-07-21-palette-oklch-basis.ts

@@ -0,0 +1,51 @@
+/**
+ * Palette color basis: hex → numeric OKLCH.
+ *
+ * The stored + edited basis moves from 8-bit hex to numeric OKLCH `{ l, c, h }`
+ * for every palette's `baseColor` and `overrides`. Lives outside the
+ * `runMigrations` framework (whose contract is the flat cssVariables bag)
+ * because it transforms the structured `editorConfigs` map — exactly like
+ * `renamePrimaryPaletteKey` / `unifyGrayPalettes`, which it composes with in
+ * `loadFromFile`. Applied unconditionally; idempotent (an already-numeric
+ * channel passes straight through) and self-sunsetting once every saved theme
+ * has been resaved in the numeric shape.
+ *
+ * The `_imported` anchor lives in `cssVariables` (a hex string) and is
+ * untouched here; the reconcile parser converts it at its own boundary.
+ */
+
+import { hexToOklch, type Oklch } from '../../palettes/oklch';
+import type { PaletteConfig } from '../themeTypes';
+
+/** A config whose color channels may still be hex strings (pre-basis on disk)
+ *  or already numeric (resaved). Lets the pre-OKLCH structural migrations stay
+ *  honestly typed while this one is the boundary that produces `PaletteConfig`. */
+export type PreOklchPaletteConfig = Omit<PaletteConfig, 'baseColor' | 'overrides'> & {
+  baseColor: string | Oklch;
+  overrides: Record<string, string | Oklch>;
+};
+
+const round = (v: number, dp: number): number => {
+  const f = 10 ** dp;
+  return Math.round(v * f) / f;
+};
+
+// Storage precision (decision 5): l, c to 4 decimals, h to 2 — beyond sub-LSB
+// fidelity so the sRGB projection is unmoved, and stable across file diffs.
+function toStoredOklch(value: string | Oklch): Oklch {
+  if (typeof value !== 'string') return value;
+  const { l, c, h } = hexToOklch(value);
+  return { l: round(l, 4), c: round(c, 4), h: round(h, 2) };
+}
+
+export function migratePaletteColorsToOklch(
+  editorConfigs: Record<string, PreOklchPaletteConfig>,
+): Record<string, PaletteConfig> {
+  const out: Record<string, PaletteConfig> = {};
+  for (const [label, cfg] of Object.entries(editorConfigs)) {
+    const overrides: Record<string, Oklch> = {};
+    for (const [k, v] of Object.entries(cfg.overrides ?? {})) overrides[k] = toStoredOklch(v);
+    out[label] = { ...cfg, baseColor: toStoredOklch(cfg.baseColor), overrides };
+  }
+  return out;
+}

package/src/editor/core/themes/migrations/2026-07-24-base-anchor-placement.ts

@@ -0,0 +1,37 @@
+/**
+ * Base-anchor placement: adopt the legacy locked-500 anchor.
+ *
+ * The old "Lock base color to position 500" toggle injected a curve anchor at
+ * x=40 (step 500) but recorded nothing about it — the editor re-found it by
+ * x-position. Placement is now persisted as `anchorPlacement` (any step, not
+ * just 500), so configs that carry the legacy anchor adopt it as a placement
+ * at step index 4. Configs whose lock was on but inert (flag true, no anchor
+ * — the shipped default for most palettes) are left alone; their placement
+ * happens on the next base-color edit.
+ *
+ * Lives outside the `runMigrations` framework (whose contract is the flat
+ * cssVariables bag) because it transforms the structured `editorConfigs` map,
+ * exactly like `migratePaletteColorsToOklch`, which it composes with in
+ * `loadFromFile`. Applied unconditionally; idempotent (skips once
+ * `anchorPlacement` exists) and self-sunsetting once every saved theme has
+ * been resaved with a placement.
+ */
+
+import { stepIndexToX } from '../../palettes/paletteDerivation';
+import type { PaletteConfig } from '../themeTypes';
+
+const LEGACY_LOCK_STEP = 4;
+
+export function adoptLegacyBaseAnchor(
+  editorConfigs: Record<string, PaletteConfig>,
+): Record<string, PaletteConfig> {
+  const x500 = stepIndexToX(LEGACY_LOCK_STEP);
+  for (const cfg of Object.values(editorConfigs)) {
+    if (cfg.anchorToBase === false || cfg.anchorPlacement !== undefined) continue;
+    const idx = (cfg.lightnessCurve ?? []).findIndex((a) => Math.abs(a.x - x500) < 0.5);
+    if (idx > 0 && idx < cfg.lightnessCurve.length - 1) {
+      cfg.anchorPlacement = { step: LEGACY_LOCK_STEP };
+    }
+  }
+  return editorConfigs;
+}

package/src/editor/core/themes/migrations/2026-07-25-background-spot-to-base.ts

@@ -0,0 +1,40 @@
+/**
+ * Background spot → base color: the solid page background used to be a
+ * separately selected palette step (`emptyStep`); it now IS the base color.
+ * To keep a saved theme's page rendering identical, the base color adopts the
+ * color the old spot actually showed (the derived value at that step, curves
+ * and overrides included) and `syncBaseAnchor` pins it there — the placement
+ * lands back on the old spot's step because the adopted L equals the curve at
+ * that x by construction. Gradient-mode configs keep their base untouched.
+ * The stray field is deleted either way so a resave drops it.
+ *
+ * Composes in `loadFromFile` after the OKLCH-basis migration (it reads a
+ * numeric baseColor). Idempotent (skips once `emptyStep` is gone) and
+ * self-sunsetting once every saved theme has been resaved.
+ */
+
+import {
+  PALETTE_SPECS,
+  derivePaletteValues,
+  syncBaseAnchor,
+} from '../../palettes/paletteDerivation';
+import type { PaletteConfig } from '../themeTypes';
+
+export function adoptBackgroundSpotAsBase(
+  editorConfigs: Record<string, PaletteConfig>,
+): Record<string, PaletteConfig> {
+  const spec = PALETTE_SPECS.find((s) => s.emptySelector)!;
+  for (const [label, cfg] of Object.entries(editorConfigs)) {
+    const legacy = cfg as PaletteConfig & { emptyStep?: string };
+    if (legacy.emptyStep === undefined) continue;
+    if (label === spec.label && (cfg.emptyMode ?? 'solid') === 'solid') {
+      const spot = derivePaletteValues(spec, cfg)[`--color-${spec.cssNamespace}-${legacy.emptyStep}`];
+      if (spot?.kind === 'color') {
+        cfg.baseColor = { l: spot.l, c: spot.c, h: spot.h };
+        syncBaseAnchor(cfg);
+      }
+    }
+    delete legacy.emptyStep;
+  }
+  return editorConfigs;
+}

package/src/editor/core/themes/themeTypes.ts

@@ -1,4 +1,6 @@
 import type { CurveAnchor } from '../../ui/curveEngine';
+import type { Oklch } from '../palettes/oklch';
+import type { HarmonyAxis } from '../palettes/colorHarmony';
 
 export type GradientStyle = 'linear' | 'radial' | 'conic';
 
@@ -8,21 +10,32 @@ export interface GradientStop {
 }
 
 export interface PaletteConfig {
-  baseColor: string;
+  /** Numeric OKLCH intent — the single stored basis. Unclamped: the store holds
+   *  what the user meant; gamut clamping is projection-only (derivation output,
+   *  swatch/canvas painting, hex/CSS serialization). */
+  baseColor: Oklch;
   lightnessCurve: CurveAnchor[];
   saturationCurve: CurveAnchor[];
   scaleCurves: Record<string, { lightness: CurveAnchor[]; saturation: CurveAnchor[] }>;
   curveOffset: Record<string, number>;
-  overrides: Record<string, string>;
+  overrides: Record<string, Oklch>;
   snappedScales: string[];
   emptyMode?: 'solid' | 'gradient';
-  emptyStep?: string;
   gradientStyle?: GradientStyle;
   gradientAngle?: number;
   gradientReverse?: boolean;
   gradientStops?: GradientStop[];
   gradientSize?: 'page' | 'window';
   anchorToBase?: boolean;
+  /**
+   * Where the base color sits in the ramp while `anchorToBase` is on: the
+   * PALETTE_STEPS index whose curve anchors are pinned to the base color
+   * (lightness = base L, saturation = multiplier 100). `displacedL` /
+   * `displacedS` remember the y of a pre-existing anchor (endpoint or
+   * user-authored) the placement overwrote at that x, so moving the
+   * placement or toggling off restores it instead of deleting it.
+   */
+  anchorPlacement?: { step: number; displacedL?: number; displacedS?: number };
   /**
    * Set to true by importers when they overlay `cssVariables[--color-{ns}-*]`
    * without owning the typed-state curves. The storage-layer reconciler uses
@@ -78,6 +91,13 @@ export interface Theme {
   cssVariables: Record<string, string>;
   fontSources?: FontSource[];
   fontStacks?: FontStack[];
+  /**
+   * Deprecated legacy field. Read when `harmonyAxes` is absent; written on save
+   * for older builds.
+   */
+  harmonyOrder?: string[];
+  /** Four fixed harmony axes, each owning a hue with an optional bound family. */
+  harmonyAxes?: HarmonyAxis[];
   /**
    * Server-attached file-name marker for round-tripping the file identity
    * back to the client. Set by `themeFileApi`'s GET handlers; read by

package/src/editor/docs/CodeBlock.svelte

@@ -47,7 +47,7 @@
     padding: var(--space-16, 1rem) var(--space-20, 1.25rem);
     overflow-x: auto;
     font-size: var(--font-size-sm, 0.875rem);
-    line-height: var(--line-height-md, 1.6);
+    line-height: var(--line-height-normal, 1.6);
   }
 
   pre code {

package/src/editor/docs/Docs.svelte

@@ -398,17 +398,19 @@
     margin: 0;
   }
   .title-block .eyebrow {
-    font-size: var(--font-size-xs, 0.75rem);
-    font-weight: var(--font-weight-semibold, 600);
+    font-family: var(--eyebrow-font-family);
+    font-size: var(--eyebrow-font-size);
+    font-weight: var(--eyebrow-font-weight);
+    line-height: var(--eyebrow-line-height);
+    letter-spacing: var(--eyebrow-letter-spacing);
+    text-transform: var(--eyebrow-text-transform);
     color: var(--text-accent, #009d9a);
-    text-transform: uppercase;
-    letter-spacing: var(--letter-spacing-wider, 0.12em);
     margin: 0 0 var(--space-8, 0.5rem);
   }
   .title-block h1 {
     font-family: var(--font-display, var(--font-sans));
     font-size: var(--font-size-5xl, 3rem);
-    line-height: var(--line-height-xs, 1.1);
+    line-height: var(--line-height-none, 1.1);
     letter-spacing: var(--letter-spacing-tight, -0.02em);
     margin: 0 0 var(--space-12, 0.75rem);
     color: var(--text-primary);
@@ -490,7 +492,7 @@
 
   .prose {
     font-size: var(--font-size-md, 1rem);
-    line-height: var(--line-height-lg, 1.65);
+    line-height: var(--line-height-relaxed, 1.65);
   }
   .md-snippet {
     margin: 0 0 var(--space-20, 1.25rem);
@@ -517,25 +519,40 @@
   .prose :global(h2),
   .prose :global(h3),
   .prose :global(h4) {
-    font-family: var(--font-display, var(--font-sans));
-    font-weight: var(--font-weight-semibold, 600);
-    letter-spacing: var(--letter-spacing-tight, -0.015em);
-    line-height: var(--line-height-sm, 1.2);
     color: var(--text-primary);
     position: relative;
   }
+  .prose :global(h1) {
+    font-family: var(--heading-xl-font-family);
+    font-size: var(--heading-xl-font-size);
+    font-weight: var(--heading-xl-font-weight);
+    line-height: var(--heading-xl-line-height);
+    letter-spacing: var(--heading-xl-letter-spacing);
+  }
   .prose :global(h2) {
-    font-size: var(--font-size-2xl, 1.5rem);
+    font-family: var(--heading-lg-font-family);
+    font-size: var(--heading-lg-font-size);
+    font-weight: var(--heading-lg-font-weight);
+    line-height: var(--heading-lg-line-height);
+    letter-spacing: var(--heading-lg-letter-spacing);
     margin: var(--space-48, 3rem) 0 var(--space-16, 1rem);
     padding-top: var(--space-12, 0.75rem);
     border-top: var(--border-width-1, 1px) solid var(--border-neutral-faint, #1c2327);
   }
   .prose :global(h3) {
-    font-size: var(--font-size-xl, 1.25rem);
+    font-family: var(--heading-md-font-family);
+    font-size: var(--heading-md-font-size);
+    font-weight: var(--heading-md-font-weight);
+    line-height: var(--heading-md-line-height);
+    letter-spacing: var(--heading-md-letter-spacing);
     margin: var(--space-32, 2rem) 0 var(--space-12, 0.75rem);
   }
   .prose :global(h4) {
-    font-size: var(--font-size-lg, 1.125rem);
+    font-family: var(--heading-sm-font-family);
+    font-size: var(--heading-sm-font-size);
+    font-weight: var(--heading-sm-font-weight);
+    line-height: var(--heading-sm-line-height);
+    letter-spacing: var(--heading-sm-letter-spacing);
     margin: var(--space-24, 1.5rem) 0 var(--space-8, 0.5rem);
     color: var(--text-secondary);
   }

package/src/editor/pages/EditorShell.svelte

@@ -4,6 +4,7 @@
   import { onMount } from 'svelte';
   import { get } from 'svelte/store';
   import VariablesTab from '../ui/VariablesTab.svelte';
+  import ColorsTab from '../ui/colors/ColorsTab.svelte';
   import ThemeFileManager from '../ui/ThemeFileManager.svelte';
   import EditorViewSwitcher from '../ui/EditorViewSwitcher.svelte';
   import ComponentsTab from '../component-editor/scaffolding/ComponentsTab.svelte';
@@ -29,6 +30,11 @@
     { id: 'utility-tokens', label: 'Utility Tokens', icon: 'fas fa-sliders' }
   ];
 
+  const colorsNavItems = [
+    { id: 'colors-wheel', label: 'Wheel', icon: 'fas fa-palette' },
+    { id: 'colors-story', label: 'Story', icon: 'fas fa-layer-group' }
+  ];
+
   const allComponentNavItems = getComponentRegistryEntries().map(({ id, label, icon, origin }) => ({ id, label, icon, origin }));
   const systemNavItems = allComponentNavItems.filter((i) => i.origin === 'system');
   const customNavItems = allComponentNavItems.filter((i) => i.origin === 'custom');
@@ -131,7 +137,27 @@
 
     {#if $editorView === 'tokens'}
       <div class="nav-items">
-        {#each tokenNavItems as item}
+        {#each tokenNavItems as item (item.id)}
+          <button
+            class="nav-item"
+            class:active={selectedTokenSection === item.id}
+            onmouseenter={(e) => showHint(item.label, e.currentTarget)}
+            onmouseleave={hideHint}
+            onclick={() => scrollToSection(item.id)}
+          >
+            <i class={item.icon}></i>
+            <span class="nav-label">{item.label}</span>
+          </button>
+        {/each}
+      </div>
+      {#if !condensed}
+        <div class="sidebar-footer">
+          <ThemeFileManager {saveStatus} onsave={handleSave} onload={handleLoad} />
+        </div>
+      {/if}
+    {:else if $editorView === 'colors'}
+      <div class="nav-items">
+        {#each colorsNavItems as item (item.id)}
           <button
             class="nav-item"
             class:active={selectedTokenSection === item.id}
@@ -151,7 +177,7 @@
       {/if}
     {:else}
       <div class="nav-items">
-        {#each systemNavItems as item}
+        {#each systemNavItems as item (item.id)}
           <button
             class="nav-item"
             class:active={$selectedComponent === item.id}
@@ -171,7 +197,7 @@
           <div class="nav-divider">
             <span class="nav-divider-label">Custom</span>
           </div>
-          {#each customNavItems as item}
+          {#each customNavItems as item (item.id)}
             <button
               class="nav-item"
               class:active={$selectedComponent === item.id}
@@ -200,6 +226,8 @@
   <main class="content">
     {#if $editorView === 'tokens'}
       <VariablesTab />
+    {:else if $editorView === 'colors'}
+      <ColorsTab />
     {:else}
       <ComponentsTab selectedComponent={$selectedComponent} />
     {/if}

package/src/editor/ui/ColorEditPanel.svelte

@@ -9,6 +9,9 @@
   interface Props {
     title?: string | null;
     showRemoveOverride?: boolean;
+    /** Hide the confirm/cancel actions for live-apply consumers (Colors view
+     *  readout) where edits commit through the store as they happen. */
+    hideActions?: boolean;
     onConfirm?: () => void;
     onCancel?: () => void;
     onRemoveOverride?: () => void;
@@ -32,6 +35,7 @@
   let {
     title = null,
     showRemoveOverride = false,
+    hideActions = false,
     onConfirm = () => {},
     onCancel = () => {},
     onRemoveOverride = () => {},
@@ -154,22 +158,24 @@
     {/if}
     <code class="hsl-values">oklch({(lPct / 100).toFixed(2)}, {chroma.toFixed(3)}, {Math.round(hue)})</code>
     {@render actions?.()}
-    <div class="hsl-panel-actions">
-      {#if showRemoveOverride}
-        <Button
-          variant="danger"
-          size="small"
-          icon="fas fa-trash"
-          on:click={onRemoveOverride}
-        >Remove override</Button>
-      {/if}
-      <InlineEditActions
-        onSave={onConfirm}
-        onCancel={onCancel}
-        saveTitle="Apply changes"
-        cancelTitle="Discard changes"
-      />
-    </div>
+    {#if !hideActions}
+      <div class="hsl-panel-actions">
+        {#if showRemoveOverride}
+          <Button
+            variant="danger"
+            size="small"
+            icon="fas fa-trash"
+            on:click={onRemoveOverride}
+          >Remove override</Button>
+        {/if}
+        <InlineEditActions
+          onSave={onConfirm}
+          onCancel={onCancel}
+          saveTitle="Apply changes"
+          cancelTitle="Discard changes"
+        />
+      </div>
+    {/if}
   </div>
   <div class="hsl-sliders">
     <div class="hsl-slider-row">

package/src/editor/ui/EditorViewSwitcher.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { editorView } from '../core/store/editorViewStore';
+  import { editorView, type EditorView } from '../core/store/editorViewStore';
   import { parentRoute } from '../core/routing/parentRouteStore';
   import { DEFAULT_COMPONENTS_PATH } from '../core/routing/ownedRoutes';
 
@@ -17,13 +17,36 @@
   // relocated route won't disable the switch.
   let componentsDisabled = $derived($parentRoute === DEFAULT_COMPONENTS_PATH);
 
-  function set(v: 'tokens' | 'components') {
+  // Editing flow order: Tokens → Colors → Components. The condensed rail cycles
+  // through these; Components is skipped while it's disabled (already on that
+  // page) so the cycle never lands on a dead view.
+  const CYCLE: readonly EditorView[] = ['tokens', 'colors', 'components'];
+  const ICONS: Record<EditorView, string> = {
+    tokens: 'fa-sliders',
+    colors: 'fa-palette',
+    components: 'fa-cubes',
+  };
+  const LABELS: Record<EditorView, string> = {
+    tokens: 'Tokens',
+    colors: 'Colors',
+    components: 'Components',
+  };
+
+  function set(v: EditorView) {
     editorView.set(v);
   }
 
-  function toggle() {
-    if (componentsDisabled) return;
-    editorView.update((v) => (v === 'tokens' ? 'components' : 'tokens'));
+  function cycle() {
+    editorView.update((current) => {
+      let i = CYCLE.indexOf(current);
+      for (let n = 0; n < CYCLE.length; n++) {
+        i = (i + 1) % CYCLE.length;
+        const next = CYCLE[i];
+        if (next === 'components' && componentsDisabled) continue;
+        return next;
+      }
+      return current;
+    });
   }
 </script>
 
@@ -31,11 +54,11 @@
   <button
     type="button"
     class="compact"
-    aria-label={$editorView === 'tokens' ? 'Switch to components' : 'Switch to tokens'}
-    title={$editorView === 'tokens' ? 'Tokens (click for components)' : 'Components (click for tokens)'}
-    onclick={toggle}
+    aria-label={`Editor view: ${LABELS[$editorView]} (click to cycle)`}
+    title={`${LABELS[$editorView]} (click to cycle views)`}
+    onclick={cycle}
   >
-    <i class="fas {$editorView === 'tokens' ? 'fa-palette' : 'fa-cubes'}"></i>
+    <i class="fas {ICONS[$editorView]}"></i>
   </button>
 {:else}
   <div class="seg-group">
@@ -52,6 +75,17 @@
         <span class="radio" aria-hidden="true"></span>
         <span>Tokens</span>
       </button>
+      <button
+        type="button"
+        role="tab"
+        class="seg-btn"
+        class:active={$editorView === 'colors'}
+        aria-selected={$editorView === 'colors'}
+        onclick={() => set('colors')}
+      >
+        <span class="radio" aria-hidden="true"></span>
+        <span>Colors</span>
+      </button>
       <button
         type="button"
         role="tab"

package/src/editor/ui/FontStackEditor.svelte

@@ -381,7 +381,6 @@
       transform var(--ui-transition-fast),
       border-color var(--ui-transition-fast);
   }
-  .slot-row:hover { border-color: var(--ui-border); }
 
   .slot-controls {
     display: grid;