@motion-proto/live-tokens 0.7.1 → 0.9.0

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

@@ -0,0 +1,99 @@
+/**
+ * Family-aware token rewrites.
+ *
+ * Color tokens encode their palette family as a hyphen segment in the slug
+ * (e.g. `--border-canvas-strong` → `canvas`, `--surface-accent-low` →
+ * `accent`). Text tokens are special-cased: `--text-primary` carries no
+ * family, `--text-{family}` and `--text-{family}-{step}` do, and `--text-{step}`
+ * resolves to the neutral text scale.
+ *
+ * These helpers let editor flows (variant family swap, per-stop monochrome
+ * snap) rewrite a token slug without re-implementing the parser each time.
+ */
+
+export const KNOWN_FAMILIES = [
+  'neutral', 'alternate', 'canvas', 'brand',
+  'accent', 'special', 'success', 'warning', 'info', 'danger',
+] as const;
+
+export type FamilyName = (typeof KNOWN_FAMILIES)[number];
+
+export const TEXT_STEPS = ['primary', 'secondary', 'tertiary', 'muted', 'disabled'] as const;
+
+export type TextStep = (typeof TEXT_STEPS)[number];
+
+/** Parse a text-scale token name into family + step. Returns null for any
+ *  non-`--text-*` slug or one whose parts don't resolve to a known step. */
+export function parseTextToken(colorRef: string): { family: FamilyName; step: TextStep } | null {
+  if (!colorRef.startsWith('--text-')) return null;
+  const rest = colorRef.slice('--text-'.length);
+  const parts = rest.split('-');
+  if (parts.length === 1) {
+    const p = parts[0];
+    if ((TEXT_STEPS as readonly string[]).includes(p)) return { family: 'neutral', step: p as TextStep };
+    if ((KNOWN_FAMILIES as readonly string[]).includes(p)) return { family: p as FamilyName, step: 'primary' };
+    return null;
+  }
+  if (parts.length === 2) {
+    const [fam, step] = parts;
+    if (
+      (KNOWN_FAMILIES as readonly string[]).includes(fam)
+      && (TEXT_STEPS as readonly string[]).includes(step)
+    ) {
+      return { family: fam as FamilyName, step: step as TextStep };
+    }
+  }
+  return null;
+}
+
+/** Inverse of parseTextToken — assemble a `--text-*` slug from family + step.
+ *  `neutral` family flattens to `--text-{step}`; `primary` step on a named
+ *  family flattens to `--text-{family}` (matches authoring conventions). */
+export function buildTextToken(family: FamilyName | string, step: TextStep | string): string {
+  if (family === 'neutral') return `--text-${step}`;
+  return step === 'primary' ? `--text-${family}` : `--text-${family}-${step}`;
+}
+
+/** Pull the family marker out of a token slug, or null if none of the
+ *  hyphen-delimited parts is a known family. */
+export function detectFamily(colorRef: string): FamilyName | null {
+  if (!colorRef.startsWith('--')) return null;
+  const parts = colorRef.slice(2).split('-');
+  for (const p of parts) {
+    if ((KNOWN_FAMILIES as readonly string[]).includes(p)) return p as FamilyName;
+  }
+  return null;
+}
+
+/** Rewrite the family marker in a slug from `oldFamily` to `newFamily`.
+ *  Returns the input unchanged when the slug doesn't reference `oldFamily`
+ *  (so unrelated tokens, literals, and out-of-family stops fall through). */
+export function swapTokenFamily(name: string, oldFamily: string, newFamily: string): string {
+  if (!name.startsWith('--')) return name;
+  const text = parseTextToken(name);
+  if (text) {
+    if (text.family !== oldFamily) return name;
+    return buildTextToken(newFamily, text.step);
+  }
+  const parts = name.slice(2).split('-');
+  const idx = parts.indexOf(oldFamily);
+  if (idx < 0) return name;
+  parts[idx] = newFamily;
+  return '--' + parts.join('-');
+}
+
+/** Coerce a slug to the given target family. Unlike swapTokenFamily this
+ *  doesn't need to know the source family — it autodetects, then rewrites.
+ *  Returns the input unchanged if no family is present (e.g. literal colors,
+ *  `transparent`, or a `--text-primary` neutral). */
+export function snapTokenToFamily(name: string, targetFamily: string): string {
+  if (!name.startsWith('--')) return name;
+  const text = parseTextToken(name);
+  if (text) {
+    if (text.family === targetFamily) return name;
+    return buildTextToken(targetFamily, text.step);
+  }
+  const fromFamily = detectFamily(name);
+  if (!fromFamily || fromFamily === targetFamily) return name;
+  return swapTokenFamily(name, fromFamily, targetFamily);
+}

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

@@ -298,3 +298,72 @@ export function palettesToVars(palettes: Record<string, PaletteConfig>): Record<
   }
   return out;
 }
