@motion-proto/live-tokens 0.40.0 → 0.41.0

package/src/editor/core/palettes/recommendText.ts

@@ -0,0 +1,216 @@
+// Suggested neutral text hierarchy for the Color Story.
+//
+// The solver (`solveTextContrast`) optimizes floors: it pushes every step to
+// the minimum L that clears its ratio, which can collapse secondary and
+// tertiary onto nearly the same value. This module instead anchors on the
+// user's current primary and derives secondary/tertiary as two even OKLCH-L
+// drops toward the background — hierarchy first, with WCAG AA (4.5) as a floor
+// rather than the driver. The floor is solved against the adverse extreme of
+// the neutral surface band so a compliant suggestion holds AA on EVERY band
+// surface (broadest reach); when the seed's reachable-L window can't span the
+// band, it falls back to the default surface and the coverage report says so.
+// Coverage is informational — callers alert on partial reach, never block.
+
+import { gamutClamp, oklchToHexClamped } from './oklch';
+import {
+  palettesToValues,
+  defaultScaleCurves,
+  BW_GUARD_MIN_L,
+  BW_GUARD_MAX_L,
+  type DerivedValue,
+  type SchemeDirection,
+} from './paletteDerivation';
+
+export { BW_GUARD_MIN_L, BW_GUARD_MAX_L };
+import { NEUTRAL_BAND } from './solveTextContrast';
+import { findLForContrast, contrastRatio, AA_BODY } from './contrast';
+import { sampleCurve, makeAnchor, type CurveAnchor } from '../../ui/curveEngine';
+import type { PaletteConfig } from '../themes/themeTypes';
+
+/** One even hierarchy drop in OKLCH L. Two drops span primary → tertiary. */
+export const SUGGESTED_STEP_DROP = 0.07;
+
+/** L difference below which current and suggested count as the same value. */
+const DIFF_EPS = 0.01;
+
+export interface SurfaceCheck {
+  var: string;
+  ratio: number;
+  meets: boolean;
+}
+
+export interface Coverage {
+  cleared: number;
+  total: number;
+  full: boolean;
+  /** Most adverse band surface met with every less-adverse one also met;
+   *  null when even the least adverse surface fails. */
+  reachVar: string | null;
+  /** Adversity-ascending (least adverse band surface first). */
+  checks: SurfaceCheck[];
+}
+
+export interface TextSuggestion {
+  step: 'primary' | 'secondary' | 'tertiary';
+  textVar: string;
+  current: { hex: string; l: number; coverage: Coverage };
+  suggested: { hex: string; l: number; c: number; coverage: Coverage };
+  differs: boolean;
+}
+
+export interface NeutralTextRecommendation {
+  scheme: SchemeDirection;
+  suggestions: TextSuggestion[];
+  anyDiffers: boolean;
+  /** Neutral Text-scale curve patch reproducing the suggested Ls at x=0/25/50
+   *  and pinning current muted/disabled at x=75/100. Null when nothing differs. */
+  patch: { lightness: CurveAnchor[]; saturation: CurveAnchor[] } | null;
+}
+
+const STEPS: { step: TextSuggestion['step']; x: number; textVar: string }[] = [
+  { step: 'primary', x: 0, textVar: '--text-primary' },
+  { step: 'secondary', x: 25, textVar: '--text-secondary' },
+  { step: 'tertiary', x: 50, textVar: '--text-tertiary' },
+];
+
+function colorL(v: DerivedValue | undefined): number | null {
+  return v?.kind === 'color' ? v.l : null;
+}
+
+export function recommendNeutralText(
+  palettes: Record<string, PaletteConfig>,
+  scheme?: SchemeDirection,
+  useBlackWhite = false,
+): NeutralTextRecommendation {
+  const neutral = palettes['Neutral']!;
+  const values = palettesToValues(palettes);
+
+  const pageBgL = colorL(values['--page-bg']) ?? colorL(values['--surface-neutral'])!;
+  const resolvedScheme: SchemeDirection = scheme ?? (pageBgL >= 0.5 ? 'light' : 'dark');
+  const direction: 'lighter' | 'darker' = resolvedScheme === 'light' ? 'darker' : 'lighter';
+  // Toward more contrast: +L for light text on dark surfaces, −L for dark text.
+  const sign = direction === 'lighter' ? 1 : -1;
+
+  const band = NEUTRAL_BAND
+    .map((v) => {
+      const value = values[v];
+      return value?.kind === 'color'
+        ? { var: v, l: value.l, hex: oklchToHexClamped(value.l, value.c, value.h) }
+        : null;
+    })
+    .filter((s): s is { var: string; l: number; hex: string } => s !== null)
+    .sort((a, b) => (a.l - b.l) * sign);
+  const bandAdverse = band[band.length - 1];
+  const surfaceDefaultHex = band.find((s) => s.var === '--surface-neutral')!.hex;
+
+  const seed = neutral.baseColor;
+  const seedL = Math.max(seed.l, 1e-4);
+  const baseC = Math.max(seed.c, 1e-9);
+  const baseH = seed.h;
+  const lMax = Math.min(1, 2 * seedL);
+
+  const curveOffset = neutral.curveOffset ?? {};
+  const lOff = curveOffset['Text-lightness'] ?? 0;
+  const sOff = curveOffset['Text-saturation'] ?? 0;
+  const satCurve = neutral.scaleCurves?.Text?.saturation ?? defaultScaleCurves.Text.saturation();
+
+  const stepChroma = (x: number): number =>
+    baseC * Math.max(0, Math.min(2, (sampleCurve(satCurve, x) + sOff) / 100));
+
+  function coverage(hex: string): Coverage {
+    const checks: SurfaceCheck[] = band.map((s) => {
+      const ratio = contrastRatio(hex, s.hex);
+      return { var: s.var, ratio, meets: ratio >= AA_BODY };
+    });
+    let reachVar: string | null = null;
+    for (const c of checks) {
+      if (!c.meets) break;
+      reachVar = c.var;
+    }
+    const cleared = checks.filter((c) => c.meets).length;
+    return { cleared, total: checks.length, full: cleared === checks.length, reachVar, checks };
+  }
+
+  // AA floors. Primary carries the broadest-reach preference: it floors
+  // against the band's adverse extreme so body text holds AA on every band
+  // surface the window can span (fallback: default surface, surfaced as
+  // partial coverage). Secondary/tertiary floor against the default surface —
+  // flooring THEM at the band extreme too would collapse the whole hierarchy
+  // onto near-white whenever the lightest band surface is a mid-tone.
+  const solveFloor = (against: string, c: number) =>
+    findLForContrast({ against, ratio: AA_BODY, direction, c, h: baseH, lMin: 0, lMax });
+
+  let primaryFloor = solveFloor(bandAdverse.hex, stepChroma(0));
+  if (contrastRatio(primaryFloor.hex, bandAdverse.hex) < AA_BODY) {
+    primaryFloor = solveFloor(surfaceDefaultHex, stepChroma(0));
+  }
+  const stepFloor = solveFloor(surfaceDefaultHex, stepChroma(50));
+
+  const towardContrast = (a: number, b: number): number => (sign > 0 ? Math.max(a, b) : Math.min(a, b));
+  const clampWindow = (l: number): number => Math.max(0, Math.min(lMax, l));
+
+  const currentL: Record<string, number> = {};
+  for (const s of STEPS) currentL[s.step] = colorL(values[s.textVar]) ?? seedL;
+
+  // Pure black/white is an affirmative choice (most designers find it too
+  // stark): opted in, primary anchors at the scheme extreme; otherwise the
+  // anchor is pulled inside the guard band, yielding only to the AA floor.
+  let primaryL: number;
+  if (useBlackWhite) {
+    primaryL = clampWindow(sign > 0 ? lMax : 0);
+  } else {
+    const guard = sign > 0
+      ? Math.max(BW_GUARD_MAX_L, primaryFloor.l)
+      : Math.min(BW_GUARD_MIN_L, primaryFloor.l);
+    const anchored = clampWindow(towardContrast(currentL.primary, primaryFloor.l));
+    primaryL = sign > 0 ? Math.min(anchored, guard) : Math.max(anchored, guard);
+  }
+  const tertiaryL = towardContrast(stepFloor.l, primaryL - sign * 2 * SUGGESTED_STEP_DROP);
+  const suggestedL: Record<string, number> = {
+    primary: primaryL,
+    secondary: towardContrast(stepFloor.l, (primaryL + tertiaryL) / 2),
+    tertiary: tertiaryL,
+  };
+
+  const suggestions: TextSuggestion[] = STEPS.map((s) => {
+    const currentValue = values[s.textVar];
+    const currentHex = currentValue?.kind === 'color'
+      ? oklchToHexClamped(currentValue.l, currentValue.c, currentValue.h)
+      : oklchToHexClamped(seedL, 0, 0);
+    const g = gamutClamp(suggestedL[s.step], stepChroma(s.x), baseH);
+    const hex = oklchToHexClamped(g.l, g.c, g.h);
+    return {
+      step: s.step,
+      textVar: s.textVar,
+      current: { hex: currentHex, l: currentL[s.step], coverage: coverage(currentHex) },
+      suggested: { hex, l: g.l, c: g.c, coverage: coverage(hex) },
+      differs: Math.abs(g.l - currentL[s.step]) > DIFF_EPS,
+    };
+  });
+
+  const anyDiffers = suggestions.some((s) => s.differs);
+
+  let patch: NeutralTextRecommendation['patch'] = null;
+  if (anyDiffers) {
+    const clampY = (v: number) => Math.max(0, Math.min(200, v));
+    const lightAnchors: CurveAnchor[] = [];
+    const satAnchors: CurveAnchor[] = [];
+    for (const s of suggestions) {
+      const x = STEPS.find((st) => st.step === s.step)!.x;
+      lightAnchors.push(makeAnchor(x, clampY((100 * s.suggested.l) / seedL - lOff)));
+      satAnchors.push(makeAnchor(x, clampY((100 * s.suggested.c) / baseC - sOff)));
+    }
+    // Pin muted/disabled at their current derived values so applying the
+    // suggestion never moves the steps it doesn't own.
+    for (const [x, textVar] of [[75, '--text-muted'], [100, '--text-disabled']] as const) {
+      const v = values[textVar];
+      const l = v?.kind === 'color' ? v.l : seedL;
+      const c = v?.kind === 'color' ? v.c : 0;
+      lightAnchors.push(makeAnchor(x, clampY((100 * l) / seedL - lOff)));
+      satAnchors.push(makeAnchor(x, clampY((100 * c) / baseC - sOff)));
+    }
+    patch = { lightness: lightAnchors, saturation: satAnchors };
+  }
+
+  return { scheme: resolvedScheme, suggestions, anyDiffers, patch };
+}

