@motion-proto/live-tokens 0.20.0 → 0.20.1

package/dist-plugin/index.cjs

@@ -52,6 +52,14 @@ function extractGlobalRootBody(source) {
   return bodies.join("\n");
 }
 
+// src/editor/core/themes/parsers/colorOpacity.ts
+var COLOR_OPACITY_RE = /^color-mix\(in srgb,\s*var\((--[a-z0-9-]+)\)\s+(\d+)%,\s*transparent\)$/i;
+function parseColorOpacity(value) {
+  const m = value.trim().match(COLOR_OPACITY_RE);
+  if (!m) return null;
+  return { name: m[1], opacity: parseInt(m[2], 10) };
+}
+
 // src/editor/core/storage/files/versionedFileResourceClient.ts
 function sanitizeFileName(name) {
   return name.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9\-_]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "") || "unnamed";
@@ -1013,11 +1021,13 @@ function themeFileApi(opts) {
   }
   function extractAliasDeclarations(body) {
     const aliases = {};
-    const re = /(--[a-z0-9-]+)\s*:\s*(var\(--[a-z0-9-]+\)|color-mix\(in srgb,\s*var\(--[a-z0-9-]+\)\s+\d+%,\s*transparent\))\s*;/gi;
+    const re = /(--[a-z0-9-]+)\s*:\s*([^;]+);/gi;
     let m;
     while ((m = re.exec(body)) !== null) {
-      const plain = m[2].match(/^var\((--[a-z0-9-]+)\)$/i);
-      aliases[m[1]] = plain ? plain[1] : m[2];
+      const value = m[2].trim();
+      const plain = value.match(/^var\((--[a-z0-9-]+)\)$/i);
+      if (plain) aliases[m[1]] = plain[1];
+      else if (parseColorOpacity(value)) aliases[m[1]] = value;
     }
     return aliases;
   }

package/dist-plugin/index.js

@@ -10,6 +10,14 @@ import {
 import fs2 from "fs";
 import path2 from "path";
 
+// src/editor/core/themes/parsers/colorOpacity.ts
+var COLOR_OPACITY_RE = /^color-mix\(in srgb,\s*var\((--[a-z0-9-]+)\)\s+(\d+)%,\s*transparent\)$/i;
+function parseColorOpacity(value) {
+  const m = value.trim().match(COLOR_OPACITY_RE);
+  if (!m) return null;
+  return { name: m[1], opacity: parseInt(m[2], 10) };
+}
+
 // src/editor/core/storage/files/versionedFileResourceClient.ts
 function sanitizeFileName(name) {
   return name.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9\-_]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "") || "unnamed";
@@ -753,11 +761,13 @@ function themeFileApi(opts) {
   }
   function extractAliasDeclarations(body) {
     const aliases = {};
-    const re = /(--[a-z0-9-]+)\s*:\s*(var\(--[a-z0-9-]+\)|color-mix\(in srgb,\s*var\(--[a-z0-9-]+\)\s+\d+%,\s*transparent\))\s*;/gi;
+    const re = /(--[a-z0-9-]+)\s*:\s*([^;]+);/gi;
     let m;
     while ((m = re.exec(body)) !== null) {
-      const plain = m[2].match(/^var\((--[a-z0-9-]+)\)$/i);
-      aliases[m[1]] = plain ? plain[1] : m[2];
+      const value = m[2].trim();
+      const plain = value.match(/^var\((--[a-z0-9-]+)\)$/i);
+      if (plain) aliases[m[1]] = plain[1];
+      else if (parseColorOpacity(value)) aliases[m[1]] = value;
     }
     return aliases;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [

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

@@ -26,7 +26,7 @@
   import { listManifests, saveAsManifest } from '../../core/manifests/manifestService';
   import type { ManifestMeta } from '../../core/themes/themeTypes';
   import { CURRENT_COMPONENT_SCHEMA_VERSION } from '../../core/themes/migrations';
-  import type { CssVarRef } from '../../core/store/editorTypes';
+  import { refToDiskValue } from '../../core/store/cssVarRef';
   import { safeFetch } from '../../core/storage/storage';
   import { API_BASE } from '../../core/storage/apiBase';
   import { flashStatus } from '../../core/flashStatus';
@@ -126,12 +126,6 @@
     }
   }
 
