@motion-proto/live-tokens 0.67.1 → 0.68.1

package/src/editor/core/sketch/sketchStyles.ts

@@ -6,7 +6,7 @@ import dashed from '../../../live-tokens/data/sketch-styles/dashed.json';
 import napkin from '../../../live-tokens/data/sketch-styles/napkin.json';
 import dry from '../../../live-tokens/data/sketch-styles/dry.json';
 
-export interface SketchStyle {
+export interface SketchStyleSettings {
   label: string;
   blurb: string;
   /** How far the fill's edge travels at its furthest, in px. Every dial that
@@ -80,7 +80,7 @@ export interface SketchStyle {
   /** Whether the two move together. Unlinked they part, and the field comes out
       stretched: blobs wider than they are tall read as a wash dragged sideways,
       the way ink pulled across a page does. Stored rather than inferred from
-      the pair matching, so a look that stretches to exactly square keeps its
+      the pair matching, so a sketchstyle that stretches to exactly square keeps its
       dials apart. */
   maskBlobLinked: boolean;
   /** Output levels on the coverage field, 0 to 1: the palest the fill gets and
@@ -144,40 +144,40 @@ export interface SketchStyle {
 /**
  * The shipped sketchstyles, read from the files the package distributes. The
  * files are the source: a project shadows one by saving a sketchstyle under the
- * same id, the editor restores a shipped look by deleting that file, and
+ * same id, the editor restores a shipped sketchstyle by deleting that file, and
  * `themeFileApi` serves these as the read-only fallback behind the project's own
- * directory. Editing a look here means editing its JSON, which is what the
+ * directory. Editing a sketchstyle here means editing its JSON, which is what the
  * Sketchstyle view already writes.
  *
  * Each file carries every dial, so there is nothing to merge a default into.
  * `sketchStyles.test.ts` pins that: the seven key sets have to match, and a dial
- * added to `SketchStyle` has to reach all seven before the suite goes green.
+ * added to `SketchStyleSettings` has to reach all seven before the suite goes green.
  *
  * Order is picker order.
  */
 const SHIPPED_FILES = { pencil, marker, whiteboard, hatched, dashed, napkin, dry };
 
-export const SKETCH_STYLES: Record<string, SketchStyle> = Object.fromEntries(
-  Object.entries(SHIPPED_FILES).map(([id, file]) => [id, file.settings as unknown as SketchStyle]),
+export const SHIPPED_SKETCH_SETTINGS: Record<string, SketchStyleSettings> = Object.fromEntries(
+  Object.entries(SHIPPED_FILES).map(([id, file]) => [id, file.settings as unknown as SketchStyleSettings]),
 );
 
 export const DEFAULT_SKETCH_STYLE = 'marker';
 
-/** The id of the look a theme carries, in the same id namespace as the shipped
+/** The id for sketch settings a theme carries, in the same id namespace as the shipped
     sketchstyles so one picker row and one `setSketch` call cover both. Never a
-    key of `SKETCH_STYLES`: a shipped style claiming it would shadow the theme's
-    own look in every picker. `index.test.ts` pins that. */
+    key of `SHIPPED_SKETCH_SETTINGS`: a shipped style claiming it would shadow the theme's
+    own sketchstyle in every picker. `index.test.ts` pins that. */
 export const THEME_SKETCH_ID = 'theme';
 
 /** Reconciled against a full sketchstyle in both directions: a value stored before a
     control existed picks up the default, and a value stored for a control since
     retired is dropped. Without the drop, a stale key survives every spread and
     makes the settings compare unequal to any baseline forever. */
-export function hydrateSketchStyle(raw: unknown): SketchStyle {
-  const base = SKETCH_STYLES[DEFAULT_SKETCH_STYLE];
-  const stored = (raw ?? {}) as Partial<SketchStyle>;
+export function hydrateSketchSettings(raw: unknown): SketchStyleSettings {
+  const base = SHIPPED_SKETCH_SETTINGS[DEFAULT_SKETCH_STYLE];
+  const stored = (raw ?? {}) as Partial<SketchStyleSettings>;
   const out = { ...base };
-  for (const key of Object.keys(base) as (keyof SketchStyle)[]) {
+  for (const key of Object.keys(base) as (keyof SketchStyleSettings)[]) {
     if (stored[key] !== undefined) (out[key] as unknown) = stored[key];
   }
   // A retired option: the fill's presence belongs to the theme, not the effect.
@@ -194,9 +194,9 @@ export function hydrateSketchStyle(raw: unknown): SketchStyle {
 }
 
 /** The second pass used to sit at a distance derived from the stroke width,
-    with no dial of its own. A look stored before the dial comes back at that
+    with no dial of its own. A sketchstyle stored before the dial comes back at that
     distance rather than at whatever the fallback sketchstyle happens to carry. */
-function restoreDerivedRetrace(stored: Record<string, unknown>, out: SketchStyle): void {
+function restoreDerivedRetrace(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   if (stored.retraceOffset === undefined) {
     out.retraceOffset = Number(Math.max(1.2, out.strokeWidth * 0.55).toFixed(2));
   }
@@ -204,7 +204,7 @@ function restoreDerivedRetrace(stored: Record<string, unknown>, out: SketchStyle
 
 /** The four displacement dials used to be stated as the map's own `scale`,
     which is the full swing: the number on the dial was twice the furthest
-    anything actually moved. They are peak travel in px now, so a look stored
+    anything actually moved. They are peak travel in px now, so a sketchstyle stored
     under the old names comes back halved and renders identically. */
 const SWING_DIALS = {
   fillScale: 'fillTravel',
@@ -216,11 +216,11 @@ const SWING_DIALS = {
 /** The pen wobble used to be stated as `frequency`, in cycles per px, which is
     the number the filter wants and not one anybody can picture. It is a
     wavelength in px now, the way the mask states its blobs. */
-function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchStyle): void {
+function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const cycles = stored.frequency;
   if (typeof cycles === 'number' && cycles > 0) out.wobble = Math.round(1 / cycles);
   // The layer count was `octaves`, and its dial ran to 5. The top two moved
-  // nothing, so a look stored there comes back at the roughest that reads.
+  // nothing, so a sketchstyle stored there comes back at the roughest that reads.
   // Both were multipliers on the frequency, so they ran the other way.
   for (const [legacy, key] of [
     ['borderFrequency', 'borderWavelength'], ['iconFrequency', 'iconWavelength'],
@@ -234,9 +234,9 @@ function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchS
   if (typeof layers === 'number') out.roughness = Math.min(3, Math.max(1, layers));
 }
 
-/** The blob size was one number for both axes. A look stored before the split
-    comes back square, with the two dials linked, which is the look it had. */
-function splitBlobAxes(stored: Record<string, unknown>, out: SketchStyle): void {
+/** The blob size was one number for both axes. A sketchstyle stored before the split
+    comes back square, with the two dials linked, which is the shape it had. */
+function splitBlobAxes(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const blob = stored.maskBlob;
   if (typeof blob !== 'number') return;
   out.maskBlobX = blob;
@@ -249,13 +249,13 @@ function splitBlobAxes(stored: Record<string, unknown>, out: SketchStyle): void
     of the field, so it came out either untouched or gone. It is a share of the
     glyph now, and the old default reads as one period across the glyph, which
     is what that size was aiming at. */
-function convertIconTileToScale(stored: Record<string, unknown>, out: SketchStyle): void {
+function convertIconTileToScale(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const tile = stored.iconMaskTile;
   if (typeof tile !== 'number') return;
   out.iconMaskScale = Math.min(5, Math.max(0.5, Number((tile / 90).toFixed(2))));
 }
 
-function halveSwingDials(stored: Record<string, unknown>, out: SketchStyle): void {
+function halveSwingDials(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   for (const [legacy, key] of Object.entries(SWING_DIALS)) {
     const value = stored[legacy];
     if (typeof value === 'number') out[key as 'fillTravel'] = value / 2;
@@ -265,7 +265,7 @@ function halveSwingDials(stored: Record<string, unknown>, out: SketchStyle): voi
 /** The mask used to be a 600-unit tile painted at `maskScale` px, with the
     coverage point buried in the hardness slope. Recover page-px blobs and
     softness, and the levels the old slope and floor put the edge at. */
-function convertTiledMask(stored: Record<string, unknown>, out: SketchStyle): void {
+function convertTiledMask(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const scale = stored.maskScale;
   if (typeof scale !== 'number') return;
   const freq = stored.maskFrequency;
@@ -283,7 +283,7 @@ function convertTiledMask(stored: Record<string, unknown>, out: SketchStyle): vo
  * levels the pair put the edge between, and rescale them onto the field as it
  * is now: stretched onto its full range before the levels see it.
  */
-function convertCutToLevels(stored: Record<string, unknown>, out: SketchStyle): void {
+function convertCutToLevels(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const contrast = stored.maskContrast;
   const coverage = stored.maskCoverage;
   if (typeof contrast !== 'number' || typeof coverage !== 'number') return;
@@ -297,9 +297,9 @@ function convertCutToLevels(stored: Record<string, unknown>, out: SketchStyle):
 
 /** The pair were input levels, a cut through the field, and are output levels
     now, the palest and densest the fill gets. The same two numbers carry over:
-    a look cut between 20% and 50% comes back as a wash between 20% and 50% ink,
+    a sketchstyle cut between 20% and 50% comes back as a wash between 20% and 50% ink,
     which keeps its spread and loses only the hole. */
-function carryLevelsToOutput(stored: Record<string, unknown>, out: SketchStyle): void {
+function carryLevelsToOutput(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   if (typeof stored.maskLevelMin === 'number') out.maskOutputMin = stored.maskLevelMin;
   if (typeof stored.maskLevelMax === 'number') out.maskOutputMax = stored.maskLevelMax;
 }

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

@@ -65,7 +65,7 @@ export const sanitizeFileName = sanitizeFileNameImpl;
 
 /** Flush the editor state to the buffer under `displayName`, the name of the
  *  theme the buffer belongs to, and clear the dirty flag. A capture reads the
- *  buffer back, so this is what makes Save and Adopt mean the look on screen. */
+ *  buffer back, so this is what makes Save and Adopt mean the theme on screen. */
 export async function persistColorsAndType(
   state: EditorState,
   displayName: string,

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

@@ -1,7 +1,7 @@
 import type { ThemeMeta, ColorsAndTypeMeta } from './themeTypes';
 
 /**
- * The one Load list. A theme is the whole look; a colors and type file is a
+ * The one Load list. A theme is the whole theme; a colors and type file is a
  * preset holding that half of one. Both belong in the same window, told apart
  * by a badge rather than by living in separate managers.
  *
@@ -10,7 +10,7 @@ import type { ThemeMeta, ColorsAndTypeMeta } from './themeTypes';
  * that copy is exactly the file the list must keep reachable.
  */
 
-export type LoadRowKind = 'look' | 'layer';
+export type LoadRowKind = 'theme' | 'layer';
 
 export interface LoadRow {
   /** `<kind>:<slug>`. The two kinds are separate resources with separate name
@@ -25,12 +25,12 @@ export interface LoadRow {
 
 export const loadRowId = (kind: LoadRowKind, slug: string): string => `${kind}:${slug}`;
 
-export function buildLoadRows(looks: ThemeMeta[], layers: ColorsAndTypeMeta[]): LoadRow[] {
-  const lookRows: LoadRow[] = looks
+export function buildLoadRows(themes: ThemeMeta[], layers: ColorsAndTypeMeta[]): LoadRow[] {
+  const themeRows: LoadRow[] = themes
     .map((f): LoadRow => ({
-      fileName: loadRowId('look', f.fileName),
+      fileName: loadRowId('theme', f.fileName),
       slug: f.fileName,
-      kind: 'look',
+      kind: 'theme',
       name: f.name,
       updatedAt: f.updatedAt,
       isProtected: f.isProtected,
@@ -46,12 +46,12 @@ export function buildLoadRows(looks: ThemeMeta[], layers: ColorsAndTypeMeta[]):
       updatedAt: f.updatedAt,
       isProtected: false,
     }));
-  return [...lookRows, ...layerRows];
+  return [...themeRows, ...layerRows];
 }
 
 /**
  * Whether picking this row loads colors and type alone. A layer file holds
- * nothing else, so it ignores the toggle; a look honors it.
+ * nothing else, so it ignores the toggle; a theme honors it.
  */
 export function isColorsOnly(row: LoadRow | null, colorsOnly: boolean): boolean {
   if (row?.kind === 'layer') return true;

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