@motion-proto/live-tokens 0.52.1 → 0.53.0

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

@@ -1,6 +1,23 @@
 import type { CurveAnchor } from '../../ui/curveEngine';
+import type { GradientValue } from './parsers/gradient';
 import type { Oklch } from '../palettes/oklch';
 import type { HarmonyAxis } from '../palettes/colorHarmony';
+/** Single source of truth for the theme schema version
+ *  (docs/plans/theme-completeness.md, Wave 2 step 5). It lives here, on the
+ *  shipped side: `vite-plugin/` is build tooling and is not in the tarball, so
+ *  anything under `src/` that reaches into it resolves in this repo and
+ *  nowhere else. `normalizeTheme.ts` re-exports this. */
+export const THEME_SCHEMA_VERSION = 4;
+
+/** What the completeness fill had to add to reach a whole theme. `components`
+ *  names each component the input carried no entry for; `aliases` counts keys
+ *  added to components it did carry; `orphans` counts keys it carries that the
+ *  current default no longer declares. */
+export interface ThemeFillReport {
+  components: string[];
+  aliases: number;
+  orphans: number;
+}
 
 export type GradientStyle = 'linear' | 'radial' | 'conic';
 
@@ -123,11 +140,22 @@ export interface GradientDiskToken {
 }
 
 /**
- * Where a live read resolved from: the unsaved `_working` buffer, the open
- * theme's embedded copy, or the shipped default. A `working` source is an
- * unsaved delta from the active theme.
+ * Where a live component config resolved from: the unsaved `_working`
+ * buffer, or the open theme's embedded copy. Every theme carries every
+ * component complete, so `working` is the only genuine divergence —
+ * anything else is what the open document itself resolves to.
+ */
+export type LiveSource = 'working' | 'theme';
+
+/**
+ * Where a live colors-and-type read resolved from. Unlike `LiveSource`, this
+ * keeps a third value: colors-and-type resolution is unchanged by the theme
+ * completeness work (docs/plans/theme-completeness.md Wave 4), so `default`
+ * still answers the one case completeness can't reach — the open theme's
+ * file itself is unreadable (a stale pointer, or deleted mid-session), so
+ * there is no document to resolve `working` or `theme` against.
  */