+
+const HEX_RE = /^#[0-9a-f]{6}$/i;
+
+/**
+ * Reconcile palette typed state against the catch-all `cssVariables` bag and
+ * report the set of variable names the typed slice now owns. Two operations:
+ *
+ *   - **Snap** (gated by `_imported`): for any palette whose `_imported` flag
+ *     is true, the imported `--color-{ns}-500` value is treated as the
+ *     authoritative anchor. Chromatic palettes get `baseColor` snapped to it;
+ *     gray palettes (Neutral/Alternate) get `tintHue` + `tintChroma` derived
+ *     from it via OKLCH. The flag is then cleared. Editor-authored palettes
+ *     (no `_imported`) are left untouched — see `temp/manifest-robustness-plan.md`
+ *     §9 for why "snap on any divergence" was wrong: it would have flipped
+ *     `themes/default.json`'s accent from teal to olive on first read.
+ *
+ *   - **Consume** (always): every variable the palette's derivation produces
+ *     is reported in `consumed` so the caller can strip it from
+ *     `cssVariables`. The renderer (`editorRenderer.ts:42`) overlays
+ *     `palettesToVars(palettes)` on top of `cssVariables` regardless, so
+ *     stripped keys were dead data anyway. Stripping makes the file
+ *     invariant explicit: catch-all carries only tokens no typed slice owns.
+ *
+ * Returns the updated palette map plus the two sets. Pure: no DOM, no I/O,
+ * no module state. Idempotent on second call with the same input (no anchor
+ * to snap to after first call's strip).
+ */
+export function reconcilePalettesFromCssVars(
+  palettes: Record<string, PaletteConfig>,
+  cssVars: Record<string, string>,
+): {
+  palettes: Record<string, PaletteConfig>;
+  consumed: ReadonlySet<string>;
+  snapped: ReadonlySet<string>;
+} {
+  const next: Record<string, PaletteConfig> = structuredClone(palettes);
+  const consumed = new Set<string>();
+  const snapped = new Set<string>();
+
+  for (const spec of PALETTE_SPECS) {
+    const current = next[spec.label];
+    if (current === undefined) continue;
+
+    if (current._imported === true) {
+      const anchorHex = cssVars[`--color-${spec.cssNamespace}-500`];
+      if (anchorHex && HEX_RE.test(anchorHex.trim())) {
+        const hex = anchorHex.trim();
+        if (spec.mode === 'gray') {
+          const { c, h } = hexToOklch(hex);
+          next[spec.label] = { ...current, tintHue: h, tintChroma: c, _imported: false };
+        } else {
+          next[spec.label] = { ...current, baseColor: hex, _imported: false };
+        }
+        snapped.add(spec.label);
+      } else {
+        // No anchor in cssVariables to snap to — flag has nothing to do; clear
+        // it so subsequent calls don't keep checking. Safe because the renderer
+        // is going to overlay palettesToVars anyway.
+        next[spec.label] = { ...current, _imported: false };
+      }
+    }
+
+    for (const k of Object.keys(derivePaletteVars(spec, next[spec.label]))) {
+      consumed.add(k);
+    }
+  }
+
+  return { palettes: next, consumed, snapped };
+}

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

@@ -23,6 +23,7 @@ import tokensCss from '../../../system/styles/tokens.css?raw';
 import { editorState } from '../store/editorStore';
 import type { EditorState } from '../store/editorTypes';
 import { extractGlobalRootBody } from '../themes/parsers/globalRootBlock';
+import { formatGradientValue } from '../themes/slices/gradients';
 
 // Re-exported for tests and downstream consumers that previously imported it
 // from this module. The canonical implementation lives in `./parsers/globalRootBlock`