package/src/editor/core/palettes/solveTextContrast.ts

@@ -0,0 +1,251 @@
+// "Derive accessible text": solve each family's Text lightness curve so the
+// derived text colors clear WCAG AA against the surfaces they sit on.
+//
+// The Text scale derives L as seedL × (curveSample/100), clamped to [0,2], so a
+// family can only reach L ∈ [0, min(1, 2·seedL)]. The solver works inside that
+// window (passed as `lMax`) and emits a 5-anchor lightness curve whose sample
+// at each step x reproduces the solved L; a companion saturation curve pins the
+// solved (possibly chroma-decayed) chroma so the round-trip is exact. Surface
+// and page colors come from the real `palettesToValues` derivation (numeric
+// OKLCH); the solver converts to hex only at its own sRGB (WCAG) boundary.
+
+import { oklchToHexClamped } from './oklch';
+import {
+  palettesToValues,
+  serializeDerivedValue,
+  PALETTE_SPECS,
+  scaleToCssVar,
+  defaultScaleCurves,
+  type DerivedValue,
+  type SchemeDirection,
+} from './paletteDerivation';
+import { findLForContrast, contrastRatio } from './contrast';
+import { sampleCurve, makeAnchor, type CurveAnchor } from '../../ui/curveEngine';
+import type { PaletteConfig } from '../themes/themeTypes';
+
+export interface ContrastPairing {
+  family: string;
+  step: string;
+  textVar: string;
+  againstVar: string;
+  targetRatio: number;
+  achievedRatio: number;
+  meets: boolean;
+  /** True when this pairing carries an AA guarantee (vs. a deliberately graded,
+   *  non-AA step like `muted`/`disabled` on chromatic families). */
+  guaranteed: boolean;
+}
+
+export interface TextSolveResult {
+  patches: Record<string, Pick<PaletteConfig, 'scaleCurves'>>;
+  report: ContrastPairing[];
+}
+
+const TEXT_STEPS: { name: string; x: number }[] = [
+  { name: 'primary', x: 0 },
+  { name: 'secondary', x: 25 },
+  { name: 'tertiary', x: 50 },
+  { name: 'muted', x: 75 },
+  { name: 'disabled', x: 100 },
+];
+
+export const NEUTRAL_BAND = [
+  '--surface-neutral-lowest', '--surface-neutral-lower', '--surface-neutral-low',
+  '--surface-neutral', '--surface-neutral-high', '--surface-neutral-higher',
+  '--surface-neutral-highest',
+];
+
+interface StepPlan {
+  ratio: number;
+  guaranteed: boolean;
+  /** 'band' = adverse extreme of the neutral surface band; 'default' = surface
+   *  default; 'worst' = adverse of {surface default, page bg}. */
+  target: 'band' | 'default' | 'worst';
+}
+
+// Neutral family sits on neutral surfaces; primary/secondary must clear the
+// adverse band extreme, tertiary/muted the default surface. Disabled is graded.
+const NEUTRAL_PLAN: Record<string, StepPlan> = {
+  primary:   { ratio: 7.0, guaranteed: true,  target: 'band' },
+  secondary: { ratio: 4.5, guaranteed: true,  target: 'band' },
+  tertiary:  { ratio: 4.5, guaranteed: true,  target: 'default' },
+  muted:     { ratio: 3.0, guaranteed: true,  target: 'default' },
+  disabled:  { ratio: 2.0, guaranteed: false, target: 'default' },
+};
+
+// Chromatic families: primary must clear the worse of surface-default / page-bg
+// (chroma decay allowed), secondary the default surface; the rest grade toward
+// the surface (non-AA).
+const CHROMATIC_PLAN: Record<string, StepPlan> = {
+  primary:   { ratio: 4.5, guaranteed: true,  target: 'worst' },
+  secondary: { ratio: 4.5, guaranteed: true,  target: 'default' },
+  tertiary:  { ratio: 3.0, guaranteed: false, target: 'default' },
+  muted:     { ratio: 2.2, guaranteed: false, target: 'default' },
+  disabled:  { ratio: 1.6, guaranteed: false, target: 'default' },
+};
+
+interface Surface {
+  var: string;
+  l: number;
+  c: number;
+  h: number;
+}
+
+function colorSurface(varName: string, value: DerivedValue | undefined): Surface | null {
+  return value?.kind === 'color' ? { var: varName, l: value.l, c: value.c, h: value.h } : null;
+}
+
+// The solver terminates in sRGB (WCAG luminance is sRGB-defined); convert the
+// numeric surface to hex only at this boundary. Clamp so contrast math sees the
+// same chroma-reduced projection the CSS ships (unclamped override surfaces).
+function surfaceHex(s: Surface): string {
+  return oklchToHexClamped(s.l, s.c, s.h);
+}
+
+// The hardest surface to clear: for lighter text the highest-luminance surface,
+// for darker text the lowest.
+function pickAdverse(surfaces: Surface[], direction: 'lighter' | 'darker'): Surface {
+  let best = surfaces[0];
+  let bestL = best.l;
+  for (const s of surfaces.slice(1)) {
+    if (direction === 'lighter' ? s.l > bestL : s.l < bestL) {
+      best = s;
+      bestL = s.l;
+    }
+  }
+  return best;
+}
+
+export function solveTextCurves(
+  palettes: Record<string, PaletteConfig>,
+  scheme?: SchemeDirection,
+): TextSolveResult {
+  const values = palettesToValues(palettes);
+  const surfaceDefault = colorSurface('--surface-neutral', values['--surface-neutral'])!;
+  const rawPageBg = values['--page-bg'];
+  const pageBg: Surface = rawPageBg?.kind === 'color'
+    ? colorSurface('--page-bg', rawPageBg)!
+    : surfaceDefault;
+  const band: Surface[] = NEUTRAL_BAND
+    .map((v) => colorSurface(v, values[v]))
+    .filter((s): s is Surface => s !== null);
+
+  const resolvedScheme: SchemeDirection =
+    scheme ?? (pageBg.l >= 0.5 ? 'light' : 'dark');
+  const direction: 'lighter' | 'darker' = resolvedScheme === 'light' ? 'darker' : 'lighter';
+
+  const bandAdverse = pickAdverse(band, direction);
+  const worstAdverse = pickAdverse([surfaceDefault, pageBg], direction);
+
+  const patches: Record<string, Pick<PaletteConfig, 'scaleCurves'>> = {};
+  const report: ContrastPairing[] = [];
+
+  for (const spec of PALETTE_SPECS) {
+    const config = palettes[spec.label];
+    if (!config) continue;
+
+    const seed = config.baseColor;
+    const seedL = Math.max(seed.l, 1e-4);
+    const baseC = Math.max(seed.c, 1e-9);
+    const baseH = seed.h;
+    const lMax = Math.min(1, 2 * seedL);
+
+    const curveOffset = config.curveOffset ?? {};
+    const lOff = curveOffset['Text-lightness'] ?? 0;
+    const sOff = curveOffset['Text-saturation'] ?? 0;
+    const satCurve = config.scaleCurves?.Text?.saturation ?? defaultScaleCurves.Text.saturation();
+
+    const isNeutral = spec.label === 'Neutral';
+    const plan = isNeutral ? NEUTRAL_PLAN : CHROMATIC_PLAN;
+
+    const lightAnchors: CurveAnchor[] = [];
+    const satAnchors: CurveAnchor[] = [];
+
+    for (const step of TEXT_STEPS) {
+      const stepPlan = plan[step.name];
+      const against =
+        stepPlan.target === 'band' ? bandAdverse :
+        stepPlan.target === 'worst' ? worstAdverse : surfaceDefault;
+
+      const origSatMul = Math.max(0, Math.min(2, (sampleCurve(satCurve, step.x) + sOff) / 100));
+      const stepChroma = baseC * origSatMul;
+
+      const solved = findLForContrast({
+        against: surfaceHex(against),
+        ratio: stepPlan.ratio,
+        direction,
+        c: stepChroma,
+        h: baseH,
+        lMin: 0,
+        lMax,
+      });
+
+      const lightY = clamp(0, 200, (100 * solved.l) / seedL - lOff);
+      const satY = clamp(0, 200, (100 * solved.c) / baseC - sOff);
+      lightAnchors.push(makeAnchor(step.x, lightY));
+      satAnchors.push(makeAnchor(step.x, satY));
+    }
+
+    patches[spec.label] = {
+      scaleCurves: { Text: { lightness: lightAnchors, saturation: satAnchors } },
+    };
+  }
+
+  // Report against the actually-derived text hexes (post-round-trip verification
+  // at the solver level, mirroring Global invariant 8).
+  const derivedValues = palettesToValues(applyPatches(palettes, patches));
+  for (const spec of PALETTE_SPECS) {
+    if (!patches[spec.label]) continue;
+    const isNeutral = spec.label === 'Neutral';
+    const plan = isNeutral ? NEUTRAL_PLAN : CHROMATIC_PLAN;
+    for (const step of TEXT_STEPS) {
+      const stepPlan = plan[step.name];
+      const textVar = scaleToCssVar('Text', step.name, spec.cssNamespace);
+      if (!textVar) continue;
+      const against =
+        stepPlan.target === 'band' ? bandAdverse :
+        stepPlan.target === 'worst' ? worstAdverse : surfaceDefault;
+      const textValue = derivedValues[textVar];
+      const againstValue = derivedValues[against.var];
+      const againstHex = againstValue?.kind === 'color' ? serializeDerivedValue(againstValue) : surfaceHex(against);
+      const achieved = textValue?.kind === 'color' ? contrastRatio(serializeDerivedValue(textValue), againstHex) : 1;
+      report.push({
+        family: spec.label,
+        step: step.name,
+        textVar,
+        againstVar: against.var,
+        targetRatio: stepPlan.ratio,
+        achievedRatio: achieved,
+        meets: achieved >= minGuarantee(step.name, stepPlan),
+        guaranteed: stepPlan.guaranteed,
+      });
+    }
+  }
+
+  return { patches, report };
+}
+
+// The AA floor a guaranteed step must clear (primary/secondary/tertiary = body
+// 4.5; neutral muted = large 3.0). Graded steps floor at 1 (informational).
+function minGuarantee(stepName: string, plan: StepPlan): number {
+  if (!plan.guaranteed) return 1;
+  return stepName === 'muted' ? 3.0 : 4.5;
+}
+
+function clamp(lo: number, hi: number, v: number): number {
+  return Math.max(lo, Math.min(hi, v));
+}
+
+function applyPatches(
+  palettes: Record<string, PaletteConfig>,
+  patches: Record<string, Pick<PaletteConfig, 'scaleCurves'>>,
+): Record<string, PaletteConfig> {
+  const out: Record<string, PaletteConfig> = {};
+  for (const [label, config] of Object.entries(palettes)) {
+    const patch = patches[label];
+    out[label] = patch
+      ? { ...config, scaleCurves: { ...config.scaleCurves, ...patch.scaleCurves } }
+      : config;
+  }
+  return out;
+}

