@motion-proto/live-tokens 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.49.0 — Working buffers are active-theme deltas
+
+### Changed (breaking)
+
+- **Working buffers are deltas from the active theme.** Loading a theme now
+  clears working buffers and changes only `themes/_active.json`; live reads
+  resolve through the active theme. Saving removes buffers whose content is now
+  durable, while deleting an active theme materialises only the deltas needed
+  to preserve the visible look.
+
+## 0.48.1 — Demo typography follows the theme
+
+### Fixed
+
+- **The demo hero follows semantic typography.** The subtitle and supporting
+  tagline now take their font families from the heading and body text-style
+  tokens, so changing the theme's primary font pairing repaints the whole hero.
+
+- **Floating-tag connectors stay visible.** Connector strings choose the
+  black or white invariant with the stronger contrast against the current page
+  background, including backgrounds with multiple gradient stops.
+
 ## 0.48.0 — Themes are documents
 
 ### Added

package/README.md

@@ -11,7 +11,7 @@ A foundational design system for quickly styling and building Svelte + Vite micr
 - **Theme editor** (`/live-tokens/editor` route, dev-only) — the home of real-time token editing. Save themes to disk as JSON, then Adopt one to bake it into static CSS for the build.
 - **Per-component editor** (`/live-tokens/components` route, dev-only) — the home of real-time component-alias editing. Pick token aliases per component without writing CSS.
 - **Live editor overlay** — pins to the top-right of every dev page. Opens the editor in a side panel or floating window so you edit *on the page you're styling*, not in a separate tab. Includes a "Page Source" button that opens the current page's `.svelte` file in VS Code.
-- **Themes** — a theme is a whole look in one file: colors and type plus a config for every component you changed, held by value. In the editor this is the Theme panel, with Colors & Type and Components as its parts. Themes are documents: loading one opens it, filling the editor's working buffer and returning every component it does not carry to its default, and nothing your site ships changes until you Adopt. A narrower load takes the colors and type alone and leaves your shapes. Export one and import it into another project to restore the full styling in one step.
+- **Themes** — a theme is a whole look in one file: colors and type plus a config for every component you changed, held by value. In the editor this is the Theme panel, with Colors & Type and Components as its parts. Themes are documents: loading one opens it with a one-file `_active.json` pointer change, live reads fall through to its content, and nothing your site ships changes until you Adopt. A narrower load takes the colors and type alone and leaves your shapes. Export one and import it into another project to restore the full styling in one step.
 - **Seven example looks** — Autumn, Halloween, Midnight Study, Ocean, Royal Velvet, Spring Meadow and Sunset each ship as a full theme: preset colors and type plus a shape personality of radius, padding, gap and border-width aliases. Each preset also names its own Google Fonts pairing, one display family and one body family, so a look carries type as well as colour and shape. They need no local files, so Load one to try a whole look on your own pages and load Motion Proto to come back. Saving over a preset writes a local copy that shadows the shipped one; delete that copy and the shipped version returns.
 - **Vite plugin** — hosts the `/api/live-tokens/{colors-and-type,component-configs,themes}/*` routes the editor reads and saves through. The single namespace keeps live-tokens' routes from colliding with anything your app serves under `/api`.
 - **Claude Code skill suite** — five bundled skills so you can drive the package in plain English. `build-page` composes pages from the shipped components. `pick-component` decides between confusing pairs (TabBar vs SegmentedControl, Card vs CollapsibleSection). `create-component` authors a new editable component against the project's naming, state-model, and import rules. `generate-theme` turns a mood brief ("bright and cheerful", "dark night theme") into a complete AA-checked color theme. `adjust-shape-space` turns "make the buttons pill shaped" or "space it out" into new radius, padding, gap, and border-width aliases. One command to install them all: `npx @motion-proto/live-tokens setup-claude`. See [Claude Code skills](#claude-code-skills) below.