-  function refToDiskValue(ref: CssVarRef): AliasDiskValue {
-    if (ref.kind === 'token') return ref.name;
-    if (ref.kind === 'literal') return ref.value;
-    return { kind: 'gradient', value: ref.value };
-  }
-
   function currentAliases(): Record<string, AliasDiskValue> {
     const slice = get(editorState).components[component];
     if (!slice) return {};

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

@@ -9,6 +9,7 @@
   import { mutate } from '../../core/store/editorStore';
   import { getDeclaredValue } from '../../core/palettes/tokenRegistry';
   import type { CssVarRef } from '../../core/store/editorTypes';
+  import { cssStringToRef, refToCss } from '../../core/store/cssVarRef';
   import { getEditorContext } from './editorContext';
   import type { Token, TypeGroupConfig } from './types';
   import type { Sibling } from './siblings';
@@ -112,9 +113,7 @@
       instead of falling back to its own family's default. */
   function declaredToRef(declared: string | null): CssVarRef | null {
     if (!declared) return null;
-    const m = declared.match(/^\s*var\((--[a-z0-9-]+)\)\s*$/i);
-    if (m) return { kind: 'token', name: m[1] };
-    return { kind: 'literal', value: declared };
+    return cssStringToRef(declared.trim());
   }
 
   /** Extract a transparency percentage from a `color-mix(in srgb, var(--X) N%, transparent)`
@@ -179,9 +178,8 @@
       const effectiveValue = (varName: string): string | null => {
         const ref = slice.aliases[varName];
         if (!ref) return getDeclaredValue(varName);
-        if (ref.kind === 'token') return `var(${ref.name})`;
-        if (ref.kind === 'literal') return ref.value;
-        return null;
+        if (ref.kind === 'gradient') return null;
+        return refToCss(ref);
       };
 
       const apply = (srcVar: string, dstVar: string) => {

package/src/editor/component-editor/scaffolding/linkedBlock.ts

@@ -5,11 +5,14 @@ import {
   editorState,
 } from '../../core/store/editorStore';
 import type { CssVarRef } from '../../core/store/editorTypes';
+import { refToCss } from '../../core/store/cssVarRef';
 import type { Token } from './types';
 
+/** Stable per-ref identity key: refs that render to the same CSS share a key,
+ *  so siblings with equal values bucket together regardless of ref kind. */
 function aliasKey(ref: CssVarRef | undefined): string {
   if (!ref) return '';
-  return ref.kind === 'token' ? `t:${ref.name}` : `v:${ref.value}`;
+  return refToCss(ref);
 }
 
 const TYPOGRAPHY_PROP_SUFFIXES = ['font-family', 'font-size', 'font-weight', 'line-height'] as const;

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

@@ -1,7 +1,7 @@
 import { get } from 'svelte/store';
 import type { AliasDiskValue, ComponentConfig } from '../themes/themeTypes';
 import { editorState, markComponentSaved } from '../store/editorStore';
-import type { CssVarRef } from '../store/editorTypes';
+import { refToDiskValue } from '../store/cssVarRef';
 import { CURRENT_COMPONENT_SCHEMA_VERSION } from '../themes/migrations';
 import {
   listComponentConfigs,
@@ -24,11 +24,6 @@ export type SaveActiveComponentResult =
   | { ok: true; fileName: string; displayName: string }
   | { ok: false; reason: 'default' | 'no-state' | 'error'; error?: unknown };
 
-function refToDiskValue(ref: CssVarRef): AliasDiskValue {
-  if (ref.kind === 'token') return ref.name;
-  if (ref.kind === 'literal') return ref.value;
-  return { kind: 'gradient', value: ref.value };
-}
 
 export async function saveActiveComponentConfig(
   component: string,

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

@@ -23,7 +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';
+import { refToCss } from '../store/cssVarRef';
 
 // Re-exported for tests and downstream consumers that previously imported it
 // from this module. The canonical implementation lives in `./parsers/globalRootBlock`
@@ -112,9 +112,7 @@ function buildOverlayRegistry(
   const overrides = new Map<string, string>();
   for (const slice of Object.values(components)) {
     for (const [varName, ref] of Object.entries(slice.aliases)) {
-      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));
+      overrides.set(varName, refToCss(ref));
     }
   }
   const getDeclared = (v: string): string | null =>

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

@@ -0,0 +1,87 @@
+/**
+ * The single classifier + renderer for `CssVarRef`. Every place that turns a
+ * CSS value string into a ref, or a ref back into CSS, routes through here so
+ * the three ref kinds (`token`, `literal`, `gradient`) are interpreted
+ * identically across the disk loader, the live-edit path, the registry, and the
+ * component renderer.
+ *
+ * A `token` may carry an optional `opacity` (a colour below 100%). Opacity
+ * serialization is delegated to `parsers/colorOpacity`, the one place that knows
+ * the `color-mix(in srgb, var(--token) NN%, transparent)` shape.
+ */
+import type { CssVarRef } from './editorTypes';
+import type { AliasDiskValue } from '../themes/themeTypes';
+import { formatGradientValue } from '../themes/slices/gradients';
+import { formatColorOpacity, parseColorOpacity } from '../themes/parsers/colorOpacity';
+
+/** True when a token carries a non-trivial opacity (a colour below 100%). */
+function hasOpacity(opacity: number | undefined): opacity is number {
+  return opacity != null && opacity < 100;
+}
+
+/** Render a ref to the CSS value string written to a custom property. */
+export function refToCss(ref: CssVarRef): string {
+  switch (ref.kind) {
+    case 'token':
+      return hasOpacity(ref.opacity) ? formatColorOpacity(ref.name, ref.opacity) : `var(${ref.name})`;
+    case 'literal':
+      return ref.value;
+    case 'gradient':
+      return formatGradientValue(ref.value);
+  }
+}
+
+/**
+ * Classify a CSS value string into a ref. Accepts a bare token name (`--x`,
+ * the disk convention), a wrapped alias (`var(--x)`, the declared-value form),
+ * a colour-opacity expression, or anything else (a raw literal). Never produces
+ * a gradient — gradients are stored as structured objects, not strings.
+ */
+export function cssStringToRef(value: string): CssVarRef {
+  const op = parseColorOpacity(value);
+  if (op) return { kind: 'token', name: op.name, opacity: op.opacity };
+  if (value.startsWith('--')) return { kind: 'token', name: value };
+  const wrapped = value.match(/^var\((--[a-z0-9-]+)\)$/);
+  if (wrapped) return { kind: 'token', name: wrapped[1] };
+  return { kind: 'literal', value };
+}
+
+/**
+ * Serialize a ref to its on-disk `AliasDiskValue`. Mirrors `refToCss` except a
+ * token is stored as its bare name (`--x`, not `var(--x)`) — the editor's disk
+ * convention — and a gradient is a structured object rather than a CSS string.
+ */
+export function refToDiskValue(ref: CssVarRef): AliasDiskValue {
+  switch (ref.kind) {
+    case 'token':
+      return hasOpacity(ref.opacity) ? formatColorOpacity(ref.name, ref.opacity) : ref.name;
+    case 'literal':
+      return ref.value;
+    case 'gradient':
+      return { kind: 'gradient', value: ref.value };
+  }
+}
+
+/** Structural equality across all ref kinds. */
+export function cssVarRefEqual(a: CssVarRef | undefined, b: CssVarRef | undefined): boolean {
+  if (!a || !b) return a === b;
+  if (a.kind !== b.kind) return false;
+  if (a.kind === 'token') {
+    const bt = b as { kind: 'token'; name: string; opacity?: number };
+    return a.name === bt.name && (a.opacity ?? 100) === (bt.opacity ?? 100);
+  }
+  if (a.kind === 'literal') return a.value === (b as { kind: 'literal'; value: string }).value;
+  const av = a.value;
+  const bv = (b as { kind: 'gradient'; value: typeof a.value }).value;
+  if (av.type !== bv.type || av.angle !== bv.angle || av.stops.length !== bv.stops.length) return false;
+  if ((av.aspectX ?? 1) !== (bv.aspectX ?? 1)) return false;
+  if ((av.aspectY ?? 1) !== (bv.aspectY ?? 1)) return false;
+  for (let i = 0; i < av.stops.length; i++) {
+    const sa = av.stops[i];
+    const sb = bv.stops[i];
+    if (sa.position !== sb.position || sa.color !== sb.color || (sa.opacity ?? 100) !== (sb.opacity ?? 100)) {
+      return false;
+    }
+  }
+  return true;
+}

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

@@ -21,6 +21,7 @@
 import type { CssVarRef, EditorState, GradientAliasValue } from './editorTypes';
 import type { AliasDiskValue, Theme } from '../themes/themeTypes';
 import { KNOWN_COMPONENT_CONFIG_KEYS } from '../components/componentConfigKeys';
+import { cssStringToRef } from './cssVarRef';
 import {
   CURRENT_THEME_SCHEMA_VERSION,
   CURRENT_COMPONENT_SCHEMA_VERSION,
@@ -421,9 +422,7 @@ function splitAliasesAndConfig(
       if (config[key] === undefined) config[key] = value;
       continue;
     }
-    aliases[key] = value.startsWith('--')
-      ? { kind: 'token', name: value }
-      : { kind: 'literal', value };
+    aliases[key] = cssStringToRef(value);
   }
   return { aliases, config };
 }

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

@@ -100,7 +100,11 @@ export interface GradientAliasValue {
 }
 
 export type CssVarRef =
-  | { kind: 'token'; name: string }
+  /** An alias to a design token. `opacity` is an optional integer percent set
+   *  only for a colour carried below 100% (serializes to
+   *  `color-mix(in srgb, var(name) opacity%, transparent)`); absent means fully
+   *  opaque, which also covers every non-colour alias (radius, spacing, font). */
+  | { kind: 'token'; name: string; opacity?: number }
   | { kind: 'literal'; value: string }
   | { kind: 'gradient'; value: GradientAliasValue };
 

package/src/editor/core/themes/parsers/colorOpacity.ts

@@ -0,0 +1,41 @@
+/**
+ * The single source of truth for a design-token colour carried at reduced
+ * opacity. A colour token below 100% opacity serializes as:
+ *
+ *   color-mix(in srgb, var(--token) NN%, transparent)
+ *
+ * 100% opacity is NOT represented here — a fully opaque colour collapses to a
+ * plain `var(--token)` alias (`CssVarRef` kind `'token'`). Everything that
+ * reads, writes, or validates this form must go through `parseColorOpacity` /
+ * `formatColorOpacity` so the canonical shape lives in exactly one place.
+ *
+ * This module is intentionally dependency-free so the dev-server vite plugin
+ * (a separate build) can import it the same way it imports `globalRootBlock`.
+ */
+
+/** `opacity` is an integer percentage in [0, 100). */
+export interface ColorOpacity {
+  /** The design-token name, e.g. `--surface-neutral-lower`. */
+  name: string;
+  /** Integer percentage, 0–99 (100 is not an opacity colour — it's a token). */
+  opacity: number;
+}
+
+const COLOR_OPACITY_RE =
+  /^color-mix\(in srgb,\s*var\((--[a-z0-9-]+)\)\s+(\d+)%,\s*transparent\)$/i;
+
+/**
+ * Parse a `color-mix(in srgb, var(--token) NN%, transparent)` string into its
+ * token name and integer opacity. Returns null for any other value (plain
+ * aliases, raw literals, gradients).
+ */
+export function parseColorOpacity(value: string): ColorOpacity | null {
+  const m = value.trim().match(COLOR_OPACITY_RE);
+  if (!m) return null;
+  return { name: m[1], opacity: parseInt(m[2], 10) };
+}
+
+/** Serialize a token + integer opacity back to the canonical color-mix string. */
+export function formatColorOpacity(name: string, opacity: number): string {
+  return `color-mix(in srgb, var(${name}) ${opacity}%, transparent)`;
+}

package/src/editor/core/themes/slices/components.ts

@@ -32,7 +32,7 @@
 import { writable, derived, get, type Readable } from 'svelte/store';
 import type { CssVarRef, EditorState } from '../../store/editorTypes';
 import { store, mutate } from '../../store/editorCore';
-import { formatGradientValue } from './gradients';
+import { refToCss, cssVarRefEqual } from '../../store/cssVarRef';
 import { CASCADING_COMPONENT_CONFIG_KEYS } from '../../components/componentConfigKeys';
 
 const EMPTY_COMPONENT_BASELINE = JSON.stringify({ aliases: {}, config: {} });
@@ -45,9 +45,7 @@ export function componentsToVars(components: EditorState['components']): Record<
   const out: Record<string, string> = {};
   for (const slice of Object.values(components)) {
     for (const [varName, ref] of Object.entries(slice.aliases)) {
-      if (ref.kind === 'token') out[varName] = `var(${ref.name})`;
-      else if (ref.kind === 'literal') out[varName] = ref.value;
-      else out[varName] = formatGradientValue(ref.value);
+      out[varName] = refToCss(ref);
     }
     for (const [key, value] of Object.entries(slice.config)) {
       if (CASCADING_COMPONENT_CONFIG_KEYS.has(key) && typeof value === 'string') {
@@ -248,25 +246,6 @@ export function getComponentPropertySiblings(component: string, varName: string)
   return siblings;
 }
 
-function cssVarRefEqual(a: CssVarRef | undefined, b: CssVarRef | undefined): boolean {
-  if (!a || !b) return a === b;
-  if (a.kind !== b.kind) return false;
-  if (a.kind === 'token') return a.name === (b as { kind: 'token'; name: string }).name;
-  if (a.kind === 'literal') return a.value === (b as { kind: 'literal'; value: string }).value;
-  // gradient: structural compare on type, angle, aspect axes, and stops.
-  const av = a.value;
-  const bv = (b as { kind: 'gradient'; value: typeof a.value }).value;
-  if (av.type !== bv.type || av.angle !== bv.angle || av.stops.length !== bv.stops.length) return false;
-  if ((av.aspectX ?? 1) !== (bv.aspectX ?? 1)) return false;
-  if ((av.aspectY ?? 1) !== (bv.aspectY ?? 1)) return false;
-  for (let i = 0; i < av.stops.length; i++) {
-    const sa = av.stops[i];
-    const sb = bv.stops[i];
-    if (sa.position !== sb.position || sa.color !== sb.color || (sa.opacity ?? 100) !== (sb.opacity ?? 100)) return false;
-  }
-  return true;
-}
-
 /** True iff `varName` is not individually opted out, has ≥2 declared siblings,
  *  and the linked siblings agree — either all sharing the same explicit alias,
  *  or all having no override (linked at the upstream default). */

package/src/editor/ui/UIPaletteSelector.svelte

@@ -6,6 +6,7 @@
   import { resolveAliasChain } from '../core/palettes/tokenRegistry';
   import { editorState } from '../core/store/editorStore';
   import { formatGradientStops } from '../core/themes/slices/gradients';
+  import { formatColorOpacity, parseColorOpacity } from '../core/themes/parsers/colorOpacity';
   import type { GradientToken } from '../core/store/editorTypes';
   import UITokenSelector from './UITokenSelector.svelte';
 
@@ -249,24 +250,19 @@
     return null;
   }
 
-  function parseOpacity(raw: string): { inner: string; opacity: number } | null {
-    const m = raw.match(/^color-mix\(in srgb,\s*(var\(--[a-z0-9-]+\))\s+(\d+)%,\s*transparent\)$/);
-    if (!m) return null;
-    return { inner: m[1], opacity: parseInt(m[2]) };
-  }
-
   function parseStatic(raw: string): { name: 'white' | 'black'; opacity: number } | null {
     const direct = raw.match(/^var\(--color-(white|black)\)$/);
     if (direct) return { name: direct[1] as 'white' | 'black', opacity: 100 };
-    const wrapped = raw.match(/^color-mix\(in srgb,\s*var\(--color-(white|black)\)\s+(\d+)%,\s*transparent\)$/);
-    if (wrapped) return { name: wrapped[1] as 'white' | 'black', opacity: parseInt(wrapped[2]) };
+    const op = parseColorOpacity(raw);
+    const m = op?.name.match(/^--color-(white|black)$/);
+    if (op && m) return { name: m[1] as 'white' | 'black', opacity: op.opacity };
     return null;
   }
 
   function buildValue(varName: string): string | null {
     if (varName === variable && opacity >= 100) return null;
     if (opacity >= 100) return varName;
-    return `color-mix(in srgb, var(${varName}) ${opacity}%, transparent)`;
+    return formatColorOpacity(varName, opacity);
   }
 
   function applyOpacity() {
@@ -399,9 +395,9 @@
     }
     chosenStatic = null;
 
-    const opacityParsed = parseOpacity(raw);
+    const opacityParsed = parseColorOpacity(raw);
     if (opacityParsed) {
-      const parsed = parseRef(opacityParsed.inner);
+      const parsed = parseRef(`var(${opacityParsed.name})`);
       if (parsed) {
         chosenCategory = parsed.category;
         chosenFamily = parsed.family;

package/src/editor/ui/UITokenSelector.svelte

@@ -3,6 +3,7 @@
   import type { Snippet } from 'svelte';
   import { setCssVar, removeCssVar, CSS_VAR_CHANGE_EVENT } from '../core/cssVarSync';
   import type { CssVarRef } from '../core/store/editorTypes';
+  import { cssStringToRef } from '../core/store/cssVarRef';
   import {
     editorState,
     setComponentAlias,
@@ -116,14 +117,13 @@
     if (component) {
       const useLinked = isLinkedDisplay;
       if (semanticName) {
-        // Mirror splitAliasesAndConfig: a `--…` reference becomes a token
-        // (rendered as `var(name)`); anything else (color-mix expressions,
-        // `transparent`, gradient tokens already wrapped) is a literal whose
-        // value is emitted as-is. Storing complex CSS as a token would render
+        // Same classifier as the disk loader (cssStringToRef): a `--…`
+        // reference becomes a token (rendered as `var(name)`); a
+        // `color-mix(... var(--token) NN%, transparent)` becomes a colour ref;
+        // anything else (`transparent`, a materialized gradient) is a literal
+        // emitted as-is. Storing complex CSS as a token would render
         // `var(color-mix(...))`, which is invalid and breaks the preview.
-        const ref: CssVarRef = semanticName.startsWith('--')
-          ? { kind: 'token', name: semanticName }
-          : { kind: 'literal', value: semanticName };
+        const ref: CssVarRef = cssStringToRef(semanticName);
         if (useLinked) setComponentAliasLinked(component, variable, ref);
         else setComponentAlias(component, variable, ref);
       } else {