@motion-proto/live-tokens 0.66.0 → 0.67.0

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

@@ -6,6 +6,7 @@ import {
   hydrateSketchStyle,
   type SketchStyle,
 } from './sketchStyles';
+import { lookById, replaceRegisteredLooks, sketchLooks } from './sketchRegistry';
 import {
   applySketchLayer,
   hostRoot,
@@ -102,18 +103,21 @@ function readBaseline(): SketchStyle | null {
   return null;
 }
 
-/** Marks a saved sketchstyle in `sketchStyleName`, so a user file named `pencil`
-    and the shipped `pencil` stay distinguishable in one string. */
-export const USER_STYLE_PREFIX = 'user:';
+/** Retired. Saved sketchstyles and shipped ones share one id namespace now, so
+    a file named `pencil` replaces the shipped Pencil rather than sitting beside
+    it. Stripped on read below; delete a release after that ships. */
+const RETIRED_USER_PREFIX = 'user:';
 
+/** Deliberately unvalidated. Looks are registered after this module is
+    imported, so an id it has never heard of is the normal case rather than a
+    fault: `selectSketchStyle` no-ops on one, and `sketchPick` already reports
+    a look nothing names as `adjusted`. Only a browser that has stored nothing
+    falls back. */
 function readStyleName(): string {
   try {
     const name = localStorage.getItem(STYLE_NAME_KEY);
-    if (
-      name === '' ||
-      (name && (name in SKETCH_STYLES || name === THEME_SKETCH_ID || name.startsWith(USER_STYLE_PREFIX)))
-    ) {
-      return name;
+    if (name !== null) {
+      return name.startsWith(RETIRED_USER_PREFIX) ? name.slice(RETIRED_USER_PREFIX.length) : name;
     }
   } catch {
     // fall through
@@ -126,9 +130,9 @@ function readStyleName(): string {
 export const sketchEnabled = writable<boolean>(readEnabled());
 export const sketchSettings = writable<SketchStyle>(readSettings());
 /** The sketchstyle the dials started from. It survives dial moves, so the grid
-    keeps showing what the current look is closest to. A shipped id, a `user:`
-    file, or `THEME_SKETCH_ID` for the look the open theme carries; empty only
-    when nothing was picked, or the picked file was deleted. */
+    keeps showing what the current look is closest to. Any id in the pool, or
+    `THEME_SKETCH_ID` for the look the open theme carries; empty only when
+    nothing was picked, or the picked file was deleted. */
 export const sketchStyleName = writable<string>(readStyleName());
 
 /** The settings as the selected sketchstyle defined them. Kept beside the live
@@ -175,9 +179,9 @@ export const themeSketchStyle = writable<SketchStyle | undefined>(undefined);
 
 /** Open a theme's sketchstyle: the dials, the on/off state, and the name
     recovered by comparison (RJC 3). Overwrites the live buffer, which
-    is what opening a theme means everywhere else (RJC 6). Never writes a
-    `user:` name here: a saved sketchstyle is a file this look may not have come
-    from, and the only thing that can name one is picking it. */
+    is what opening a theme means everywhere else (RJC 6). The name is recovered
+    over the whole pool, so a theme carrying a look a saved file also holds is
+    named by that file rather than falling back to `THEME_SKETCH_ID`. */
 export function openThemeSketchStyle(sketchStyle: SketchStyle | undefined): void {
   themeSketchStyle.set(sketchStyle);
   if (!sketchStyle) {
@@ -186,7 +190,7 @@ export function openThemeSketchStyle(sketchStyle: SketchStyle | undefined): void
     sketchStyleName.set('');
     return;
   }
-  const matched = (Object.keys(SKETCH_STYLES) as string[]).find((name) => sameLook(SKETCH_STYLES[name], sketchStyle));
+  const matched = get(sketchLooks).find((look) => sameLook(look.settings, sketchStyle))?.id;
   sketchSettings.set({ ...sketchStyle });
   sketchBaseline.set({ ...sketchStyle });
   sketchStyleName.set(matched ?? THEME_SKETCH_ID);
@@ -249,14 +253,17 @@ export const sketchOffLook = derived(
   },
 );
 
-export function selectSketchStyle(name: string): void {
-  const style = SKETCH_STYLES[name];
-  if (!style) return;
+/** Takes any id in the pool: shipped, or registered from a file or a consumer.
+    Silent for an id nothing knows, the way it has always been for an unknown
+    shipped name. */
+export function selectSketchStyle(id: string): void {
+  const look = lookById(id);
+  if (!look) return;
   markSketchTouched();
   if (get(sketchEnabled)) liveMovedSinceBake.set(true);
-  sketchStyleName.set(name);
-  sketchBaseline.set({ ...style });
-  sketchSettings.set({ ...style });
+  sketchStyleName.set(id);
+  sketchBaseline.set({ ...look.settings });
+  sketchSettings.set({ ...look.settings });
 }
 
 /** Saved sketchstyles, listed from the data tree. Empty until
@@ -264,17 +271,22 @@ export function selectSketchStyle(name: string): void {
     the network. */
 export const savedSketchStyles = writable<SketchStyleMeta[]>([]);
 
+/** Lists the files and registers them in one gesture, so the editor's grid and
+    a built site's picker read the same pool. Loading every file to list them is
+    affordable: a sketchstyle is a few dozen numbers, and the alternative is a
+    grid that cannot paint a row until it is picked. */
 export async function refreshSavedSketchStyles(): Promise<void> {
-  savedSketchStyles.set(await listSketchStyles());
-}
-
-export async function selectSavedSketchStyle(fileName: string): Promise<void> {
-  const file = await loadSketchStyle(fileName);
-  markSketchTouched();
-  if (get(sketchEnabled)) liveMovedSinceBake.set(true);
-  sketchStyleName.set(USER_STYLE_PREFIX + fileName);
-  sketchBaseline.set({ ...file.settings });
-  sketchSettings.set(file.settings);
+  const files = await listSketchStyles();
+  const loaded = await Promise.all(files.map((f) => loadSketchStyle(f.fileName)));
+  savedSketchStyles.set(files);
+  replaceRegisteredLooks(
+    files.map((file, i) => ({
+      id: file.fileName,
+      label: file.name || file.fileName,
+      settings: loaded[i].settings,
+      source: file.isPackage ? ('shipped' as const) : ('file' as const),
+    })),
+  );
 }
 
 /** Writes whatever the dials currently say to a named file and selects it, so
@@ -291,15 +303,34 @@ export async function saveCurrentSketchStyle(name: string): Promise<string> {
   await refreshSavedSketchStyles();
   sketchSettings.set(settings);
   sketchBaseline.set({ ...settings });
-  sketchStyleName.set(USER_STYLE_PREFIX + fileName);
+  sketchStyleName.set(fileName);
   return fileName;
 }
 
+/** Overwrite the selected saved sketchstyle. The file name comes from the
+    selection rather than from re-slugifying the label, because the two can
+    disagree: a file hand-edited to a new display name would otherwise be saved
+    beside itself under a fresh slug instead of over itself. The label comes
+    from the look for the same reason, so the name the grid shows survives.
+
+    No `markSketchTouched`: the button only lights once a dial has moved, and
+    every dial goes through `updateSketchSettings`, which marks it. */
+export async function saveSelectedSketchStyle(): Promise<void> {
+  const look = lookById(get(sketchStyleName));
+  if (look?.source !== 'file') throw new Error('No saved sketchstyle is selected');
+  const settings = { ...get(sketchSettings) };
+  await saveSketchStyle(look.id, look.label, settings);
+  await refreshSavedSketchStyles();
+  // Re-baselining is what disables the button again and returns the readout
+  // from "Modified from X" to the saved blurb.
+  sketchBaseline.set(settings);
+}
+
 export async function deleteSavedSketchStyle(fileName: string): Promise<void> {
   await deleteSketchStyle(fileName);
   await refreshSavedSketchStyles();
   // The dials keep their values; only the name stops naming a file that exists.
-  if (get(sketchStyleName) === USER_STYLE_PREFIX + fileName) {
+  if (get(sketchStyleName) === fileName) {
     sketchStyleName.set('');
     sketchBaseline.set(null);
   }

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

@@ -12,6 +12,9 @@ export interface SketchStyleMeta {
   name: string;
   fileName: string;
   updatedAt: string;
+  /** Served from the package rather than this project, so there is no local
+      file to write over or delete. Saving over one creates that file. */
+  isPackage: boolean;
 }
 
 const BASE = `${API_BASE}/sketch-styles`;

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

@@ -1,3 +1,11 @@
+import pencil from '../../../live-tokens/data/sketch-styles/pencil.json';
+import marker from '../../../live-tokens/data/sketch-styles/marker.json';
+import whiteboard from '../../../live-tokens/data/sketch-styles/whiteboard.json';
+import hatched from '../../../live-tokens/data/sketch-styles/hatched.json';
+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 {
   label: string;
   blurb: string;
@@ -59,8 +67,22 @@ export interface SketchStyle {
   hatchInk: number;
   strokeStyle: 'solid' | 'dashed';
   maskOn: boolean;
-  /** Wavelength of the coverage noise, in page px. Small gives speckle, large gives broad patches. */
-  maskBlob: number;
+  /** Blob size of the coverage noise, in page px, across and down. Small gives
+      speckle, large gives broad patches. */
+  maskBlobX: number;
+  maskBlobY: number;
+  /** Which way the stretch runs, in degrees clockwise from level. Nothing at
+      all while the two blob sizes match, since a field the same in every
+      direction is the same field turned. The tile only meets itself at the
+      angles that land the page's axes back on whole cells, so the dial is
+      answered with the nearest of those. */
+  maskAngle: number;
+  /** 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
+      dials apart. */
+  maskBlobLinked: boolean;
   /** Output levels on the coverage field, 0 to 1: the palest the fill gets and
       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
@@ -119,100 +141,25 @@ export interface SketchStyle {
   iconMaskScale: number;
 }
 
-const base: SketchStyle = {
-  label: '', blurb: '',
-  fillTravel: 1.5, strokeTravel: 1.5, wobble: 45, roughness: 3,
-  borderWavelength: 1, waveform: 1,
-  strokeWidth: 1.5, doubleStroke: false, retraceOffset: 1.2, retracePass: 'copy',
-  fillStyle: 'solid', hatchInk: 0.4, strokeStyle: 'solid',
-  pressure: 0.25, pressureMod: 0.35, pooling: 1.2, strokeInk: 1,
-  maskOn: true, maskBlob: 100, maskOutputMin: 0.45, maskOutputMax: 1,
-  maskOctaves: 2, maskGrain: 'fractal', maskPosterize: 1, maskSoftness: 1.5,
-  jitterX: 2.5, jitterY: 2.5, jitterRot: 0.6, jitterScale: 0.035,
-  cornerSpread: 10, cornerTravel: 8,
-  iconTravel: 1.25, iconWavelength: 0.625, iconMaskOn: true, iconMaskScale: 1,
-};
-
-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,
-    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,
-  },
-
-  marker: {
-    ...base, label: 'Marker',
-    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.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,
-  },
-
-  whiteboard: {
-    ...base, label: 'Whiteboard',
-    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: 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,
-  },
-
-  hatched: {
-    ...base, label: 'Hatched',
-    blurb: 'An etching. The fill is angled shading, the outline a single hard-edged scratch that chatters along its length. No mask: the hatch is the texture.',
-    fillTravel: 1.25, strokeTravel: 1.5, wobble: 24, roughness: 3, waveform: 3,
-    strokeWidth: 1.5, fillStyle: 'hatched', hatchInk: 0.5, doubleStroke: false,
-    maskOn: false, iconMaskOn: false,
-    jitterX: 1.5, jitterY: 1.5, jitterRot: 0.4, jitterScale: 0.03,
-    cornerSpread: 6, cornerTravel: 6,
-    pressure: 0.3, pressureMod: 0.45, pooling: 0.8, iconTravel: 1.25, iconWavelength: 0.5,
-  },
-
-  dashed: {
-    ...base, label: 'Dashed',
-    blurb: 'A drafting outline. One slow drift along the ruler, broken into strokes, with jitter, mask and pressure all off. The clean pole.',
-    strokeStyle: 'dashed', strokeTravel: 1, fillTravel: 0.5, wobble: 120, roughness: 1, waveform: 1,
-    strokeWidth: 1.5, doubleStroke: false,
-    maskOn: false, iconMaskOn: false,
-    jitterX: 0, jitterY: 0, jitterRot: 0, jitterScale: 0,
-    cornerSpread: 4, cornerTravel: 3,
-    pressure: 0, pressureMod: 0, pooling: 0, iconTravel: 0,
-  },
-
-  napkin: {
-    ...base, label: 'Napkin',
-    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: 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,
-  },
+/**
+ * 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
+ * `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
+ * 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.
+ *
+ * Order is picker order.
+ */
+const SHIPPED_FILES = { pencil, marker, whiteboard, hatched, dashed, napkin, dry };
 
-  dry: {
-    ...base, label: 'Dry marker',
-    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.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,
-    pressure: 0.4, pressureMod: 0.8, pooling: 1.5, iconTravel: 1.75, iconMaskScale: 3.8,
-  },
-};
+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 DEFAULT_SKETCH_STYLE = 'marker';
 
@@ -239,6 +186,7 @@ export function hydrateSketchStyle(raw: unknown): SketchStyle {
   convertCutToLevels(stored as Record<string, unknown>, out);
   carryLevelsToOutput(stored as Record<string, unknown>, out);
   halveSwingDials(stored as Record<string, unknown>, out);
+  splitBlobAxes(stored as Record<string, unknown>, out);
   convertCyclesToWavelength(stored as Record<string, unknown>, out);
   convertIconTileToScale(stored as Record<string, unknown>, out);
   restoreDerivedRetrace(stored as Record<string, unknown>, out);
@@ -286,6 +234,16 @@ 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 {
+  const blob = stored.maskBlob;
+  if (typeof blob !== 'number') return;
+  out.maskBlobX = blob;
+  out.maskBlobY = blob;
+  out.maskBlobLinked = true;
+}
+
 /** The icon mask tile used to be a px size, which is a unit the glyph it covers
     has no say in: 90px against a 16px icon put a whole glyph inside one patch
     of the field, so it came out either untouched or gone. It is a share of the
@@ -311,7 +269,10 @@ function convertTiledMask(stored: Record<string, unknown>, out: SketchStyle): vo
   const scale = stored.maskScale;
   if (typeof scale !== 'number') return;
   const freq = stored.maskFrequency;
-  if (typeof freq === 'number') out.maskBlob = Math.round(scale / (freq * LEGACY_TILE));
+  if (typeof freq === 'number') {
+    out.maskBlobX = Math.round(scale / (freq * LEGACY_TILE));
+    out.maskBlobY = out.maskBlobX;
+  }
   const soft = stored.maskSoftness;
   if (typeof soft === 'number') out.maskSoftness = Number(((soft * scale) / LEGACY_TILE).toFixed(1));
 }

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

@@ -38,10 +38,22 @@ 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.
 
-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.
+All seven ship as files, one per look, under
+`src/live-tokens/data/sketch-styles/` in the package. There is no look 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
+of your own, alongside the shipped seven, as a file under
+`src/live-tokens/data/sketch-styles/` in your project. **Save** writes them back
+over the sketchstyle you have selected, and lights as soon as the dials leave
+it. On one of your own it writes that file. On a shipped one it writes your
+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.
+
+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.
 
 ## The dials
 
@@ -50,8 +62,11 @@ saving a theme; see "Where the settings live" below.
   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 and how many levels of
-  detail, then work the field as a levels control. The field always runs black
+  thins the fill with a field of blotches: set their size across and down and
+  how many levels of detail, then work the field as a levels control. The two
+  sizes move together under a chain; break it and the blotches stretch, which
+  reads as ink dragged along the axis you widened, and a **Rotation** dial joins
+  them to point that stretch anywhere you like. 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
@@ -81,9 +96,9 @@ 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
+**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
+you can pick from any theme. Neither touches the open theme, and neither marks
 the look off the theme.
 
 ## Shipping the layer
@@ -111,11 +126,38 @@ A visitor who has picked a look 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.
 
-If your site offers a sketch picker, `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 one of the shipped seven, since that row already names it. Give the
-row `setSketch(look.id)` like any other, and a visitor who wanders off the
-theme's look can come back to it.
+### Your own sketchstyles
+
+The dev server lists the files in `sketch-styles/`. A built site has no server
+to ask, so it hands them over at boot, the way it hands over components:
+
+```ts
+const files = import.meta.glob<{ name?: string; settings: unknown }>(
+  './live-tokens/data/sketch-styles/*.json',
+  { eager: true, import: 'default' },
+);
+
+await bootLiveTokens(App, '#app', {
+  sketchLooks: 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
+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.
+
+`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.
 
 ## Drawing your own elements
 

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

@@ -7,7 +7,7 @@ export const docContent: Record<string, string> = {
   "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 four views:\n\n- **Tokens**: the design-system primitives (colour, type, spacing, and so on).\n  They apply everywhere your site uses them.\n- **Color Wheel**: the harmony wheel, the palette curves, and the story your colours\n  tell across a page.\n- **Components**: per-component editors. Re-Assign what tokens a component uses\n  without changing the underlying system.\n- **Sketchstyle**: an effect layer that redraws the page by hand. See\n  [Sketch mode](sketch-mode.md).\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",
   "light-and-dark": "# Light and dark\n\nSome things on a page cannot be written as a token. A wordmark drawn in white\ndisappears on a pale theme. Ink that multiplies onto paper vanishes on a dark\none. A photograph behind a headline is dark no matter what the palette says.\n\nEach of those needs the same fact first: which way does the surface behind this\nthing lean? One attribute carries it.\n\n## The attribute\n\n`data-backdrop` is either `light` or `dark`, and it does two things at once: it\nselects, so a rule can key on it, and it sets `color-scheme`, so every\n`light-dark()` under it resolves the half that reads.\n\n```css\n.title {\n  color: light-dark(var(--color-black), var(--color-white));\n}\n```\n\nThat line is right on both sides of the theme, and it is right inside a dark\nband on a pale page, because the nearest `color-scheme` wins.\n\n## Stating it\n\nPut it in the markup when the surface knows its own tone — a hero over a\nphotograph, a plate that stays pale in every theme:\n\n```svelte\n<div class=\"hero-panel\" data-backdrop=\"dark\">\n```\n\nA stated tone beats any measurement, and it inherits, so everything inside the\npanel resolves against it.\n\n## Measuring it\n\nWhere the tone is a property of the theme rather than of the markup, let it be\nmeasured:\n\n```svelte\n<script>\n  import { backdrop } from '@motion-proto/live-tokens/backdrop';\n</script>\n\n<section use:backdrop>\n```\n\nThe action reads whatever actually paints behind the element — the nearest\nancestor with an opaque fill, averaged across its gradient stops, falling back\nto the theme's `--page-bg` — and stamps the answer. It re-reads when the theme\nchanges, which the editor does by rewriting custom properties with no reload,\nso the stamp follows a live edit.\n\nThe page itself is stamped for you: the build bakes the production theme's\npolarity into `tokens.generated.css`, so the first paint is already right, and\n`syncDocumentBackdrop()` keeps `<html>` current as themes switch.\n\n```ts\nimport { syncDocumentBackdrop } from '@motion-proto/live-tokens/backdrop';\n\nsyncDocumentBackdrop();\n```\n\n## Reading it from JavaScript\n\nAnything that paints outside CSS — a canvas, a WebGL uniform, an `<img>` that\ncomes in two versions — asks the same question through the same module:\n\n```ts\nimport { isLightBackdrop, watchBackdrop, cssColorToHex } from '@motion-proto/live-tokens/backdrop';\n\nconst stop = watchBackdrop(logoEl, {\n  stamp: false,\n  onChange: (polarity) => (src = polarity === 'light' ? darkMark : lightMark),\n});\n```\n\n`isLightBackdrop(el)` answers once. `watchBackdrop` keeps answering and returns\na stop function. `cssColorToHex` resolves any CSS colour — including the\n`oklch()` a token holds — to a hex a non-CSS consumer can take.\n\n## What it does not do\n\nPolarity is a property of a surface, not of a component, so nothing is stamped\nfor you below `<html>`: a section that needs an answer either states one or asks\nfor one. And a measurement reads the paint at the moment it runs — an element\nthat scrolls from a pale band onto a dark one keeps the answer it was given.\nState the tone on each band instead.\n",
-  "sketch-mode": "# Sketch mode\n\nSketch mode redraws your whole page as if it had been drawn by hand. Every\ncomponent keeps its own colours, spacing and corners; what changes is the line\nthey are drawn with.\n\nIt is an effect layer, not a set of token values. It never touches a token\nitself, so turning it off returns every component to exactly what its tokens\nalready say.\n\nOpen the **Sketchstyle** view in the editor and switch **Sketch mode** on. The effect\napplies to the page behind the editor as well as to the preview, so what you see\nin context is what it does.\n\n## What it draws\n\nEach component's fill and outline are repainted from the tokens that component\nalready owns. The real background and border are hidden behind them, then both\nare pushed around one shared field of noise. Because every component samples the\nsame field, the whole page reads as one drawing rather than as a set of\nseparately wobbled boxes.\n\n## The sketchstyles\n\nSeven looks ship with the package, and each is a complete set of dials rather\nthan just a name:\n\n- **Pencil.** Two graphite passes on their own seeds, so the outline disagrees\n  with itself the way a hand coming back round does.\n- **Marker.** A broad translucent nib gone round twice on the same line, so the\n  overlap darkens and the ink pools where it slows.\n- **Whiteboard.** The fattest nib on glass, with a mask that streaks the fill\n  like a half-wiped board.\n- **Hatched.** An etching. The fill is angled shading and the outline a single\n  hard-edged scratch.\n- **Dashed.** A drafting outline: one slow drift along the ruler, broken into\n  strokes. The clean pole.\n- **Napkin.** Ballpoint in a hurry. Everything loose at once.\n- **Dry marker.** Ink that ran out. One scratchy pass over a mostly eaten fill.\n\nPick one, then move whatever you like. **Save as sketchstyle…** keeps your\ndials under a name of your own, alongside the shipped seven, as a file under\n`src/live-tokens/data/sketch-styles/`. That is a different gesture from\nsaving a theme; see \"Where the settings live\" below.\n\n## The dials\n\n- **Border.** How far the outline travels and how long its wave is, then its\n  width, ink, pressure and pooling. A second pass either copies the first line a\n  few pixels off or runs it through the pen again on its own seed.\n- **Fill.** Solid or hatched, how far the fill's edge travels, and how far each\n  instance is offset, rotated and scaled from its neighbours. **Ink coverage**\n  thins the fill with a field of blotches: set their size and how many levels of\n  detail, then work the field as a levels control. The field always runs black\n  to white whatever the noise underneath. Steps flattens it into tones, and\n  Output squeezes the whole of it into the range the ink covers, from how pale\n  it gets at its thinnest to how dense at its fullest. Menus and tooltips are\n  drawn solid whatever the coverage dials say: they float over the page, and a\n  fill worn through in patches lets the page show through them.\n- **Shape.** **Corner spread** rounds each corner by its own share of the dial,\n  so no two match. **Corner travel** leans the drawn box into a quadrilateral\n  with no two sides parallel. This is the dial that stops a component reading as\n  a rectangle.\n- **Icons and SVG.** Glyph travel and wavelength on their own scale. A glyph is\n  all curves already, so it needs more travel than a card's long straight edge\n  before the wobble reads at all.\n- **Noise.** The shared field itself: its wavelength, how many layers of detail\n  sit on it, and the shape of its wave. A square wave sends nearly every edge to\n  full travel, which is what makes the effect stronger rather than bigger.\n\n## Where the settings live\n\nThe sketch layer is part of the theme, the same way colors and type are.\n**Save** in the Theme panel folds your dials into the open theme; **Load**\napplies whatever a theme carries, and turns the effect off for a theme that\ncarries none.\n\nUntil you save, the dials sit in your browser only. The Theme panel calls\nthat state off the theme, the same word it uses for an unsaved component\nchange. The built-in **Motion Proto** theme is read-only, so Save\nis disabled there; use **Save As** to fold the dials into a theme of your\nown.\n\n**Save as sketchstyle…** in the **Sketchstyle** view is a different gesture. It\nwrites a named sketchstyle to `src/live-tokens/data/sketch-styles/`, a look you\ncan pick from any theme. It never touches the open theme, and it never marks\nthe look off the theme.\n\n## Shipping the layer\n\nThe dev server reads the open theme and paints whatever it carries. A built site\nhas no server to ask, so it hands the field over itself:\n\n```ts\nimport { seedSketchFromTheme } from '@motion-proto/live-tokens/sketch';\nimport theme from './live-tokens/data/themes/sketchy.json';\n\nseedSketchFromTheme(theme.sketchStyle);\nawait bootLiveTokens(App, '#app');\n```\n\nCall it before mounting, so the look is up on the first frame. Pass the field\nraw. A theme written against older dial names is carried forward on the way in,\nthe same reconciliation the dev server runs on every theme it reads.\n\nNothing is baked. `tokens.generated.css` still holds token values only, and the\nlayer stays JavaScript the page runs, because it builds an SVG filter bank\nrather than a set of custom properties.\n\nA visitor who has picked a look of their own keeps it, None included. The theme\nseeds a browser that has decided nothing and never overwrites one that has, so\ncalling this on every boot is safe.\n\nIf your site offers a sketch picker, `themeSketchLook` is the theme's own look\nas one more row. It is null when the theme carries none, and null when what it\ncarries is one of the shipped seven, since that row already names it. Give the\nrow `setSketch(look.id)` like any other, and a visitor who wanders off the\ntheme's look can come back to it.\n\n## Drawing your own elements\n\nThe layer draws a fixed set of parts: the shipped components, and four classes\nit reserves for you. Nothing else is touched, so a page element or a\nconsumer-authored component is left crisp until it carries one of them.\n\n| Class               | For                                                       |\n|---------------------|-----------------------------------------------------------|\n| `sketch-surface`    | A box. The default treatment.                              |\n| `sketch-container`  | A large box. Tilts less, so the type inside stays readable. |\n| `sketch-chip`       | A small box. Finer fill mask, more rotation, less travel.   |\n| `sketch-rule`       | A line rather than a box. No rotation, no rounded ends.     |\n\nPick by size, not by kind: a card and a modal both take `sketch-container`, a\nbadge and a pill both take `sketch-chip`.\n\nThe class opts the element in; it names no colours, so the element states its\nown. `--sketch-fill`, `--sketch-stroke`, `--sketch-hatch-color`,\n`--sketch-radius` and `--sketch-shadow` name the fill, the outline, the hatching\nink, the corners and the shadow for one element and everything inside it. The\nlayer blanks the real background and border, so an element whose fill matters\nunder Sketch mode has to name it here as well as paint it.\n\nThe layer also paints on the element's `::before` and `::after`, forces its\n`overflow` visible, and gives it a stacking context of its own. Keep the class\noff anything that owns a pseudo-element, clips its content, or is positioned\nabsolutely, and put it on a wrapper instead.\n\n```css\n.my-callout {\n  background: var(--surface-brand-lowest);\n  border: var(--border-width-1) solid var(--border-brand);\n  border-radius: var(--radius-xl);\n\n  --sketch-fill: var(--surface-brand-lowest);\n  --sketch-stroke: var(--border-brand);\n  --sketch-radius: var(--radius-xl);\n}\n```\n\nA gradient is a valid fill: the shorthand's last layer takes a colour or an\nimage, so `--sketch-fill` accepts either. States work the same way, since\nnothing is competing with you for the value:\n\n```css\n.my-callout:hover { --sketch-stroke: var(--border-brand-strong); }\n```\n\n## Images inside a drawn part\n\nA drawn part's `overflow` is forced visible, because the fill and outline are\npainted on pseudo-elements that travel past the box and would otherwise be cut\noff at its edge. A background that bleeds is the effect working. An image that\nbleeds is not: it keeps its square corners while the card around it turns.\n\nMedia that runs to a part's edge therefore has to carry that part's corners\nitself. `--sketch-radius` is the radius the layer drew, and it inherits, so a\nchild can read it and fall back to its own value when Sketch mode is off:\n\n```css\n.cover {\n  overflow: hidden;\n  border-top-left-radius: var(--sketch-radius, var(--card-default-radius));\n  border-top-right-radius: var(--sketch-radius, var(--card-default-radius));\n}\n```\n\nCorner spread is per-corner and per-instance, so at high spread the crop is the\nmean rather than an exact trace of the drawn edge.\n\nA rule made from a `border` is not a box and cannot be displaced. Make it an\nelement, give it `sketch-rule`, and name its ink:\n\n```html\n<div class=\"rule sketch-rule\"></div>\n```\n```css\n.rule {\n  height: var(--border-width-2);\n  background: var(--border-brand);\n  --sketch-fill: var(--border-brand);\n}\n```\n\nIcons and inline SVG take the wobble directly, since a glyph has no box to\nredraw. Body type is left alone: an icon is a shape and survives a wobble, a\nparagraph is not.\n\n`--sketch-icon-off` names what a subtree's glyphs are drawn with instead. It\ninherits, so one declaration covers everything under it, and it takes the ink\nmask off as well as the wobble:\n\n```css\n/* Crisp. Chrome, a logo, anything that has to stay exact. */\n.app-bar { --sketch-icon-off: none; }\n\n/* Drawn back rather than off, at a third of the travel. Small artwork, and\n   type set as an SVG, which the layer reads as one large glyph. */\n.wordmark { --sketch-icon-off: var(--sketch-icon-soft); }\n```\n\nThe **Blotch size** dial under Icons and SVG is a share of the glyph rather than\na px size, because no px size is right for both a 16px icon and a page-wide\ndrawing. At 100% every glyph gets one period of the field across it whatever its\nsize. Below that the field repeats inside the glyph and the blotches get finer.\nAbove it a glyph reads part of one blotch, so the mask thins the whole glyph\nunevenly instead of breaking it up. The fill's blotches stay in px, since a\ncomponent does have a size to state one against.\n",
+  "sketch-mode": "# Sketch mode\n\nSketch mode redraws your whole page as if it had been drawn by hand. Every\ncomponent keeps its own colours, spacing and corners; what changes is the line\nthey are drawn with.\n\nIt is an effect layer, not a set of token values. It never touches a token\nitself, so turning it off returns every component to exactly what its tokens\nalready say.\n\nOpen the **Sketchstyle** view in the editor and switch **Sketch mode** on. The effect\napplies to the page behind the editor as well as to the preview, so what you see\nin context is what it does.\n\n## What it draws\n\nEach component's fill and outline are repainted from the tokens that component\nalready owns. The real background and border are hidden behind them, then both\nare pushed around one shared field of noise. Because every component samples the\nsame field, the whole page reads as one drawing rather than as a set of\nseparately wobbled boxes.\n\n## The sketchstyles\n\nSeven looks ship with the package, and each is a complete set of dials rather\nthan just a name:\n\n- **Pencil.** Two graphite passes on their own seeds, so the outline disagrees\n  with itself the way a hand coming back round does.\n- **Marker.** A broad translucent nib gone round twice on the same line, so the\n  overlap darkens and the ink pools where it slows.\n- **Whiteboard.** The fattest nib on glass, with a mask that streaks the fill\n  like a half-wiped board.\n- **Hatched.** An etching. The fill is angled shading and the outline a single\n  hard-edged scratch.\n- **Dashed.** A drafting outline: one slow drift along the ruler, broken into\n  strokes. The clean pole.\n- **Napkin.** Ballpoint in a hurry. Everything loose at once.\n- **Dry marker.** Ink that ran out. One scratchy pass over a mostly eaten fill.\n\nAll seven ship as files, one per look, under\n`src/live-tokens/data/sketch-styles/` in the package. There is no look that\nexists only as code, so every one of them can be read, copied and edited.\n\nPick one, then move whatever you like. **Save As** keeps your dials under a name\nof your own, alongside the shipped seven, as a file under\n`src/live-tokens/data/sketch-styles/` in your project. **Save** writes them back\nover the sketchstyle you have selected, and lights as soon as the dials leave\nit. On one of your own it writes that file. On a shipped one it writes your\nproject's own copy under the same name, which takes its place in the list;\ndelete that copy and the shipped file behind it comes back. Both are a\ndifferent gesture from saving a theme; see \"Where the settings live\" below.\n\nYour sketchstyles and the shipped ones are one list. A sketchstyle named after\na shipped one replaces it, keeping its place in the list, so a project that\nwants its own Pencil saves one and every picker shows that one instead.\n\n## The dials\n\n- **Border.** How far the outline travels and how long its wave is, then its\n  width, ink, pressure and pooling. A second pass either copies the first line a\n  few pixels off or runs it through the pen again on its own seed.\n- **Fill.** Solid or hatched, how far the fill's edge travels, and how far each\n  instance is offset, rotated and scaled from its neighbours. **Ink coverage**\n  thins the fill with a field of blotches: set their size across and down and\n  how many levels of detail, then work the field as a levels control. The two\n  sizes move together under a chain; break it and the blotches stretch, which\n  reads as ink dragged along the axis you widened, and a **Rotation** dial joins\n  them to point that stretch anywhere you like. The field always runs black\n  to white whatever the noise underneath. Steps flattens it into tones, and\n  Output squeezes the whole of it into the range the ink covers, from how pale\n  it gets at its thinnest to how dense at its fullest. Menus and tooltips are\n  drawn solid whatever the coverage dials say: they float over the page, and a\n  fill worn through in patches lets the page show through them.\n- **Shape.** **Corner spread** rounds each corner by its own share of the dial,\n  so no two match. **Corner travel** leans the drawn box into a quadrilateral\n  with no two sides parallel. This is the dial that stops a component reading as\n  a rectangle.\n- **Icons and SVG.** Glyph travel and wavelength on their own scale. A glyph is\n  all curves already, so it needs more travel than a card's long straight edge\n  before the wobble reads at all.\n- **Noise.** The shared field itself: its wavelength, how many layers of detail\n  sit on it, and the shape of its wave. A square wave sends nearly every edge to\n  full travel, which is what makes the effect stronger rather than bigger.\n\n## Where the settings live\n\nThe sketch layer is part of the theme, the same way colors and type are.\n**Save** in the Theme panel folds your dials into the open theme; **Load**\napplies whatever a theme carries, and turns the effect off for a theme that\ncarries none.\n\nUntil you save, the dials sit in your browser only. The Theme panel calls\nthat state off the theme, the same word it uses for an unsaved component\nchange. The built-in **Motion Proto** theme is read-only, so Save\nis disabled there; use **Save As** to fold the dials into a theme of your\nown.\n\n**Save** and **Save As** in the **Sketchstyle** view are a different gesture.\nThey write a named sketchstyle to `src/live-tokens/data/sketch-styles/`, a look\nyou can pick from any theme. Neither touches the open theme, and neither marks\nthe look off the theme.\n\n## Shipping the layer\n\nThe dev server reads the open theme and paints whatever it carries. A built site\nhas no server to ask, so it hands the field over itself:\n\n```ts\nimport { seedSketchFromTheme } from '@motion-proto/live-tokens/sketch';\nimport theme from './live-tokens/data/themes/sketchy.json';\n\nseedSketchFromTheme(theme.sketchStyle);\nawait bootLiveTokens(App, '#app');\n```\n\nCall it before mounting, so the look is up on the first frame. Pass the field\nraw. A theme written against older dial names is carried forward on the way in,\nthe same reconciliation the dev server runs on every theme it reads.\n\nNothing is baked. `tokens.generated.css` still holds token values only, and the\nlayer stays JavaScript the page runs, because it builds an SVG filter bank\nrather than a set of custom properties.\n\nA visitor who has picked a look of their own keeps it, None included. The theme\nseeds a browser that has decided nothing and never overwrites one that has, so\ncalling this on every boot is safe.\n\n### Your own sketchstyles\n\nThe dev server lists the files in `sketch-styles/`. A built site has no server\nto ask, so it hands them over at boot, the way it hands over components:\n\n```ts\nconst files = import.meta.glob<{ name?: string; settings: unknown }>(\n  './live-tokens/data/sketch-styles/*.json',\n  { eager: true, import: 'default' },\n);\n\nawait bootLiveTokens(App, '#app', {\n  sketchLooks: Object.entries(files).map(([path, file]) => {\n    const id = path.split('/').pop()!.replace('.json', '');\n    return { id, label: file.name || id, settings: file.settings };\n  }),\n});\n```\n\nProjects made with `create` ship this already. The file's slug is the look's\nid, so a sketchstyle picked in the editor keeps working once the site is built.\n\n### Building a picker\n\n`sketchLooks` is every look on offer, shipped and your own, as a store. Give\neach row `setSketch(look.id)`, and add your own **None** row: off is a state of\nthe effect rather than one of the looks.\n\n`themeSketchLook` is the theme's own look as one more row. It is null when the\ntheme carries none, and null when what it carries is a look already in\n`sketchLooks`, since that row names it. Its id goes to `setSketch` like any\nother, so a visitor who wanders off the theme's look can come back to it.\n\n## Drawing your own elements\n\nThe layer draws a fixed set of parts: the shipped components, and four classes\nit reserves for you. Nothing else is touched, so a page element or a\nconsumer-authored component is left crisp until it carries one of them.\n\n| Class               | For                                                       |\n|---------------------|-----------------------------------------------------------|\n| `sketch-surface`    | A box. The default treatment.                              |\n| `sketch-container`  | A large box. Tilts less, so the type inside stays readable. |\n| `sketch-chip`       | A small box. Finer fill mask, more rotation, less travel.   |\n| `sketch-rule`       | A line rather than a box. No rotation, no rounded ends.     |\n\nPick by size, not by kind: a card and a modal both take `sketch-container`, a\nbadge and a pill both take `sketch-chip`.\n\nThe class opts the element in; it names no colours, so the element states its\nown. `--sketch-fill`, `--sketch-stroke`, `--sketch-hatch-color`,\n`--sketch-radius` and `--sketch-shadow` name the fill, the outline, the hatching\nink, the corners and the shadow for one element and everything inside it. The\nlayer blanks the real background and border, so an element whose fill matters\nunder Sketch mode has to name it here as well as paint it.\n\nThe layer also paints on the element's `::before` and `::after`, forces its\n`overflow` visible, and gives it a stacking context of its own. Keep the class\noff anything that owns a pseudo-element, clips its content, or is positioned\nabsolutely, and put it on a wrapper instead.\n\n```css\n.my-callout {\n  background: var(--surface-brand-lowest);\n  border: var(--border-width-1) solid var(--border-brand);\n  border-radius: var(--radius-xl);\n\n  --sketch-fill: var(--surface-brand-lowest);\n  --sketch-stroke: var(--border-brand);\n  --sketch-radius: var(--radius-xl);\n}\n```\n\nA gradient is a valid fill: the shorthand's last layer takes a colour or an\nimage, so `--sketch-fill` accepts either. States work the same way, since\nnothing is competing with you for the value:\n\n```css\n.my-callout:hover { --sketch-stroke: var(--border-brand-strong); }\n```\n\n## Images inside a drawn part\n\nA drawn part's `overflow` is forced visible, because the fill and outline are\npainted on pseudo-elements that travel past the box and would otherwise be cut\noff at its edge. A background that bleeds is the effect working. An image that\nbleeds is not: it keeps its square corners while the card around it turns.\n\nMedia that runs to a part's edge therefore has to carry that part's corners\nitself. `--sketch-radius` is the radius the layer drew, and it inherits, so a\nchild can read it and fall back to its own value when Sketch mode is off:\n\n```css\n.cover {\n  overflow: hidden;\n  border-top-left-radius: var(--sketch-radius, var(--card-default-radius));\n  border-top-right-radius: var(--sketch-radius, var(--card-default-radius));\n}\n```\n\nCorner spread is per-corner and per-instance, so at high spread the crop is the\nmean rather than an exact trace of the drawn edge.\n\nA rule made from a `border` is not a box and cannot be displaced. Make it an\nelement, give it `sketch-rule`, and name its ink:\n\n```html\n<div class=\"rule sketch-rule\"></div>\n```\n```css\n.rule {\n  height: var(--border-width-2);\n  background: var(--border-brand);\n  --sketch-fill: var(--border-brand);\n}\n```\n\nIcons and inline SVG take the wobble directly, since a glyph has no box to\nredraw. Body type is left alone: an icon is a shape and survives a wobble, a\nparagraph is not.\n\n`--sketch-icon-off` names what a subtree's glyphs are drawn with instead. It\ninherits, so one declaration covers everything under it, and it takes the ink\nmask off as well as the wobble:\n\n```css\n/* Crisp. Chrome, a logo, anything that has to stay exact. */\n.app-bar { --sketch-icon-off: none; }\n\n/* Drawn back rather than off, at a third of the travel. Small artwork, and\n   type set as an SVG, which the layer reads as one large glyph. */\n.wordmark { --sketch-icon-off: var(--sketch-icon-soft); }\n```\n\nThe **Blotch size** dial under Icons and SVG is a share of the glyph rather than\na px size, because no px size is right for both a 16px icon and a page-wide\ndrawing. At 100% every glyph gets one period of the field across it whatever its\nsize. Below that the field repeats inside the glyph and the blotches get finer.\nAbove it a glyph reads part of one blotch, so the mask thins the whole glyph\nunevenly instead of breaking it up. The fill's blotches stay in px, since a\ncomponent does have a size to state one against.\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, a setting for every component, and the sketch layer, in one\nfile. It carries the name the look ships under, whether production is running\nit, and **Adopt**. Three parts sit under it, each a read-out rather than a\nfile 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- **Sketchstyle** names the look the theme's sketch layer carries: its label, or\n  off the theme when what's on screen no longer matches what was saved, or\n  none when the theme carries no sketch layer. It travels with the theme\n  like colors and type do, but never reaches a production build.\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, a setting for every component, and the\n  sketch layer.\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, writing most parts to a buffer,\n  `_working.json`, one slot each; the sketch layer has no buffer and stays\n  live in the browser until you save. **Save** captures all of it into the\n  open 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## Fonts\n\nType is part of the look, so it saves, loads and ships with the theme rather\nthan on its own. Four named stacks carry it:\n\n| Stack | Used by |\n|---|---|\n| `--font-display` | headings |\n| `--font-sans` | body text and most UI |\n| `--font-serif` | anywhere you ask for it |\n| `--font-mono` | code |\n\nEach stack is a family followed by its fallbacks, so a page still reads while a\nweb font loads, and still reads if it never does. **Project fonts**, in the\nColors and type editor, is where families come from: type a Google Fonts family\nname and the editor checks it, or paste a fonts URL, an embed tag, or your own\n`@font-face` rules. Removing a family puts the stack back on its fallbacks.\n\nYou can also set both faces at once from the command line:\n\n```bash\nnpx live-tokens set-fonts fonts.json\n```\n\nwith a brief naming the families:\n\n```json\n{ \"display\": \"Fraunces\", \"body\": \"Nunito Sans\" }\n```\n\nIt checks each family against Google Fonts, works out the weights that family\nactually has, and binds it to its stack. Like every other edit, the result lands\nin the buffer, so **Save** keeps it. In Claude Code, asking for a font pairing in\nplain English runs the same command.\n\nA font is only requested by the browser once something on the page uses it, so\ncarrying a family you no longer reference costs nothing at load. Adopting is\nwhat writes the font imports your site ships, into `fonts.css`.\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, sketch\nlayer included, so you can try each look and compare. **Save** in that window\nopens and adopts the previewed theme in one step: the active pointer changes,\nthe buffers clear, the editor works on it, and production ships it. **Cancel**\nreturns you to where you were, unsaved sketch dials included. 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 and your sketch layer stay as they are, and\nthe theme you have open stays open. Saved colors and type files are listed\nthere too, marked *colors & type*, and picking one is always that narrower\nload.\n\n## Shipping\n\n**Adopt**, in the Theme panel, is the \"ship it\" step. It saves the open theme,\nthen bakes the colors and type plus every component the theme carries into\n`src/live-tokens/data/tokens.generated.css`, which your build bundles alongside\n`tokens.css`. The sketch layer is the one part of the theme Adopt never bakes:\nit stays a preview. Fonts regenerate to match. The line under the theme name\nsays whether production is running 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 save-then-bake 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  sketch-styles/\n    my-look.json         a sketchstyle saved from the Sketchstyle view\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, a\nsetting for every component, and the sketch layer. It depends on no other\nfile, so deleting 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, along with the\n  sketch layer, which has no buffer of its own and lives only in the browser\n  until Save writes it. That file is the durable copy of your look; matching\n  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",
 };