@motion-proto/live-tokens 0.20.0 → 0.21.0

package/README.md

@@ -216,18 +216,20 @@ export default defineConfig({
 
 No `css: 'injected'` workaround, no `optimizeDeps` excludes — `vite build` works as-is. (You'll want the full `themeFileApi` plugin and `bootLiveTokens` / `<LiveTokensRouter>` from the Quick install section above when you're ready to persist edits to disk and ship a real app.)
 
-## Greenfield? Use the starter
+## Greenfield? Scaffold a new app
 
-If you're starting from scratch, skip the manual wiring and clone the repo as a template — `App.svelte`, `main.ts`, the router, and a placeholder `Home.svelte` saying "put your content here" are all pre-wired.
+If you're starting from scratch, skip the manual wiring:
 
 ```bash
-npx degit motionproto/live-tokens my-app
+npx @motion-proto/live-tokens create my-app
 cd my-app
 npm install
 npm run dev
 ```
 
-Open http://localhost:5173 and replace `src/app/Home.svelte` with your content. The rest of the wiring is already done — it's the same code the npm package ships, just with the App-shell scaffolding included.
+This generates a Svelte + Vite app that **depends on** the package — `vite.config.ts`, `main.ts`, `App.svelte`, the `themeFileApi` plugin, and a placeholder `src/pages/Home.svelte` are all pre-wired. The token CSS is seeded from the version you scaffolded against, so it never drifts. Open http://localhost:5173 and replace `Home.svelte` with your content; upgrade the package later with `npm update`.
+
+(The older `npx degit motionproto/live-tokens` route cloned this whole repo as your app — the package's source, tests, and all. `create` gives you a thin consumer app instead.)
 
 ## Consumer-authored components
 

package/bin/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // CLI for @motion-proto/live-tokens.
 // Subcommands:
+//   create <dir>             Scaffold a new app that depends on this package.
 //   setup-claude [--force]   Copy bundled Claude Code skills into ./.claude/skills/.
 //   check-component <id>     Validate a component against the add-component skill contract.
 
@@ -10,10 +11,13 @@ import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { checkComponent, formatReport } from './check-component.mjs';
 import { runMigrate, formatMigrateResult } from './migrate.mjs';
+import { runCreate, formatCreateResult } from './create.mjs';
 
 const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
 
 Commands:
+  create <dir> [--force]      Scaffold a new Svelte + Vite app wired up with
+                              live-tokens (editor, components, theme tokens)
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
   check-component <id>        Validate <id>'s runtime, editor, and registration
                               against the live-tokens-create-component contract
@@ -35,6 +39,24 @@ if (!command || command === '--help' || command === '-h') {
   process.exit(0);
 }
 
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+if (command === 'create' || command === 'init') {
+  const targetArg = rest.find((a) => !a.startsWith('-'));
+  if (!targetArg) {
+    fail(`Usage: npx @motion-proto/live-tokens create <project-directory>`);
+  }
+  const force = rest.includes('--force');
+  const targetDir = resolve(process.cwd(), targetArg);
+  try {
+    const result = runCreate({ targetDir, pkgRoot, force });
+    console.log(formatCreateResult(result, targetArg));
+    process.exit(0);
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+}
+
 if (command === 'check-component') {
   const id = rest[0];
   if (!id) fail(`Usage: npx @motion-proto/live-tokens check-component <id>`);
@@ -70,7 +92,6 @@ if (process.platform === 'win32') {
 
 const force = rest.includes('--force');
 
-const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const srcSkills = join(pkgRoot, '.claude', 'skills');
 
 if (!existsSync(srcSkills)) {

package/bin/create.mjs

@@ -0,0 +1,89 @@
+// `create` subcommand: scaffold a new Svelte + Vite app that depends on the
+// published package. Extracted from cli.mjs so it can be unit-tested.
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+// npm strips dotfiles from published tarballs, so the template ships them
+// renamed; `create` restores the leading dot on scaffold.
+const DOTFILES = [['_gitignore', '.gitignore']];
+
+// Seeded from THIS installed package (src → scaffold) so the generated app's
+// token/theme CSS never drifts from the version it was created against.
+const SEEDS = [
+  ['src/system/styles/tokens.css', 'src/system/styles/tokens.css'],
+  ['src/live-tokens/data/tokens.generated.css', 'src/live-tokens/data/tokens.generated.css'],
+  ['src/app/site.css', 'src/styles/site.css'],
+];
+
+const PLACEHOLDER_FILES = ['package.json', 'index.html', 'README.md'];
+
+export function appNameFrom(targetDir) {
+  return (
+    (targetDir.split(/[/\\]/).filter(Boolean).pop() || '')
+      .replace(/[^a-z0-9._-]+/gi, '-')
+      .replace(/^[-.]+|[-.]+$/g, '')
+      .toLowerCase() || 'live-tokens-app'
+  );
+}
+
+export function runCreate({ targetDir, pkgRoot, force = false }) {
+  const templateDir = join(pkgRoot, 'template');
+  if (!existsSync(templateDir)) {
+    throw new Error(`Template not found at ${templateDir}. Is the package installed correctly?`);
+  }
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !force) {
+    throw new Error(`${targetDir} is not empty. Pass --force to scaffold into it anyway.`);
+  }
+
+  const appName = appNameFrom(targetDir);
+  const ltVersion = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+
+  cpSync(templateDir, targetDir, { recursive: true });
+
+  for (const [from, to] of DOTFILES) {
+    const src = join(targetDir, from);
+    if (existsSync(src)) renameSync(src, join(targetDir, to));
+  }
+
+  for (const [srcRel, destRel] of SEEDS) {
+    const src = join(pkgRoot, srcRel);
+    const dest = join(targetDir, destRel);
+    mkdirSync(dirname(dest), { recursive: true });
+    if (existsSync(src)) cpSync(src, dest);
+    else writeFileSync(dest, '');
+  }
+
+  for (const rel of PLACEHOLDER_FILES) {
+    const p = join(targetDir, rel);
+    if (!existsSync(p)) continue;
+    const filled = readFileSync(p, 'utf8')
+      .replaceAll('__APP_NAME__', appName)
+      .replaceAll('__LT_VERSION__', `^${ltVersion}`);
+    writeFileSync(p, filled);
+  }
+
+  return { appName, targetDir: resolve(targetDir), ltVersion };
+}
+
+export function formatCreateResult({ appName, targetDir }, targetArg) {
+  return [
+    ``,
+    `Scaffolded ${appName} → ${targetDir}`,
+    ``,
+    `Next steps:`,
+    `  cd ${targetArg}`,
+    `  npm install`,
+    `  npm run dev`,
+    ``,
+    `Then open http://localhost:5173 and edit src/pages/Home.svelte.`,
+  ].join('\n');
+}

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.21.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -26,6 +26,7 @@
     "dist-plugin",
     ".claude/skills",
     "bin",
+    "template",
     "!**/*.test.ts",
     "!**/*.spec.ts",
     "!**/__tests__/**",
@@ -89,7 +90,8 @@
     "check:no-style-imports": "node scripts/check-no-style-imports.mjs",
     "check:editor-font-isolation": "node scripts/check-editor-font-isolation.mjs",
     "check:smoke-install": "bash scripts/smoke-install.sh",
-    "prepublishOnly": "npm run check:no-style-imports && npm run check:editor-font-isolation && npm run build:lib && npm run check:smoke-install"
+    "check:smoke-create": "bash scripts/smoke-create.sh",
+    "prepublishOnly": "npm run check:no-style-imports && npm run check:editor-font-isolation && npm run build:lib && 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

@@ -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 {

package/template/README.md

@@ -0,0 +1,36 @@
+# __APP_NAME__
+
+Scaffolded with [`@motion-proto/live-tokens`](https://github.com/motionproto/live-tokens).
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:5173.
+
+## What you have
+
+- `src/pages/Home.svelte` — the starter page. Replace it with your own content.
+- `src/App.svelte` — your routes. `<LiveTokensRouter>` adds the dev-only
+  `/editor` (theme tokens) and `/components` (per-component aliases) routes.
+- `src/system/styles/tokens.css` — your theme token vocabulary. The dev server
+  writes edits here when you use the in-browser editor.
+- `src/styles/site.css` — themed page typography. Yours to edit.
+
+## Editing live
+
+Run `npm run dev`, then click **Open Token Editor** on the home page (or visit
+`/editor`). Changes persist to `src/system/styles/tokens.css` and the JSON under
+`src/live-tokens/data/`. The editor is dev-only — `npm run build` ships plain
+CSS variables and the components you used, nothing else.
+
+## Adding components
+
+The package ships ~25 editable components (Button, Card, Table, Dialog, …).
+Import them from `@motion-proto/live-tokens/components/<Name>.svelte`. To author
+your own editable component, install the Claude Code skills:
+
+```bash
+npx @motion-proto/live-tokens setup-claude
+```

package/template/_gitignore

@@ -0,0 +1,15 @@
+node_modules
+dist
+dist-ssr
+*.local
+*.log
+
+# Editor-written backups stay local to each machine; the live JSON/CSS commit.
+src/live-tokens/data/themes/_backups/
+src/live-tokens/data/manifests/_backups/
+src/live-tokens/data/component-configs/*/_backups/
+src/system/styles/_backups/
+
+.DS_Store
+.vscode/*
+!.vscode/extensions.json

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__APP_NAME__</title>
+  </head>
+  <body style="margin: 0;">
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-check --tsconfig ./tsconfig.json"
+  },
+  "dependencies": {
+    "@motion-proto/live-tokens": "__LT_VERSION__"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@types/node": "^25.9.1",
+    "sass": "^1.98.0",
+    "svelte": "^5.55.5",
+    "svelte-check": "^4.4.8",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.14"
+  }
+}

package/template/src/App.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+  import { LiveTokensRouter } from '@motion-proto/live-tokens';
+
+  // <LiveTokensRouter> owns the dev-only /editor and /components routes.
+  // Declare your own pages here. Lazy imports keep each page's CSS
+  // side-effects out of the editor routes; omit `label` to keep a route
+  // reachable by URL but hidden from the overlay nav rail.
+  const pages = {
+    '/': {
+      lazy: () => import('./pages/Home.svelte'),
+      label: 'Home',
+      icon: 'fa-home',
+      source: 'src/pages/Home.svelte',
+    },
+  };
+</script>
+
+<LiveTokensRouter {pages} />

package/template/src/main.ts

@@ -0,0 +1,12 @@
+// Token CSS order matters: defaults → editor overrides → fonts. The first two
+// are project-local (the dev plugin writes to them); fonts ship with the package.
+import './system/styles/tokens.css';
+import './live-tokens/data/tokens.generated.css';
+import '@motion-proto/live-tokens/app/fonts.css';
+
+import { bootLiveTokens, configureEditor } from '@motion-proto/live-tokens';
+import App from './App.svelte';
+
+configureEditor({ storagePrefix: 'app-' });
+
+bootLiveTokens(App, '#app');

package/template/src/pages/Home.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+  // site.css carries themed page typography (bare h1/p/a rules that consume
+  // theme tokens). Imported per-page, not globally, so the editor routes stay
+  // theme-immune. It's yours to edit — see src/styles/site.css.
+  import '../styles/site.css';
+  import Card from '@motion-proto/live-tokens/components/Card.svelte';
+  import Button from '@motion-proto/live-tokens/components/Button.svelte';
+  import { navigate } from '@motion-proto/live-tokens';
+
+  const isDev = import.meta.env.DEV;
+</script>
+
+<div class="home">
+  <section class="stub">
+    <Card>
+      <span class="eyebrow">Your app lives here</span>
+      <h1>Home</h1>
+      <p>
+        Replace this with your own content. Edit <code>src/pages/Home.svelte</code>
+        to get started, or add routes in <code>src/App.svelte</code>. Components
+        and theme tokens are editable live while <code>npm run dev</code> is running.
+      </p>
+      {#if isDev}
+        <div class="actions">
+          <Button on:click={() => navigate('/editor')}>Open Token Editor</Button>
+          <Button variant="secondary" on:click={() => navigate('/components')}>Components</Button>
+        </div>
+      {/if}
+    </Card>
+  </section>
+</div>
+
+<style>
+  .home {
+    display: grid;
+    grid-template-columns: repeat(var(--columns-count), 1fr);
+    column-gap: var(--columns-gutter);
+    max-width: var(--columns-max-width);
+    margin: 0 auto;
+    padding: var(--space-48) var(--space-32);
+    min-height: 100vh;
+    align-content: center;
+  }
+
+  .stub {
+    grid-column: 4 / span 6;
+  }
+
+  .eyebrow {
+    display: block;
+    font-size: var(--font-size-sm);
+    font-weight: var(--font-weight-normal);
+    text-transform: uppercase;
+    color: var(--text-tertiary);
+    margin-bottom: var(--space-8);
+  }
+
+  h1 {
+    font-family: var(--font-display);
+    font-size: var(--font-size-4xl);
+    color: var(--text-primary);
+    margin: 0 0 var(--space-12);
+  }
+
+  p {
+    color: var(--text-secondary);
+    line-height: 1.6;
+  }
+
+  code {
+    background: var(--surface-neutral-high);
+    padding: 2px 6px;
+    border-radius: var(--radius-sm);
+    font-family: var(--font-mono, monospace);
+    font-size: 0.9em;
+  }
+
+  .actions {
+    display: flex;
+    gap: var(--space-12);
+    flex-wrap: wrap;
+    margin-top: var(--space-20);
+  }
+</style>

package/template/src/vite-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="svelte" />
+/// <reference types="vite/client" />

package/template/svelte.config.js

@@ -0,0 +1,6 @@
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import("@sveltejs/vite-plugin-svelte").SvelteConfig} */
+export default {
+  preprocess: vitePreprocess(),
+};

package/template/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.svelte"]
+}

package/template/vite.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vite';
+import { svelte, vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+import { themeFileApi } from '@motion-proto/live-tokens/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    svelte({ preprocess: vitePreprocess() }),
+    // Dev-only: persists editor changes to src/system/styles/tokens.css and
+    // the JSON under src/live-tokens/data/. No effect on `vite build`.
+    themeFileApi({ tokensCssPath: 'src/system/styles/tokens.css' }),
+  ],
+});