@motion-proto/live-tokens 0.1.1 → 0.3.2

package/src/lib/migrations/2026-04-24-legacy-keys-and-bg-to-canvas.ts

@@ -0,0 +1,71 @@
+import type { Migration } from './index';
+
+/**
+ * Theme migration (2026-04-24): rename legacy CSS-var keys to their
+ * current names, drop a few orphaned tokens, and convert the entire
+ * `-bg`/`-bg-*` family to the `-canvas` namespace.
+ *
+ * Old themes saved before the rename keep loading; the migrated bag flows
+ * through the normal domain routing.
+ */
+const LEGACY_KEY_RENAMES: Record<string, string | null> = {
+  '--empty': '--page-bg',
+  '--empty-attachment': '--page-bg-attachment',
+  // Orphan exports dropped from tokens.css; no new home — silently discard.
+  '--border-neutral': null,
+  // Shadow cleanup: these five tokens were removed (low/zero consumers,
+  // aesthetic drift). Dialog migrated onto --shadow-2xl; focus rings moved
+  // to their own --ring-focus-* namespace, which themes don't carry by
+  // default — tokens.css provides the canonical values.
+  '--shadow-app': null,
+  '--shadow-card': null,
+  '--shadow-overlay': null,
+  '--shadow-focus': null,
+  '--shadow-glow-green': null,
+};
+
+// bg → canvas: rename every key in the --color-bg-*, --surface-bg(-*)?,
+// --border-bg(-*)?, --text-bg(-*)? families to their canvas equivalents.
+// Pattern match (rather than static entries in LEGACY_KEY_RENAMES) because
+// the families carry ~28 keys between them and listing each is noise.
+const BG_TO_CANVAS_PREFIXES = ['--color-bg-', '--surface-bg', '--border-bg', '--text-bg'] as const;
+
+function migrateBgToCanvas(rawVars: Record<string, string>): void {
+  for (const oldKey of Object.keys(rawVars)) {
+    for (const prefix of BG_TO_CANVAS_PREFIXES) {
+      if (!oldKey.startsWith(prefix)) continue;
+      // Only the -bg boundary should swap; don't accidentally rename
+      // --text-bgthing or similar.
+      const suffix = oldKey.slice(prefix.length);
+      if (suffix && !suffix.startsWith('-')) continue;
+      const newKey = prefix.replace('-bg', '-canvas') + suffix;
+      if (newKey === oldKey) continue;
+      const value = rawVars[oldKey];
+      delete rawVars[oldKey];
+      if (!(newKey in rawVars)) rawVars[newKey] = value;
+      break;
+    }
+  }
+}
+
+function migrateLegacyKeys(rawVars: Record<string, string>): void {
+  for (const [oldKey, newKey] of Object.entries(LEGACY_KEY_RENAMES)) {
+    if (!(oldKey in rawVars)) continue;
+    const value = rawVars[oldKey];
+    delete rawVars[oldKey];
+    if (newKey && !(newKey in rawVars)) rawVars[newKey] = value;
+  }
+  migrateBgToCanvas(rawVars);
+}
+
+export const themeMigration_2026_04_24_legacyKeysAndBgToCanvas: Migration = {
+  id: '2026-04-24-legacy-keys-and-bg-to-canvas',
+  fromVersion: 0,
+  toVersion: 1,
+  appliesTo: 'theme',
+  apply(rawVars) {
+    const out = { ...rawVars };
+    migrateLegacyKeys(out);
+    return out;
+  },
+};

package/src/lib/migrations/2026-04-27-segmentedcontrol-disabled-flatten.ts

