@motion-proto/live-tokens 0.67.0 → 0.68.1

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

@@ -2,7 +2,7 @@ import { liveMovedSinceBake } from '../productionPulse';
 import { openThemeSlug } from '../store/editorConfigStore';
 import { loadThemeFromApi } from '../store/editorStore';
 import { migrateColorsAndTypeFonts } from '../fonts/fontMigration';
-import { openThemeSketchStyle } from '../sketch/sketchStore';
+import { openThemeSketchSettings } from '../sketch/sketchStore';
 import type { ApplyThemeResult } from './themeService';
 
 const CHANNEL_NAME = 'live-tokens:active-theme:v1';
@@ -43,7 +43,7 @@ export function hydrateAppliedTheme(fileName: string, result: ApplyThemeResult):
   migrateColorsAndTypeFonts(colorsAndType);
   loadThemeFromApi(colorsAndType, structuredClone(result.componentConfigs));
   openThemeSlug.set(fileName);
-  openThemeSketchStyle(result.theme.sketchStyle);
+  openThemeSketchSettings(result.theme.sketchSettings);
   liveMovedSinceBake.set(false);
   if (typeof document !== 'undefined') {
     document.dispatchEvent(new CustomEvent<AppliedThemeDetail>(THEME_APPLIED_EVENT, {

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

@@ -65,9 +65,9 @@ export async function initializeTheme(): Promise<void> {
 
   const active = await safeFetch<Theme>(`${API_BASE}/themes/active`);
   // A failed fetch is not "the theme carries no sketchstyle": treating null as
-  // absent would tell the panel the look is off the theme, or hand a fresh
+  // absent would tell the panel the sketchstyle is off the theme, or hand a fresh
   // browser a blank buffer, over a fetch that will likely succeed next time.
   // The same call a built site makes (`@motion-proto/live-tokens/sketch`), so
   // one rule decides what a theme's sketchstyle means at boot in both.
-  if (active) seedSketchFromTheme(active.sketchStyle);
+  if (active) seedSketchFromTheme(active.sketchSettings);
 }

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

@@ -7,15 +7,15 @@ import { getActiveColorsAndType } from './colorsAndTypeService';
 import { broadcastAppliedTheme, hydrateAppliedTheme } from './themeDocumentSync';
 import { CURRENT_COMPONENT_SCHEMA_VERSION } from './migrations';
 import { THEME_SCHEMA_VERSION } from './themeTypes';
-import { liveSketchStyle, themeSketchStyle } from '../sketch/sketchStore';
+import { liveSketchSettings, themeSketchSettings } from '../sketch/sketchStore';
 
 export type { ThemeFillReport };
 
 /**
  * REST client for theme files, the documents of the editor. A theme carries a
- * whole look by value: the colors and type plus a config for every component
+ * whole content by value: the colors and type plus a config for every component
  * this install has. One theme is open (`themes/_active.json`) and one is
- * published (`themes/_production.json`); the live look is the open theme plus
+ * published (`themes/_production.json`); the live content is the open theme plus
  * whatever the `_working` buffers hold over it.
  *
  * `default` is the protected baseline — cannot be overwritten or deleted, and
@@ -75,7 +75,7 @@ export interface ApplyThemeResult {
  * 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.
+ * Production is untouched, so trying a content cannot change what the site ships.
  * The resolved response hydrates the caller immediately, then broadcasts the
  * same typed state to every already-open same-origin host/editor document.
  * Each store renderer projects that state into its own document, so a theme
@@ -96,7 +96,7 @@ export async function applyTheme(fileName: string): Promise<ApplyThemeResult> {
   return result;
 }
 
-export interface AdoptLookResult {
+export interface AdoptThemeResult {
   ok: boolean;
   /** The theme production now ships. */
   productionTheme: { fileName: string; name: string; updatedAt: string };
@@ -111,7 +111,7 @@ export interface AdoptLookResult {
  * Answers 409 `ACTIVE_IS_PROTECTED` while the Default theme is open, which the
  * caller recovers from by forking it under a name of the user's own.
  */
-export async function adoptLook(): Promise<AdoptLookResult> {
+export async function adoptTheme(): Promise<AdoptThemeResult> {
   const res = await fetch(`${API_BASE}/production`, { method: 'PUT' });
   if (!res.ok) {
     const body = await res.json().catch(() => ({}));
@@ -135,7 +135,7 @@ function withoutLiveMarkers<T extends { _fileName?: string; _source?: unknown }>
 }
 
 /**
- * The look as it stands: the live colors and type plus the live config of
+ * The content as it stands: the live colors and type plus the live config of
  * every component this install has, all by value. A theme is a complete
  * document (`docs/plans/theme-completeness.md`), so the capture carries every
  * component, not just the ones off their default.
@@ -145,7 +145,7 @@ function withoutLiveMarkers<T extends { _fileName?: string; _source?: unknown }>
  * way out of `GET /colors-and-type/active`, which matters: the server trusts an
  * already-embedded copy and runs no migrations over it on write.
  */
-async function captureLook(): Promise<Pick<Theme, 'colorsAndType' | 'componentConfigs' | 'sketchStyle'>> {
+async function captureThemeContent(): Promise<Pick<Theme, 'colorsAndType' | 'componentConfigs' | 'sketchSettings'>> {
   const liveColorsAndType = await getActiveColorsAndType();
   if (!liveColorsAndType) {
     throw new Error('No live colors and type to capture');
@@ -159,11 +159,11 @@ async function captureLook(): Promise<Pick<Theme, 'colorsAndType' | 'componentCo
   });
   // Sketchstyle has no server door of its own (RJC 8): the live buffer, not a
   // fetch, is the source of truth for what the dials currently say.
-  return { colorsAndType: withoutLiveMarkers(liveColorsAndType), componentConfigs, sketchStyle: liveSketchStyle() };
+  return { colorsAndType: withoutLiveMarkers(liveColorsAndType), componentConfigs, sketchSettings: liveSketchSettings() };
 }
 
 /**
- * Capture the current look into a new theme file and open it. Used by the
+ * Capture the current content into a new theme file and open it. Used by the
  * theme panel's Save As action and by the fork-then-Adopt flow the protected
  * Default theme forces.
  */
@@ -171,7 +171,7 @@ export async function saveAsTheme(
   fileName: string,
   displayName: string,
 ): Promise<void> {
-  const look = await captureLook();
+  const content = await captureThemeContent();
   const now = new Date().toISOString();
   await saveTheme(fileName, {
     name: displayName,
@@ -179,15 +179,15 @@ export async function saveAsTheme(
     updatedAt: now,
     schemaVersion: THEME_SCHEMA_VERSION,
     componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
-    ...look,
+    ...content,
   });
-  themeSketchStyle.set(look.sketchStyle);
+  themeSketchSettings.set(content.sketchSettings);
   liveMovedSinceBake.set(true);
   await setActiveTheme(fileName);
 }
 
 /**
- * Re-capture the current look into the open theme file. Used by the theme
+ * Re-capture the current content into the open theme file. Used by the theme
  * panel's Save action and by both Adopt paths, which publish what is saved.
  * The server rejects with 403 while the protected `default` theme is open.
  */
@@ -196,16 +196,16 @@ export async function saveActiveTheme(displayName?: string): Promise<void> {
   if (!active || !active._fileName) {
     throw new Error('No active theme');
   }
-  const look = await captureLook();
+  const content = await captureThemeContent();
   await saveTheme(active._fileName, {
     name: displayName ?? active.name,
     createdAt: active.createdAt,
     updatedAt: new Date().toISOString(),
     schemaVersion: THEME_SCHEMA_VERSION,
     componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
-    ...look,
+    ...content,
   });
-  themeSketchStyle.set(look.sketchStyle);
+  themeSketchSettings.set(content.sketchSettings);
   liveMovedSinceBake.set(true);
 }
 

package/src/editor/core/themes/{lookSummary.ts → themeSummary.ts}

@@ -1,17 +1,17 @@
 import type { ComponentSummary } from '../components/componentConfigService';
 
-export interface LookProductionInput {
+export interface ThemeProductionInput {
   /** Slug of the theme the editor has open. */
   openTheme: string;
   /** Slug of the published theme, or null while the read has not landed. */
   productionTheme: string | null;
-  /** Live look moved past what the published theme holds: unsaved edits, or a
+  /** Live theme moved past what the published theme holds: unsaved edits, or a
    *  save since the last Adopt. */
   unpublished: boolean;
 }
 
-export interface LookProductionState {
-  /** True when production is known to ship the look on screen. */
+export interface ThemeProductionState {
+  /** True when production is known to ship the theme on screen. */
   inProduction: boolean;
   /** True while the production theme is unread: neither claim can be made. */
   unknown: boolean;
@@ -22,9 +22,9 @@ export interface LookProductionState {
 }
 
 /**
- * Whether production is running the look on screen. Production is one saved
+ * Whether production is running the theme on screen. Production is one saved
  * theme, so the first half is an identity check against the open one; the
- * second half is the live look sitting ahead of what was published, which
+ * second half is the live theme sitting ahead of what was published, which
  * `unpublished` carries.
  *
  * A null production read is not an answer, so it is neither state: `unknown`
@@ -32,11 +32,11 @@ export interface LookProductionState {
  * neutral state, which keeps a mount from flashing the alarm without letting a
  * read that never lands read as shipped forever.
  */
-export function lookProductionState({
+export function themeProductionState({
   openTheme,
   productionTheme,
   unpublished,
-}: LookProductionInput): LookProductionState {
+}: ThemeProductionInput): ThemeProductionState {
   const unknown = productionTheme === null;
   const themeOff = !unknown && productionTheme !== openTheme;
   return {
@@ -48,6 +48,6 @@ export function lookProductionState({
 }
 
 /** How many components run an unsaved buffer, diverging from what the open theme carries. */
-export function countComponentsOffLook(components: ComponentSummary[]): number {
+export function countComponentsOffTheme(components: ComponentSummary[]): number {
   return components.filter((c) => c.source === 'working').length;
 }

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

@@ -2,13 +2,17 @@ import type { CurveAnchor } from '../../ui/curveEngine';
 import type { GradientValue } from './parsers/gradient';
 import type { Oklch } from '../palettes/oklch';
 import type { HarmonyAxis } from '../palettes/colorHarmony';
-import type { SketchStyle } from '../sketch/sketchStyles';
+import type { SketchStyleSettings } from '../sketch/sketchStyles';
 /** 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;
+/** 5 renamed the sketch field from `sketchStyle` to `sketchSettings`. The bump
+ *  is what makes the boot pass rewrite a theme still on the old key: the read
+ *  accepts both, but a built site reads its theme JSON raw and would see
+ *  `undefined` until the file itself was converted. */
+export const THEME_SCHEMA_VERSION = 5;
 
 /** 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
@@ -240,7 +244,7 @@ export interface ComponentConfigMeta {
 }
 
 /**
- * A saved look, encapsulated: the colors and type plus a config for every
+ * A saved theme, encapsulated: the colors and type plus a config for every
  * 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
@@ -267,7 +271,7 @@ export interface Theme {
    *  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.
+   *  whole-theme 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
@@ -280,10 +284,10 @@ export interface Theme {
    *  buy no isolation. `normalizeTheme` sets this on every read; an embedded
    *  config's own `schemaVersion` (if hand-authored) is ignored and stripped. */
   componentSchemaVersion: number;
-  /** The sketchstyle this look paints, by value. Absent means the look is
+  /** The sketchstyle this theme paints, by value. Absent means the theme is
    *  crisp: presence is the on state, so there is no separate flag that can
    *  disagree with the dials beside it (RJC 1). */
-  sketchStyle?: SketchStyle;
+  sketchSettings?: SketchStyleSettings;
   /** Server-attached file-name marker. Same role as `ColorsAndType._fileName`. */
   _fileName?: string;
 }

package/src/editor/docs/content/getting-started.md

@@ -54,7 +54,7 @@ the editor swaps live.
 To ship, click **Adopt** in the Theme panel. That saves the open theme and bakes
 it into `src/live-tokens/data/tokens.generated.css`, which your build bundles
 alongside `tokens.css`. Adopt is the only action that changes what your site
-ships, so try any look you like first. The editor itself never reaches
+ships, so try any theme you like first. The editor itself never reaches
 production.
 
 Already have a Svelte 5 + Vite app? The

package/src/editor/docs/content/sketch-mode.md

@@ -22,7 +22,7 @@ separately wobbled boxes.
 
 ## The sketchstyles
 
-Seven looks ship with the package, and each is a complete set of dials rather
+Seven sketchstyles ship with the package, and each is a complete set of dials rather
 than just a name:
 
 - **Pencil.** Two graphite passes on their own seeds, so the outline disagrees
@@ -38,8 +38,8 @@ than just a name:
 - **Napkin.** Ballpoint in a hurry. Everything loose at once.
 - **Dry marker.** Ink that ran out. One scratchy pass over a mostly eaten fill.
 
-All seven ship as files, one per look, under
-`src/live-tokens/data/sketch-styles/` in the package. There is no look that
+All seven ship as files, one per sketchstyle, under
+`src/live-tokens/data/sketch-styles/` in the package. There is no sketchstyle that
 exists only as code, so every one of them can be read, copied and edited.
 
 Pick one, then move whatever you like. **Save As** keeps your dials under a name
@@ -51,6 +51,11 @@ project's own copy under the same name, which takes its place in the list;
 delete that copy and the shipped file behind it comes back. Both are a
 different gesture from saving a theme; see "Where the settings live" below.
 
+A theme carries its sketch settings by value, so it can hold a set that belongs
+to no file. The list shows that set as **Unsaved**. It owns no file, so there is
+nothing for Save to write over; **Save As** turns it into a sketchstyle like any
+other, which you can then save over and delete.
+
 Your sketchstyles and the shipped ones are one list. A sketchstyle named after
 a shipped one replaces it, keeping its place in the list, so a project that
 wants its own Pencil saves one and every picker shows that one instead.
@@ -97,9 +102,9 @@ is disabled there; use **Save As** to fold the dials into a theme of your
 own.
 
 **Save** and **Save As** in the **Sketchstyle** view are a different gesture.
-They write a named sketchstyle to `src/live-tokens/data/sketch-styles/`, a look
+They write a named sketchstyle to `src/live-tokens/data/sketch-styles/`, a sketchstyle
 you can pick from any theme. Neither touches the open theme, and neither marks
-the look off the theme.
+the theme as changed.
 
 ## Shipping the layer
 
@@ -110,11 +115,11 @@ has no server to ask, so it hands the field over itself:
 import { seedSketchFromTheme } from '@motion-proto/live-tokens/sketch';
 import theme from './live-tokens/data/themes/sketchy.json';
 
-seedSketchFromTheme(theme.sketchStyle);
+seedSketchFromTheme(theme.sketchSettings);
 await bootLiveTokens(App, '#app');
 ```
 
-Call it before mounting, so the look is up on the first frame. Pass the field
+Call it before mounting, so the sketch layer is up on the first frame. Pass the field
 raw. A theme written against older dial names is carried forward on the way in,
 the same reconciliation the dev server runs on every theme it reads.
 
@@ -122,7 +127,7 @@ Nothing is baked. `tokens.generated.css` still holds token values only, and the
 layer stays JavaScript the page runs, because it builds an SVG filter bank
 rather than a set of custom properties.
 
-A visitor who has picked a look of their own keeps it, None included. The theme
+A visitor who has picked a sketchstyle of their own keeps it, None included. The theme
 seeds a browser that has decided nothing and never overwrites one that has, so
 calling this on every boot is safe.
 
@@ -138,26 +143,26 @@ const files = import.meta.glob<{ name?: string; settings: unknown }>(
 );
 
 await bootLiveTokens(App, '#app', {
-  sketchLooks: Object.entries(files).map(([path, file]) => {
+  sketchStyles: Object.entries(files).map(([path, file]) => {
     const id = path.split('/').pop()!.replace('.json', '');
     return { id, label: file.name || id, settings: file.settings };
   }),
 });
 ```
 
-Projects made with `create` ship this already. The file's slug is the look's
+Projects made with `create` ship this already. The file's slug is the sketchstyle's
 id, so a sketchstyle picked in the editor keeps working once the site is built.
 
 ### Building a picker
 
-`sketchLooks` is every look on offer, shipped and your own, as a store. Give
-each row `setSketch(look.id)`, and add your own **None** row: off is a state of
-the effect rather than one of the looks.
+`sketchStyles` is every sketchstyle on offer, shipped and your own, as a store. Give
+each row `setSketch(style.id)`, and add your own **None** row: off is a state of
+the effect rather than one of the sketchstyles.
 
-`themeSketchLook` is the theme's own look as one more row. It is null when the
-theme carries none, and null when what it carries is a look already in
-`sketchLooks`, since that row names it. Its id goes to `setSketch` like any
-other, so a visitor who wanders off the theme's look can come back to it.
+`unsavedSketchStyle` is the settings the theme carries as one more row. It is null when the
+theme carries none, and null when what it carries matches a sketchstyle already in
+`sketchStyles`, since that row names it. Its id goes to `setSketch` like any
+other, so a visitor who wanders off the theme's own settings can come back to it.
 
 ## Drawing your own elements
 

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

@@ -1,12 +1,12 @@
 # Themes
 
-Save your work, switch between looks, and ship one to production.
+Save your work, switch between themes, and ship one to production.
 
 ## The Theme panel
 
-The **Theme** panel at the foot of the editor sidebar holds the whole look:
+The **Theme** panel at the foot of the editor sidebar holds the whole theme:
 colors, type, a setting for every component, and the sketch layer, in one
-file. It carries the name the look ships under, whether production is running
+file. It carries the name the theme ships under, whether production is running
 it, and **Adopt**. Three parts sit under it, each a read-out rather than a
 file to manage.
 
@@ -14,7 +14,7 @@ file to manage.
   define their appearance. It names the two faces the page is showing.
 - **Components** counts how many components have an unsaved edit that has not
   been saved into the theme, and opens the component editors.
-- **Sketchstyle** names the look the theme's sketch layer carries: its label, or
+- **Sketchstyle** names the sketchstyle the theme's sketch layer carries: its label, or
   off the theme when what's on screen no longer matches what was saved, or
   none when the theme carries no sketch layer. It travels with the theme
   like colors and type do, but never reaches a production build.
@@ -26,7 +26,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, a setting for every component, and the
+  the whole theme: the colors and type, a setting for every component, and the
   sketch layer.
 - **The open theme** is the one the editor is working on, named in
   `themes/_active.json`. One at a time.
@@ -40,11 +40,11 @@ A theme is a document, and the editor works the way any editor does.
   Picker performs that Adopt for you.
 
 Absence is the answer for anything untouched: a buffer exists only where the
-live look diverges from the active theme, so a newly opened theme has none.
+live theme diverges from the active theme, so a newly opened theme has none.
 
 ## Fonts
 
-Type is part of the look, so it saves, loads and ships with the theme rather
+Type is part of the theme, so it saves, loads and ships with the theme rather
 than on its own. Four named stacks carry it:
 
 | Stack | Used by |
@@ -85,7 +85,7 @@ what writes the font imports your site ships, into `fonts.css`.
 
 In the Theme panel:
 
-- **Save** captures the look on screen into the open theme. Your colors and type
+- **Save** captures the theme on screen into the open theme. Your colors and type
   go in as part of it, so there is nothing to save first.
 - **Save As** names a new theme. Use it for your first save and for forking.
 
@@ -104,7 +104,7 @@ 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, sketch
-layer included, so you can try each look and compare. **Save** in that window
+layer included, so you can try each theme and compare. **Save** in that window
 opens and adopts the previewed 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, unsaved sketch dials included. Previewing alone
@@ -125,10 +125,10 @@ then bakes the colors and type plus every component the theme carries into
 it stays a preview. Fonts regenerate to match. The line under the theme name
 says whether production is running this theme.
 
-Production is one saved theme, so nothing else publishes. Trying a look, moving
+Production is one saved theme, so nothing else publishes. Trying a theme, moving
 a token, saving a theme: all of it leaves the generated CSS alone until you
 Adopt. A component editor's Adopt runs the same save-then-bake step, because a
-component never ships alone. Adopting while Motion Proto is open saves your look
+component never ships alone. Adopting while Motion Proto is open saves your theme
 as a theme of your own first, since the built-in one is read-only.
 
 Production builds (`npm run build`) ship only that plain CSS and your

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

@@ -11,8 +11,8 @@ src/live-tokens/data/
   themes/
     _active.json         names the theme the editor has open
     _production.json     names the theme your site ships
-    default.json         Motion Proto, the built-in look, rewritten at boot
-    my-brand.json        a saved theme: the whole look in one file
+    default.json         Motion Proto, the built-in theme, rewritten at boot
+    my-brand.json        a saved theme: the whole theme in one file
   colors-and-type/
     _working.json        unsaved colors and type edits
   component-configs/
@@ -21,14 +21,14 @@ src/live-tokens/data/
       _working.json      unsaved Button edits
       my-button.json     a preset you saved from the Button editor
   sketch-styles/
-    my-look.json         a sketchstyle saved from the Sketchstyle view
+    my-style.json        a sketchstyle saved from the Sketchstyle view
   tokens.generated.css   the baked CSS your production build ships
 src/system/styles/
   tokens.css             your token vocabulary, hand-authored, never written
   fonts.css              font imports, rewritten when you Adopt
 ```
 
-A saved theme carries the whole look by value: the colors and type, a
+A saved theme carries everything by value: the colors and type, a
 setting for every component, and the sketch layer. It depends on no other
 file, so deleting anything else never breaks it.
 
@@ -40,11 +40,11 @@ file, so deleting anything else never breaks it.
   components, **Save all** writes those buffers together.
 - **Save** captures the buffers into the open theme's file, along with the
   sketch layer, which has no buffer of its own and lives only in the browser
-  until Save writes it. That file is the durable copy of your look; matching
+  until Save writes it. That file is the durable copy of your theme; 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.
+  themes 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.