@@ -111,7 +112,9 @@ function buildOverlayRegistry(
   const overrides = new Map<string, string>();
   for (const slice of Object.values(components)) {
     for (const [varName, ref] of Object.entries(slice.aliases)) {
-      overrides.set(varName, ref.kind === 'token' ? `var(${ref.name})` : ref.value);
+      if (ref.kind === 'token') overrides.set(varName, `var(${ref.name})`);
+      else if (ref.kind === 'literal') overrides.set(varName, ref.value);
+      else overrides.set(varName, formatGradientValue(ref.value));
     }
   }
   const getDeclared = (v: string): string | null =>

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

@@ -18,8 +18,8 @@
  * orchestrate across slices and stay here.
  */
 
-import type { CssVarRef, EditorState } from './editorTypes';
-import type { Theme } from '../themes/themeTypes';
+import type { CssVarRef, EditorState, GradientAliasValue } from './editorTypes';
+import type { AliasDiskValue, Theme } from '../themes/themeTypes';
 import { KNOWN_COMPONENT_CONFIG_KEYS } from '../components/componentConfigKeys';
 import {
   CURRENT_THEME_SCHEMA_VERSION,
@@ -205,12 +205,200 @@ export {
 // 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,
-  aliases: Record<string, string>,
+  aliasesIn: Record<string, AliasDiskValue>,
+  rawConfig: Record<string, unknown> | undefined,
   fileVersion: number,
-): Record<string, string> {
-  return runMigrations('component-config', fileVersion, aliases, { component });
+): { 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,
+      },
+    };
+  }
 }
 
 /**
@@ -219,12 +407,18 @@ function migrateComponentAliases(
  * config bucket, and wraps the remainder as `CssVarRef` discriminated unions.
  */
 function splitAliasesAndConfig(
-  rawAliases: Record<string, string>,
+  rawAliases: Record<string, AliasDiskValue>,
   rawConfig: Record<string, unknown> | undefined,
 ): { aliases: Record<string, CssVarRef>; config: Record<string, unknown> } {
   const aliases: Record<string, CssVarRef> = {};
   const config: Record<string, unknown> = { ...(rawConfig ?? {}) };
   for (const [key, value] of Object.entries(rawAliases)) {
+    if (typeof value !== 'string') {
+      if (value.kind === 'gradient') {
+        aliases[key] = { kind: 'gradient', value: value.value as GradientAliasValue };
+      }
+      continue;
+    }
     if (KNOWN_COMPONENT_CONFIG_KEYS.has(key)) {
       if (config[key] === undefined) config[key] = value;
       continue;
@@ -249,12 +443,12 @@ function splitAliasesAndConfig(
 export function loadComponentActive(
   component: string,
   activeFile: string,
-  aliases: Record<string, string>,
+  aliases: Record<string, AliasDiskValue>,
   config?: Record<string, unknown>,
   schemaVersion: number = 0,
 ): void {
-  const migrated = migrateComponentAliases(component, aliases, schemaVersion);
-  const split = splitAliasesAndConfig(migrated, config);
+  const migrated = migrateComponentAliases(component, aliases, config, schemaVersion);
+  const split = splitAliasesAndConfig(migrated.aliases, migrated.config);
   mutate(`load ${component}/${activeFile}`, (s) => {
     s.components[component] = { activeFile, aliases: { ...split.aliases }, config: { ...split.config } };
   });
@@ -264,7 +458,7 @@ export function loadComponentActive(
 
 export interface ComponentSeed {
   activeFile: string;
-  aliases: Record<string, string>;
+  aliases: Record<string, AliasDiskValue>;
   config?: Record<string, unknown>;
   schemaVersion?: number;
 }
@@ -282,8 +476,8 @@ export function seedComponentsFromApi(
   store.update((s) => {
     s.components = {};
     for (const [comp, cfg] of Object.entries(configs)) {
-      const migrated = migrateComponentAliases(comp, cfg.aliases, cfg.schemaVersion ?? 0);
-      const split = splitAliasesAndConfig(migrated, cfg.config);
+      const migrated = migrateComponentAliases(comp, cfg.aliases, cfg.config, cfg.schemaVersion ?? 0);
+      const split = splitAliasesAndConfig(migrated.aliases, migrated.config);
       s.components[comp] = { activeFile: cfg.activeFile, aliases: { ...split.aliases }, config: { ...split.config } };
       setSavedComponentBaseline(comp, componentBaseline(split));
     }

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

@@ -43,24 +43,25 @@ export interface ColumnsState {
   margin: number;
 }
 
-export type CssVarRef =
-  | { kind: 'token'; name: string }
-  | { kind: 'literal'; value: string };
-
-export interface ComponentSlice {
-  activeFile: string;
-  aliases: Record<string, CssVarRef>;
-  config: Record<string, unknown>;
-  unlinked?: string[];
-}
-
-export type GradientType = 'linear' | 'radial';
+/** Gradient render mode.
+ *  - `linear` / `radial`: real gradients with N stops + angle (linear) or radius (radial).
+ *  - `solid`: collapses to the first stop's color. Angle/radius/extra stops carried in
+ *    the payload but ignored by the renderer; toggling back restores the prior shape.
+ *  - `none`: transparent. Same carry-forward semantics — payload retained for
+ *    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;
 }
@@ -71,9 +72,51 @@ export interface GradientToken {
   type: GradientType;
   /** Degrees, applies to linear only. */
   angle: number;
+  /** Pixel radius for radial gradients. When absent or zero, the renderer
+   *  emits CSS's default ellipse/farthest-corner shape. */
+  radius?: number;
+  /** Horizontal center position for radial gradients, 0–100. Defaults to 50. */
+  centerX?: number;
+  /** Horizontal stretch factor for the radial ellipse (1–8). Defaults to 1.
+   *  With aspectY, the rendered semi-axes are `radius * aspect*`, so both
+   *  shape (ratio) and size are encoded together. Both = 1 keeps the legacy
+   *  `circle` render path verbatim. */
+  aspectX?: number;
+  /** Vertical stretch factor for the radial ellipse (1–8). Defaults to 1. */
+  aspectY?: number;
   stops: GradientTokenStop[];
 }
 
+/** 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[];
+}
+
+export type CssVarRef =
+  | { kind: 'token'; name: string }
+  | { kind: 'literal'; value: string }
+  | { kind: 'gradient'; value: GradientAliasValue };
+
+export interface ComponentSlice {
+  activeFile: string;
+  aliases: Record<string, CssVarRef>;
+  config: Record<string, unknown>;
+  unlinked?: string[];
+}
+
 /**
  * Single source of truth for everything a saved token file depends on, plus
  * the domain state currently scattered across VariablesTab local `let` fields.