@@ -0,0 +1,43 @@
+import type { Migration } from './index';
+
+/**
+ * Component-config migration (2026-04-27, segmentedcontrol only): the
+ * disabled component state used to be modeled as an interaction state on
+ * the default option (`--segmentedcontrol-option-disabled-*`); it's now
+ * its own top-level component state (`--segmentedcontrol-disabled-*`).
+ *
+ * Selected-disabled was briefly introduced as a state then removed — a
+ * disabled control can't have a selected option. Selected-hover was also
+ * briefly introduced then removed when the editor flattened to a single
+ * 4-state list (default/selected/hover/disabled); the selected pill now
+ * looks the same regardless of pointer state. Drop the legacy keys on load.
+ */
+const OPTION_DISABLED_PREFIX = '--segmentedcontrol-option-disabled-';
+const DISABLED_PREFIX = '--segmentedcontrol-disabled-';
+const SELECTED_DISABLED_PREFIX = '--segmentedcontrol-selected-disabled-';
+const SELECTED_HOVER_PREFIX = '--segmentedcontrol-selected-hover-';
+
+export const componentMigration_2026_04_27_segmentedcontrolDisabledFlatten: Migration = {
+  id: '2026-04-27-segmentedcontrol-disabled-flatten',
+  fromVersion: 1,
+  toVersion: 2,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    if (meta.component !== 'segmentedcontrol') return { ...rawVars };
+    const out: Record<string, string> = {};
+    for (const [oldKey, value] of Object.entries(rawVars)) {
+      let key = oldKey;
+      // Drop short-lived selected-disabled tokens (impossible state).
+      if (key.startsWith(SELECTED_DISABLED_PREFIX)) continue;
+      // Drop short-lived selected-hover tokens (selected pill no longer has
+      // a hover variation).
+      if (key.startsWith(SELECTED_HOVER_PREFIX)) continue;
+      // Move option-disabled-* tokens to disabled-* (component-state level).
+      if (key.startsWith(OPTION_DISABLED_PREFIX)) {
+        key = DISABLED_PREFIX + key.slice(OPTION_DISABLED_PREFIX.length);
+      }
+      if (!(key in out)) out[key] = value;
+    }
+    return out;
+  },
+};

package/src/lib/migrations/2026-05-08-collapsiblesection-frame-and-cleanup.ts

@@ -0,0 +1,68 @@
+import type { Migration } from './index';
+
+/**
+ * Component-config migration (2026-05-08, collapsiblesection only):
+ * variant chrome was reorganised so each variant only owns the tokens it can
+ * actually paint. Three changes:
+ *
+ * 1. Container's outer chrome moved into a single `frame` group. The old
+ *    default-state border / border-width / radius drove header chrome at v3;
+ *    they now drive the always-on frame instead. We copy those values across
+ *    so users keep their tuned border / radius. Surface is also copied so the
+ *    box's background reads identically — the header strip can still be tinted
+ *    on hover via the surviving default-surface.
+ *
+ * 2. Per-state border tokens that no longer paint anything are dropped:
+ *    - chromeless border / border-width / radius for every state
+ *    - container hover/active border / border-width / radius
+ *    - divider radius for every state (divider keeps border / border-width
+ *      since they paint the bottom rule per state)
+ *
+ * 3. The expanded panel only carries padding (chromeless/divider) or
+ *    surface + padding (container). Drop the rest.
+ */
+const PFX = '--collapsiblesection-';
+
+export const componentMigration_2026_05_08_collapsiblesectionFrameAndCleanup: Migration = {
+  id: '2026-05-08-collapsiblesection-frame-and-cleanup',
+  fromVersion: 3,
+  toVersion: 4,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    if (meta.component !== 'collapsiblesection') return { ...rawVars };
+    const out: Record<string, string> = {};
+
+    // First pass: seed container-frame-* from container-default-* so user
+    // values for the (former-header, now-frame) chrome are preserved.
+    for (const prop of ['surface', 'border', 'border-width', 'radius'] as const) {
+      const src = `${PFX}container-default-${prop}`;
+      if (src in rawVars) {
+        out[`${PFX}container-frame-${prop}`] = rawVars[src];
+      }
+    }
+
+    for (const [key, value] of Object.entries(rawVars)) {
+      // Drop chromeless per-state border / border-width / radius (no chrome).
+      if (/^--collapsiblesection-chromeless-(default|hover|active)-(border|border-width|radius)$/.test(key)) continue;
+
+      // Drop container hover/active border / border-width / radius (frame owns these now).
+      if (/^--collapsiblesection-container-(hover|active)-(border|border-width|radius)$/.test(key)) continue;
+
+      // Drop container default-state border / border-width / radius (already
+      // copied above into frame-*; the header strip no longer paints them).
+      if (/^--collapsiblesection-container-default-(border|border-width|radius)$/.test(key)) continue;
+
+      // Drop divider per-state radius (divider has no rounded corners).
+      if (/^--collapsiblesection-divider-(default|hover|active)-radius$/.test(key)) continue;
+
+      // Drop expanded border / border-width / radius for every variant.
+      if (/^--collapsiblesection-(chromeless|divider|container)-expanded-(border|border-width|radius)$/.test(key)) continue;
+
+      // Drop expanded surface for chromeless / divider (only container keeps it).
+      if (/^--collapsiblesection-(chromeless|divider)-expanded-surface$/.test(key)) continue;
+
+      if (!(key in out)) out[key] = value;
+    }
+    return out;
+  },
+};

