@motion-proto/live-tokens 0.61.0 → 0.63.0

package/src/editor/core/sketch/{sketchPresetService.ts → sketchStyleService.ts}

@@ -1,24 +1,24 @@
 import { API_BASE } from '../storage/apiBase';
-import { hydrateSketchSettings, type SketchSettings } from './sketchPresets';
+import { hydrateSketchStyle, type SketchStyle } from './sketchStyles';
 
-export interface SketchPresetFile {
+export interface SketchStyleFile {
   name: string;
   createdAt?: string;
   updatedAt?: string;
-  settings: SketchSettings;
+  settings: SketchStyle;
 }
 
-export interface SketchPresetMeta {
+export interface SketchStyleMeta {
   name: string;
   fileName: string;
   updatedAt: string;
 }
 
-const BASE = `${API_BASE}/sketch-presets`;
+const BASE = `${API_BASE}/sketch-styles`;
 
 /** Slug for the file name. The display name is stored inside the file, so this
     only has to be stable, unique-ish and inside the route's charset. */
-export function slugifySketchPreset(name: string): string {
+export function slugifySketchStyle(name: string): string {
   return name
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
@@ -26,24 +26,24 @@ export function slugifySketchPreset(name: string): string {
     .slice(0, 60);
 }
 
-export async function listSketchPresets(): Promise<SketchPresetMeta[]> {
+export async function listSketchStyles(): Promise<SketchStyleMeta[]> {
   const res = await fetch(BASE);
-  if (!res.ok) throw new Error('Failed to list sketch presets');
+  if (!res.ok) throw new Error('Failed to list sketchstyles');
   const body = await res.json();
   return body.files ?? [];
 }
 
-export async function loadSketchPreset(fileName: string): Promise<SketchPresetFile> {
+export async function loadSketchStyle(fileName: string): Promise<SketchStyleFile> {
   const res = await fetch(`${BASE}/${encodeURIComponent(fileName)}`);
-  if (!res.ok) throw new Error(`Failed to load sketch preset: ${fileName}`);
+  if (!res.ok) throw new Error(`Failed to load sketchstyle: ${fileName}`);
   const body = await res.json();
-  return { ...body, settings: hydrateSketchSettings(body.settings) };
+  return { ...body, settings: hydrateSketchStyle(body.settings) };
 }
 
-export async function saveSketchPreset(
+export async function saveSketchStyle(
   fileName: string,
   name: string,
-  settings: SketchSettings,
+  settings: SketchStyle,
 ): Promise<void> {
   const res = await fetch(`${BASE}/${encodeURIComponent(fileName)}`, {
     method: 'PUT',
@@ -56,7 +56,7 @@ export async function saveSketchPreset(
   }
 }
 
-export async function deleteSketchPreset(fileName: string): Promise<void> {
+export async function deleteSketchStyle(fileName: string): Promise<void> {
   const res = await fetch(`${BASE}/${encodeURIComponent(fileName)}`, { method: 'DELETE' });
   if (!res.ok) {
     const err = await res.json().catch(() => ({ error: 'Delete failed' }));

package/src/editor/core/sketch/{sketchPresets.ts → sketchStyles.ts}

@@ -1,4 +1,4 @@
-export interface SketchSettings {
+export interface SketchStyle {
   label: string;
   blurb: string;
   /** How far the fill's edge travels at its furthest, in px. Every dial that
@@ -62,11 +62,10 @@ export interface SketchSettings {
   /** Wavelength of the coverage noise, in page px. Small gives speckle, large gives broad patches. */
   maskBlob: number;
   /** Output levels on the coverage field, 0 to 1: the palest the fill gets and
-      the densest. 0 is bare and 1 is whole, so 0.4 to 1 is a fill that is never
-      thinner than 40% ink, and 0 to 0.8 one that never quite fills in. Close
-      together is a flat wash, far apart a strong blotch. The field is stretched
-      onto its own measured range before they apply, so both mean the same thing
-      at every grain and octave count. */
+      the densest. The whole field is squeezed into the gap, never cut at it, so
+      0.4 to 1 is a fill that is never thinner than 40% ink and 0 to 0.8 one
+      that never quite fills in. Close together is a flat wash, far apart a
+      strong blotch. */
   maskOutputMin: number;
   maskOutputMax: number;
   /** Detail layers. 1-2 gives broad blobs, 4+ goes cloudy and stops reading as blotches. */
@@ -120,7 +119,7 @@ export interface SketchSettings {
   iconMaskScale: number;
 }
 
-const base: SketchSettings = {
+const base: SketchStyle = {
   label: '', blurb: '',
   fillTravel: 1.5, strokeTravel: 1.5, wobble: 45, roughness: 3,
   borderWavelength: 1, waveform: 1,
@@ -134,13 +133,13 @@ const base: SketchSettings = {
   iconTravel: 1.25, iconWavelength: 0.625, iconMaskOn: true, iconMaskScale: 1,
 };
 
-export const SKETCH_PRESETS: Record<string, SketchSettings> = {
+export const SKETCH_STYLES: Record<string, SketchStyle> = {
   pencil: {
     ...base, label: 'Pencil',
     blurb: 'Two graphite passes on their own seeds, so the outline disagrees with itself the way a hand coming back round does. Tight grain, little else.',
     fillTravel: 0.75, strokeTravel: 1.25, wobble: 30, roughness: 3, waveform: 1,
     strokeWidth: 1.25, doubleStroke: true, retracePass: 'reseeded', retraceOffset: 1.5, strokeInk: 0.85,
-    maskBlob: 40, maskOutputMin: 0.62, maskOutputMax: 1, maskOctaves: 3, maskPosterize: 1, maskSoftness: 0.6,
+    maskBlob: 40, maskOutputMin: 0.62, maskOutputMax: 1, maskOctaves: 3, maskPosterize: 1, maskSoftness: 0,
     jitterX: 1.5, jitterY: 1.5, jitterRot: 0.35, jitterScale: 0.022,
     cornerSpread: 6, cornerTravel: 4.5,
     pressure: 0.15, pressureMod: 0.3, pooling: 0, iconTravel: 0.75,
@@ -151,7 +150,7 @@ export const SKETCH_PRESETS: Record<string, SketchSettings> = {
     blurb: 'Broad translucent nib gone round twice on the same line, so the overlap darkens and the ink pools where it slows.',
     fillTravel: 2, strokeTravel: 1.5, wobble: 56, waveform: 1.4, borderWavelength: 1.3,
     strokeWidth: 4, doubleStroke: true, retracePass: 'copy', strokeInk: 0.52, retraceOffset: 2.2,
-    maskBlob: 115, maskOutputMin: 0.21, maskOutputMax: 1, maskOctaves: 3, maskPosterize: 4, maskSoftness: 2.5,
+    maskBlob: 115, maskOutputMin: 0.42, maskOutputMax: 1, maskOctaves: 3, maskPosterize: 4, maskSoftness: 4,
     jitterX: 3, jitterY: 3, jitterRot: 0.8, jitterScale: 0.045,
     cornerSpread: 10, cornerTravel: 8,
     pressure: 0.2, pressureMod: 0.25, pooling: 2, iconTravel: 1.25, iconMaskScale: 4,
@@ -162,8 +161,8 @@ export const SKETCH_PRESETS: Record<string, SketchSettings> = {
     blurb: 'The fattest nib on glass. One long smooth undulation, and a veined mask that streaks the fill like a half-wiped board.',
     fillTravel: 2.5, strokeTravel: 2.5, wobble: 90, roughness: 1, waveform: 1, borderWavelength: 1.5,
     strokeWidth: 5.5, doubleStroke: true, retracePass: 'copy', strokeInk: 0.66, retraceOffset: 3,
-    maskGrain: 'turbulence', maskBlob: 180, maskOutputMin: 0.42, maskOutputMax: 0.9,
-    maskOctaves: 1, maskPosterize: 3, maskSoftness: 5,
+    maskGrain: 'turbulence', maskBlob: 180, maskOutputMin: 0.42, maskOutputMax: 1,
+    maskOctaves: 1, maskPosterize: 3, maskSoftness: 8,
     jitterX: 4.5, jitterY: 4.5, jitterRot: 1.2, jitterScale: 0.07,
     cornerSpread: 14, cornerTravel: 11,
     pressure: 0.15, pressureMod: 0.15, pooling: 3.5, iconTravel: 1.75, iconMaskScale: 1.5,
@@ -196,7 +195,7 @@ export const SKETCH_PRESETS: Record<string, SketchSettings> = {
     blurb: 'Ballpoint in a hurry. Everything loose at once: a square wave sends every edge to full travel, and the second pass lands wherever it lands.',
     fillTravel: 3, strokeTravel: 2.25, wobble: 50, roughness: 3, waveform: 2.5,
     strokeWidth: 2.25, doubleStroke: true, retracePass: 'reseeded', retraceOffset: 4, strokeInk: 1,
-    maskBlob: 150, maskOutputMin: 0.43, maskOutputMax: 0.95, maskOctaves: 2, maskPosterize: 2, maskSoftness: 6.7,
+    maskBlob: 150, maskOutputMin: 0.43, maskOutputMax: 0.95, maskOctaves: 2, maskPosterize: 2, maskSoftness: 10,
     jitterX: 6, jitterY: 6, jitterRot: 1.8, jitterScale: 0.1,
     cornerSpread: 20, cornerTravel: 17,
     pressure: 0.45, pressureMod: 0.6, pooling: 2.5, iconTravel: 2.25, iconMaskScale: 3.6,
@@ -207,7 +206,7 @@ export const SKETCH_PRESETS: Record<string, SketchSettings> = {
     blurb: 'Ink that ran out. One scratchy pass that breaks up along its length, over a fill the mask has worn nearly through in patches.',
     fillTravel: 2.25, strokeTravel: 1.75, wobble: 50, waveform: 2, borderWavelength: 0.5,
     strokeWidth: 3.5, doubleStroke: false, strokeInk: 0.4,
-    maskBlob: 150, maskOutputMin: 0.15, maskOutputMax: 0.91,
+    maskBlob: 150, maskOutputMin: 0.24, maskOutputMax: 0.91,
     maskOctaves: 2, maskPosterize: 4, maskSoftness: 1.75,
     jitterX: 5, jitterY: 5, jitterRot: 1.4, jitterScale: 0.08,
     cornerSpread: 16, cornerTravel: 13,
@@ -215,17 +214,17 @@ export const SKETCH_PRESETS: Record<string, SketchSettings> = {
   },
 };
 
-export const DEFAULT_SKETCH_PRESET = 'marker';
+export const DEFAULT_SKETCH_STYLE = 'marker';
 
-/** Reconciled against a full preset in both directions: a value stored before a
+/** 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 hydrateSketchSettings(raw: unknown): SketchSettings {
-  const base = SKETCH_PRESETS[DEFAULT_SKETCH_PRESET];
-  const stored = (raw ?? {}) as Partial<SketchSettings>;
+export function hydrateSketchStyle(raw: unknown): SketchStyle {
+  const base = SKETCH_STYLES[DEFAULT_SKETCH_STYLE];
+  const stored = (raw ?? {}) as Partial<SketchStyle>;
   const out = { ...base };
-  for (const key of Object.keys(base) as (keyof SketchSettings)[]) {
+  for (const key of Object.keys(base) as (keyof SketchStyle)[]) {
     if (stored[key] !== undefined) (out[key] as unknown) = stored[key];
   }
   // A retired option: the fill's presence belongs to the theme, not the effect.
@@ -242,8 +241,8 @@ export function hydrateSketchSettings(raw: unknown): SketchSettings {
 
 /** 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
-    distance rather than at whatever the fallback preset happens to carry. */
-function restoreDerivedRetrace(stored: Record<string, unknown>, out: SketchSettings): void {
+    distance rather than at whatever the fallback sketchstyle happens to carry. */
+function restoreDerivedRetrace(stored: Record<string, unknown>, out: SketchStyle): void {
   if (stored.retraceOffset === undefined) {
     out.retraceOffset = Number(Math.max(1.2, out.strokeWidth * 0.55).toFixed(2));
   }
@@ -263,7 +262,7 @@ 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: SketchSettings): void {
+function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchStyle): 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
@@ -286,13 +285,13 @@ function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchS
     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: SketchSettings): void {
+function convertIconTileToScale(stored: Record<string, unknown>, out: SketchStyle): 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: SketchSettings): void {
+function halveSwingDials(stored: Record<string, unknown>, out: SketchStyle): void {
   for (const [legacy, key] of Object.entries(SWING_DIALS)) {
     const value = stored[legacy];
     if (typeof value === 'number') out[key as 'fillTravel'] = value / 2;
@@ -302,7 +301,7 @@ function halveSwingDials(stored: Record<string, unknown>, out: SketchSettings):
 /** 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: SketchSettings): void {
+function convertTiledMask(stored: Record<string, unknown>, out: SketchStyle): void {
   const scale = stored.maskScale;
   if (typeof scale !== 'number') return;
   const freq = stored.maskFrequency;
@@ -317,7 +316,7 @@ function convertTiledMask(stored: Record<string, unknown>, out: SketchSettings):
  * 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: SketchSettings): void {
+function convertCutToLevels(stored: Record<string, unknown>, out: SketchStyle): void {
   const contrast = stored.maskContrast;
   const coverage = stored.maskCoverage;
   if (typeof contrast !== 'number' || typeof coverage !== 'number') return;
@@ -333,7 +332,7 @@ function convertCutToLevels(stored: Record<string, unknown>, out: SketchSettings
     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,
     which keeps its spread and loses only the hole. */
-function carryLevelsToOutput(stored: Record<string, unknown>, out: SketchSettings): void {
+function carryLevelsToOutput(stored: Record<string, unknown>, out: SketchStyle): void {
   if (typeof stored.maskLevelMin === 'number') out.maskOutputMin = stored.maskLevelMin;
   if (typeof stored.maskLevelMax === 'number') out.maskOutputMax = stored.maskLevelMax;
 }

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

@@ -2,6 +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 type { ApplyThemeResult } from './themeService';
 
 const CHANNEL_NAME = 'live-tokens:active-theme:v1';
@@ -42,6 +43,7 @@ export function hydrateAppliedTheme(fileName: string, result: ApplyThemeResult):
   migrateColorsAndTypeFonts(colorsAndType);
   loadThemeFromApi(colorsAndType, structuredClone(result.componentConfigs));
   openThemeSlug.set(fileName);
+  openThemeSketchStyle(result.theme.sketchStyle);
   liveMovedSinceBake.set(false);
   if (typeof document !== 'undefined') {
     document.dispatchEvent(new CustomEvent<AppliedThemeDetail>(THEME_APPLIED_EVENT, {

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

@@ -1,10 +1,11 @@
-import type { AliasDiskValue, ColorsAndType } from './themeTypes';
+import type { AliasDiskValue, ColorsAndType, Theme } from './themeTypes';
 import { openThemeSlug } from '../store/editorConfigStore';
 import { migrateColorsAndTypeFonts } from '../fonts/fontMigration';
 import { loadFromFile, seedComponentsFromApi } from '../store/editorStore';
 import { getActiveComponentConfig, type ComponentSummary } from '../components/componentConfigService';
 import { safeFetch } from '../storage/storage';
 import { API_BASE } from '../storage/apiBase';
+import { hasPersistedSketchState, openThemeSketchStyle, themeSketchStyle } from '../sketch/sketchStore';
 
 interface ListComponentsDto {
   components: ComponentSummary[];
@@ -61,4 +62,21 @@ export async function initializeTheme(): Promise<void> {
     // and CSS defaults because one request happened to fail during boot.
     if (!componentReadFailed) seedComponentsFromApi(configs);
   }
+
+  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
+  // browser a blank buffer, over a fetch that will likely succeed next time.
+  if (active) {
+    if (hasPersistedSketchState()) {
+      // The buffer already painted on the first frame; boot only learns what
+      // the theme holds so unsaved dial work reads as unsaved rather than
+      // getting silently overwritten (that overwrite is what Apply is for).
+      themeSketchStyle.set(active.sketchStyle);
+    } else {
+      // Nothing was ever recorded in this browser: the theme's value becomes
+      // the live value, the same reconciliation opening a theme performs.
+      openThemeSketchStyle(active.sketchStyle);
+    }
+  }
 }

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

@@ -7,6 +7,7 @@ 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';
 
 export type { ThemeFillReport };
 
@@ -144,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'>> {
+async function captureLook(): Promise<Pick<Theme, 'colorsAndType' | 'componentConfigs' | 'sketchStyle'>> {
   const liveColorsAndType = await getActiveColorsAndType();
   if (!liveColorsAndType) {
     throw new Error('No live colors and type to capture');
@@ -156,7 +157,9 @@ async function captureLook(): Promise<Pick<Theme, 'colorsAndType' | 'componentCo
     const config = configs[i];
     if (config) componentConfigs[c.name] = withoutLiveMarkers(config);
   });
-  return { colorsAndType: withoutLiveMarkers(liveColorsAndType), componentConfigs };
+  // 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() };
 }
 
 /**
@@ -178,6 +181,7 @@ export async function saveAsTheme(
     componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
     ...look,
   });
+  themeSketchStyle.set(look.sketchStyle);
   liveMovedSinceBake.set(true);
   await setActiveTheme(fileName);
 }
@@ -201,6 +205,7 @@ export async function saveActiveTheme(displayName?: string): Promise<void> {
     componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
     ...look,
   });
+  themeSketchStyle.set(look.sketchStyle);
   liveMovedSinceBake.set(true);
 }
 

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

@@ -2,6 +2,7 @@ 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';
 /** 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
@@ -279,6 +280,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
+   *  crisp: presence is the on state, so there is no separate flag that can
+   *  disagree with the dials beside it (RJC 1). */
+  sketchStyle?: SketchStyle;
   /** Server-attached file-name marker. Same role as `ColorsAndType._fileName`. */
   _fileName?: string;
 }

package/src/editor/docs/content/editing-tokens.md

@@ -11,7 +11,7 @@ The editor has four views:
   tell across a page.
 - **Components**: per-component editors. Re-Assign what tokens a component uses
   without changing the underlying system.
-- **Sketch Style**: an effect layer that redraws the page by hand. See
+- **Sketchstyle**: an effect layer that redraws the page by hand. See
   [Sketch mode](sketch-mode.md).
 
 This page covers **Tokens**. For components, see

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

@@ -4,12 +4,11 @@ Sketch mode redraws your whole page as if it had been drawn by hand. Every
 component keeps its own colours, spacing and corners; what changes is the line
 they are drawn with.
 
-It is an effect layer, not a set of token values. It reads nothing from your
-theme and writes nothing back, so it never touches a token, never lands in a
-theme file, and never reaches the CSS you ship. Turn it off and every trace of
-it goes.
+It is an effect layer, not a set of token values. It never touches a token
+itself, so turning it off returns every component to exactly what its tokens
+already say. A production build never carries the drawing.
 
-Open the **Sketch Style** view in the editor and switch **Sketch mode** on. The effect
+Open the **Sketchstyle** view in the editor and switch **Sketch mode** on. The effect
 applies to the page behind the editor as well as to the preview, so what you see
 in context is what it does.
 
@@ -21,10 +20,10 @@ are pushed around one shared field of noise. Because every component samples the
 same field, the whole page reads as one drawing rather than as a set of
 separately wobbled boxes.
 
-## The presets
+## The sketchstyles
 
 Seven looks ship with the package, and each is a complete set of dials rather
-than a style name:
+than just a name:
 
 - **Pencil.** Two graphite passes on their own seeds, so the outline disagrees
   with itself the way a hand coming back round does.
@@ -39,9 +38,10 @@ than a style name:
 - **Napkin.** Ballpoint in a hurry. Everything loose at once.
 - **Dry marker.** Ink that ran out. One scratchy pass over a mostly eaten fill.
 
-Pick one, then move whatever you like. **Save** keeps your dials under a name of
-your own, alongside the shipped seven, as a file under
-`src/live-tokens/data/sketch-presets/`.
+Pick one, then move whatever you like. **Save as sketchstyle…** keeps your
+dials under a name of your own, alongside the shipped seven, as a file under
+`src/live-tokens/data/sketch-styles/`. That is a different gesture from
+saving a theme; see "Where the settings live" below.
 
 ## The dials
 
@@ -50,8 +50,13 @@ your own, alongside the shipped seven, as a file under
   few pixels off or runs it through the pen again on its own seed.
 - **Fill.** Solid or hatched, how far the fill's edge travels, and how far each
   instance is offset, rotated and scaled from its neighbours. **Ink coverage**
-  thins the fill with a field of blotches: set their size, how many levels of
-  detail, how pale and how dense they go, and how soft their edges are.
+  thins the fill with a field of blotches: set their size and how many levels of
+  detail, then work the field as a levels control. The field always runs black
+  to white whatever the noise underneath. Steps flattens it into tones, and
+  Output squeezes the whole of it into the range the ink covers, from how pale
+  it gets at its thinnest to how dense at its fullest. Menus and tooltips are
+  drawn solid whatever the coverage dials say: they float over the page, and a
+  fill worn through in patches lets the page show through them.
 - **Shape.** **Corner spread** rounds each corner by its own share of the dial,
   so no two match. **Corner travel** leans the drawn box into a quadrilateral
   with no two sides parallel. This is the dial that stops a component reading as
@@ -65,14 +70,25 @@ your own, alongside the shipped seven, as a file under
 
 ## Where the settings live
 
-The dials you are moving live in your browser, so the effect follows you across
-reloads and stays off everyone else's screen. **Save** writes a named preset to
-`src/live-tokens/data/sketch-presets/`, which is the only thing that reaches
-disk.
+The sketch layer is part of the theme, the same way colors and type are.
+**Save** in the Theme panel folds your dials into the open theme; **Load**
+applies whatever a theme carries, and turns the effect off for a theme that
+carries none.
+
+Until you save, the dials sit in your browser only. The Theme panel calls
+that state off the theme, the same word it uses for an unsaved component
+change. The built-in **Motion Proto** theme is read-only, so Save
+is disabled there; use **Save As** to fold the dials into a theme of your
+own.
+
+**Save as sketchstyle…** in the **Sketchstyle** view is a different gesture. It
+writes a named sketchstyle to `src/live-tokens/data/sketch-styles/`, a look you
+can pick from any theme. It never touches the open theme, and it never marks
+the look off the theme.
 
 Sketch mode is a tool for looking at the page, not a layer the page can ship.
-Nothing is written into a theme, `tokens.generated.css` never sees it, and a
-production build has no sketch layer in it at all.
+The theme records the dials, but nothing bakes them: `tokens.generated.css`
+never sees them, and a production build has no sketch layer in it at all.
 
 ## Drawing your own elements
 

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

@@ -5,14 +5,19 @@ 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, 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, a setting for every component, and the sketch layer, in one
+file. It carries the name the look ships under, whether production is running
+it, and **Adopt**. Three 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 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
+  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.
 
 A theme holds its own copy of every part, so one theme can never break another.
 
@@ -21,13 +26,15 @@ 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.
+  the whole look: 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.
 - **Your unsaved edits** are what the page shows right now. The editor keeps
-  them in your browser as you work and writes them to a buffer, `_working.json`,
-  one slot per part of the look. **Save** captures that buffer into the open
-  theme.
+  them in your browser as you work, writing most parts to a buffer,
+  `_working.json`, one slot each; the sketch layer has no buffer and stays
+  live in the browser until you save. **Save** captures all of it into the
+  open theme.
 - **The production theme** is the one your site ships, named in
   `themes/_production.json`. **Adopt** changes it; saving a preset in the Theme
   Picker performs that Adopt for you.
@@ -96,29 +103,31 @@ to it, and the editor never overwrites it, so start your own with **Save As**.
 ## Switching
 
 **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, 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 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
+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
+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
-stays open. Saved colors and type files are listed there too, marked *colors &
-type*, and picking one is always that narrower load.
+the fonts: your component settings and your sketch layer stay as they are, and
+the theme you have open stays open. Saved colors and type files are listed
+there too, marked *colors & type*, and picking one is always that narrower
+load.
 
 ## Shipping
 
-**Adopt**, in the Theme panel, is the "ship it" step, and it ships the whole
-look. It saves the open theme, then bakes that theme into
+**Adopt**, in the Theme panel, is the "ship it" step. It saves the open theme,
+then bakes the colors and type plus every component the theme carries into
 `src/live-tokens/data/tokens.generated.css`, which your build bundles alongside
-`tokens.css`: the colors and type plus every component the theme carries. Fonts
-regenerate to match. The line under the theme name says whether production is
-running this theme.
+`tokens.css`. The sketch layer is the one part of the theme Adopt never bakes:
+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
 a token, saving a theme: all of it leaves the generated CSS alone until you
-Adopt. A component editor's Adopt runs the same whole-look step, because a
+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
 as a theme of your own first, since the built-in one is read-only.
 

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

@@ -20,15 +20,17 @@ src/live-tokens/data/
       default.json       Button's shipped settings, derived at boot
       _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
   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 plus a
-setting for every component. It depends on no other file, so deleting
-anything else never breaks it.
+A saved theme carries the whole look 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.
 
 ## What writes when
 
@@ -36,8 +38,10 @@ anything else never breaks it.
   edits in the browser as you work and writes them to the `_working.json`
   buffers when you save a component. When the Theme panel finds several dirty
   components, **Save all** writes those buffers together.
-- **Save** captures the buffers into the open theme's file. That file is the
-  durable copy of your look; matching buffers are then removed.
+- **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
+  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.