@@ -56,7 +56,7 @@ A project last opened on 0.47.1 or earlier still keeps its colors and type in `t
 
 By default, the plugin reads and writes under one folder: `src/live-tokens/data/`. Inside that folder live three subdirectories — `colors-and-type/`, `themes/`, `component-configs/` — each owned by the plugin.
 
-`themes/` holds the documents: one file per whole look, plus `_active.json` naming the one the editor has open and `_production.json` naming the one your site ships. `colors-and-type/` and `component-configs/{comp}/` hold each layer's `default.json` baseline, any preset you save by name, and the `_working.json` buffer for edits you have not saved into a theme. A buffer exists only where the look sits off the shipped default, so a new project has none.
+`themes/` holds the documents: one file per whole look, plus `_active.json` naming the one the editor has open and `_production.json` naming the one your site ships. `colors-and-type/` and `component-configs/{comp}/` hold each layer's `default.json` baseline, any preset you save by name, and the `_working.json` buffer for edits you have not saved into the active theme. A buffer is a delta from that open document, so ordinary theme switching leaves none.
 
 To move them, create a `live-tokens.config.json` at your project root:
 

package/bin/generate-theme.mjs

@@ -5,7 +5,7 @@
 // TS sources), enforces the AA contrast gate, and saves the result as a theme:
 // <themesDir>/<slug>.json, the document that carries the whole look by value.
 // Unless --no-activate it then opens that theme the way the dev server's apply
-// door does — the embedded copies land in the reserved `_working` buffers and
+// door does — existing `_working` buffers are cleared and
 // `themes/_active.json` names it. Nothing else moves, so generating a theme
 // cannot change what the site ships.
 //
@@ -97,9 +97,8 @@ function resolveCarrySource({ carryFrom, colorsAndTypeDir, componentConfigsDir,
       readData(colorsAndTypeDir, 'colors-and-type', 'default'),
   );
 
-  // Presence is the model's own rule for "off the shipped default": a buffer
-  // exists only where the layer sits off it, and a theme carries only the
-  // components it changes.
+  // A working buffer is an unsaved delta from the active theme; absent theme
+  // component entries fall through to the component defaults.
   const componentConfigs = {};
   for (const comp of comps) {
     const live =
@@ -168,7 +167,7 @@ export async function runGenerateTheme({
   if (!dryRun) {
     mkdirSync(dirs.themesDir, { recursive: true });
     writeFileSync(themePath, JSON.stringify(theme, null, 2) + '\n');
-    if (activate) applyTheme(theme, slug, dirs);
+    if (activate) applyTheme(slug, dirs);
   }
 
   return {
@@ -185,21 +184,15 @@ export async function runGenerateTheme({
   };
 }
 
-/** The apply door's write set, reproduced: the theme's copies fill the reserved
- *  buffers, every component it does not carry is cleared back to the default,
- *  and `themes/_active.json` names the open document. Production is untouched. */
-function applyTheme(theme, slug, dirs) {
-  mkdirSync(dirs.colorsAndTypeDir, { recursive: true });
-  writeFileSync(
-    join(dirs.colorsAndTypeDir, '_working.json'),
-    JSON.stringify(theme.colorsAndType, null, 2),
-  );
+/** The apply door's write set, reproduced: clear every working delta and point
+ *  `themes/_active.json` at the open document. Production is untouched. */
+function applyTheme(slug, dirs) {
+  const colorsWorking = join(dirs.colorsAndTypeDir, '_working.json');
+  if (existsSync(colorsWorking)) rmSync(colorsWorking);
 
   for (const comp of componentNames(dirs.componentConfigsDir)) {
     const workingPath = join(dirs.componentConfigsDir, comp, '_working.json');
-    const embedded = theme.componentConfigs[comp];
-    if (embedded) writeFileSync(workingPath, JSON.stringify({ ...embedded, component: comp }, null, 2));
-    else if (existsSync(workingPath)) rmSync(workingPath);
+    if (existsSync(workingPath)) rmSync(workingPath);
   }
 
   writeFileSync(join(dirs.themesDir, '_active.json'), JSON.stringify({ activeFile: slug }));

package/dist-plugin/adjust/index.d.cts

@@ -1,4 +1,4 @@
-import { A as AliasDiskValue, a as ComponentConfig } from '../themeTypes-DMHZOnUn.cjs';
+import { A as AliasDiskValue, a as ComponentConfig } from '../themeTypes-DSwKq-bj.cjs';
 export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-DBN0RPuT.cjs';
 
 type AdjustKind = 'radius' | 'padding' | 'gap' | 'border-width';

package/dist-plugin/adjust/index.d.ts

@@ -1,4 +1,4 @@
-import { A as AliasDiskValue, a as ComponentConfig } from '../themeTypes-DMHZOnUn.js';
+import { A as AliasDiskValue, a as ComponentConfig } from '../themeTypes-DSwKq-bj.js';
 export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-DBN0RPuT.js';
 
 type AdjustKind = 'radius' | 'padding' | 'gap' | 'border-width';

package/dist-plugin/generateColorsAndType/index.d.cts

@@ -1,4 +1,4 @@
-import { F as FontSource, b as FontStack, G as GradientDiskToken, O as Oklch, H as HarmonyMode, C as ColorsAndType } from '../themeTypes-DMHZOnUn.cjs';
+import { F as FontSource, b as FontStack, G as GradientDiskToken, O as Oklch, H as HarmonyMode, C as ColorsAndType } from '../themeTypes-DSwKq-bj.cjs';
 export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-DBN0RPuT.cjs';
 
 /**

package/dist-plugin/generateColorsAndType/index.d.ts

@@ -1,4 +1,4 @@
-import { F as FontSource, b as FontStack, G as GradientDiskToken, O as Oklch, H as HarmonyMode, C as ColorsAndType } from '../themeTypes-DMHZOnUn.js';
+import { F as FontSource, b as FontStack, G as GradientDiskToken, O as Oklch, H as HarmonyMode, C as ColorsAndType } from '../themeTypes-DSwKq-bj.js';
 export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-DBN0RPuT.js';
 
 /**

package/dist-plugin/index.cjs

@@ -1931,6 +1931,50 @@ ${lines.join("\n")}
     if (!cfg) return null;
     return { data: cfg, source: "default" };
   }
+  function resolveSavedColorsAndType(theme) {
+    if (theme?.colorsAndType) return theme.colorsAndType;
+    const shipped = colorsAndTypeResource.readJson("default");
+    return shipped ? normalizeColorsAndType(shipped) : null;
+  }
+  function resolveSavedComponentConfig(comp, theme) {
+    const embedded = theme?.componentConfigs[comp];
+    if (embedded) return { ...embedded, component: comp };
+    return readComponentConfig(comp, "default");
+  }
+  function sameJsonValue(a, b) {
+    if (a === null || b === null) return a === b;
+    if (typeof a !== typeof b) return false;
+    if (typeof a !== "object") return a === b;
+    if (Array.isArray(a) || Array.isArray(b)) {
+      return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((value, i) => sameJsonValue(value, b[i]));
+    }
+    const aRecord = a;
+    const bRecord = b;
+    const aKeys = Object.keys(aRecord).sort();
+    const bKeys = Object.keys(bRecord).sort();
+    return aKeys.length === bKeys.length && aKeys.every((key, i) => key === bKeys[i] && sameJsonValue(aRecord[key], bRecord[key]));
+  }
+  function pruneMatchingWorking(theme) {
+    const colorsWorking = colorsAndTypeResource.readWorking();
+    const savedColors = resolveSavedColorsAndType(theme);
+    if (colorsWorking !== null && savedColors !== null && sameJsonValue(normalizeColorsAndType(colorsWorking), savedColors)) {
+      colorsAndTypeResource.clearWorking();
+    }
+    for (const comp of listComponentNames()) {
+      const r = componentResource(comp);
+      const working = r.readWorking();
+      if (working !== null && sameJsonValue(working, resolveSavedComponentConfig(comp, theme))) {
+        r.clearWorking();
+      }
+    }
+  }
+  function clearAllWorking() {
+    colorsAndTypeResource.clearWorking();
+    if (!import_fs4.default.existsSync(COMPONENT_CONFIGS_DIR)) return;
+    for (const entry of import_fs4.default.readdirSync(COMPONENT_CONFIGS_DIR, { withFileTypes: true })) {
+      if (entry.isDirectory()) componentResource(entry.name).clearWorking();
+    }
+  }
   function formatAliasGradient(v) {
     const stopColor = (s) => {
       const base = s.color.startsWith("--") ? `var(${s.color})` : s.color;
@@ -2037,7 +2081,10 @@ ${lines.join("\n")}
   async function handleSetWorkingColorsAndType({ req, res }) {
     const body = await readBufferBody(req, res);
     if (!body) return;
-    colorsAndTypeResource.writeWorking(body);
+    const normalized = normalizeColorsAndType(body);
+    const saved = resolveSavedColorsAndType(activeTheme());
+    if (saved !== null && sameJsonValue(normalized, saved)) colorsAndTypeResource.clearWorking();
+    else colorsAndTypeResource.writeWorking(body);
     jsonResponse(res, 200, { ok: true });
   }
   async function handleClearWorkingColorsAndType({ res }) {
@@ -2139,7 +2186,9 @@ ${lines.join("\n")}
     if (rejectUnknownComponent(res, comp)) return;
     const body = await readBufferBody(req, res);
     if (!body) return;
-    componentResource(comp).writeWorking(body);
+    const r = componentResource(comp);
+    if (sameJsonValue(body, resolveSavedComponentConfig(comp, activeTheme()))) r.clearWorking();
+    else r.writeWorking(body);
     jsonResponse(res, 200, { ok: true });
   }
   async function handleClearComponentWorking({ params, res }) {
@@ -2261,6 +2310,7 @@ ${lines.join("\n")}
       return;
     }
     themesResource.setActiveName(fileName);
+    pruneMatchingWorking(readTheme(fileName)?.theme ?? null);
     jsonResponse(res, 200, { ok: true, activeFile: fileName });
   }
   async function handleThemeByName({ params, req, res }) {
@@ -2292,6 +2342,7 @@ ${lines.join("\n")}
         }
       }
       writeTheme(fileName, theme);
+      if (themesResource.getActiveName() === fileName) pruneMatchingWorking(theme);
       jsonResponse(res, 200, { ok: true, fileName });
       return;
     }
@@ -2308,10 +2359,35 @@ ${lines.join("\n")}
         return;
       }
       if (import_fs4.default.existsSync(filePath)) {
+        const deletingActive = themesResource.getActiveName() === fileName;
+        const liveColors = deletingActive ? resolveLiveColorsAndType(activeTheme()) : null;
+        const liveComponents = {};
+        if (deletingActive) {
+          for (const comp of listComponentNames()) {
+            const resolved = resolveLiveComponentConfig(comp, activeTheme());
+            if (resolved) liveComponents[comp] = resolved.data;
+          }
+        }
         import_fs4.default.unlinkSync(filePath);
-        if (themesResource.existingPath(fileName) === null && themesResource.getActiveName() === fileName) {
+        if (themesResource.existingPath(fileName) === null && deletingActive) {
           themesResource.setActiveName("default");
         }
+        if (deletingActive) {
+          const replacement = activeTheme();
+          const savedColors = resolveSavedColorsAndType(replacement);
+          if (liveColors && !sameJsonValue(liveColors.data, savedColors)) {
+            colorsAndTypeResource.writeWorking(liveColors.data);
+          } else {
+            colorsAndTypeResource.clearWorking();
+          }
+          for (const comp of listComponentNames()) {
+            const r = componentResource(comp);
+            const live = liveComponents[comp] ?? null;
+            const saved = resolveSavedComponentConfig(comp, replacement);
+            if (live !== null && !sameJsonValue(live, saved)) r.writeWorking({ ...live });
+            else r.clearWorking();
+          }
+        }
       } else if (themesResource.existingPath(fileName)) {
         jsonResponse(res, 403, {
           error: "Cannot delete a theme shipped with the package. Saving it creates a local copy; deleting that copy restores the shipped version.",
@@ -2332,20 +2408,12 @@ ${lines.join("\n")}
       return;
     }
     const { theme } = read;
-    const isDefault = fileName === "default";
-    if (!isDefault && !theme.colorsAndType) {
+    if (!theme.colorsAndType) {
       jsonResponse(res, 422, { error: "This theme carries no colors and type" });
       return;
     }
-    if (isDefault) colorsAndTypeResource.clearWorking();
-    else colorsAndTypeResource.writeWorking(theme.colorsAndType);
+    clearAllWorking();
     const knownComponents = listComponentNames();
-    for (const comp of knownComponents) {
-      const embedded = isDefault ? void 0 : theme.componentConfigs[comp];
-      const r = componentResource(comp);
-      if (embedded) r.writeWorking({ ...embedded, component: comp });
-      else r.clearWorking();
-    }
     themesResource.setActiveName(fileName);
     const resolvedConfigs = {};
     for (const comp of knownComponents) {

package/dist-plugin/index.js

@@ -656,6 +656,50 @@ ${lines.join("\n")}
     if (!cfg) return null;
     return { data: cfg, source: "default" };
   }
+  function resolveSavedColorsAndType(theme) {
+    if (theme?.colorsAndType) return theme.colorsAndType;
+    const shipped = colorsAndTypeResource.readJson("default");
+    return shipped ? normalizeColorsAndType(shipped) : null;
+  }
+  function resolveSavedComponentConfig(comp, theme) {
+    const embedded = theme?.componentConfigs[comp];
+    if (embedded) return { ...embedded, component: comp };
+    return readComponentConfig(comp, "default");
+  }
+  function sameJsonValue(a, b) {
+    if (a === null || b === null) return a === b;
+    if (typeof a !== typeof b) return false;
+    if (typeof a !== "object") return a === b;
+    if (Array.isArray(a) || Array.isArray(b)) {
+      return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((value, i) => sameJsonValue(value, b[i]));
+    }
+    const aRecord = a;
+    const bRecord = b;
+    const aKeys = Object.keys(aRecord).sort();
+    const bKeys = Object.keys(bRecord).sort();
+    return aKeys.length === bKeys.length && aKeys.every((key, i) => key === bKeys[i] && sameJsonValue(aRecord[key], bRecord[key]));
+  }
+  function pruneMatchingWorking(theme) {
+    const colorsWorking = colorsAndTypeResource.readWorking();
+    const savedColors = resolveSavedColorsAndType(theme);
+    if (colorsWorking !== null && savedColors !== null && sameJsonValue(normalizeColorsAndType(colorsWorking), savedColors)) {
+      colorsAndTypeResource.clearWorking();
+    }
+    for (const comp of listComponentNames()) {
+      const r = componentResource(comp);
+      const working = r.readWorking();
+      if (working !== null && sameJsonValue(working, resolveSavedComponentConfig(comp, theme))) {
+        r.clearWorking();
+      }
+    }
+  }
+  function clearAllWorking() {
+    colorsAndTypeResource.clearWorking();
+    if (!fs.existsSync(COMPONENT_CONFIGS_DIR)) return;
+    for (const entry of fs.readdirSync(COMPONENT_CONFIGS_DIR, { withFileTypes: true })) {
+      if (entry.isDirectory()) componentResource(entry.name).clearWorking();
+    }
+  }
   function formatAliasGradient(v) {
     const stopColor = (s) => {
       const base = s.color.startsWith("--") ? `var(${s.color})` : s.color;
@@ -762,7 +806,10 @@ ${lines.join("\n")}
   async function handleSetWorkingColorsAndType({ req, res }) {
     const body = await readBufferBody(req, res);
     if (!body) return;
-    colorsAndTypeResource.writeWorking(body);
+    const normalized = normalizeColorsAndType(body);
+    const saved = resolveSavedColorsAndType(activeTheme());
+    if (saved !== null && sameJsonValue(normalized, saved)) colorsAndTypeResource.clearWorking();
+    else colorsAndTypeResource.writeWorking(body);
     jsonResponse(res, 200, { ok: true });
   }
   async function handleClearWorkingColorsAndType({ res }) {
@@ -864,7 +911,9 @@ ${lines.join("\n")}
     if (rejectUnknownComponent(res, comp)) return;
     const body = await readBufferBody(req, res);
     if (!body) return;
-    componentResource(comp).writeWorking(body);
+    const r = componentResource(comp);
+    if (sameJsonValue(body, resolveSavedComponentConfig(comp, activeTheme()))) r.clearWorking();
+    else r.writeWorking(body);
     jsonResponse(res, 200, { ok: true });
   }
   async function handleClearComponentWorking({ params, res }) {
@@ -986,6 +1035,7 @@ ${lines.join("\n")}
       return;
     }
     themesResource.setActiveName(fileName);
+    pruneMatchingWorking(readTheme(fileName)?.theme ?? null);
     jsonResponse(res, 200, { ok: true, activeFile: fileName });
   }
   async function handleThemeByName({ params, req, res }) {
@@ -1017,6 +1067,7 @@ ${lines.join("\n")}
         }
       }
       writeTheme(fileName, theme);
+      if (themesResource.getActiveName() === fileName) pruneMatchingWorking(theme);
       jsonResponse(res, 200, { ok: true, fileName });
       return;
     }
@@ -1033,10 +1084,35 @@ ${lines.join("\n")}
         return;
       }
       if (fs.existsSync(filePath)) {
+        const deletingActive = themesResource.getActiveName() === fileName;
+        const liveColors = deletingActive ? resolveLiveColorsAndType(activeTheme()) : null;
+        const liveComponents = {};
+        if (deletingActive) {
+          for (const comp of listComponentNames()) {
+            const resolved = resolveLiveComponentConfig(comp, activeTheme());
+            if (resolved) liveComponents[comp] = resolved.data;
+          }
+        }
         fs.unlinkSync(filePath);
-        if (themesResource.existingPath(fileName) === null && themesResource.getActiveName() === fileName) {
+        if (themesResource.existingPath(fileName) === null && deletingActive) {
           themesResource.setActiveName("default");
         }
+        if (deletingActive) {
+          const replacement = activeTheme();
+          const savedColors = resolveSavedColorsAndType(replacement);
+          if (liveColors && !sameJsonValue(liveColors.data, savedColors)) {
+            colorsAndTypeResource.writeWorking(liveColors.data);
+          } else {
+            colorsAndTypeResource.clearWorking();
+          }
+          for (const comp of listComponentNames()) {
+            const r = componentResource(comp);
+            const live = liveComponents[comp] ?? null;
+            const saved = resolveSavedComponentConfig(comp, replacement);
+            if (live !== null && !sameJsonValue(live, saved)) r.writeWorking({ ...live });
+            else r.clearWorking();
+          }
+        }
       } else if (themesResource.existingPath(fileName)) {
         jsonResponse(res, 403, {
           error: "Cannot delete a theme shipped with the package. Saving it creates a local copy; deleting that copy restores the shipped version.",
@@ -1057,20 +1133,12 @@ ${lines.join("\n")}
       return;
     }
     const { theme } = read;
-    const isDefault = fileName === "default";
-    if (!isDefault && !theme.colorsAndType) {
+    if (!theme.colorsAndType) {
       jsonResponse(res, 422, { error: "This theme carries no colors and type" });
       return;
     }
-    if (isDefault) colorsAndTypeResource.clearWorking();
-    else colorsAndTypeResource.writeWorking(theme.colorsAndType);
+    clearAllWorking();
     const knownComponents = listComponentNames();
-    for (const comp of knownComponents) {
-      const embedded = isDefault ? void 0 : theme.componentConfigs[comp];
-      const r = componentResource(comp);
-      if (embedded) r.writeWorking({ ...embedded, component: comp });
-      else r.clearWorking();
-    }
     themesResource.setActiveName(fileName);
     const resolvedConfigs = {};
     for (const comp of knownComponents) {

package/dist-plugin/{themeTypes-DMHZOnUn.d.cts → themeTypes-DSwKq-bj.d.cts}

@@ -134,9 +134,8 @@ interface GradientDiskToken {
 }
 /**
  * Where a live read resolved from: the unsaved `_working` buffer, the open
- * theme's embedded copy, or the shipped default. It says which layer answered,
- * never whether the content was edited — applying a theme fills the buffer for
- * every layer it carries.
+ * theme's embedded copy, or the shipped default. A `working` source is an
+ * unsaved delta from the active theme.
  */
 type LiveSource = 'working' | 'theme' | 'default';
 interface ColorsAndType {

package/dist-plugin/{themeTypes-DMHZOnUn.d.ts → themeTypes-DSwKq-bj.d.ts}

@@ -134,9 +134,8 @@ interface GradientDiskToken {
 }
 /**
  * Where a live read resolved from: the unsaved `_working` buffer, the open
- * theme's embedded copy, or the shipped default. It says which layer answered,
- * never whether the content was edited — applying a theme fills the buffer for
- * every layer it carries.
+ * theme's embedded copy, or the shipped default. A `working` source is an
+ * unsaved delta from the active theme.
  */
 type LiveSource = 'working' | 'theme' | 'default';
 interface ColorsAndType {

package/package.json

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

package/src/editor/core/themes/themeService.ts

@@ -63,9 +63,9 @@ export interface ApplyThemeResult {
 }
 
 /**
- * Open a theme: the server writes its embedded copies into the `_working`
- * buffers, clears the buffer of every component it does not carry, points
- * `themes/_active.json` at it and returns the resolved state in one payload.
+ * Open a theme: the server clears the `_working` buffers, points
+ * `themes/_active.json` at it, and returns the resolved state in one payload.
+ * Live reads then fall through to the theme's embedded layers.
  * Production is untouched, so trying a look cannot change what the site ships.
  * Clients follow with a full page reload; opening a theme is a "blow up the
  * world" action.

package/src/editor/core/themes/themeTypes.ts

@@ -112,9 +112,8 @@ export interface GradientDiskToken {
 
 /**
  * Where a live read resolved from: the unsaved `_working` buffer, the open
- * theme's embedded copy, or the shipped default. It says which layer answered,
- * never whether the content was edited — applying a theme fills the buffer for
- * every layer it carries.
+ * theme's embedded copy, or the shipped default. A `working` source is an
+ * unsaved delta from the active theme.
  */
 export type LiveSource = 'working' | 'theme' | 'default';
 
@@ -194,9 +193,10 @@ export interface ComponentConfigMeta {
 /**
  * A saved look, encapsulated: the colors and type plus a config for every
  * component that sits off its default, all carried by value. Themes are the
- * documents of the editor. Applying one opens it: its embedded copies land in
- * the reserved `_working` buffers and `themes/_active.json` names it. Saving
- * captures the live buffers back into it; Adopt publishes it, and only then is
+ * documents of the editor. Applying one opens it by clearing the reserved
+ * `_working` buffers and updating `themes/_active.json`; live reads fall through
+ * to its embedded copies. Saving captures live deltas back into it; Adopt
+ * publishes it, and only then is
  * `tokens.generated.css` rebaked.
  */
 export interface Theme {

package/src/editor/docs/content/themes-workflow.md

@@ -33,7 +33,7 @@ A theme is a document, and the editor works the way any editor does.
   `themes/_production.json`. Only **Adopt** changes it.
 
 Absence is the answer for anything untouched: a buffer exists only where the
-look sits off the shipped default, so a new project has none at all.
+live look diverges from the active theme, so a newly opened theme has none.
 
 ## Saving
 
@@ -56,9 +56,10 @@ to it, and the editor never overwrites it, so start your own with **Save As**.
 
 **Load** lists your saved themes and the seven example looks. Picking one shows
 it on the page as a preview with nothing written to disk, so you can try each
-look and compare. **Save** in that window opens the previewed theme: its copies
-fill the buffers, components it does not carry go back to their defaults, and
-the editor works on it from then on. **Cancel** returns you to where you were.
+look and compare. **Save** in that window opens the previewed theme: the active
+pointer changes, the buffers clear, components it does not carry fall through
+to their defaults, and the editor works on it from then on. **Cancel** returns
+you to where you were.
 Trying a look never changes what your site ships.
 
 **Colors and type only. Keep my shapes.** narrows the load to the palette and

package/src/editor/docs/content/where-themes-live.md

@@ -34,12 +34,13 @@ deleting anything else never breaks it.
 
 - **Editing** changes the page through CSS variables. The editor keeps your
   edits in the browser as you work and writes them to the `_working.json`
-  buffers when you save a component or capture the look. A buffer exists only
-  where your look sits off the shipped default, so a fresh project has none.
+  buffers when you save a component. A buffer exists only where the live layer
+  differs from the active theme's saved layer, so a fresh project has none.
 - **Save** captures the buffers into the open theme's file. That file is the
-  durable copy of your look.
-- **Load** fills the buffers from the theme you picked and points
-  `themes/_active.json` at it. Nothing else changes, so trying looks is free.
+  durable copy of your look; matching buffers are then removed.
+- **Load** clears the buffers and points `themes/_active.json` at the theme you
+  picked. Live reads fall through to that file. Nothing else changes, so trying
+  looks is free and ordinary switching changes only the pointer.
 - **Adopt** points `themes/_production.json` at the open theme, bakes it into
   `tokens.generated.css`, and rewrites `fonts.css` to match. It is the only
   action that changes what your site ships.

package/src/editor/docs/content.generated.ts

@@ -6,6 +6,6 @@ export const docContent: Record<string, string> = {
   "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/live-tokens/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/live-tokens/components` view.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
   "editing-tokens": "# Editing tokens\n\nA tour of the editor. The page behind it repaints on every change; saving\nwrites a theme file you can reload later.\n\nThe editor has two views:\n\n- **Tokens**: the design-system primitives (colour, type, spacing, and so on).\n  They apply everywhere your site uses them.\n- **Components**: per-component editors. Re-Assign what tokens a component uses\n  without changing the underlying system.\n\nThis page covers **Tokens**. For components, see\n[Creating components](creating-components.md).\n\n## Palettes\n\nMost colour work happens here. Each palette (Brand, Accent, Neutral, Canvas,\nSuccess, Warning, Info, Danger, and a few more) has:\n\n- **Base colour.** Pick a hex; the palette derives an 11-step ramp (100 to 950)\n  from it.\n- **Curves.** Two curves shape how lightness and saturation fall off across the\n  ramp. Drag the handles to bias it darker, lighter, or more saturated.\n- **Overrides.** Lock a single step to a hand-picked hex when the curve doesn't\n  land where you want.\n\nEditing a palette base ripples through every colour that depends on it, in real\ntime. Colours use OKLCH, so the ramp stays perceptually even across hues\nwithout muddy mid-tones.\n\n## Type\n\n- **Fonts.** Add sources from Google Fonts, Adobe (Typekit), a CSS URL, or an\n  inline `@font-face`. The font loads in the page as soon as you add it.\n- **Stacks.** Named font cascades you reference by token, such as a display\n  stack and a body stack.\n- **Sizes and weights.** A t-shirt scale (xs, sm, md, lg, xl, 2xl…) for size and\n  a numeric scale (100 to 900) for weight.\n\n## Spacing, radius, shadow\n\nNumeric scales with a slider per step.\n\n- **Spacing**: the padding, gap, and margin scale.\n- **Radius**: none through full.\n- **Shadow**: colour, offset, blur, spread, and opacity per step, with stacked\n  shadows supported.\n\nChange a step and every element using it repaints.\n\n## Overlays and gradients\n\n- **Overlays** are translucent tints layered over surfaces, like the subtle\n  tint a card gets on hover. Set a colour and opacity per state.\n- **Gradients** are reusable gradient tokens with a stop list and direction, for\n  hero panels and accent backgrounds.\n\n## Columns\n\nThe page-grid overlay. Set column count, gutter, and outer margin, and toggle\nthe visual guide with `Cmd/Ctrl+G`. Pages built on the column system reflow\nlive.\n\n## Saving\n\nThe editor saves to your browser continuously, so work survives a reload\nmid-edit. Writing a file is a separate step: the **Theme** panel at the foot of\nthe sidebar has **Save**, **Save As**, and **Load**, and each theme is one JSON\nfile under `src/live-tokens/data/themes/`.\n\nThe header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`). You can keep\nmany themes side by side; one is open at a time, and only **Adopt** publishes\none. See [Themes](themes-workflow.md) for the full lifecycle.\n",
   "getting-started": "# Getting started\n\nScaffold a live token site in a moments. You need Node 20 or later, a\npackage manager (npm, pnpm, or yarn), and a browser. Open claude code in your repo and start building.\n\n## Scaffold a new app\n\n```bash\nnpm create @motion-proto/live-tokens@latest my-app\ncd my-app\nnpm install\nnpm run dev\n```\n\nOpen the URL Vite prints (usually `http://localhost:5173`). You get a\none-page Svelte + Vite app that depends on the published package, with the\neditor wired up and the full component set ready to import.\n\n`npx @motion-proto/live-tokens create my-app` runs the same scaffold without\nthe initialiser package.\n\n### What the scaffold gives you\n\nEvery editable file lives under `src/` and is committed, so `npm install` and\nversion upgrades never touch your styles. The package code stays in\n`node_modules`.\n\n| Path | What it is |\n|------|------------|\n| `src/pages/Home.svelte` | The starter page. Replace it with your own content. |\n| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds dev-only routes under a reserved `/live-tokens/*` namespace: `/live-tokens/editor`, `/live-tokens/components`, and `/live-tokens/docs`. |\n| `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |\n| `src/styles/site.css` | Themed page typography, yours to edit. |\n\n## Your first edit\n\n1. Run `npm run dev` and open the home page.\n2. Click **Open Token Editor**, or visit `/live-tokens/editor`. The editor opens beside\n   the page.\n3. Open **Palettes**, pick **Brand**, and change the base hex. The page\n   repaints as you type.\n4. In the **Theme** panel at the foot of the sidebar, choose **Save As**. Your\n   theme appears as JSON under `src/live-tokens/data/themes/`.\n5. Reload. The editor reopens on your theme, so the page returns as you left\n   it.\n\n## What you just changed\n\nEvery edit sets a CSS custom property on `:root`. Your components read those\nproperties through `var(--...)`. There is no token build step and no\npreprocessor rewriting your code: the page renders against plain CSS variables\nthe editor swaps live.\n\nTo ship, click **Adopt** in the Theme panel. That saves the open theme and bakes\nit into `src/live-tokens/data/tokens.generated.css`, which your build bundles\nalongside `tokens.css`. Adopt is the only action that changes what your site\nships, so try any look you like first. The editor itself never reaches\nproduction.\n\nAlready have a Svelte 5 + Vite app? The\n[README](https://github.com/motionproto/live-tokens#readme) covers installing\ninto an existing project.\n\n## Where to go next\n\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own component\n  editable.\n",