package/src/lib/migrations/2026-05-08-collapsiblesection-variant-namespace.ts

@@ -0,0 +1,35 @@
+import type { Migration } from './index';
+
+/**
+ * Component-config migration (2026-05-08, collapsiblesection only): the
+ * component grew Cloudscape-style variants (chromeless / divider / container).
+ * Existing tokens were unscoped — `--collapsiblesection-{state}-*` and
+ * `--collapsiblesection-expanded-*`. They map onto the new `container` variant
+ * since that preserves the previous chromed appearance; chromeless and divider
+ * fall through to the component's CSS defaults.
+ */
+const PREFIX = '--collapsiblesection-';
+const STATE_NAMES = new Set(['default', 'hover', 'active', 'expanded']);
+
+export const componentMigration_2026_05_08_collapsiblesectionVariantNamespace: Migration = {
+  id: '2026-05-08-collapsiblesection-variant-namespace',
+  fromVersion: 2,
+  toVersion: 3,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    if (meta.component !== 'collapsiblesection') return { ...rawVars };
+    const out: Record<string, string> = {};
+    for (const [oldKey, value] of Object.entries(rawVars)) {
+      let key = oldKey;
+      if (key.startsWith(PREFIX)) {
+        const tail = key.slice(PREFIX.length);
+        const firstSegment = tail.split('-', 1)[0];
+        if (STATE_NAMES.has(firstSegment)) {
+          key = `${PREFIX}container-${tail}`;
+        }
+      }
+      if (!(key in out)) out[key] = value;
+    }
+    return out;
+  },
+};

package/src/lib/migrations/2026-05-10-sectiondivider-gradient-stops.ts

@@ -0,0 +1,50 @@
+import type { Migration } from './index';
+
+/**
+ * Component-config migration (2026-05-10, sectiondivider only):
+ * the per-variant gradient was 4 fixed-position color stops with a hard-coded
+ * 135deg angle. It now exposes angle + 3× (color + position). User-tuned colors
+ * from the old stops are preserved (1 → 1-color, 2 → 2-color, 4 → 3-color);
+ * stop 3's color is dropped because the new shape only has three slots.
+ * Angle defaults to 135deg and positions to 0%/50%/100% — the same effect the
+ * old hard-coded `linear-gradient(135deg, ... 0%, ... 30%, ... 60%, ... 100%)`
+ * approximated.
+ */
+const PFX = '--sectiondivider-';
+const VARIANTS = ['canvas', 'neutral', 'alternate', 'primary', 'accent', 'special'] as const;
+const OLD_STOP_RE = /^--sectiondivider-(canvas|neutral|alternate|primary|accent|special)-gradient-stop-\d+$/;
+
+export const componentMigration_2026_05_10_sectiondividerGradientStops: Migration = {
+  id: '2026-05-10-sectiondivider-gradient-stops',
+  fromVersion: 4,
+  toVersion: 5,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    if (meta.component !== 'sectiondivider') return { ...rawVars };
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      if (OLD_STOP_RE.test(key)) continue;
+      out[key] = value;
+    }
+    // Idempotent: only fill in keys that the file doesn't already carry.
+    // `default.json` is unstamped (v0) and re-runs every load, so seeding
+    // unconditionally would clobber user-tuned values on configs already on
+    // the new shape.
+    const setIfMissing = (key: string, fallback: string) => {
+      if (!(key in out)) out[key] = fallback;
+    };
+    for (const v of VARIANTS) {
+      const old1 = rawVars[`${PFX}${v}-gradient-stop-1`];
+      const old2 = rawVars[`${PFX}${v}-gradient-stop-2`];
+      const old4 = rawVars[`${PFX}${v}-gradient-stop-4`];
+      setIfMissing(`${PFX}${v}-gradient-angle`, '--gradient-angle-diagonal');
+      setIfMissing(`${PFX}${v}-gradient-stop-1-color`, old1 ?? `--surface-${v}-highest`);
+      setIfMissing(`${PFX}${v}-gradient-stop-1-position`, '--gradient-stop-start');
+      setIfMissing(`${PFX}${v}-gradient-stop-2-color`, old2 ?? `--surface-${v}-higher`);
+      setIfMissing(`${PFX}${v}-gradient-stop-2-position`, '--gradient-stop-mid');
+      setIfMissing(`${PFX}${v}-gradient-stop-3-color`, old4 ?? `--surface-${v}`);
+      setIfMissing(`${PFX}${v}-gradient-stop-3-position`, '--gradient-stop-end');
+    }
+    return out;
+  },
+};