-export type LiveSource = 'working' | 'theme' | 'default';
+export type ColorsAndTypeSource = 'working' | 'theme' | 'default';
 
 export interface ColorsAndType {
   name: string;
@@ -148,8 +176,8 @@ export interface ColorsAndType {
    * handlers; read by `themeInit` to seed `openThemeSlug`. Not persisted.
    */
   _fileName?: string;
-  /** Server-attached marker: which of the three live layers answered. */
-  _source?: LiveSource;
+  /** Server-attached marker: which live layer answered. See `ColorsAndTypeSource`. */
+  _source?: ColorsAndTypeSource;
   /**
    * Migration stamp. Absent on legacy files, treated as 0; the loader runs
    * any registered theme migrations whose `fromVersion >= file.schemaVersion`.
@@ -174,7 +202,7 @@ export interface ColorsAndTypeMeta {
  *  gradients that can't compress to a single string. */
 export type AliasDiskValue =
   | string
-  | { kind: 'gradient'; value: { type: 'linear' | 'radial' | 'solid' | 'none'; angle: number; radius?: number; centerX?: number; aspectX?: number; aspectY?: number; stops: { position: number; color: string; opacity?: number }[] } };
+  | { kind: 'gradient'; value: GradientValue };
 
 export interface ComponentConfig {
   name: string;
@@ -188,7 +216,10 @@ export interface ComponentConfig {
    * theme, not a config file. Set by the component-configs GET handlers.
    */
   _fileName?: string;
-  /** Server-attached marker: which of the three live layers answered. */
+  /** Server-attached marker: which live layer answered — `working` the
+   *  buffer, `theme` the open document's embedded copy. No third value:
+   *  every theme carries every component, so there is no shipped-default
+   *  layer left to report (unlike `ColorsAndTypeSource`). */
   _source?: LiveSource;
   /**
    * Migration stamp. Absent on legacy files, treated as 0. See `ColorsAndType.schemaVersion`.
@@ -204,11 +235,11 @@ 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 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
+ * component this install has, all carried by value. Themes are the 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 {
@@ -217,14 +248,32 @@ export interface Theme {
   updatedAt: string;
   /** Migration stamp. 1 was the pointer form (colors-and-type + config
    *  basenames); 2 encapsulated it under a `theme` key; 3 spells that key
-   *  `colorsAndType`. The server rewrites older files at boot. */
-  schemaVersion: 3;
+   *  `colorsAndType`; 4 makes the theme complete (`docs/plans/
+   *  theme-completeness.md`, Wave 2) — every known component and every alias
+   *  key its `default.json` declares, by value. The server rewrites older
+   *  files at boot. */
+  schemaVersion: typeof THEME_SCHEMA_VERSION;
   /** Full colors-and-type content. */
   colorsAndType: ColorsAndType;
-  /** Component id → its config. Delta encoding: a component absent here is on
-   *  its default. Defaults are never inlined — the local `default.json` derived
-   *  from the component source is canonical, and a frozen copy would drift. */
+  /** Component id → its config, by value, one entry per component this
+   *  install has and every alias key that component's `default.json`
+   *  declares. `normalizeTheme` migrates each embedded config to the current
+   *  component schema and then fills any gap from the local default, on every
+   *  read (Waves 1 and 2 of `docs/plans/theme-completeness.md`); both the
+   *  migration and the fill are persisted on the next write, so a theme is a
+   *  whole-look document rather than a diff against a moving baseline.
+   *  `component-configs/<id>/default.json` is the derivation product of that
+   *  component's `:global(:root)`, not a resolution layer this map defers to
+   *  — a config for a component this install does not have, or an alias key
+   *  its current default no longer declares, is kept exactly as read (RJC 3)
+   *  rather than dropped. */
   componentConfigs: Record<string, ComponentConfig>;
+  /** Migration stamp for every embedded component config in this theme, one
+   *  field for all of them: `CURRENT_COMPONENT_SCHEMA_VERSION` is a single
+   *  global counter over every component migration, so a per-entry stamp would
+   *  buy no isolation. `normalizeTheme` sets this on every read; an embedded
+   *  config's own `schemaVersion` (if hand-authored) is ignored and stripped. */
+  componentSchemaVersion: number;
   /** Server-attached file-name marker. Same role as `ColorsAndType._fileName`. */
   _fileName?: string;
 }
@@ -238,13 +287,14 @@ export interface Theme {
  */
 export interface ThemeBundle {
   /** Discriminator for safe identification of bundle JSON files. Paired with
-   *  the version below: import accepts this kind only at v3, and the
+   *  the version below: import accepts this kind at v3 and v4, and the
    *  `manifest-bundle` every release through 0.47.1 wrote only at v1. */
   kind: 'theme-bundle';
   /** Tracks the enclosed theme's schema. Import still accepts 1, where the
    *  envelope carried a pointer theme plus separately inlined colors and type
-   *  and `${component}/${configName}`-keyed configs. */
-  schemaVersion: 3;
+   *  and `${component}/${configName}`-keyed configs, and 3, from before the
+   *  Wave 2 completeness bump — `normalizeTheme` fills either on the way in. */
+  schemaVersion: typeof THEME_SCHEMA_VERSION;
   /** Sender's `@motion-proto/live-tokens` package version. Receiver can
    *  compare to its own to warn about compatibility drift. */
   liveTokensVersion: string;

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

@@ -5,14 +5,14 @@ Save your work, switch between looks, and ship one to production.
 ## The Theme panel
 
 The **Theme** panel at the foot of the editor sidebar holds the whole look:
-colors, type, and a setting for every component you changed, in one file. It
-carries the name the look ships under, whether production is running it, and
-**Adopt**. Two parts sit under it, each a read-out rather than a file to manage.
+colors, type, and a setting for every component, in one file. It carries the
+name the look ships under, whether production is running it, and **Adopt**.
+Two parts sit under it, each a read-out rather than a file to manage.
 
 - **Colors & Type** holds the design tokens. Components read those tokens to
   define their appearance. It names the two faces the page is showing.
-- **Components** counts how many components run something the theme does not
-  carry, and opens the component editors.
+- **Components** counts how many components have an unsaved edit that has not
+  been saved into the theme, and opens the component editors.
 
 A theme holds its own copy of every part, so one theme can never break another.
 
@@ -21,8 +21,7 @@ A theme holds its own copy of every part, so one theme can never break another.
 A theme is a document, and the editor works the way any editor does.
 
 - **A theme** is a named JSON file in `src/live-tokens/data/themes/`. It carries
-  the whole look: the colors and type plus a setting for every component you
-  changed.
+  the whole look: the colors and type plus a setting for every component.
 - **The open theme** is the one the editor is working on, named in
   `themes/_active.json`. One at a time.
 - **Your unsaved edits** are what the page shows right now. The editor keeps
@@ -60,10 +59,9 @@ to it, and the editor never overwrites it, so start your own with **Save As**.
 **Load**—or clicking the active theme's name—opens the Theme Picker. Picking a
 theme 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 and adopts the previewed
-theme in one step: the active pointer changes, the buffers clear, components it
-does not carry fall through to their defaults, the editor works on it, and
-production ships it. **Cancel** returns you to where you were. Previewing alone
-never changes what your site ships.
+theme in one step: the active pointer changes, the buffers clear, the editor
+works on it, and production ships it. **Cancel** returns you to where you were.
+Previewing alone never changes what your site ships.
 
 **Colors and type only. Keep my shapes.** narrows the load to the palette and
 the fonts: your component settings stay as they are and the theme you have open

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

@@ -27,8 +27,8 @@ src/system/styles/
 ```
 
 A saved theme carries the whole look by value: the colors and type plus a
-setting for every component you changed. It depends on no other file, so
-deleting anything else never breaks it.
+setting for every component. It depends on no other file, so deleting
+anything else never breaks it.
 
 ## What writes when
 

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.** Three curves shape the ramp, in stack order: Hue, Saturation,\n  Lightness. Drag the handles to bias it warmer or cooler, more or less\n  saturated, darker or lighter. Hue drifts the ramp's temperature without\n  moving contrast, because OKLCH hue rotation is close to lightness-preserving.\n  It holds ±45 degrees; a bigger shift belongs on the base colour or the\n  harmony axis.\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`. **Adopt** changes it; saving a preset in the Theme\n  Picker performs that Adopt for you.\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 editors keep their own unsaved state. If one or more components are\nwaiting when you use **Save**, **Save As**, or **Adopt**, the Theme panel offers\nto save all of them before continuing. You can accept once instead of visiting\neach component, or cancel to review them individually. A component editor's\n**Save As** creates a reusable component preset.\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**—or clicking the active theme's name—opens the Theme Picker. Picking a\ntheme shows it on the page as a preview with nothing written to disk, so you can\ntry each look and compare. **Save** in that window opens and adopts the previewed\ntheme in one step: the active pointer changes, the buffers clear, components it\ndoes not carry fall through to their defaults, the editor works on it, and\nproduction ships it. **Cancel** returns you to where you were. Previewing alone\nnever 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. When the Theme panel finds several dirty\n  components, **Save all** writes those buffers together.\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\nProjects upgraded from 0.48 may initially contain working files copied from the\nactive theme. On the first dev-server boot, exact copies are removed\nautomatically. Any file that differs is kept as unsaved work, so no migration\ncommand is required.\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, in one file. It carries the\nname the look ships under, whether production is running it, and **Adopt**.\nTwo 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 have an unsaved edit that has not\n  been saved into the theme, 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.\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`. **Adopt** changes it; saving a preset in the Theme\n  Picker performs that Adopt for you.\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 editors keep their own unsaved state. If one or more components are\nwaiting when you use **Save**, **Save As**, or **Adopt**, the Theme panel offers\nto save all of them before continuing. You can accept once instead of visiting\neach component, or cancel to review them individually. A component editor's\n**Save As** creates a reusable component preset.\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**—or clicking the active theme's name—opens the Theme Picker. Picking a\ntheme shows it on the page as a preview with nothing written to disk, so you can\ntry each look and compare. **Save** in that window opens and adopts the previewed\ntheme in one step: the active pointer changes, the buffers clear, the editor\nworks on it, and production ships it. **Cancel** returns you to where you were.\nPreviewing alone 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. It depends on no other file, so deleting\nanything 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. When the Theme panel finds several dirty\n  components, **Save all** writes those buffers together.\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\nProjects upgraded from 0.48 may initially contain working files copied from the\nactive theme. On the first dev-server boot, exact copies are removed\nautomatically. Any file that differs is kept as unsaved work, so no migration\ncommand is required.\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/index.ts

@@ -36,6 +36,7 @@ export type {
   ColorsAndType,
   ColorsAndTypeMeta,
   LiveSource,
+  ColorsAndTypeSource,
   GradientStyle,
   GradientStop,
   FontSource,

package/src/editor/styles/ui-editor.css

@@ -36,10 +36,13 @@
   --ui-gray-850: #c7c7c7;
   --ui-gray-950: #f2f2f2;
 
+  /* Every level down to muted clears WCAG AA (4.5:1) on the chrome surfaces
+     it lands on, so no rung of the ramp is unreadable: muted bottoms out at
+     4.66:1 on --ui-surface. Only disabled sits below AA, which 1.4.3 exempts. */
   --ui-text-primary:    #ffffff;
   --ui-text-secondary:  var(--ui-gray-800);
-  --ui-text-tertiary:   var(--ui-gray-700);
-  --ui-text-muted:      var(--ui-gray-500);
+  --ui-text-tertiary:   var(--ui-gray-750);
+  --ui-text-muted:      var(--ui-gray-700);
   --ui-text-disabled:   var(--ui-gray-400);
   --ui-text-accent:     var(--ui-gray-950);
   --ui-text-success:    var(--ui-gray-850);

package/src/editor/ui/PaletteEditor.svelte

@@ -5,6 +5,7 @@
   import ColorEditPanel from './ColorEditPanel.svelte';
   import OverridesPanel from './palette/OverridesPanel.svelte';
   import UIPillButton from './UIPillButton.svelte';
+  import UIReveal from './UIReveal.svelte';
   import GradientStopEditor from './palette/GradientStopEditor.svelte';
   import ScaleCurveEditor from './palette/ScaleCurveEditor.svelte';
   import PaletteBase from './palette/PaletteBase.svelte';
@@ -639,8 +640,8 @@
           </button>
           <div class="swatch gray-swatch bookend" style="background: #000000"></div>
         </div>
-      {#if paletteEditorOpen}
-        <div class="curve-grid-span" style="grid-column: 2 / {paletteStepLightness.length + 2}">
+      <UIReveal open={paletteEditorOpen} style="grid-column: 2 / {paletteStepLightness.length + 2}">
+        <div class="curve-grid-span">
           {#if anchorUnlockPrompt && anchorToBase}
             <div class="anchor-unlock-notice" role="alert">
               <i class="fas fa-triangle-exclamation" aria-hidden="true"></i>
@@ -700,7 +701,7 @@
             onAutoSmoothChange={handleAutoSmooth}
           />
         </div>
-      {/if}
+      </UIReveal>
       </div>
 
       {#if emptySelector && emptyMode === 'gradient'}
@@ -766,18 +767,20 @@
     <span>Text, Surfaces &amp; Borders</span>
   </button>
 
-  {#if showDerived}
-    <div class="scales-row">
-      {#each scales.filter(s => s.isText) as scale}
-        {@render overridesPanel(scale, true, derivedHexForBase)}
-      {/each}
-    </div>
-    <div class="scales-row">
-      {#each scales.filter(s => !s.isText) as scale}
-        {@render overridesPanel(scale, true, derivedHexForBase)}
-      {/each}
+  <UIReveal open={showDerived}>
+    <div class="derived-rows">
+      <div class="scales-row">
+        {#each scales.filter(s => s.isText) as scale}
+          {@render overridesPanel(scale, true, derivedHexForBase)}
+        {/each}
+      </div>
+      <div class="scales-row">
+        {#each scales.filter(s => !s.isText) as scale}
+          {@render overridesPanel(scale, true, derivedHexForBase)}
+        {/each}
+      </div>
     </div>
-  {/if}
+  </UIReveal>
 
   <!-- Color Edit Panel (non-base edits) -->
   {#if !isEditingBase && panelOpen && editingColor}
@@ -855,6 +858,14 @@
     min-width: 0;
   }
 
+  /* Carries the column gap the two rows used to get from .palette-editor,
+     now that the reveal wrapper sits between them and it. */
+  .derived-rows {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ui-space-20);
+  }
+
   .scale-section {
     display: flex;
     flex-direction: column;
@@ -964,7 +975,11 @@
     align-items: start;
     justify-content: start;
     min-width: 0;
-    max-width: calc(var(--swatch-cols) * 4.5rem + (var(--swatch-cols) - 1) * var(--swatch-gap, var(--ui-space-4)));
+    /* Definite width, not max-width: the grid is a shrink-to-fit flex item, so
+       without it the palette sized itself to the curve row below and shrank
+       every time the graphs were collapsed. */
+    width: calc(var(--swatch-cols) * 4.5rem + (var(--swatch-cols) - 1) * var(--swatch-gap, var(--ui-space-4)));
+    max-width: 100%;
   }
 
   /* The picker rides the same track geometry as the curve editors below, so

package/src/editor/ui/ThemePanel.svelte

@@ -21,6 +21,7 @@
     saveActiveTheme,
     exportTheme,
     importTheme,
+    type ThemeFillReport,
   } from '../core/themes/themeService';
   import {
     THEME_APPLIED_EVENT,
@@ -119,7 +120,6 @@
       if (active) {
         openThemeSlug.set(active._fileName ?? 'default');
         currentDisplayName = active.name ?? $openThemeSlug;
-        lookConfigs = active.componentConfigs;
       }
     } catch {
       // silent
@@ -149,15 +149,11 @@
   // ── Components ────────────────────────────────────────────────────────
   //
   // The per-component file managers live in the component editors; the list
-  // here answers one question — how many components run something the open
-  // theme does not carry.
+  // here answers one question — how many components carry an unsaved buffer.
 
   let components: ComponentSummary[] = $state([]);
-  let lookConfigs: Theme['componentConfigs'] | null = $state(null);
 
-  let componentsOffLook = $derived(
-    lookConfigs ? countComponentsOffLook(components, lookConfigs, activeIsProtected) : 0,
-  );
+  let componentsOffLook = $derived(countComponentsOffLook(components));
 
   async function refreshComponents() {
     try {
@@ -194,7 +190,6 @@
     const handleThemeApplied = (event: Event) => {
       const { result } = (event as CustomEvent<AppliedThemeDetail>).detail;
       currentDisplayName = result.theme.name;
-      lookConfigs = result.theme.componentConfigs;
     };
     document.addEventListener(THEME_APPLIED_EVENT, handleThemeApplied);
     return () => document.removeEventListener(THEME_APPLIED_EVENT, handleThemeApplied);
@@ -453,6 +448,13 @@
     await commitWholeLook();
   }
 
+  function filledNote(filled: ThemeFillReport): string | null {
+    const n = filled.components.length;
+    if (n === 0) return null;
+    return `${n} component${n === 1 ? '' : 's'} arrived with gaps. `
+      + `The editor filled them from the current defaults.`;
+  }
+
   async function commitWholeLook() {
     const row = previewRow;
     if (!row) return;
@@ -468,14 +470,19 @@
     let result: Awaited<ReturnType<typeof applyTheme>>;
     try {
       result = await applyTheme(row.slug);
+      const notes: string[] = [];
       if (result.skippedComponents.length > 0) {
-        window.alert(
-          `Loaded "${row.name}". These components are not installed here, so their `
-            + `saved settings were skipped:\n\n${result.skippedComponents.join(', ')}`,
+        notes.push(
+          `These components are not installed here, so their saved settings were `
+            + `skipped:\n${result.skippedComponents.join(', ')}`,
         );
       }
+      const filled = filledNote(result.filled);
+      if (filled) notes.push(filled);
+      if (notes.length > 0) {
+        window.alert(`Loaded "${row.name}".\n\n${notes.join('\n\n')}`);
+      }
       currentDisplayName = result.theme.name;
-      lookConfigs = result.theme.componentConfigs;
       showFileList = false;
     } catch (err) {
       window.alert(`Failed to load theme: ${(err as Error).message}`);
@@ -600,6 +607,8 @@
           `The file was missing this data, which fell back to the default:\n${result.dropped.join('\n')}`,
         );
       }
+      const filled = filledNote(result.filled);
+      if (filled) notes.push(filled);
       if (notes.length > 0) {
         window.alert(`Imported as "${result.theme}".\n\n${notes.join('\n\n')}`);
       }
@@ -671,7 +680,7 @@
     <span class="mfm-header-label">Theme</span>
     <UIInfoPopover title="Theme" ariaLabel="About the theme">
       <p>
-        A <strong>theme</strong> is a whole look in one file: the colors and type plus a setting for every component you changed.
+        A <strong>theme</strong> is a whole look in one file: the colors and type plus a setting for every component.
       </p>
       <p>
         It holds its own copy of that data, so the theme you open is the whole look, and one theme can never break another.
@@ -680,13 +689,13 @@
         <strong>Load</strong> opens the list. Picking a theme shows it on the page as a preview, so you can try each look with nothing written to disk. Pick another to compare, or <strong>Cancel</strong> to go back to where you were.
       </p>
       <p>
-        <strong>Save</strong> opens and adopts the previewed theme: the editor works on it from then on and production ships it immediately. Components it does not carry go back to their defaults. Previewing and cancelling never change what your site ships.
+        <strong>Save</strong> opens and adopts the previewed theme: the editor works on it from then on and production ships it immediately. Previewing and cancelling never change what your site ships.
       </p>
       <p>
         <strong>Colors and type only</strong> in that window takes the palette and the fonts and leaves your shapes and component settings alone.
       </p>
       <p>
-        The <strong>active</strong> theme is the one the editor has open. <strong>Adopt</strong> saves it and ships it to production, colors and type plus every component you changed. The line under the name says whether production is running this theme.
+        The <strong>active</strong> theme is the one the editor has open. <strong>Adopt</strong> saves it and ships it to production, colors and type plus every component. The line under the name says whether production is running this theme.
       </p>
       <p>
         If components have unsaved edits, Save and Adopt offer to save all of them before continuing. You can cancel to review or save components individually.

package/src/editor/ui/Toggle.svelte

@@ -45,7 +45,7 @@
   .toggle {
     display: inline-flex;
     align-items: center;
-    gap: var(--space-8);
+    gap: var(--ui-space-8);
     cursor: pointer;
     user-select: none;
 
@@ -57,16 +57,16 @@
       cursor: not-allowed;
 
       .toggle-track {
-        background: var(--surface-neutral-lower);
-        border-color: var(--border-neutral-faint);
+        background: var(--ui-surface-lower);
+        border-color: var(--ui-border-low);
       }
 
       .toggle-thumb {
-        background: var(--text-disabled);
+        background: var(--ui-text-disabled);
       }
 
       .toggle-label {
-        color: var(--text-disabled);
+        color: var(--ui-text-disabled);
       }
     }
   }
@@ -74,13 +74,13 @@
   .toggle-track {
     position: relative;
     width: 2.25rem;
-    height: var(--space-20);
-    border-radius: var(--radius-2xl);
-    border: var(--border-width-1) solid var(--border-neutral);
-    background: var(--surface-neutral-low);
+    height: var(--ui-space-20);
+    border-radius: var(--ui-radius-2xl);
+    border: 1px solid var(--ui-border);
+    background: var(--ui-surface-low);
     padding: 0;
     cursor: inherit;
-    transition: background var(--duration-150), border-color var(--duration-150);
+    transition: background var(--ui-transition-fast), border-color var(--ui-transition-fast);
     flex-shrink: 0;
 
     &.on {
@@ -89,34 +89,34 @@
     }
 
     &:hover:not(:disabled) {
-      border-color: var(--border-neutral-medium);
+      border-color: var(--ui-border-high);
     }
 
     &:focus-visible {
-      outline: var(--border-width-2) solid var(--border-brand);
-      outline-offset: var(--space-2);
+      outline: 2px solid var(--ui-text-primary);
+      outline-offset: var(--ui-space-2);
     }
   }
 
   .toggle-thumb {
     position: absolute;
-    top: var(--space-2);
-    left: var(--space-2);
+    top: var(--ui-space-2);
+    left: var(--ui-space-2);
     width: 0.875rem;
     height: 0.875rem;
-    border-radius: var(--radius-full);
-    background: var(--text-secondary);
-    transition: transform var(--duration-150), background var(--duration-150);
+    border-radius: var(--ui-radius-full);
+    background: var(--ui-text-secondary);
+    transition: transform var(--ui-transition-fast), background var(--ui-transition-fast);
 
     .on & {
-      transform: translateX(var(--space-16));
-      background: var(--text-primary);
+      transform: translateX(var(--ui-space-16));
+      background: var(--ui-text-primary);
     }
   }
 
   .toggle-label {
-    font-size: var(--font-size-md);
-    color: var(--text-secondary);
+    font-size: var(--ui-font-size-md);
+    color: var(--ui-text-secondary);
     line-height: 1;
   }
 </style>

package/src/editor/ui/UIPillButton.svelte

@@ -115,7 +115,7 @@
   .ui-pill[aria-disabled='true'] {
     background: linear-gradient(180deg, rgba(255, 255, 255, 0.06) 0%, rgba(255, 255, 255, 0.10) 100%);
     border-color: rgba(255, 255, 255, 0.22);
-    color: var(--ui-text-muted, #4d4d4d);
+    color: var(--ui-text-disabled, #333333);
     cursor: not-allowed;
     pointer-events: none;
   }