@motion-proto/live-tokens 0.56.1 → 0.58.0

package/src/editor/core/store/editorTypes.ts

@@ -1,5 +1,5 @@
 import type { PaletteConfig, FontSource, FontStack } from '../themes/themeTypes';
-import type { GradientStop, GradientValue } from '../themes/parsers/gradient';
+import type { GradientStop, GradientValue, LinearDirection } from '../themes/parsers/gradient';
 import type { HarmonyAxis } from '../palettes/colorHarmony';
 
 export interface ShadowGlobals {
@@ -57,6 +57,9 @@ export interface GradientToken {
   type: GradientType;
   /** Degrees, applies to linear only. */
   angle: number;
+  /** `to <side-or-corner>`, emitted instead of `angle` on a linear gradient.
+   *  Tracks the box's aspect the way a fixed angle cannot. */
+  direction?: LinearDirection;
   /** Pixel radius for radial gradients. When absent or zero, the renderer
    *  emits CSS's default ellipse/farthest-corner shape. */
   radius?: number;

package/src/editor/core/store/editorViewStore.ts

@@ -1,13 +1,13 @@
 import { writable } from 'svelte/store';
 
-export type EditorView = 'tokens' | 'components' | 'colors';
+export type EditorView = 'tokens' | 'components' | 'colors' | 'sketch';
 export type SidebarCondensed = boolean | 'auto';
 
 const VIEW_KEY = 'lt.editorView';
 const CONDENSED_KEY = 'lt.sidebarCondensed';
 
 function isEditorView(v: unknown): v is EditorView {
-  return v === 'tokens' || v === 'components' || v === 'colors';
+  return v === 'tokens' || v === 'components' || v === 'colors' || v === 'sketch';
 }
 
 // Session-scoped, not persistent: opening the editor fresh always starts on

package/src/editor/core/store/gradientSource.ts

@@ -24,13 +24,17 @@ import {
   setGradientStop,
   addGradientStop,
   removeGradientStop,
+  setGradientDirection,
 } from '../themes/slices/gradients';
+import type { LinearDirection } from '../themes/parsers/gradient';
 import { setComponentAlias } from '../themes/slices/components';
 import { mutate } from './editorCore';
 
 export interface GradientSourceSnapshot {
   type: GradientType;
   angle: number;
+  /** `to <side-or-corner>` heading; overrides `angle` when set. */
+  direction?: LinearDirection;
   /** Horizontal center for radial gradients, 0–100. */
   centerX?: number;
   /** Per-axis stretch factors for the radial ellipse (1 = unscaled). */
@@ -48,6 +52,7 @@ export interface GradientSource {
   setAll(next: GradientSourceSnapshot): void;
   setType(type: GradientType): void;
   setAngle(angle: number): void;
+  setDirection(direction: LinearDirection | undefined): void;
   setCenterX(centerX: number): void;
   setAspect(aspect: { x: number; y: number }): void;
   setStop(index: number, partial: Partial<GradientTokenStop>): void;
@@ -63,6 +68,7 @@ export function colorsAndTypeGradientSource(variable: string): GradientSource {
     return {
       type: t.type,
       angle: t.angle,
+      direction: t.direction,
       centerX: t.centerX,
       aspectX: t.aspectX,
       aspectY: t.aspectY,
@@ -78,6 +84,7 @@ export function colorsAndTypeGradientSource(variable: string): GradientSource {
     setCenterX: (x) => setGradientCenterX(variable, x),
     setAspect: (a) => setGradientAspect(variable, a),
     setStop: (i, p) => setGradientStop(variable, i, p),
+    setDirection: (d) => setGradientDirection(variable, d),
     addStop: (s) => addGradientStop(variable, s),
     removeStop: (i) => removeGradientStop(variable, i),
   };
@@ -130,6 +137,7 @@ export function componentGradientSource(component: string, varName: string): Gra
     return {
       type: value.type,
       angle: value.angle,
+      direction: value.direction,
       centerX: value.centerX,
       aspectX: value.aspectX,
       aspectY: value.aspectY,
@@ -151,6 +159,7 @@ export function componentGradientSource(component: string, varName: string): Gra
           ? {
               type: ref.value.type,
               angle: ref.value.angle,
+              ...(ref.value.direction !== undefined ? { direction: ref.value.direction } : {}),
               ...(ref.value.centerX !== undefined ? { centerX: ref.value.centerX } : {}),
               ...(ref.value.aspectX !== undefined ? { aspectX: ref.value.aspectX } : {}),
               ...(ref.value.aspectY !== undefined ? { aspectY: ref.value.aspectY } : {}),
@@ -167,6 +176,7 @@ export function componentGradientSource(component: string, varName: string): Gra
     setAll: (next) => writeComponentGradient(component, varName, {
       type: next.type,
       angle: next.angle,
+      ...(next.direction !== undefined ? { direction: next.direction } : {}),
       ...(next.centerX !== undefined ? { centerX: next.centerX } : {}),
       ...(next.aspectX !== undefined ? { aspectX: next.aspectX } : {}),
       ...(next.aspectY !== undefined ? { aspectY: next.aspectY } : {}),
@@ -181,7 +191,11 @@ export function componentGradientSource(component: string, varName: string): Gra
       }
       g.type = t;
     }),
-    setAngle: (a) => update(`set gradient angle ${varName}`, (g) => { g.angle = a; }),
+    setAngle: (a) => update(`set gradient angle ${varName}`, (g) => {
+      g.angle = a;
+      g.direction = undefined;
+    }),
+    setDirection: (d) => update(`set gradient direction ${varName}`, (g) => { g.direction = d; }),
     setCenterX: (x) => update(`set gradient center ${varName}`, (g) => { g.centerX = x; }),
     setAspect: (a) => update(`set gradient aspect ${varName}`, (g) => {
       // Drop axes that equal 1 so persisted JSON stays minimal and pre-aspect

package/src/editor/core/themes/parsers/gradient.ts

@@ -3,6 +3,7 @@
  * A component alias that owns a gradient serializes to one of two shapes:
  *
  *   linear-gradient(<angle>deg, <stop>, <stop>, …)
+ *   linear-gradient(<to side-or-corner>, <stop>, <stop>, …)
  *   radial-gradient(<shape> at <cx>% 50%, <stop>, <stop>, …)
  *
  * `solid` and `none` are NOT represented here. `solid` renders as its first
@@ -35,6 +36,47 @@
  */
 import { parseColorOpacity, formatColorOpacity } from './colorOpacity';
 
+/** The `to <side-or-corner>` keywords CSS accepts in place of an angle. A
+ *  keyword angles the gradient line off the box's own diagonal, so it tracks
+ *  the element's aspect ratio where a fixed angle cannot: `to bottom right`
+ *  reads as ~95deg across a wide heading and ~111deg once that heading wraps.
+ *  That is the whole reason to carry them — a degree cannot express it. */
+export const LINEAR_DIRECTIONS = [
+  'to top',
+  'to top right',
+  'to right',
+  'to bottom right',
+  'to bottom',
+  'to bottom left',
+  'to left',
+  'to top left',
+] as const;
+
+export type LinearDirection = (typeof LINEAR_DIRECTIONS)[number];
+
+/** The angle each keyword equals on a square box. Sides are exact at any
+ *  aspect (`to right` is 90deg, always); corners hold only at 1:1, which is
+ *  the point of the keyword. Stored alongside a direction so the dial shows
+ *  something honest and clearing the keyword lands on the nearest angle
+ *  rather than snapping to 0deg (bottom-to-top). */
+export const DIRECTION_ANGLES: Record<LinearDirection, number> = {
+  'to top': 0,
+  'to top right': 45,
+  'to right': 90,
+  'to bottom right': 135,
+  'to bottom': 180,
+  'to bottom left': 225,
+  'to left': 270,
+  'to top left': 315,
+};
+
+function parseDirection(raw: string): LinearDirection | null {
+  const norm = raw.trim().toLowerCase().replace(/\s+/g, ' ');
+  return (LINEAR_DIRECTIONS as readonly string[]).includes(norm)
+    ? (norm as LinearDirection)
+    : null;
+}
+
 export interface GradientStop {
   /** 0–100 percentage along the gradient axis. */
   position: number;
@@ -54,6 +96,10 @@ export interface GradientStop {
 export interface GradientValue {
   type: 'linear' | 'radial' | 'solid' | 'none';
   angle: number;
+  /** Emitted in place of `angle` on a `linear` gradient. `angle` is retained
+   *  underneath so clearing the direction restores the user's degrees, the
+   *  same way a radial keeps its angle. */
+  direction?: LinearDirection;
   radius?: number;
   centerX?: number;
   aspectX?: number;
@@ -101,7 +147,8 @@ function formatRadialShape(v: GradientValue): string {
  *  into a CSS background declaration.
  *  - `none`   → `transparent` (no background paint).
  *  - `solid`  → the first stop's colour (no gradient function).
- *  - `linear` → `linear-gradient(<angle>deg, <stops>)`.
+ *  - `linear` → `linear-gradient(<angle>deg, <stops>)`, or
+ *    `linear-gradient(<direction>, <stops>)` when `direction` is set.
  *  - `radial` → `radial-gradient(<shape> at <centerX>% 50%, <stops>)`, where
  *    shape is `circle [radius]` at aspect 1 and `ellipse rx ry` otherwise.
  *    Aspects are independent stretch factors, not an area-preserving ratio:
@@ -113,12 +160,16 @@ export function formatGradientValue(v: GradientValue): string {
     return first ? formatStopColor(first) : 'transparent';
   }
   const stops = formatGradientStops(v.stops);
-  if (v.type === 'linear') return `linear-gradient(${v.angle}deg, ${stops})`;
+  if (v.type === 'linear') {
+    return `linear-gradient(${v.direction ?? `${v.angle}deg`}, ${stops})`;
+  }
   return `radial-gradient(${formatRadialShape(v)} at ${v.centerX ?? 50}% 50%, ${stops})`;
 }
 
 const NUM = String.raw`-?\d+(?:\.\d+)?`;
-const LINEAR_RE = new RegExp(String.raw`^linear-gradient\(\s*(${NUM})deg\s*,\s*(.+)\)$`, 'i');
+const HEADING = String.raw`${NUM}deg|to\s+\w+(?:\s+\w+)?`;
+const LINEAR_RE = new RegExp(String.raw`^linear-gradient\(\s*(${HEADING})\s*,\s*(.+)\)$`, 'i');
+const DEG_RE = new RegExp(String.raw`^(${NUM})deg$`, 'i');
 const RADIAL_RE = new RegExp(
   String.raw`^radial-gradient\(\s*(circle|circle\s+${NUM}px|ellipse\s+${NUM}px\s+${NUM}px)\s+at\s+(${NUM})%\s+50%\s*,\s*(.+)\)$`,
   'i',
@@ -192,8 +243,15 @@ export function parseGradientValue(value: string): GradientValue | null {
   const css = value.trim();
   const linear = css.match(LINEAR_RE);
   if (linear) {
+    const deg = linear[1].match(DEG_RE);
+    const direction = deg ? null : parseDirection(linear[1]);
+    // A heading that is neither degrees nor a keyword we know is not our form.
+    if (!deg && !direction) return null;
     const stops = parseStops(linear[2]);
-    return stops && { type: 'linear', angle: parseFloat(linear[1]), stops };
+    if (!stops) return null;
+    return deg
+      ? { type: 'linear', angle: parseFloat(deg[1]), stops }
+      : { type: 'linear', angle: 0, direction: direction!, stops };
   }
   const radial = css.match(RADIAL_RE);
   if (!radial) return null;

package/src/editor/core/themes/slices/gradients.ts

@@ -1,5 +1,5 @@
 /**
- * Gradients slice — fixed four-slot scale (--gradient-1 … --gradient-4),
+ * Gradients slice — an open `--gradient-N` library seeded with four slots,
  * each rendering to a single CSS var. Stops carry token-name references
  * (`--color-brand-500`); the renderer wraps them in `var(...)` so palette
  * edits flow through.
@@ -8,15 +8,34 @@ import type { EditorState, GradientToken, GradientTokenStop, GradientType } from
 import type { GradientDiskToken } from '../themeTypes';
 import { mutate } from '../../store/editorCore';
 import { formatGradientValue, formatGradientStops as formatStopList } from '../parsers/gradient';
+import { DIRECTION_ANGLES, type LinearDirection } from '../parsers/gradient';
 
 export { formatGradientValue };
 
+/** A well-formed library slot: `--gradient-` followed by a number. Anything
+ *  else is pre-numbering data the loader and the persistence guard reject. */
+export const GRADIENT_SLOT_RE = /^--gradient-\d+$/;
+
+export function isGradientSlot(variable: string): boolean {
+  return GRADIENT_SLOT_RE.test(variable);
+}
+
+/** The next free slot name, so callers never collide with an existing one. */
+export function nextGradientSlot(tokens: readonly GradientToken[]): string {
+  const used = new Set(tokens.map((t) => t.variable));
+  for (let n = 1; ; n++) {
+    const name = `--gradient-${n}`;
+    if (!used.has(name)) return name;
+  }
+}
+
 export function makeDefaultGradients(): GradientToken[] {
   return [
     {
       variable: '--gradient-1',
       type: 'linear',
-      angle: 90,
+      angle: DIRECTION_ANGLES['to right'],
+      direction: 'to right',
       stops: [
         { position: 0, color: '--color-brand-500' },
         { position: 100, color: '--color-accent-500' },
@@ -34,7 +53,8 @@ export function makeDefaultGradients(): GradientToken[] {
     {
       variable: '--gradient-3',
       type: 'linear',
-      angle: 90,
+      angle: DIRECTION_ANGLES['to right'],
+      direction: 'to right',
       stops: [
         { position: 0, color: '--color-success-500' },
         { position: 100, color: '--color-info-500' },
@@ -57,20 +77,29 @@ export function makeDefaultGradients(): GradientToken[] {
  * field and scrub the rendered `--gradient-N` strings from the vars bag — they
  * are a projection kept for production CSS, never a basis. Files without the
  * field (saved before gradients round-tripped) keep the seeded defaults, which
- * match what those files rendered. A file whose slots don't match the fixed
- * four is stale-shaped and also keeps defaults, mirroring the persistence
- * layer's `migrateGradients` guard.
+ * match what those files rendered.
+ *
+ * The library is open-ended: any number of `--gradient-N` slots loads, so a
+ * project can carry as many as its design needs. What still fails the guard is
+ * a stale *shape* — a token named `--gradient-progress`, from before the slots
+ * were numbered — which keeps defaults, mirroring `migrateGradients`.
  */
 export function loadGradientsFromFile(
   next: EditorState,
   gradients: GradientDiskToken[] | undefined,
   rawVars: Record<string, string>,
 ): void {
-  const expected = makeDefaultGradients().map((g) => g.variable).sort();
-  for (const name of expected) delete rawVars[name];
-  const have = (gradients ?? []).map((g) => g.variable).sort();
-  const matches = have.length === expected.length && expected.every((v, i) => v === have[i]);
-  if (matches) next.gradients.tokens = structuredClone(gradients) as GradientToken[];
+  for (const g of makeDefaultGradients()) {
+    delete rawVars[g.variable];
+    delete rawVars[stopsVariable(g.variable)];
+  }
+  for (const t of gradients ?? []) {
+    delete rawVars[t.variable];
+    delete rawVars[stopsVariable(t.variable)];
+  }
+  if (gradients?.length && gradients.every((g) => isGradientSlot(g.variable))) {
+    next.gradients.tokens = structuredClone(gradients) as GradientToken[];
+  }
 }
 
 /** Stops portion only — used by the palette selector to materialize a
@@ -84,6 +113,7 @@ function formatGradient(t: GradientToken): string {
   return formatGradientValue({
     type: t.type,
     angle: t.angle,
+    direction: t.direction,
     centerX: t.centerX,
     aspectX: t.aspectX,
     aspectY: t.aspectY,
@@ -91,9 +121,22 @@ function formatGradient(t: GradientToken): string {
   });
 }
 
+/** The suffix carrying a token's stop list on its own, so a consumer can keep
+ *  the theme's colours while supplying its own geometry:
+ *  `linear-gradient(to top, var(--gradient-5-stops))`. The same stops then
+ *  serve every direction a design needs without duplicating a token per angle. */
+export const STOPS_VAR_SUFFIX = '-stops';
+
+export function stopsVariable(variable: string): string {
+  return `${variable}${STOPS_VAR_SUFFIX}`;
+}
+
 export function gradientsToVars(g: EditorState['gradients']): Record<string, string> {
   const out: Record<string, string> = {};
-  for (const t of g.tokens) out[t.variable] = formatGradient(t);
+  for (const t of g.tokens) {
+    out[t.variable] = formatGradient(t);
+    out[stopsVariable(t.variable)] = formatStopList(t.stops);
+  }
   return out;
 }
 
@@ -105,13 +148,14 @@ function findGradient(s: EditorState, variable: string): GradientToken | undefin
  *  Used by the editor to restore a pre-edit snapshot on Cancel. */
 export function setGradient(
   variable: string,
-  next: { type: GradientType; angle: number; centerX?: number; aspectX?: number; aspectY?: number; stops: GradientTokenStop[] },
+  next: { type: GradientType; angle: number; direction?: LinearDirection; centerX?: number; aspectX?: number; aspectY?: number; stops: GradientTokenStop[] },
 ): void {
   mutate(`replace gradient ${variable}`, (s) => {
     const t = findGradient(s, variable);
     if (!t) return;
     t.type = next.type;
     t.angle = next.angle;
+    t.direction = next.direction;
     t.centerX = next.centerX;
     t.aspectX = next.aspectX;
     t.aspectY = next.aspectY;
@@ -126,10 +170,27 @@ export function setGradientType(variable: string, type: GradientType): void {
   });
 }
 
+/** Setting degrees clears any direction keyword: the two are alternative
+ *  headings for the same gradient, and the one you just set is the one you
+ *  meant. The angle underneath a direction is preserved until then. */
 export function setGradientAngle(variable: string, angle: number): void {
   mutate(`set gradient angle ${variable}`, (s) => {
     const t = findGradient(s, variable);
-    if (t) t.angle = angle;
+    if (!t) return;
+    t.angle = angle;
+    t.direction = undefined;
+  });
+}
+
+/** `undefined` drops back to the stored `angle`. Setting a keyword also moves
+ *  `angle` to that keyword's square-box equivalent, so the dial reflects the
+ *  gradient and clearing the keyword keeps roughly the same direction. */
+export function setGradientDirection(variable: string, direction: LinearDirection | undefined): void {
+  mutate(`set gradient direction ${variable}`, (s) => {
+    const t = findGradient(s, variable);
+    if (!t) return;
+    t.direction = direction;
+    if (direction) t.angle = DIRECTION_ANGLES[direction];
   });
 }
 

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

@@ -111,7 +111,12 @@ export interface FontSource {
 
 export type SystemCascadePreset = 'system-ui-sans' | 'system-ui-serif' | 'system-ui-mono';
 export type GenericFamily = 'sans-serif' | 'serif' | 'monospace' | 'cursive' | 'fantasy';
-export type FontStackVariable = '--font-display' | '--font-sans' | '--font-serif' | '--font-mono';
+export type FontStackVariable =
+  | '--font-display'
+  | '--font-sans'
+  | '--font-serif'
+  | '--font-mono'
+  | '--font-editorial';
 
 export type FontStackSlot =
   | { kind: 'project'; familyId: string }

package/src/editor/docs/Docs.svelte

@@ -98,6 +98,7 @@
         { path: '01-overview',         title: 'Overview' },
         { path: 'getting-started',     title: 'Getting started' },
         { path: 'editing-tokens',      title: 'Editing tokens' },
+        { path: 'sketch-mode',         title: 'Sketch mode' },
         { path: 'themes-workflow',     title: 'Themes' },
         { path: 'where-themes-live',   title: 'Where themes live' },
         { path: 'creating-components', title: 'Creating components' },
@@ -254,7 +255,7 @@
     <SideNavigation
       class="docs-sidebar"
       sections={navSections}
-      titleLabel="Live Tokens"
+      titleLabel="LiveTokens"
       titleHref="#01-overview"
       currentPath={parsedHash.chapter}
       open={sidebarOpen}
@@ -283,11 +284,11 @@
     <div class="docs-main" bind:this={scrollPane}>
     <header class="docs-page-header">
       <div class="title-block">
-        <p class="eyebrow">Live Tokens</p>
+        <p class="eyebrow">LiveTokens</p>
         <h1>Documentation</h1>
         <p class="lede">
           Set up a project, edit your tokens live, and ship a theme. A short
-          guide to styling and building with Live Tokens.
+          guide to styling and building with LiveTokens.
         </p>
       </div>
     </header>

package/src/editor/docs/chapters.ts

@@ -13,6 +13,7 @@ export const chapters: Chapter[] = [
   { id: '01-overview',         title: 'Overview' },
   { id: 'getting-started',     title: 'Getting started' },
   { id: 'editing-tokens',      title: 'Editing tokens' },
+  { id: 'sketch-mode',         title: 'Sketch mode' },
   { id: 'themes-workflow',     title: 'Themes' },
   { id: 'where-themes-live',   title: 'Where themes live' },
   { id: 'creating-components', title: 'Creating components' },

package/src/editor/docs/content/01-overview.md

@@ -1,6 +1,6 @@
 # Overview
 
-Live Tokens is a design system for building Svelte microsites quickly. You
+LiveTokens is a design system for building Svelte microsites quickly. You
 style your site by editing tokens and components in a live editor. When it looks right, you save the theme and ship it.
 
 ## How it works
@@ -27,6 +27,7 @@ style your site by editing tokens and components in a live editor. When it looks
 - **[Getting started](getting-started.md)**: scaffold a project and make your
   first edit.
 - **[Editing tokens](editing-tokens.md)**: a tour of the editor.
+- **[Sketch mode](sketch-mode.md)**: redraw the page by hand.
 - **[Themes](themes-workflow.md)**: save, switch, and ship.
 - **[Creating components](creating-components.md)**: make your own components
   editable.

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

@@ -3,12 +3,16 @@
 A tour of the editor. The page behind it repaints on every change; saving
 writes a theme file you can reload later.
 
-The editor has two views:
+The editor has four views:
 
 - **Tokens**: the design-system primitives (colour, type, spacing, and so on).
   They apply everywhere your site uses them.
+- **Color Wheel**: the harmony wheel, the palette curves, and the story your colours
+  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
+  [Sketch mode](sketch-mode.md).
 
 This page covers **Tokens**. For components, see
 [Creating components](creating-components.md).

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

@@ -0,0 +1,183 @@
+# Sketch mode
+
+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.
+
+Open the **Sketch Style** 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.
+
+## What it draws
+
+Each component's fill and outline are repainted from the tokens that component
+already owns. The real background and border are hidden behind them, then both
+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
+
+Seven looks ship with the package, and each is a complete set of dials rather
+than a style name:
+
+- **Pencil.** Two graphite passes on their own seeds, so the outline disagrees
+  with itself the way a hand coming back round does.
+- **Marker.** A broad translucent nib gone round twice on the same line, so the
+  overlap darkens and the ink pools where it slows.
+- **Whiteboard.** The fattest nib on glass, with a mask that streaks the fill
+  like a half-wiped board.
+- **Hatched.** An etching. The fill is angled shading and the outline a single
+  hard-edged scratch.
+- **Dashed.** A drafting outline: one slow drift along the ruler, broken into
+  strokes. The clean pole.
+- **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/`.
+
+## The dials
+
+- **Border.** How far the outline travels and how long its wave is, then its
+  width, ink, pressure and pooling. A second pass either copies the first line a
+  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.
+- **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
+  a rectangle.
+- **Icons and SVG.** Glyph travel and wavelength on their own scale. A glyph is
+  all curves already, so it needs more travel than a card's long straight edge
+  before the wobble reads at all.
+- **Noise.** The shared field itself: its wavelength, how many layers of detail
+  sit on it, and the shape of its wave. A square wave sends nearly every edge to
+  full travel, which is what makes the effect stronger rather than bigger.
+
+## 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.
+
+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.
+
+## Drawing your own elements
+
+The layer draws a fixed set of parts: the shipped components, and four classes
+it reserves for you. Nothing else is touched, so a page element or a
+consumer-authored component is left crisp until it carries one of them.
+
+| Class               | For                                                       |
+|---------------------|-----------------------------------------------------------|
+| `sketch-surface`    | A box. The default treatment.                              |
+| `sketch-container`  | A large box. Tilts less, so the type inside stays readable. |
+| `sketch-chip`       | A small box. Finer fill mask, more rotation, less travel.   |
+| `sketch-rule`       | A line rather than a box. No rotation, no rounded ends.     |
+
+Pick by size, not by kind: a card and a modal both take `sketch-container`, a
+badge and a pill both take `sketch-chip`.
+
+The class opts the element in; it names no colours, so the element states its
+own. `--sketch-fill`, `--sketch-stroke`, `--sketch-hatch-color`,
+`--sketch-radius` and `--sketch-shadow` name the fill, the outline, the hatching
+ink, the corners and the shadow for one element and everything inside it. The
+layer blanks the real background and border, so an element whose fill matters
+under Sketch mode has to name it here as well as paint it.
+
+The layer also paints on the element's `::before` and `::after`, forces its
+`overflow` visible, and gives it a stacking context of its own. Keep the class
+off anything that owns a pseudo-element, clips its content, or is positioned
+absolutely, and put it on a wrapper instead.
+
+```css
+.my-callout {
+  background: var(--surface-brand-lowest);
+  border: var(--border-width-1) solid var(--border-brand);
+  border-radius: var(--radius-xl);
+
+  --sketch-fill: var(--surface-brand-lowest);
+  --sketch-stroke: var(--border-brand);
+  --sketch-radius: var(--radius-xl);
+}
+```
+
+A gradient is a valid fill: the shorthand's last layer takes a colour or an
+image, so `--sketch-fill` accepts either. States work the same way, since
+nothing is competing with you for the value:
+
+```css
+.my-callout:hover { --sketch-stroke: var(--border-brand-strong); }
+```
+
+## Images inside a drawn part
+
+A drawn part's `overflow` is forced visible, because the fill and outline are
+painted on pseudo-elements that travel past the box and would otherwise be cut
+off at its edge. A background that bleeds is the effect working. An image that
+bleeds is not: it keeps its square corners while the card around it turns.
+
+Media that runs to a part's edge therefore has to carry that part's corners
+itself. `--sketch-radius` is the radius the layer drew, and it inherits, so a
+child can read it and fall back to its own value when Sketch mode is off:
+
+```css
+.cover {
+  overflow: hidden;
+  border-top-left-radius: var(--sketch-radius, var(--card-default-radius));
+  border-top-right-radius: var(--sketch-radius, var(--card-default-radius));
+}
+```
+
+Corner spread is per-corner and per-instance, so at high spread the crop is the
+mean rather than an exact trace of the drawn edge.
+
+A rule made from a `border` is not a box and cannot be displaced. Make it an
+element, give it `sketch-rule`, and name its ink:
+
+```html
+<div class="rule sketch-rule"></div>
+```
+```css
+.rule {
+  height: var(--border-width-2);
+  background: var(--border-brand);
+  --sketch-fill: var(--border-brand);
+}
+```
+
+Icons and inline SVG take the wobble directly, since a glyph has no box to
+redraw. Body type is left alone: an icon is a shape and survives a wobble, a
+paragraph is not.
+
+`--sketch-icon-off` names what a subtree's glyphs are drawn with instead. It
+inherits, so one declaration covers everything under it:
+
+```css
+/* Crisp. Chrome, a logo, anything that has to stay exact. */
+.app-bar { --sketch-icon-off: none; }
+
+/* Drawn back rather than off, at a third of the travel. Small artwork, and
+   type set as an SVG, which the layer reads as one large glyph. */
+.wordmark { --sketch-icon-off: var(--sketch-icon-soft); }
+```
+
+The **Blotch size** dial under Icons and SVG is a share of the glyph rather than
+a px size, because no px size is right for both a 16px icon and a page-wide
+drawing. At 100% every glyph gets one period of the field across it whatever its
+size. Below that the field repeats inside the glyph and the blotches get finer.
+Above it a glyph reads part of one blotch, so the mask thins the whole glyph
+unevenly instead of breaking it up. The fill's blotches stay in px, since a
+component does have a size to state one against.