-  "themes-workflow": "# Themes\n\nSave your work, switch between looks, and ship one to production.\n\n## The Theme panel\n\nThe **Theme** panel at the foot of the editor sidebar holds the whole look:\ncolors, type, and a setting for every component you changed, in one file. It\ncarries the name the look ships under, whether production is running it, and\n**Adopt**. Two parts sit under it, each a read-out rather than a file to manage.\n\n- **Colors & Type** holds the design tokens. Components read those tokens to\n  define their appearance. It names the two faces the page is showing.\n- **Components** counts how many components run something the theme does not\n  carry, and opens the component editors.\n\nA theme holds its own copy of every part, so one theme can never break another.\n\n## How themes work\n\nA theme is a document, and the editor works the way any editor does.\n\n- **A theme** is a named JSON file in `src/live-tokens/data/themes/`. It carries\n  the whole look: the colors and type plus a setting for every component you\n  changed.\n- **The open theme** is the one the editor is working on, named in\n  `themes/_active.json`. One at a time.\n- **Your unsaved edits** are what the page shows right now. The editor keeps\n  them in your browser as you work and writes them to a buffer, `_working.json`,\n  one slot per part of the look. **Save** captures that buffer into the open\n  theme.\n- **The production theme** is the one your site ships, named in\n  `themes/_production.json`. Only **Adopt** changes it.\n\nAbsence is the answer for anything untouched: a buffer exists only where the\nlook sits off the shipped default, so a new project has none at all.\n\n## Saving\n\nIn the Theme panel:\n\n- **Save** captures the look on screen into the open theme. Your colors and type\n  go in as part of it, so there is nothing to save first.\n- **Save As** names a new theme. Use it for your first save and for forking.\n\nComponent edits are the exception. Each component editor holds its own unsaved\nstate, which this panel cannot write, so save a component in its editor before\ncapturing it. The panel says how many are waiting.\n\nNames are tidied to lowercase with hyphens, so \"My Brand!\" becomes `my-brand`,\nand a leading underscore is dropped: those names are reserved for the buffer.\n**Motion Proto** is the built-in theme and is read-only. You can always return\nto it, and the editor never overwrites it, so start your own with **Save As**.\n\n## Switching\n\n**Load** lists your saved themes and the seven example looks. Picking one shows\nit on the page as a preview with nothing written to disk, so you can try each\nlook and compare. **Save** in that window opens the previewed theme: its copies\nfill the buffers, components it does not carry go back to their defaults, and\nthe editor works on it from then on. **Cancel** returns you to where you were.\nTrying a look never changes what your site ships.\n\n**Colors and type only. Keep my shapes.** narrows the load to the palette and\nthe fonts: your component settings stay as they are and the theme you have open\nstays open. Saved colors and type files are listed there too, marked *colors &\ntype*, and picking one is always that narrower load.\n\n## Shipping\n\n**Adopt**, in the Theme panel, is the \"ship it\" step, and it ships the whole\nlook. It saves the open theme, then bakes that theme into\n`src/live-tokens/data/tokens.generated.css`, which your build bundles alongside\n`tokens.css`: the colors and type plus every component the theme carries. Fonts\nregenerate to match. The line under the theme name says whether production is\nrunning this theme.\n\nProduction is one saved theme, so nothing else publishes. Trying a look, moving\na token, saving a theme: all of it leaves the generated CSS alone until you\nAdopt. A component editor's Adopt runs the same whole-look step, because a\ncomponent never ships alone. Adopting while Motion Proto is open saves your look\nas a theme of your own first, since the built-in one is read-only.\n\nProduction builds (`npm run build`) ship only that plain CSS and your\ncomponents. No editor, no JSON loading, no runtime indirection.\n\n## Keeping your work safe\n\nEverything under `src/live-tokens/data/` is plain JSON, so commit it. Themes show\nup as readable diffs you can review per branch, and the buffer shows up as the\nwork you have not saved into a theme yet. Nothing is backed up anywhere else:\ngit is your safety net. To experiment freely, **Save As** a new name first, then\nedit.\n\n## Where to go next\n\n- **[Where themes live](where-themes-live.md)**: the files behind all of this,\n  and what writes each one.\n- **[Creating components](creating-components.md)**: make your own components\n  editable in the same editor.\n",
-  "where-themes-live": "# Where themes live\n\nEverything the editor writes is plain JSON and CSS inside your project. There\nis no database and no hidden state: the files are the storage, and git is the\nhistory.\n\n## The data tree\n\n```\nsrc/live-tokens/data/\n  themes/\n    _active.json         names the theme the editor has open\n    _production.json     names the theme your site ships\n    default.json         Motion Proto, the built-in look, rewritten at boot\n    my-brand.json        a saved theme: the whole look in one file\n  colors-and-type/\n    _working.json        unsaved colors and type edits\n  component-configs/\n    button/\n      default.json       Button's shipped settings, derived at boot\n      _working.json      unsaved Button edits\n      my-button.json     a preset you saved from the Button editor\n  tokens.generated.css   the baked CSS your production build ships\nsrc/system/styles/\n  tokens.css             your token vocabulary, hand-authored, never written\n  fonts.css              font imports, rewritten when you Adopt\n```\n\nA saved theme carries the whole look by value: the colors and type plus a\nsetting for every component you changed. It depends on no other file, so\ndeleting anything else never breaks it.\n\n## What writes when\n\n- **Editing** changes the page through CSS variables. The editor keeps your\n  edits in the browser as you work and writes them to the `_working.json`\n  buffers when you save a component or capture the look. A buffer exists only\n  where your look sits off the shipped default, so a fresh project has none.\n- **Save** captures the buffers into the open theme's file. That file is the\n  durable copy of your look.\n- **Load** fills the buffers from the theme you picked and points\n  `themes/_active.json` at it. Nothing else changes, so trying looks is free.\n- **Adopt** points `themes/_production.json` at the open theme, bakes it into\n  `tokens.generated.css`, and rewrites `fonts.css` to match. It is the only\n  action that changes what your site ships.\n\nThe `default.json` files are the shipped baseline. The editor derives them at\nboot and refreshes them when the package updates; it never saves your work\nover them.\n\n## What to commit\n\nAll of it. The data tree is designed to live in git: themes diff readably, the\ntwo pointers say what is open and what ships, and a `_working.json` in a diff\nis exactly the work you have not yet saved into a theme. Nothing is backed up\nanywhere else.\n\n## Where to go next\n\n- **[Themes](themes-workflow.md)**: the workflow built on these files: saving,\n  loading, and shipping.\n",
+  "themes-workflow": "# Themes\n\nSave your work, switch between looks, and ship one to production.\n\n## The Theme panel\n\nThe **Theme** panel at the foot of the editor sidebar holds the whole look:\ncolors, type, and a setting for every component you changed, in one file. It\ncarries the name the look ships under, whether production is running it, and\n**Adopt**. Two parts sit under it, each a read-out rather than a file to manage.\n\n- **Colors & Type** holds the design tokens. Components read those tokens to\n  define their appearance. It names the two faces the page is showing.\n- **Components** counts how many components run something the theme does not\n  carry, and opens the component editors.\n\nA theme holds its own copy of every part, so one theme can never break another.\n\n## How themes work\n\nA theme is a document, and the editor works the way any editor does.\n\n- **A theme** is a named JSON file in `src/live-tokens/data/themes/`. It carries\n  the whole look: the colors and type plus a setting for every component you\n  changed.\n- **The open theme** is the one the editor is working on, named in\n  `themes/_active.json`. One at a time.\n- **Your unsaved edits** are what the page shows right now. The editor keeps\n  them in your browser as you work and writes them to a buffer, `_working.json`,\n  one slot per part of the look. **Save** captures that buffer into the open\n  theme.\n- **The production theme** is the one your site ships, named in\n  `themes/_production.json`. Only **Adopt** changes it.\n\nAbsence is the answer for anything untouched: a buffer exists only where the\nlive look diverges from the active theme, so a newly opened theme has none.\n\n## Saving\n\nIn the Theme panel:\n\n- **Save** captures the look on screen into the open theme. Your colors and type\n  go in as part of it, so there is nothing to save first.\n- **Save As** names a new theme. Use it for your first save and for forking.\n\nComponent edits are the exception. Each component editor holds its own unsaved\nstate, which this panel cannot write, so save a component in its editor before\ncapturing it. The panel says how many are waiting.\n\nNames are tidied to lowercase with hyphens, so \"My Brand!\" becomes `my-brand`,\nand a leading underscore is dropped: those names are reserved for the buffer.\n**Motion Proto** is the built-in theme and is read-only. You can always return\nto it, and the editor never overwrites it, so start your own with **Save As**.\n\n## Switching\n\n**Load** lists your saved themes and the seven example looks. Picking one shows\nit on the page as a preview with nothing written to disk, so you can try each\nlook and compare. **Save** in that window opens the previewed theme: the active\npointer changes, the buffers clear, components it does not carry fall through\nto their defaults, and the editor works on it from then on. **Cancel** returns\nyou to where you were.\nTrying a look never changes what your site ships.\n\n**Colors and type only. Keep my shapes.** narrows the load to the palette and\nthe fonts: your component settings stay as they are and the theme you have open\nstays open. Saved colors and type files are listed there too, marked *colors &\ntype*, and picking one is always that narrower load.\n\n## Shipping\n\n**Adopt**, in the Theme panel, is the \"ship it\" step, and it ships the whole\nlook. It saves the open theme, then bakes that theme into\n`src/live-tokens/data/tokens.generated.css`, which your build bundles alongside\n`tokens.css`: the colors and type plus every component the theme carries. Fonts\nregenerate to match. The line under the theme name says whether production is\nrunning this theme.\n\nProduction is one saved theme, so nothing else publishes. Trying a look, moving\na token, saving a theme: all of it leaves the generated CSS alone until you\nAdopt. A component editor's Adopt runs the same whole-look step, because a\ncomponent never ships alone. Adopting while Motion Proto is open saves your look\nas a theme of your own first, since the built-in one is read-only.\n\nProduction builds (`npm run build`) ship only that plain CSS and your\ncomponents. No editor, no JSON loading, no runtime indirection.\n\n## Keeping your work safe\n\nEverything under `src/live-tokens/data/` is plain JSON, so commit it. Themes show\nup as readable diffs you can review per branch, and the buffer shows up as the\nwork you have not saved into a theme yet. Nothing is backed up anywhere else:\ngit is your safety net. To experiment freely, **Save As** a new name first, then\nedit.\n\n## Where to go next\n\n- **[Where themes live](where-themes-live.md)**: the files behind all of this,\n  and what writes each one.\n- **[Creating components](creating-components.md)**: make your own components\n  editable in the same editor.\n",
+  "where-themes-live": "# Where themes live\n\nEverything the editor writes is plain JSON and CSS inside your project. There\nis no database and no hidden state: the files are the storage, and git is the\nhistory.\n\n## The data tree\n\n```\nsrc/live-tokens/data/\n  themes/\n    _active.json         names the theme the editor has open\n    _production.json     names the theme your site ships\n    default.json         Motion Proto, the built-in look, rewritten at boot\n    my-brand.json        a saved theme: the whole look in one file\n  colors-and-type/\n    _working.json        unsaved colors and type edits\n  component-configs/\n    button/\n      default.json       Button's shipped settings, derived at boot\n      _working.json      unsaved Button edits\n      my-button.json     a preset you saved from the Button editor\n  tokens.generated.css   the baked CSS your production build ships\nsrc/system/styles/\n  tokens.css             your token vocabulary, hand-authored, never written\n  fonts.css              font imports, rewritten when you Adopt\n```\n\nA saved theme carries the whole look by value: the colors and type plus a\nsetting for every component you changed. It depends on no other file, so\ndeleting anything else never breaks it.\n\n## What writes when\n\n- **Editing** changes the page through CSS variables. The editor keeps your\n  edits in the browser as you work and writes them to the `_working.json`\n  buffers when you save a component. A buffer exists only where the live layer\n  differs from the active theme's saved layer, so a fresh project has none.\n- **Save** captures the buffers into the open theme's file. That file is the\n  durable copy of your look; matching buffers are then removed.\n- **Load** clears the buffers and points `themes/_active.json` at the theme you\n  picked. Live reads fall through to that file. Nothing else changes, so trying\n  looks is free and ordinary switching changes only the pointer.\n- **Adopt** points `themes/_production.json` at the open theme, bakes it into\n  `tokens.generated.css`, and rewrites `fonts.css` to match. It is the only\n  action that changes what your site ships.\n\nThe `default.json` files are the shipped baseline. The editor derives them at\nboot and refreshes them when the package updates; it never saves your work\nover them.\n\n## What to commit\n\nAll of it. The data tree is designed to live in git: themes diff readably, the\ntwo pointers say what is open and what ships, and a `_working.json` in a diff\nis exactly the work you have not yet saved into a theme. Nothing is backed up\nanywhere else.\n\n## Where to go next\n\n- **[Themes](themes-workflow.md)**: the workflow built on these files: saving,\n  loading, and shipping.\n",
 };