package/src/lib/migrations/2026-05-13-primary-to-brand.ts

@@ -0,0 +1,90 @@
+import type { Migration } from './index';
+
+/**
+ * 2026-05-13: rename the `primary` color family to `brand`.
+ *
+ * The word "primary" was overloaded — both a color-family slot (alongside
+ * info/success/danger/etc.) AND the top of the neutral text-emphasis ramp
+ * (`--text-primary` / `--text-secondary` / `--text-tertiary`). Tokens like
+ * `--text-primary-color` only existed because `--text-primary` was already
+ * taken by neutral. Renaming the family to `brand` dissolves the collision:
+ *
+ *   --color-primary-{step}    → --color-brand-{step}
+ *   --surface-primary[-step]  → --surface-brand[-step]
+ *   --border-primary[-step]   → --border-brand[-step]
+ *   --text-primary-color      → --text-brand
+ *   --text-primary-{step}     → --text-brand-{step}   (step in secondary|tertiary|muted|disabled)
+ *
+ * The neutral text ramp (`--text-primary`, `--text-secondary`, …) is **left
+ * untouched** — it's a different namespace that just happens to share the
+ * word. The match list below enumerates the brand-family names explicitly so
+ * a substring-on-`primary` mistake can't clobber neutral text or unrelated
+ * tokens like `--button-primary-*` (component variant, not family).
+ */
+
+const PALETTE_STEPS = ['100','200','300','400','500','600','700','800','850','900','950'] as const;
+const SURFACE_SUFFIXES = ['lowest','lower','low','high','higher','highest'] as const;
+const BORDER_SUFFIXES = ['faint','subtle','medium','strong'] as const;
+const TEXT_SUFFIXES = ['secondary','tertiary','muted','disabled'] as const;
+
+const RENAME_MAP: Record<string, string> = (() => {
+  const m: Record<string, string> = {};
+  for (const step of PALETTE_STEPS) m[`--color-primary-${step}`] = `--color-brand-${step}`;
+  m['--surface-primary'] = '--surface-brand';
+  for (const suf of SURFACE_SUFFIXES) m[`--surface-primary-${suf}`] = `--surface-brand-${suf}`;
+  m['--border-primary'] = '--border-brand';
+  for (const suf of BORDER_SUFFIXES) m[`--border-primary-${suf}`] = `--border-brand-${suf}`;
+  m['--text-primary-color'] = '--text-brand';
+  for (const suf of TEXT_SUFFIXES) m[`--text-primary-${suf}`] = `--text-brand-${suf}`;
+  return m;
+})();
+
+function renameToken(name: string): string {
+  return RENAME_MAP[name] ?? name;
+}
+
+/** Rewrite keys only — used for theme cssVariables (values are hex). */
+function renameKeys(rawVars: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(rawVars)) {
+    out[renameToken(k)] = v;
+  }
+  return out;
+}
+
+/** Rewrite both keys and values — used for component-config aliases. */
+function renameKeysAndValues(rawVars: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(rawVars)) {
+    out[renameToken(k)] = renameToken(v);
+  }
+  return out;
+}
+
+export const themeMigration_2026_05_13_primaryToBrand: Migration = {
+  id: '2026-05-13-primary-to-brand-theme',
+  fromVersion: 1,
+  toVersion: 2,
+  appliesTo: 'theme',
+  apply: renameKeys,
+};
+
+export const componentMigration_2026_05_13_primaryToBrand: Migration = {
+  id: '2026-05-13-primary-to-brand-component',
+  fromVersion: 5,
+  toVersion: 6,
+  appliesTo: 'component-config',
+  apply: renameKeysAndValues,
+};
+
+/**
+ * Helper for loadFromFile: rename `theme.editorConfigs.Primary` → `Brand`.
+ * Lives here (with the rest of the rename) instead of in the migration
+ * framework because the framework's contract is `Record<string, string>` —
+ * editorConfigs is a structured palette-config map and can't pass through it.
+ */
+export function renamePrimaryPaletteKey<T>(editorConfigs: Record<string, T>): Record<string, T> {
+  if (!('Primary' in editorConfigs) || 'Brand' in editorConfigs) return editorConfigs;
+  const { Primary, ...rest } = editorConfigs;
+  return { ...rest, Brand: Primary };
+}

package/src/lib/migrations/index.ts