package/src/editor/core/store/editorCore.ts

@@ -412,7 +412,8 @@ export function __getPastAt(idx: number): EditorState | undefined {
 function paletteSnapshot(s: EditorState): Record<string, { base: string; overrides: number }> {
   const out: Record<string, { base: string; overrides: number }> = {};
   for (const [k, v] of Object.entries(s.palettes ?? {})) {
-    out[k] = { base: v.baseColor, overrides: Object.keys(v.overrides).length };
+    const { l, c, h } = v.baseColor;
+    out[k] = { base: `oklch(${l} ${c} ${h})`, overrides: Object.keys(v.overrides).length };
   }
   return out;
 }

package/src/editor/core/store/editorPersistence.ts

@@ -20,6 +20,7 @@ import { store } from './editorCore';
 import { quietGet, quietSet } from '../storage/storage';
 import { makeDefaultGradients } from '../themes/slices/gradients';
 import { seedShadowsFromDom } from '../themes/slices/shadows';
+import { sanitizeHarmonyAxes, axesFromLegacyOrder } from '../palettes/colorHarmony';
 
 // Resolve the persist key lazily (per-call) so library consumers that invoke
 // `configureEditor({storagePrefix})` before the first store write get the
@@ -87,6 +88,22 @@ export function normalizeComponents(state: EditorState): EditorState {
   return { ...state, components };
 }
 
+// `hydrate` shallow-merges persisted state over `emptyState()`, which always
+// seeds a default `harmonyAxes`. So a pre-axes session (persisted `harmonyOrder`,
+// no `harmonyAxes`) surfaces here with the injected default axes over its real
+// palettes. The new store never persists `harmonyOrder`, so its presence is the
+// definitive pre-axes signal: migrate from it, seeding hues off the palettes.
+// Otherwise reconcile the persisted axes. Either way, drop the stale legacy key.
+export function normalizeHarmonyAxes(state: EditorState): EditorState {
+  const legacy = (state as { harmonyOrder?: unknown }).harmonyOrder;
+  const axes = legacy !== undefined
+    ? axesFromLegacyOrder(legacy, state.palettes)
+    : sanitizeHarmonyAxes(state.harmonyAxes, state.palettes);
+  const next = { ...state, harmonyAxes: axes };
+  delete (next as { harmonyOrder?: unknown }).harmonyOrder;
+  return next;
+}
+
 export function hydrate(): void {
   // Corrupt state, missing key, or unavailable storage all return null;
   // the editor falls through to the empty default in that case.
@@ -95,7 +112,7 @@ export function hydrate(): void {
     // Shallow-merge onto default shape so older persisted state missing
     // newly-added domain fields still loads.
     const merged = { ...emptyStateFactory(), ...(parsed as object) } as EditorState;
-    store.set(normalizeComponents(migrateGradients(merged)));
+    store.set(normalizeHarmonyAxes(normalizeComponents(migrateGradients(merged))));
   }
   // m13 fix: seed shadows from the DOM at hydrate time so the editor
   // captures the tokens.css baseline regardless of whether the user opens

package/src/editor/core/store/editorStore.ts

@@ -29,6 +29,10 @@ import {
 } from '../themes/migrations';
 import { renamePrimaryPaletteKey } from '../themes/migrations/2026-05-13-primary-to-brand';
 import { unifyGrayPalettes } from '../themes/migrations/2026-06-05-palette-unification';
+import { migratePaletteColorsToOklch, type PreOklchPaletteConfig } from '../themes/migrations/2026-07-21-palette-oklch-basis';
+import { adoptLegacyBaseAnchor } from '../themes/migrations/2026-07-24-base-anchor-placement';
+import { adoptBackgroundSpotAsBase } from '../themes/migrations/2026-07-25-background-spot-to-base';
+import { defaultHarmonyAxes, sanitizeHarmonyAxes, axesFromLegacyOrder } from '../palettes/colorHarmony';
 import { __resetRendererCacheForTests, installRenderer } from './editorRenderer';
 import {
   store,
@@ -87,6 +91,7 @@ function emptyState(): EditorState {
     columns: { ...DEFAULT_COLUMNS },
     components: {},
     gradients: { tokens: makeDefaultGradients() },
+    harmonyAxes: defaultHarmonyAxes(),
     cssVars: {},
   };
 }
@@ -512,7 +517,13 @@ const domainLoaders: Record<string, DomainLoader> = {
  */
 export function loadFromFile(theme: Theme): void {
   const next = emptyState();
-  next.palettes = unifyGrayPalettes(renamePrimaryPaletteKey(structuredClone(theme.editorConfigs ?? {})));
+  // Structural palette migrations, innermost → outermost: rename Primary→Brand,
+  // drop the gray "mode", convert every color channel to the numeric OKLCH
+  // basis, adopt any legacy locked-500 anchor as a persisted placement, then
+  // fold a legacy background spot into the base color. The clone is still
+  // pre-basis (hex or already-numeric) on disk.
+  const raw = structuredClone(theme.editorConfigs ?? {}) as Record<string, PreOklchPaletteConfig>;
+  next.palettes = adoptBackgroundSpotAsBase(adoptLegacyBaseAnchor(migratePaletteColorsToOklch(unifyGrayPalettes(renamePrimaryPaletteKey(raw)))));
   next.fonts.sources = structuredClone(theme.fontSources ?? []);
   next.fonts.stacks  = structuredClone(theme.fontStacks  ?? []);
   const rawVars = runMigrations(
@@ -525,6 +536,9 @@ export function loadFromFile(theme: Theme): void {
   // (or in components' case, vars that wouldn't have been in the theme to
   // begin with).
   for (const load of Object.values(domainLoaders)) load(next, rawVars);
+  next.harmonyAxes = theme.harmonyAxes
+    ? sanitizeHarmonyAxes(theme.harmonyAxes, next.palettes)
+    : axesFromLegacyOrder(theme.harmonyOrder, next.palettes);
   next.cssVars = rawVars;
   resetHistoryForLoad();
   store.set(next);
@@ -550,6 +564,9 @@ export function toTheme(state: EditorState, meta: { name: string }): Theme {
   if (state.shadows.tokens.length > 0) {
     Object.assign(cssVariables, shadowsToVars(state.shadows));
   }
+  // Compat: bound families in axis order for older builds. Omitted when nothing
+  // is bound — an empty legacy list would resurrect the default trio on load.
+  const boundOrder = state.harmonyAxes.filter((a) => a.family !== null).map((a) => a.family!);
   return {
     name: meta.name,
     createdAt: now,
@@ -558,6 +575,8 @@ export function toTheme(state: EditorState, meta: { name: string }): Theme {
     cssVariables,
     fontSources: state.fonts.sources,
     fontStacks: state.fonts.stacks,
+    harmonyAxes: state.harmonyAxes,
+    ...(boundOrder.length > 0 ? { harmonyOrder: boundOrder } : {}),
     schemaVersion: CURRENT_THEME_SCHEMA_VERSION,
   };
 }

package/src/editor/core/store/editorTypes.ts

@@ -1,4 +1,5 @@
 import type { PaletteConfig, FontSource, FontStack } from '../themes/themeTypes';
+import type { HarmonyAxis } from '../palettes/colorHarmony';
 
 export interface ShadowGlobals {
   angle: number;
@@ -136,5 +137,8 @@ export interface EditorState {
   columns: ColumnsState;
   components: Record<string, ComponentSlice>;
   gradients: { tokens: GradientToken[] };
+  /** Four fixed axes (index = role: Anchor/Secondary/Tertiary/Quaternary); each
+   *  owns a hue; family is the live-bound color or null. */
+  harmonyAxes: HarmonyAxis[];
   cssVars: Record<string, string>;
 }

package/src/editor/core/store/editorViewStore.ts

@@ -1,15 +1,19 @@
 import { writable } from 'svelte/store';
 
-export type EditorView = 'tokens' | 'components';
+export type EditorView = 'tokens' | 'components' | 'colors';
 export type SidebarCondensed = boolean | 'auto';
 
 const VIEW_KEY = 'lt.editorView';
 const CONDENSED_KEY = 'lt.sidebarCondensed';
 
+function isEditorView(v: unknown): v is EditorView {
+  return v === 'tokens' || v === 'components' || v === 'colors';
+}
+
 function readView(): EditorView {
   try {
     const v = localStorage.getItem(VIEW_KEY);
-    if (v === 'components' || v === 'tokens') return v;
+    if (isEditorView(v)) return v;
   } catch {}
   return 'tokens';
 }
@@ -41,7 +45,7 @@ sidebarCondensed.subscribe((v) => {
 if (typeof window !== 'undefined') {
   window.addEventListener('storage', (e) => {
     if (e.key === VIEW_KEY) {
-      if (e.newValue === 'tokens' || e.newValue === 'components') editorView.set(e.newValue);
+      if (isEditorView(e.newValue)) editorView.set(e.newValue);
     } else if (e.key === CONDENSED_KEY) {
       if (e.newValue === 'true') sidebarCondensed.set(true);
       else if (e.newValue === 'false') sidebarCondensed.set(false);