package/src/editor/ui/ThemePanel.svelte

@@ -400,8 +400,8 @@
             + `saved settings were skipped:\n\n${result.skippedComponents.join(', ')}`,
         );
       }
-      // applyTheme opens the theme: it fills the working buffers and points
-      // `themes/_active.json` at it. Reload to rehydrate the editor from those.
+      // applyTheme opens the theme: it clears working deltas and points
+      // `themes/_active.json` at it. Reload to rehydrate through the resolver.
       window.location.reload();
     } catch (err) {
       window.alert(`Failed to load theme: ${(err as Error).message}`);
@@ -511,8 +511,8 @@
   async function handleDelete(row: LoadRow) {
     if (row.isProtected) return;
     if (row.kind === 'layer') return deleteColorsFile(row);
-    // Deleting the open theme is legal: the working buffer survives its
-    // document, so the look on screen stays. Where open lands depends on
+    // Deleting the open theme is legal: the server materialises only the
+    // deltas needed to keep the look on screen. Where open lands depends on
     // something the client can't see — deleting a local copy that shadows a
     // shipped theme restores the shipped one and keeps naming it, while
     // deleting a local-only theme sends open back to Motion Proto.

package/src/system/components/FloatingTokenTags.css

@@ -7,6 +7,7 @@
  */
 
 .ftt-stage {
+  --ftt-contrast-color: var(--color-white);
   position: relative;
   width: 100%;
   height: 100%;
@@ -73,7 +74,7 @@
 }
 
 .ftt-string {
-  stroke: #d4ccc6;
+  stroke: var(--ftt-contrast-color);
   stroke-width: 2;
   stroke-linecap: round;
   vector-effect: non-scaling-stroke;

package/src/system/components/FloatingTokenTags.svelte

@@ -35,6 +35,7 @@
 <script lang="ts">
   import MenuSelect from './MenuSelect.svelte';
   import { SvelteMap } from 'svelte/reactivity';
+  import { contrastTokenForBackground } from '../internal/backgroundContrast';
   // `.ftt-tag` is hand-rolled (not Badge) so editing badge-* tokens doesn't
   // repaint the playground. The dropdown uses MenuSelect on purpose.
   import './FloatingTokenTags.css';
@@ -189,10 +190,22 @@
     return name ? `var(${name})` : undefined;
   }
 
+  let lastPageBackground = '';
+  function syncConnectorContrast() {
+    if (!stageEl) return;
+    const styles = getComputedStyle(stageEl);
+    const pageBackground = styles.getPropertyValue('--page-bg').trim();
+    if (pageBackground === lastPageBackground) return;
+    lastPageBackground = pageBackground;
+    const token = contrastTokenForBackground(pageBackground);
+    stageEl.style.setProperty('--ftt-contrast-color', `var(${token})`);
+  }
+
   // Kite strings and energy balls are recomputed each frame from the box's
   // measured rect so intrinsic sizing drives anchor placement.
   function syncFrame() {
     if (!stageEl) return;
+    syncConnectorContrast();
     const stageRect = stageEl.getBoundingClientRect();
     if (stageRect.width === 0 || stageRect.height === 0) return;
 

package/src/system/internal/backgroundContrast.ts

@@ -0,0 +1,54 @@
+export type ContrastColorToken = '--color-black' | '--color-white';
+
+type Rgb = { r: number; g: number; b: number };
+
+const HEX_RE = /#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})\b/gi;
+const RGB_RE = /rgba?\(\s*([\d.]+%?)\s*[, ]\s*([\d.]+%?)\s*[, ]\s*([\d.]+%?)(?:\s*[,/]\s*[\d.]+%?)?\s*\)/gi;
+
+function channel(value: string): number {
+  const parsed = Number.parseFloat(value);
+  return value.endsWith('%') ? parsed * 2.55 : parsed;
+}
+
+function parseHex(hex: string): Rgb {
+  const full = hex.length <= 4
+    ? hex.slice(1).split('').map(part => part + part).join('')
+    : hex.slice(1, 7);
+  return {
+    r: Number.parseInt(full.slice(0, 2), 16),
+    g: Number.parseInt(full.slice(2, 4), 16),
+    b: Number.parseInt(full.slice(4, 6), 16),
+  };
+}
+
+function colorsIn(background: string): Rgb[] {
+  const colors: Rgb[] = [];
+  for (const match of background.matchAll(HEX_RE)) colors.push(parseHex(match[0]));
+  for (const match of background.matchAll(RGB_RE)) {
+    colors.push({ r: channel(match[1]), g: channel(match[2]), b: channel(match[3]) });
+  }
+  return colors;
+}
+
+function linearChannel(value: number): number {
+  const srgb = Math.max(0, Math.min(255, value)) / 255;
+  return srgb <= 0.04045 ? srgb / 12.92 : ((srgb + 0.055) / 1.055) ** 2.4;
+}
+
+function luminance({ r, g, b }: Rgb): number {
+  return 0.2126 * linearChannel(r) + 0.7152 * linearChannel(g) + 0.0722 * linearChannel(b);
+}
+
+/**
+ * Pick the invariant black/white token with the stronger minimum contrast
+ * against every explicit colour in a solid or gradient page background.
+ */
+export function contrastTokenForBackground(background: string): ContrastColorToken {
+  const colors = colorsIn(background);
+  if (colors.length === 0) return '--color-white';
+
+  const luminances = colors.map(luminance);
+  const blackMinimum = Math.min(...luminances.map(value => (value + 0.05) / 0.05));
+  const whiteMinimum = Math.min(...luminances.map(value => 1.05 / (value + 0.05)));
+  return blackMinimum >= whiteMinimum ? '--color-black' : '--color-white';
+}