@@ -0,0 +1,93 @@
+/**
+ * Schema-versioned migration runner.
+ *
+ * Each migration lives in its own dated file (`YYYY-MM-DD-<short-name>.ts`)
+ * and exports a `Migration` object. Saved theme / component-config files
+ * carry a `schemaVersion` stamp; on load, only migrations with
+ * `fromVersion >= file.schemaVersion` are applied — once every on-disk file
+ * is past a given version, that migration's bookkeeping is dead code and
+ * the file can be deleted.
+ *
+ * Theme and component-config have INDEPENDENT version sequences. Every
+ * theme migration steps the theme version; every component-config migration
+ * steps the component-config version. There is no shared 'both' kind.
+ */
+export interface MigrationMeta {
+  /** Component id when the migration runs in component-config context. */
+  component?: string;
+}
+
+export interface Migration {
+  /** Unique identifier; convention: `YYYY-MM-DD-<short-name>`. */
+  id: string;
+  /** Pre-condition version — files at or below this are unmigrated for this step. */
+  fromVersion: number;
+  /** Post-condition version — files past this no longer need this migration. */
+  toVersion: number;
+  /** Which storage flavor this applies to. */
+  appliesTo: 'theme' | 'component-config';
+  /** Pure transform on the raw vars map. May add, remove, or rename keys. */
+  apply(rawVars: Record<string, string>, meta: MigrationMeta): Record<string, string>;
+}
+
+import { themeMigration_2026_04_24_legacyKeysAndBgToCanvas } from './2026-04-24-legacy-keys-and-bg-to-canvas';
+import { componentMigration_2026_04_24_prefixAndSuffixRenames } from './2026-04-24-component-prefix-and-suffix-renames';
+import { componentMigration_2026_04_27_segmentedcontrolDisabledFlatten } from './2026-04-27-segmentedcontrol-disabled-flatten';
+import { componentMigration_2026_05_08_collapsiblesectionVariantNamespace } from './2026-05-08-collapsiblesection-variant-namespace';
+import { componentMigration_2026_05_08_collapsiblesectionFrameAndCleanup } from './2026-05-08-collapsiblesection-frame-and-cleanup';
+import { componentMigration_2026_05_10_sectiondividerGradientStops } from './2026-05-10-sectiondivider-gradient-stops';
+import {
+  themeMigration_2026_05_13_primaryToBrand,
+  componentMigration_2026_05_13_primaryToBrand,
+} from './2026-05-13-primary-to-brand';
+
+/**
+ * Registered migrations. Order in this array does not matter — the runner
+ * filters by `appliesTo` and sorts by `toVersion` before applying.
+ */
+export const MIGRATIONS: Migration[] = [
+  themeMigration_2026_04_24_legacyKeysAndBgToCanvas,
+  themeMigration_2026_05_13_primaryToBrand,
+  componentMigration_2026_04_24_prefixAndSuffixRenames,
+  componentMigration_2026_04_27_segmentedcontrolDisabledFlatten,
+  componentMigration_2026_05_08_collapsiblesectionVariantNamespace,
+  componentMigration_2026_05_08_collapsiblesectionFrameAndCleanup,
+  componentMigration_2026_05_10_sectiondividerGradientStops,
+  componentMigration_2026_05_13_primaryToBrand,
+];
+
+function countFor(kind: 'theme' | 'component-config'): number {
+  return MIGRATIONS.filter((m) => m.appliesTo === kind).length;
+}
+
+/**
+ * Current schema versions. Computed from the registered migrations so that
+ * adding a new dated migration file (and importing it above) auto-bumps the
+ * relevant constant.
+ */
+export const CURRENT_THEME_SCHEMA_VERSION = countFor('theme');
+export const CURRENT_COMPONENT_SCHEMA_VERSION = countFor('component-config');
+
+/**
+ * Apply all migrations for a given kind whose fromVersion is at or above the
+ * file's stamped version. Pure: returns a new map; never mutates the input.
+ *
+ * The "fromVersion >= fileVersion" filter is what gives this its TTL: once
+ * every saved file has been resaved past version N, the migration with
+ * fromVersion=N can be deleted without affecting any load path.
+ */
+export function runMigrations(
+  kind: 'theme' | 'component-config',
+  fileVersion: number,
+  rawVars: Record<string, string>,
+  meta: MigrationMeta = {},
+): Record<string, string> {
+  const applicable = MIGRATIONS
+    .filter((m) => m.appliesTo === kind && m.fromVersion >= fileVersion)
+    .sort((a, b) => a.toVersion - b.toVersion);
+  let out = { ...rawVars };
+  for (const m of applicable) {
+    out = m.apply(out, meta);
+  }
+  return out;
+}