@motion-proto/live-tokens 0.52.1 → 0.53.0

package/dist-plugin/migrateData/index.js

@@ -7,7 +7,10 @@ import {
   normalizeTheme,
   planLegacyRenames,
   versionedFileResourceServer
-} from "../chunk-6OZFXIQI.js";
+} from "../chunk-232GZGQU.js";
+import {
+  CURRENT_COMPONENT_SCHEMA_VERSION
+} from "../chunk-NE6N66EE.js";
 import {
   readLiveTokensConfig,
   resolveDataDirs
@@ -151,6 +154,7 @@ function migrateData(opts) {
   const resolvers = {
     readColorsAndType: (name) => colorsRes.readJson(name),
     readComponentConfig: (comp, name) => compRes(comp).readJson(name),
+    listComponentNames: () => comps,
     normalizeColorsAndType: (colorsAndType) => colorsAndType
   };
   const upgradedThemes = [];
@@ -230,7 +234,6 @@ function migrateData(opts) {
       for (const comp of comps) {
         const pointed = prodConfigs.get(comp);
         if (!isObject(pointed)) continue;
-        if (sameContent(pointed, defaultConfig(comp))) continue;
         componentConfigs[comp] = stripMarkers(pointed);
       }
       recoveredTheme = {
@@ -239,7 +242,11 @@ function migrateData(opts) {
         updatedAt: now,
         schemaVersion: THEME_SCHEMA_VERSION,
         colorsAndType: isObject(prodColors) ? stripMarkers(prodColors) : null,
-        componentConfigs
+        componentConfigs,
+        // The configs above are what boot just wrote (`prodConfigs`, read off
+        // the pointed files), at the current component schema — not 0, which
+        // would misdescribe them as unmigrated.
+        componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION
       };
       const slug = nextAvailableName((n) => themesRes.existingPath(n) !== null, RECOVERED_SLUG);
       recoveredThemePath = themesRes.filePath(slug);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -111,7 +111,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "npm run test:e2e:contract && npm run test:e2e:stateful",
-    "test:e2e:contract": "playwright test tests/e2e/component-render-contract.spec.ts tests/e2e/component-alias-contract.spec.ts --workers=4",
+    "test:e2e:contract": "playwright test tests/e2e/component-render-contract.spec.ts tests/e2e/component-alias-contract.spec.ts --workers=${PLAYWRIGHT_WORKERS:-4}",
     "test:e2e:stateful": "playwright test tests/e2e/live-editing.spec.ts tests/e2e/theme-workflow.spec.ts --workers=1",
     "test:e2e:components": "playwright test tests/e2e/component-render-contract.spec.ts",
     "test:e2e:ui": "playwright test --ui",
@@ -120,6 +120,7 @@
     "build:lib": "npm run build:plugin",
     "deploy:local": "bash scripts/deploy-local.sh",
     "check:no-style-imports": "node scripts/check-no-style-imports.mjs",
+    "check:no-tooling-imports": "node scripts/check-no-tooling-imports.mjs",
     "check:slot-prose": "node scripts/check-slot-prose.mjs",
     "check:overlay-portal": "node scripts/check-overlay-portal.mjs",
     "check:editor-font-isolation": "node scripts/check-editor-font-isolation.mjs",
@@ -127,13 +128,14 @@
     "check:production-is-default": "node scripts/check-production-is-default.mjs",
     "check:docs-content": "node scripts/sync-docs.mjs --check",
     "check:token-contract": "node scripts/check-token-contract.mjs",
+    "check:preset-themes": "node scripts/check-preset-themes.mjs",
     "sync:component-defaults": "node scripts/sync-component-defaults.mjs --write",
     "sync:docs": "node scripts/sync-docs.mjs --write",
-    "generate:preset-themes": "node scripts/generate-preset-themes.mjs",
+    "seed:preset-theme": "node scripts/seed-preset-theme.mjs",
     "collapse:theme": "node scripts/collapse-theme-to-default.mjs",
     "check:smoke-install": "bash scripts/smoke-install.sh",
     "check:smoke-create": "bash scripts/smoke-create.sh",
-    "prepublishOnly": "npm run check:no-style-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:token-contract && npm run check:smoke-install && npm run check:smoke-create"
+    "prepublishOnly": "npm run check:no-style-imports && npm run check:no-tooling-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:token-contract && npm run check:preset-themes && npm run check:smoke-install && npm run check:smoke-create"
   },
   "peerDependencies": {
     "@sveltejs/vite-plugin-svelte": "^7.0",

package/src/editor/component-editor/scaffolding/ComponentFileManager.svelte

@@ -5,10 +5,7 @@
 <script lang="ts">
   import { onMount, onDestroy } from 'svelte';
   import UIInfoPopover from '../../ui/UIInfoPopover.svelte';
-  import type {
-    ComponentConfigMeta,
-    LiveSource,
-  } from '../../core/themes/themeTypes';
+  import type { ComponentConfigMeta } from '../../core/themes/themeTypes';
   import { componentSourceFile } from './componentSources';
   import {
     getActiveComponentConfig,
@@ -73,7 +70,6 @@
   // Saved presets. Nothing live points at one: the component runs its working
   // buffer, and the theme it belongs to carries the copy that ships.
   let files: ComponentConfigMeta[] = $state([]);
-  let liveSource: LiveSource = $state('default');
   let openTheme: { fileName: string; name: string } = $state({
     fileName: 'default',
     name: 'Motion Proto',
@@ -94,18 +90,13 @@
   let compDirty = $derived($componentDirty[component] ?? false);
   let openIsProtected = $derived(openTheme.fileName === 'default');
   // Both rows name a document, because that is what a config belongs to now:
-  // the component runs the open theme's config (or the shipped default), and
-  // production ships the published theme's.
-  let editorDoc = $derived(liveSource === 'default' ? 'default' : openTheme.fileName);
-  let productionDoc = $derived(
-    $productionTheme
-      ? ($productionTheme.componentConfigs[component] ? $productionTheme._fileName ?? 'default' : 'default')
-      : null,
-  );
-  let editorName = $derived(liveSource === 'default' ? 'Default' : openTheme.name);
-  let productionName = $derived(
-    productionDoc === null ? '—' : productionDoc === 'default' ? 'Default' : $productionTheme?.name ?? '—',
-  );
+  // every theme carries every component by value, so the component always
+  // runs the open theme's config, and production always runs the published
+  // theme's.
+  let editorDoc = $derived(openTheme.fileName);
+  let productionDoc = $derived($productionTheme?._fileName ?? null);
+  let editorName = $derived(openTheme.name);
+  let productionName = $derived(productionDoc === null ? '—' : $productionTheme?.name ?? '—');
   // Saving writes the buffer, which the bake has not seen: the document is
   // still the published one, so only the shared signal can say the config on
   // screen is not what production runs.
@@ -123,11 +114,8 @@
     if (data) files = data.files;
   }
 
-  /** Which layer the component's live config comes from, and the theme it
-   *  belongs to. Both ride on the live read door's markers. */
+  /** The theme the component belongs to, by the open document's own markers. */
   async function refreshLive() {
-    const cfg = await getActiveComponentConfig(component);
-    if (cfg) liveSource = cfg._source ?? 'default';
     try {
       const theme = await getActiveTheme();
       if (theme) openTheme = { fileName: theme._fileName ?? 'default', name: theme.name };
@@ -186,7 +174,6 @@
       component,
       componentConfigFromState($editorState, component, openTheme.name),
     );
-    liveSource = 'working';
     markComponentSaved(component);
     bumpComponentActiveRevision();
   }
@@ -233,7 +220,6 @@
       const { _fileName, _source, ...cfg } = await loadComponentConfig(component, file.fileName);
       await writeWorkingComponentConfig(component, { ...cfg, component });
       loadComponentActive(component, cfg.aliases, cfg.config, cfg.schemaVersion ?? 0);
-      liveSource = 'working';
       bumpComponentActiveRevision();
     } catch {
       // intentional: see comment above

package/src/editor/component-editor/scaffolding/LinkedBlock.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
-  import { fade, slide } from 'svelte/transition';
+  import { fade } from 'svelte/transition';
   import TokenLayout from './TokenLayout.svelte';
+  import UIReveal from '../../ui/UIReveal.svelte';
   import LinkageChart from './LinkageChart.svelte';
   import { getEditorContext } from './editorContext';
   import type { LinkedBlockResult, LinkedGroup } from './linkedBlock';
@@ -11,7 +12,6 @@
   const reduceMotion = typeof window !== 'undefined'
     && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true;
   const fadeDur = reduceMotion ? 0 : 140;
-  const slideDur = reduceMotion ? 0 : 200;
 
   interface Props {
     component: string;
@@ -139,8 +139,8 @@
         {/if}
       </span>
     </button>
-    {#if sectionExpanded}
-      <div class="linked-grid" transition:slide|local={{ duration: slideDur }}>
+    <UIReveal open={sectionExpanded}>
+      <div class="linked-grid">
         {#each cards as card (card.row.variable)}
           {@const cardExpanded = expandedCards[card.row.variable] === true}
           {@const cardHovered = hoveredVar === card.row.variable}
@@ -176,8 +176,8 @@
                 >({card.unlinkedText})</span>
               {/if}
             </button>
-            {#if cardExpanded}
-              <div class="chart-wrap" transition:slide|local={{ duration: slideDur }}>
+            <UIReveal open={cardExpanded}>
+              <div class="chart-wrap">
                 <LinkageChart
                   contexts={card.contexts}
                   broken={card.brokenContexts}
@@ -187,11 +187,11 @@
                   onselect={handleChartSelect}
                 />
               </div>
-            {/if}
+            </UIReveal>
           </article>
         {/each}
       </div>
-    {/if}
+    </UIReveal>
   </section>
 {/if}
 

package/src/editor/core/components/adjustAliases.ts

@@ -1,4 +1,4 @@
-import { matchesKind } from './aliasKinds';
+import { matchesKind, stripSide } from './aliasKinds';
 import type { AliasDiskValue, ComponentConfig } from '../themes/themeTypes';
 
 export type AdjustKind = 'radius' | 'padding' | 'gap' | 'border-width';
@@ -52,12 +52,21 @@ const RADIUS_RUNGS = [
 /** The editor picker's 12-step subset (`UIPaddingSelector`), not the full
     `--space-*` scale: every value this engine writes must stay re-editable
     by hand in the picker. */
-const SPACE_RUNGS = [
+const SPACE_SETTABLE = [
   '--space-0', '--space-2', '--space-4', '--space-6', '--space-8', '--space-10',
   '--space-12', '--space-16', '--space-20', '--space-24', '--space-32', '--space-48',
 ];
 
-const SPACE_FAMILY = [...SPACE_RUNGS, '--space-40', '--space-64', '--space-96', '--space-128'];
+const SPACE_RUNGS = SPACE_SETTABLE;
+
+/** Content insets stop at `--space-4`. Below it the text sits against its own
+    edge, which is a deliberate choice rather than somewhere a relative
+    "tighter" should deposit you. Outer space is exempt: a 2px gap between an
+    icon and its label, or a 2px margin under a bar, is ordinary design. Both
+    rungs stay pickable by hand and settable by name. */
+const INSET_RUNGS = SPACE_SETTABLE.slice(SPACE_SETTABLE.indexOf('--space-4'));
+
+const SPACE_FAMILY = [...SPACE_SETTABLE, '--space-40', '--space-64', '--space-96', '--space-128'];
 
 const BORDER_WIDTH_RUNGS = [
   '--border-width-0', '--border-width-1', '--border-width-2', '--border-width-3',
@@ -66,48 +75,66 @@ const BORDER_WIDTH_RUNGS = [
   '--border-width-24',
 ];
 
-const LADDERS: Record<AdjustKind, { rungs: string[]; family: string[] }> = {
-  radius: { rungs: RADIUS_RUNGS, family: [...RADIUS_RUNGS, RADIUS_FULL] },
-  padding: { rungs: SPACE_RUNGS, family: SPACE_FAMILY },
-  gap: { rungs: SPACE_RUNGS, family: SPACE_FAMILY },
-  'border-width': { rungs: BORDER_WIDTH_RUNGS, family: BORDER_WIDTH_RUNGS },
+const LADDERS: Record<AdjustKind, { rungs: string[]; settable: string[]; family: string[] }> = {
+  radius: {
+    rungs: RADIUS_RUNGS,
+    settable: [...RADIUS_RUNGS, RADIUS_FULL],
+    family: [...RADIUS_RUNGS, RADIUS_FULL],
+  },
+  padding: { rungs: SPACE_RUNGS, settable: SPACE_SETTABLE, family: SPACE_FAMILY },
+  gap: { rungs: SPACE_RUNGS, settable: SPACE_SETTABLE, family: SPACE_FAMILY },
+  'border-width': {
+    rungs: BORDER_WIDTH_RUNGS,
+    settable: BORDER_WIDTH_RUNGS,
+    family: BORDER_WIDTH_RUNGS,
+  },
 };
 
 const TOKEN_NAME = /^--[a-z0-9-]+$/;
 
 type Outcome = { from: string; to: string } | { skip: SkipReason };
 
-function rungsFor(op: AdjustOp): string[] {
-  return op.kind === 'radius' && op.full ? [...RADIUS_RUNGS, RADIUS_FULL] : LADDERS[op.kind].rungs;
+/** `-margin` shares the padding kind, so the inset floor keys off the variable
+    rather than the kind. */
+function rungsFor(op: AdjustOp, variable: string): string[] {
+  if (op.kind === 'radius') return op.full ? [...RADIUS_RUNGS, RADIUS_FULL] : RADIUS_RUNGS;
+  if (op.kind === 'padding' && stripSide(variable).endsWith('-padding')) return INSET_RUNGS;
+  return LADDERS[op.kind].rungs;
 }
 
 function spaceStep(token: string): number {
   return Number(token.slice('--space-'.length));
 }
 
-/** `<=` sends an exact tie (`--space-40`, midway between 32 and 48) upward. */
-function nearestSpaceRung(token: string, rungs: string[]): number {
+/** An off-rung value has no step to count from, so landing on the first rung
+    the shift points at is itself that shift's opening step. Snapping to the
+    nearest rung instead would spend two visible steps on a one-step request.
+    Returns -1 when the ladder holds nothing in that direction. */
+function snapRung(token: string, rungs: string[], direction: number): number {
   const step = spaceStep(token);
-  let best = 0;
-  for (let i = 1; i < rungs.length; i++) {
-    if (Math.abs(spaceStep(rungs[i]) - step) <= Math.abs(spaceStep(rungs[best]) - step)) best = i;
+  if (direction > 0) return rungs.findIndex((rung) => spaceStep(rung) > step);
+  for (let index = rungs.length - 1; index >= 0; index--) {
+    if (spaceStep(rungs[index]) < step) return index;
   }
-  return best;
+  return -1;
 }
 
-function resolve(op: AdjustOp, value: AliasDiskValue): Outcome {
+function resolve(op: AdjustOp, variable: string, value: AliasDiskValue): Outcome {
   if (typeof value !== 'string' || !TOKEN_NAME.test(value)) return { skip: 'raw-value' };
   if (!LADDERS[op.kind].family.includes(value)) return { skip: 'off-ladder' };
   if (op.set !== undefined) return { from: value, to: op.set };
 
-  const rungs = rungsFor(op);
+  const rungs = rungsFor(op, variable);
   let index = rungs.indexOf(value);
+  let shift = op.shift!;
   if (index < 0) {
     if (value === RADIUS_FULL) return { skip: 'pill-preserved' };
-    index = nearestSpaceRung(value, rungs);
+    index = snapRung(value, rungs, shift);
+    if (index < 0) return { skip: 'clamped' };
+    shift -= Math.sign(shift);
   }
 
-  const wanted = index + op.shift!;
+  const wanted = index + shift;
   const landed = Math.min(Math.max(wanted, 0), rungs.length - 1);
   if (landed !== wanted && rungs[landed] === value) return { skip: 'clamped' };
   return { from: value, to: rungs[landed] };
@@ -123,7 +150,7 @@ function validateOp(op: AdjustOp, configs: Record<string, ComponentConfig>): voi
   const hasSet = op.set !== undefined;
   const hasShift = op.shift !== undefined;
   if (hasSet === hasShift) throw new Error(`A ${op.kind} op needs exactly one of "set" or "shift"`);
-  const settable = op.kind === 'radius' ? ladder.family : ladder.rungs;
+  const settable = ladder.settable;
   if (hasSet && !settable.includes(op.set!)) {
     throw new Error(`"${op.set}" is not on the ${op.kind} ladder`);
   }
@@ -161,7 +188,7 @@ export function adjustAliases(
 
       for (const [variable, value] of Object.entries(config.aliases)) {
         if (!matchesKind(variable, op.kind)) continue;
-        const outcome = resolve(op, value);
+        const outcome = resolve(op, variable, value);
         if ('skip' in outcome) {
           reportFor(component).skips.push({ variable, value, reason: outcome.skip });
           continue;

package/src/editor/core/components/aliasKinds.ts

@@ -64,10 +64,15 @@ const MATCHER_BY_KIND = Object.fromEntries(
 
 const SIDE_SUFFIXES = ['-top', '-right', '-bottom', '-left'];
 
+/** Drops a per-side suffix so callers can test the parent name. */
+export function stripSide(variable: string): string {
+  const side = SIDE_SUFFIXES.find((s) => variable.endsWith(s));
+  return side ? variable.slice(0, -side.length) : variable;
+}
+
 /** Side-aware kind test. Per-side paddings (`--card-default-body-padding-top`)
     are written by UIPaddingSelector and never declared as editor tokens, so
     `rawKind` never meets one; the CLI does, and they belong with their parent. */
 export function matchesKind(variable: string, kind: TokenKind): boolean {
-  const side = SIDE_SUFFIXES.find((s) => variable.endsWith(s));
-  return MATCHER_BY_KIND[kind](side ? variable.slice(0, -side.length) : variable);
+  return MATCHER_BY_KIND[kind](stripSide(variable));
 }

package/src/editor/core/components/componentConfigService.ts

@@ -58,7 +58,7 @@ export const deleteComponentConfig = (component: string, fileName: string): Prom
   resourceFor(component).remove(fileName);
 
 /** The config the component is running: the buffer, else the open theme's
- *  copy, else the component default. `_source` says which. */
+ *  copy (every theme carries every component by value). `_source` says which. */
 export const getActiveComponentConfig = (component: string): Promise<ComponentConfig | null> =>
   resourceFor(component).getActive();
 

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

@@ -28,6 +28,7 @@ import {
   CURRENT_COMPONENT_SCHEMA_VERSION,
   runMigrations,
 } from '../themes/migrations';
+import { migrateComponentConfig } from '../themes/migrateComponentConfig';
 import { renamePrimaryPaletteKey } from '../themes/migrations/2026-05-13-primary-to-brand';
 import {
   renameBackgroundPaletteKey,
@@ -220,202 +221,11 @@ export {
 // `fromVersion >= file.schemaVersion`, then `splitAliasesAndConfig` routes
 // literal-valued knobs (per `KNOWN_COMPONENT_CONFIG_KEYS`) into the config
 // bucket and wraps the remainder as `CssVarRef` discriminated unions.
-
-/**
- * Migrate a disk-shape alias bag through the registered migration runner.
- *
- * The runner is string-typed by contract (most migrations only do
- * key/value string rewrites). Object-valued entries — currently just
- * inline `{ kind: 'gradient', value: ... }` payloads — pass through
- * untouched: we split the bag into string/object subsets, run the runner
- * on the string subset, then merge.
- *
- * For sectiondivider's legacy 7-flat-token gradients we run a synthesis
- * step BEFORE the migration runner that would strip those tokens. The
- * synthesized gradient object lands in the object subset and survives
- * the stripping pass.
- */
-function migrateComponentAliases(
-  component: string,
-  aliasesIn: Record<string, AliasDiskValue>,
-  rawConfig: Record<string, unknown> | undefined,
-  fileVersion: number,
-): { aliases: Record<string, AliasDiskValue>; config: Record<string, unknown> } {
-  const stringPart: Record<string, string> = {};
-  const objectPart: Record<string, AliasDiskValue> = {};
-  for (const [k, v] of Object.entries(aliasesIn)) {
-    if (typeof v === 'string') stringPart[k] = v;
-    else objectPart[k] = v;
-  }
-  // String-valued config entries join the migration input so a migration can
-  // rename or relocate them. After migration the bag flows through
-  // `splitAliasesAndConfig` which routes KNOWN keys back to config and the
-  // rest to aliases — this is what lets a migration *move* a key from the
-  // config bucket to the aliases bucket by also removing it from KNOWN.
-  // Config wins over an aliases-bucket collision on the same key: the legacy
-  // single-bucket → split-bucket move preserved "explicit config field beats
-  // legacy alias-bucketed value", and that contract still holds.
-  // Non-string config values (rare; reserved for future structured payloads)
-  // pass through untouched.
-  const configOut: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(rawConfig ?? {})) {
-    if (typeof v === 'string') stringPart[k] = v;
-    else configOut[k] = v;
-  }
-  if (component === 'sectiondivider') {
-    synthesizeSectionDividerGradients(stringPart, objectPart);
-  }
-  const migratedString = runMigrations('component-config', fileVersion, stringPart, { component });
-  const migratedObject = component === 'sectiondivider'
-    ? renameSectionDividerObjectSlots(objectPart)
-    : objectPart;
-  return {
-    aliases: { ...migratedString, ...migratedObject },
-    config: configOut,
-  };
-}
-
-/**
- * v8→v9 companion to `componentMigration_2026_05_20_sectiondividerSlimVariants`:
- * the structured background payload is reshaped from six color families →
- * three size variants (lg/md/sm). Canvas's gradient is taken as the canonical
- * seed and fanned across all three new variants; other families' gradients
- * are dropped. Idempotent — keys already at the final shape pass through.
- *
- * Sources accepted (in priority order, first-found wins for canvas's slot):
- *   --sectiondivider-canvas-background  (current/in-progress shape)
- *   --sectiondivider-canvas-gradient    (v7-era shape)
- *   --sectiondivider-color-canvas-background  (intermediate shape that landed
- *                                              briefly during the color-prop pivot)
- *
- * The migration runner only sees string keys, so this object-shape rename
- * has to live alongside the runner call.
- */
-const FAMILIES = ['canvas', 'neutral', 'alternate', 'primary', 'accent', 'special'] as const;
-const SIZE_VARIANTS = ['lg', 'md', 'sm'] as const;
-function renameSectionDividerObjectSlots(
-  objectPart: Record<string, AliasDiskValue>,
-): Record<string, AliasDiskValue> {
-  // Find canvas's gradient under any historical key shape.
-  const canvasSourceKeys = [
-    '--sectiondivider-canvas-background',
-    '--sectiondivider-canvas-gradient',
-    '--sectiondivider-color-canvas-background',
-  ];
-  let canvasGradient: AliasDiskValue | undefined;
-  for (const key of canvasSourceKeys) {
-    if (objectPart[key] !== undefined) {
-      canvasGradient = objectPart[key];
-      break;
-    }
-  }
-
-  // If we found a canvas gradient (any era), fan it into the three new
-  // per-variant background slots and drop every other family's gradient.
-  // If no canvas gradient is found, pass through non-family keys verbatim
-  // so non-migration data (theme tokens, other components) isn't touched.
-  const out: Record<string, AliasDiskValue> = {};
-  for (const [key, value] of Object.entries(objectPart)) {
-    // Skip any sectiondivider per-family gradient; the canvas fan-out emits
-    // the canonical set below.
-    let isFamilyGradient = false;
-    for (const f of FAMILIES) {
-      if (
-        key === `--sectiondivider-${f}-background`
-        || key === `--sectiondivider-${f}-gradient`
-        || key === `--sectiondivider-color-${f}-background`
-      ) {
-        isFamilyGradient = true;
-        break;
-      }
-    }
-    // Pass through anything that's already at the final lg/md/sm shape so
-    // re-running the migration is idempotent.
-    if (isFamilyGradient) continue;
-    out[key] = value;
-  }
-  if (canvasGradient !== undefined) {
-    for (const v of SIZE_VARIANTS) {
-      out[`--sectiondivider-${v}-background`] = canvasGradient;
-    }
-  }
-  return out;
-}
-
-/** SectionDivider variants that ship gradient aliases. */
-const SECTIONDIVIDER_VARIANTS = ['canvas', 'neutral', 'alternate', 'primary', 'accent', 'special'] as const;
-
-/**
- * Collapse legacy 7-flat-token gradients (`{angle, stop-{1,2,3}-{color,position}}`)
- * for each sectiondivider variant into one structured gradient alias at
- * `--sectiondivider-{v}-gradient`. The flat tokens stay in `stringPart`
- * for the migration runner to strip; the structured payload joins
- * `objectPart` so the merge produces the new shape.
- *
- * Skips variants that already declare a gradient alias (object form) so
- * round-tripping doesn't overwrite user edits.
- */
-function synthesizeSectionDividerGradients(
-  stringPart: Record<string, string>,
-  objectPart: Record<string, AliasDiskValue>,
-): void {
-  const GRADIENT_ANGLE_TOKENS: Record<string, number> = {
-    '--gradient-angle-horizontal': 90,
-    '--gradient-angle-vertical': 180,
-    '--gradient-angle-diagonal': 135,
-    '--gradient-angle-counter-diagonal': 45,
-  };
-  const GRADIENT_STOP_POSITIONS: Record<string, number> = {
-    '--gradient-stop-start': 0,
-    '--gradient-stop-mid': 50,
-    '--gradient-stop-end': 100,
-  };
-  const parseAngle = (raw: string | undefined): number => {
-    if (!raw) return 135;
-    if (raw.startsWith('--')) return GRADIENT_ANGLE_TOKENS[raw] ?? 135;
-    const m = raw.match(/^(-?\d+(?:\.\d+)?)\s*deg$/i);
-    return m ? parseFloat(m[1]) : 135;
-  };
-  const parsePosition = (raw: string | undefined, fallback: number): number => {
-    if (!raw) return fallback;
-    if (raw.startsWith('--')) return GRADIENT_STOP_POSITIONS[raw] ?? fallback;
-    const m = raw.match(/^(-?\d+(?:\.\d+)?)\s*%$/);
-    return m ? parseFloat(m[1]) : fallback;
-  };
-  const parseStopColor = (raw: string | undefined): { color: string; opacity?: number } | null => {
-    if (!raw) return null;
-    if (raw.startsWith('--')) return { color: raw };
-    const mix = raw.match(/^color-mix\(\s*in\s+srgb\s*,\s*var\((--[a-z0-9-]+)\)\s+([\d.]+)%\s*,\s*transparent\s*\)$/i);
-    if (mix) return { color: mix[1], opacity: parseFloat(mix[2]) };
-    return null;
-  };
-  for (const v of SECTIONDIVIDER_VARIANTS) {
-    const slot = `--sectiondivider-${v}-gradient`;
-    if (slot in objectPart) continue;
-    const angleKey = `${slot}-angle`;
-    const has1 = stringPart[`${slot}-stop-1-color`] !== undefined;
-    const has2 = stringPart[`${slot}-stop-2-color`] !== undefined;
-    const has3 = stringPart[`${slot}-stop-3-color`] !== undefined;
-    if (!has1 && !has2 && !has3) continue;
-    const stops: { position: number; color: string; opacity?: number }[] = [];
-    const positionDefaults = [0, 50, 100];
-    for (let i = 1; i <= 3; i++) {
-      const c = parseStopColor(stringPart[`${slot}-stop-${i}-color`]);
-      if (!c) continue;
-      const pos = parsePosition(stringPart[`${slot}-stop-${i}-position`], positionDefaults[i - 1]);
-      stops.push({ position: pos, color: c.color, ...(c.opacity !== undefined ? { opacity: c.opacity } : {}) });
-    }
-    if (stops.length < 2) continue;
-    objectPart[slot] = {
-      kind: 'gradient',
-      value: {
-        type: 'linear',
-        angle: parseAngle(stringPart[angleKey]),
-        stops,
-      },
-    };
-  }
-}
+//
+// The migration itself — `migrateComponentConfig`, plus its sectiondivider
+// gradient helpers — lives in `../themes/migrateComponentConfig` so the
+// server (`normalizeTheme`) can run the same pass over an embedded theme
+// config instead of reading it raw.
 
 /**
  * Disk-shape → in-memory split. Routes legacy single-bucket aliases that
@@ -459,7 +269,7 @@ export function toComponentSlice(
   config?: Record<string, unknown>,
   schemaVersion: number = 0,
 ): { aliases: Record<string, CssVarRef>; config: Record<string, unknown> } {
-  const migrated = migrateComponentAliases(component, aliases, config, schemaVersion);
+  const migrated = migrateComponentConfig(component, aliases, config, schemaVersion);
   return splitAliasesAndConfig(migrated.aliases, migrated.config);
 }
 

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

@@ -1,4 +1,5 @@
 import type { PaletteConfig, FontSource, FontStack } from '../themes/themeTypes';
+import type { GradientStop, GradientValue } from '../themes/parsers/gradient';
 import type { HarmonyAxis } from '../palettes/colorHarmony';
 
 export interface ShadowGlobals {
@@ -46,20 +47,9 @@ export interface ColumnsState {
  *    round-trip when the user toggles back to a real gradient. */
 export type GradientType = 'linear' | 'radial' | 'solid' | 'none';
 
-export interface GradientTokenStop {
-  /** 0–100 percentage along the gradient axis. */
-  position: number;
-  /** CSS variable name the stop resolves through (e.g. '--color-brand-500'). */
-  color: string;
-  /** When `false`, this stop is an explicit off-palette override: the stop
-   *  picker opens to any color (not family-filtered), and the stop is skipped
-   *  by family-swap rewrites so its color survives a variant family change.
-   *  Defaults to true (follow family) on read; absence is the same as `true`.
-   *  Only meaningful for gradients rendered inside a family-aware context. */
-  monochrome?: boolean;
-  /** 0–100 alpha applied to the stop's color. Defaults to 100 (fully opaque). */
-  opacity?: number;
-}
+/** One stop of a gradient. Defined by `themes/parsers/gradient`, which owns
+ *  the shape so the CSS form and the persisted form cannot drift apart. */
+export type GradientTokenStop = GradientStop;
 
 export interface GradientToken {
   /** Output CSS variable, e.g. '--gradient-1'. */
@@ -83,22 +73,11 @@ export interface GradientToken {
 }
 
 /** Structured gradient payload carried inline on a component alias.
- *  Mirrors GradientToken minus `variable` (the alias key itself is the
- *  binding). Used when a component owns a per-instance gradient that
- *  doesn't share the theme-level `--gradient-N` library. */
-export interface GradientAliasValue {
-  type: GradientType;
-  angle: number;
-  /** See GradientToken.radius. */
-  radius?: number;
-  /** See GradientToken.centerX. */
-  centerX?: number;
-  /** See GradientToken.aspectX. */
-  aspectX?: number;
-  /** See GradientToken.aspectY. */
-  aspectY?: number;
-  stops: GradientTokenStop[];
-}
+ *  `GradientToken` minus `variable` (the alias key itself is the binding).
+ *  Used when a component owns a per-instance gradient that doesn't share the
+ *  theme-level `--gradient-N` library. Defined by `themes/parsers/gradient`,
+ *  the module that serializes and parses this shape. */
+export type GradientAliasValue = GradientValue;
 
 export type CssVarRef =
   /** An alias to a design token. `opacity` is an optional integer percent set