@motion-proto/live-tokens 0.57.0 → 0.59.0

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

@@ -26,6 +26,12 @@ const ID = 'lt-sketch';
     identical twins, which is the single biggest tell that it is not hand drawn. */
 const SEEDS = [0, 1, 2, 3, 4];
 
+/** The soft glyph bank, as a share of the icon travel. Travel is stated in px
+    against a glyph whose size the layer cannot know, so the dial that suits a
+    card's worth of artwork tears a 16px icon apart. An element that cannot take
+    the full amount names this bank instead of going crisp. */
+const ICON_SOFT = 0.35;
+
 const HATCH_ANGLE = 45;
 /** The second set of stripes leans and spaces itself a little off the first.
     Half a pixel of pitch against 7 puts the beat about 90px apart, and the two
@@ -221,10 +227,19 @@ const PART_SPECS: readonly PartSpec[] = [
   // outline: a line does not get drawn around.
   { sel: '.sd-hairline', fill: 'var(--_divider-hairline-color)', strokeless: true },
 
-  // Consumer opt-in. A page element that is not a component but paints a
-  // token-driven surface sets --sketch-fill / --sketch-stroke itself and
-  // carries this class; the layer then treats it like any other part.
+  // Consumer opt-in. A page element or a consumer-authored component that
+  // paints a token-driven surface sets --sketch-fill / --sketch-stroke itself
+  // and carries one of these; the layer then treats it like any other part.
+  // They name no colour, so no rule is emitted for them and whatever the
+  // element declared survives.
+  //
+  // Which one to carry is a question of size, not of kind. The shipped parts
+  // are sorted the same way below: a container tilts less than the type inside
+  // it can tolerate, a chip is smaller than one blob of the fill mask. A part
+  // that is neither takes `.sketch-surface` and the middle treatment.
   { sel: '.sketch-surface' },
+  { sel: '.sketch-container' },
+  { sel: '.sketch-chip' },
   { sel: '.sketch-rule', strokeless: true },
 ];
 
@@ -438,7 +453,8 @@ export function buildDefsMarkup(s: SketchSettings): string {
     // Icons are glyphs a few tens of pixels across, read at a glance, with no
     // redundancy to lose. A high-frequency field at a small amplitude wobbles
     // the outline without pulling a stroke off the shape it belongs to.
-    displace(`${ID}-icon-${seed}`, base / s.iconWavelength, seed + 63, s.iconTravel, 40, 0, 0),
+    displace(`${ID}-icon-${seed}`, base / s.iconWavelength, seed + 63, s.iconTravel, 40, 0, 0) +
+    displace(`${ID}-icon-soft-${seed}`, base / s.iconWavelength, seed + 63, s.iconTravel * ICON_SOFT, 40, 0, 0),
   ).join('');
 
   // Ink pooling. Blur spreads the stroke, then a steep alpha ramp re-sharpens
@@ -651,6 +667,10 @@ export function buildStylesheet(s: SketchSettings): string {
       `--sketch-stroke-filter:url(#${ID}-stroke-0);` +
       `--sketch-mask:${s.maskOn || s.iconMaskOn ? buildMaskUri(s) : 'none'};` +
       `--sketch-mask-tile:${MASK_TILE}px;` +
+      `--sketch-icon-mask-tile:${Math.round(s.iconMaskScale * 100)}%;` +
+      // Named here rather than on the icons themselves, so an ancestor asking
+      // for the soft bank resolves it against a value it can actually see.
+      `--sketch-icon-soft:url(#${ID}-icon-soft-0);` +
       `--sketch-jit-x-base:${s.jitterX}px;` +
       `--sketch-jit-y-base:${s.jitterY}px;` +
       `--sketch-jit-rot-base:${s.jitterRot}deg;` +
@@ -668,15 +688,14 @@ export function buildStylesheet(s: SketchSettings): string {
    * that element's own origin and sampled at a different offset per instance,
    * so two parts the same size are not blotched alike.
    *
-   * `mask-clip: no-clip` is load-bearing on the fill. A mask clips what it masks
-   * to the border box by default, and the shadow the fill casts lies outside
-   * that box, so switching coverage on took every shadow with it. Unclipped, the
-   * tile runs on over the shadow and thins it where the ink beside it is thin,
-   * which is what ink that is not there would do.
+   * `mask-clip: no-clip` asks for the painting area not to be restricted, which
+   * is what a layer the filter has already carried outside its own box needs.
+   * Chrome does not honour it — see `bleed` below, which is what actually keeps
+   * the drawn edge off the border box.
    */
-  const coverage = (tile: string, pos: string) =>
+  const coverage = (size: string, pos: string) =>
     `mask-image:var(--sketch-mask, none);` +
-    `mask-size:${tile} ${tile};` +
+    `mask-size:${size};` +
     `mask-mode:luminance;mask-repeat:repeat;mask-clip:no-clip;` +
     `mask-position:var(${pos}, 0 0);`;
 
@@ -684,11 +703,13 @@ export function buildStylesheet(s: SketchSettings): string {
   // than through a redrawn ::before. Body type is deliberately left alone: an
   // icon is a shape and survives a wobble, a paragraph is not.
   //
-  // `--sketch-icon-off` is the opt-out. It inherits, so any chrome that lives
-  // in the host document (the overlay bar) sets it once on its own root and
-  // every icon under it resolves to `none` regardless of specificity.
-  // `svg` covers inline artwork the same way. The injected filter bank is
-  // itself an svg in the body, so it has to be excluded or it filters itself.
+  // `--sketch-icon-off` names what to draw a subtree's glyphs with instead:
+  // `none` keeps them crisp, `var(--sketch-icon-soft)` draws them at a fraction
+  // of the travel. It inherits, so any chrome that lives in the host document
+  // (the overlay bar) sets it once on its own root and every icon under it
+  // follows regardless of specificity. `svg` covers inline artwork the same
+  // way. The injected filter bank is itself an svg in the body, so it has to be
+  // excluded or it filters itself.
   const iconSel = `[class*="fa-"], svg:not([${DEFS_ATTR}])`;
   const iconsOn = s.iconTravel > 0 || s.iconMaskOn;
   const icons = iconsOn
@@ -697,14 +718,24 @@ export function buildStylesheet(s: SketchSettings): string {
           ? `filter:var(--sketch-icon-off, var(--sketch-icon-filter, url(#${ID}-icon-0)));`
           : '') +
         // The ink mask reads as coverage on a glyph the way it does on a fill,
-        // but the component tile is hundreds of px across: a whole icon would
-        // sample one patch of it and either survive intact or disappear. A
-        // tile near icon size puts several blotches across each glyph.
-        (s.iconMaskOn ? coverage(`${s.iconMaskTile}px`, '--sketch-icon-mask-pos') : '') +
+        // but the fill states its tile in px and a glyph has no fixed size to
+        // state one against: the component tile is hundreds of px across, so a
+        // whole icon sampled one flat patch of it and came out either untouched
+        // or gone.
+        //
+        // The glyph is the unit instead. A percentage resolves against the
+        // element the mask is laid on, so the tile scales with whatever it
+        // covers and the dial reads the same on a 16px icon as on a page-wide
+        // drawing. `auto` on the other axis keeps the tile square.
+        (s.iconMaskOn
+          ? coverage('auto var(--sketch-icon-mask-tile)', '--sketch-icon-mask-pos')
+          : '') +
       `}` +
       SEEDS.map((seed, i) =>
         `${on} :is(${iconSel}):nth-child(5n + ${i + 1})` +
-          `{--sketch-icon-filter:url(#${ID}-icon-${seed});--sketch-icon-mask-pos:${MASK_POS[i]};}`,
+          `{--sketch-icon-filter:url(#${ID}-icon-${seed});` +
+          `--sketch-icon-soft:url(#${ID}-icon-soft-${seed});` +
+          `--sketch-icon-mask-pos:${MASK_POS[i]};}`,
       ).join('')
     : '';
 
@@ -722,6 +753,46 @@ export function buildStylesheet(s: SketchSettings): string {
     ? `border-radius:${[1, 2, 3, 4].map(cornerRadius).join(' ')};`
     : 'border-radius:inherit;';
 
+  /**
+   * How far past its own box the fill layer is drawn on.
+   *
+   * A mask is applied AFTER the filter, and its painting area stops at the
+   * border box whatever `mask-clip` says: Chrome accepts `no-clip`, computes it
+   * back, and clips anyway. Every pixel the displacement pushed outside the box
+   * was erased along a straight rectangle, and because `jitterScale` grows each
+   * fill one-sidedly the drawn shape always covered its own box — so what
+   * survived was the box itself, ruler-straight with perfectly circular
+   * corners, under a stroke that wobbled freely because it carries no mask.
+   *
+   * The fill is drawn on a box this much larger instead, with the paint held to
+   * the middle of it, so the mask's painting area covers everything the pen laid
+   * down. Only what the FILTER moves has to fit: the jitter transform runs after
+   * the mask and carries the finished layer whole.
+   */
+  const bleed = s.maskOn ? Math.ceil(s.cornerTravel + s.fillTravel) + 4 : 0;
+
+  /** Padding subtracts from a corner, so the bleed added here comes back off at
+      the content box and the paint turns exactly where it did before. The
+      inherit is spent at this point: a bleeding fill has to state its corners,
+      and `--sketch-radius` is what it states them from. */
+  const fillCorners = bleed === 0
+    ? corners
+    : `border-radius:${s.cornerSpread > 0
+      ? [1, 2, 3, 4].map((i) => `calc(${cornerRadius(i)} + ${bleed}px)`).join(' ')
+      : `calc(var(--sketch-radius, 0px) + ${bleed}px)`};`;
+
+  /** Grow the box, hold the paint to the middle of it. `content-box` sizing
+      keeps the content area at the element's own size, which a rule two pixels
+      tall cannot do under `border-box`; the two `auto`s are for Button, whose
+      shimmer ::before states `width: 100%` and would otherwise pin the grown box
+      back to the element. `background` is a shorthand and resets both box
+      properties, so `bleedPaint` follows every declaration of it. */
+  const bleedBox = bleed === 0
+    ? 'inset:0 !important;'
+    : `inset:-${bleed}px !important;padding:${bleed}px;box-sizing:content-box;` +
+      `width:auto !important;height:auto !important;`;
+  const bleedPaint = bleed === 0 ? '' : 'background-origin:content-box;background-clip:content-box;';
+
   const host =
     `${el}{` +
       `--sketch-jit-x:var(--sketch-jit-x-base);` +
@@ -754,12 +825,17 @@ export function buildStylesheet(s: SketchSettings): string {
   // effect is switched on, because `left` animates from -100% to 0.
   const fill =
     `${el}::before{` +
-      `content:'';position:absolute;inset:0 !important;transition:none !important;` +
-      `z-index:-1;${corners}` +
+      `content:'';position:absolute;${bleedBox}transition:none !important;` +
+      `z-index:-1;${fillCorners}` +
       `background:var(--sketch-fill, var(--surface-neutral-lower));` +
-      `box-shadow:var(--sketch-shadow, none);` +
+      bleedPaint +
+      // A shadow is cast from the border box, and the bleed is not where the
+      // drawing is. The five parts that name one (card, dialog, menu, table,
+      // tooltip) go without while coverage is on rather than wear a halo the
+      // width of the bleed; every other part's token is --shadow-none anyway.
+      (bleed === 0 ? 'box-shadow:var(--sketch-shadow, none);' : '') +
       `filter:var(--sketch-fill-filter);` +
-      (s.maskOn ? coverage('var(--sketch-mask-tile)', '--sketch-mask-pos') : '') +
+      (s.maskOn ? coverage('var(--sketch-mask-tile) var(--sketch-mask-tile)', '--sketch-mask-pos') : '') +
       `transform:translate(` +
         `calc(var(--sketch-jx, 0) * var(--sketch-jit-x, 0px)),` +
         `calc(var(--sketch-jy, 0) * var(--sketch-jit-y, 0px))` +
@@ -799,6 +875,7 @@ export function buildStylesheet(s: SketchSettings): string {
         `${hatchInk('1')} 0 1.5px,` +
         `transparent 1.5px 7px),` +
       `var(--sketch-fill, var(--surface-neutral-lower));` +
+      bleedPaint +
     `}`;
 
   // A translucent nib. The retrace pass below overlaps this one, so where both
@@ -890,7 +967,8 @@ export function buildStylesheet(s: SketchSettings): string {
   // Large panels tilt less than the type inside them can tolerate; small chips
   // can take more rotation but less travel.
   const perPart =
-    `${el}:is(.card, .card-header, .panel, .dialog, .table-wrapper, .sidenavigation)` +
+    `${el}:is(.card, .card-header, .panel, .dialog, .table-wrapper, .sidenavigation,` +
+      ` .sketch-container)` +
       `{--sketch-jit-rot:calc(var(--sketch-jit-rot-base) * 0.3);}` +
     // A rule is one or two pixels tall. The full-size displacement tears it into
     // dashes and a translate that large lifts it clean off its own row, so it
@@ -904,7 +982,7 @@ export function buildStylesheet(s: SketchSettings): string {
       // rather than as a hand.
       `--sketch-corner-spread:0px;` +
     `}` +
-    `${el}:is(.badge, .toggle .track){` +
+    `${el}:is(.badge, .toggle .track, .sketch-chip){` +
       // A chip is smaller than one blob at the tile the cards read it at, so it
       // lands wholly inside a patch and comes out either untouched or gone.
       // Shrinking the tile puts several blotches across it, which is the same
@@ -925,8 +1003,8 @@ export function buildStylesheet(s: SketchSettings): string {
       `--sketch-stroke-filter:url(#${ID}-stroke-sm-2);` +
     `}`;
 
-  // `.sketch-surface` names its own colours, so it emits no rule and keeps
-  // whatever the page set.
+  // The `.sketch-*` opt-in classes name their own colours, so they emit no rule
+  // and keep whatever the page set.
   const colours = PART_SPECS.map((p) => {
     const f = p.fill ?? (p.stem ? `var(--${p.stem}-surface)` : null);
     const st = p.stroke ?? (p.stem ? `var(--${p.stem}-border)` : null);

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

@@ -109,10 +109,15 @@ export interface SketchSettings {
   iconWavelength: number;
   /** Ink coverage over icons. Independent of `maskOn`, which governs fills. */
   iconMaskOn: boolean;
-  /** Icon mask tile, in px. Near glyph size puts several blotches across one
-      icon; at the fill's tile size a whole icon samples a single patch and
-      either survives intact or vanishes. */
-  iconMaskTile: number;
+  /** Icon mask tile, as a share of the glyph it covers. A px size cannot be
+      right for both a 16px icon and a page-wide illustration: the tile that
+      blotches the drawing swallows the icon whole, and one cut for the icon
+      is dust on the drawing. Stated against the glyph, the tile scales with
+      whatever it is laid on. At 1 every glyph gets one period of the field
+      across it; below that the field repeats inside the glyph and the blotches
+      get finer; above it a glyph reads part of a blotch and the mask acts as
+      an uneven wash over the whole thing. */
+  iconMaskScale: number;
 }
 
 const base: SketchSettings = {
@@ -122,11 +127,11 @@ const base: SketchSettings = {
   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.35, maskOutputMax: 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, iconMaskTile: 90,
+  iconTravel: 1.25, iconWavelength: 0.625, iconMaskOn: true, iconMaskScale: 1,
 };
 
 export const SKETCH_PRESETS: Record<string, SketchSettings> = {
@@ -135,7 +140,7 @@ export const SKETCH_PRESETS: Record<string, SketchSettings> = {
     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.55, maskOutputMax: 1, maskOctaves: 3, maskPosterize: 1, maskSoftness: 0.6,
+    maskBlob: 40, maskOutputMin: 0.62, maskOutputMax: 1, maskOctaves: 3, maskPosterize: 1, maskSoftness: 0.6,
     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,
@@ -146,10 +151,10 @@ export const SKETCH_PRESETS: Record<string, SketchSettings> = {
     blurb: 'Broad translucent nib gone round twice on the same line, so the overlap darkens and the ink pools where it slows.',
     fillTravel: 2, strokeTravel: 1.5, wobble: 56, waveform: 1.4, borderWavelength: 1.3,
     strokeWidth: 4, doubleStroke: true, retracePass: 'copy', strokeInk: 0.52, retraceOffset: 2.2,
-    maskBlob: 95, maskOutputMin: 0.4, maskOutputMax: 1, maskOctaves: 2, maskPosterize: 4, maskSoftness: 2.8,
+    maskBlob: 115, maskOutputMin: 0.21, maskOutputMax: 1, maskOctaves: 3, maskPosterize: 4, maskSoftness: 2.5,
     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,
+    pressure: 0.2, pressureMod: 0.25, pooling: 2, iconTravel: 1.25, iconMaskScale: 4,
   },
 
   whiteboard: {
@@ -157,11 +162,11 @@ export const SKETCH_PRESETS: Record<string, SketchSettings> = {
     blurb: 'The fattest nib on glass. One long smooth undulation, and a veined mask that streaks the fill like a half-wiped board.',
     fillTravel: 2.5, strokeTravel: 2.5, wobble: 90, roughness: 1, waveform: 1, borderWavelength: 1.5,
     strokeWidth: 5.5, doubleStroke: true, retracePass: 'copy', strokeInk: 0.66, retraceOffset: 3,
-    maskGrain: 'turbulence', maskBlob: 180, maskOutputMin: 0.3, maskOutputMax: 1,
+    maskGrain: 'turbulence', maskBlob: 180, maskOutputMin: 0.42, maskOutputMax: 0.9,
     maskOctaves: 1, maskPosterize: 3, maskSoftness: 5,
     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, iconMaskTile: 140,
+    pressure: 0.15, pressureMod: 0.15, pooling: 3.5, iconTravel: 1.75, iconMaskScale: 1.5,
   },
 
   hatched: {
@@ -191,22 +196,22 @@ export const SKETCH_PRESETS: Record<string, SketchSettings> = {
     blurb: 'Ballpoint in a hurry. Everything loose at once: a square wave sends every edge to full travel, and the second pass lands wherever it lands.',
     fillTravel: 3, strokeTravel: 2.25, wobble: 50, roughness: 3, waveform: 2.5,
     strokeWidth: 2.25, doubleStroke: true, retracePass: 'reseeded', retraceOffset: 4, strokeInk: 1,
-    maskBlob: 150, maskOutputMin: 0.25, maskOutputMax: 1, maskOctaves: 2, maskPosterize: 2, maskSoftness: 6.7,
+    maskBlob: 150, maskOutputMin: 0.43, maskOutputMax: 0.95, maskOctaves: 2, maskPosterize: 2, maskSoftness: 6.7,
     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,
+    pressure: 0.45, pressureMod: 0.6, pooling: 2.5, iconTravel: 2.25, iconMaskScale: 3.6,
   },
 
   dry: {
     ...base, label: 'Dry marker',
-    blurb: 'Ink that ran out. One scratchy pass that breaks up along its length, over a fill the veined mask has mostly eaten.',
+    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,
-    maskGrain: 'turbulence', maskBlob: 120, maskOutputMin: 0, maskOutputMax: 0.85,
-    maskOctaves: 2, maskPosterize: 1, maskSoftness: 3,
+    maskBlob: 150, maskOutputMin: 0.15, 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, iconMaskTile: 60,
+    pressure: 0.4, pressureMod: 0.8, pooling: 1.5, iconTravel: 1.75, iconMaskScale: 3.8,
   },
 };
 
@@ -230,6 +235,7 @@ export function hydrateSketchSettings(raw: unknown): SketchSettings {
   carryLevelsToOutput(stored as Record<string, unknown>, out);
   halveSwingDials(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);
   return out;
 }
@@ -275,6 +281,17 @@ function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchS
   if (typeof layers === 'number') out.roughness = Math.min(3, Math.max(1, layers));
 }
 
+/** 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
+    glyph now, and the old default reads as one period across the glyph, which
+    is what that size was aiming at. */
+function convertIconTileToScale(stored: Record<string, unknown>, out: SketchSettings): void {
+  const tile = stored.iconMaskTile;
+  if (typeof tile !== 'number') return;
+  out.iconMaskScale = Math.min(5, Math.max(0.5, Number((tile / 90).toFixed(2))));
+}
+
 function halveSwingDials(stored: Record<string, unknown>, out: SketchSettings): void {
   for (const [legacy, key] of Object.entries(SWING_DIALS)) {
     const value = stored[legacy];

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

@@ -1,7 +1,14 @@
 /**
  * The single source of truth for the CSS form of a shadow scale token:
  *
- *   <x>px <y>px <blur>px <spread>px hsla(<h>, <s>%, <l>%, <a>)
+ *   <x>px <y>px <blur>px [<spread>px] hsla(<h>, <s>%, <l>%, <a>)
+ *
+ * The spread slot is written only when it is non-zero. A three-length shadow is
+ * legal in `box-shadow` (spread defaults to 0) and in `filter: drop-shadow()`,
+ * which has no spread slot at all — so one token dresses both, and a component
+ * casting from an image's alpha reads the same variable as one casting from a
+ * box. Dial a spread and the token grows its fourth length: still a shadow,
+ * no longer a filter.
  *
  * Everything that reads or writes that form goes through `parseShadowCss` /
  * `shadowTokenCss`, so the theme generator (Node, no store) and the editor
@@ -33,16 +40,17 @@ export function computeAngleDistance(x: number, y: number): { angle: number; dis
 }
 
 export function shadowTokenCss(t: ShadowValue): string {
-  return `${t.x}px ${t.y}px ${t.blur}px ${t.spread}px hsla(${t.hue}, ${t.saturation}%, ${t.lightness}%, ${t.opacity})`;
+  const spread = t.spread ? `${t.spread}px ` : '';
+  return `${t.x}px ${t.y}px ${t.blur}px ${spread}hsla(${t.hue}, ${t.saturation}%, ${t.lightness}%, ${t.opacity})`;
 }
 
 export function parseShadowCss(variable: string, raw: string): ShadowToken | null {
-  const m = raw.trim().match(/^(-?\d+)px\s+(-?\d+)px\s+(\d+)px\s+(-?\d+)px\s+hsla\(([\d.]+),\s*([\d.]+)%,\s*([\d.]+)%,\s*([\d.]+)\)$/);
+  const m = raw.trim().match(/^(-?\d+)px\s+(-?\d+)px\s+(\d+)px\s+(?:(-?\d+)px\s+)?hsla\(([\d.]+),\s*([\d.]+)%,\s*([\d.]+)%,\s*([\d.]+)\)$/);
   if (!m) return null;
   const x = parseInt(m[1], 10);
   const y = parseInt(m[2], 10);
   const blur = parseInt(m[3], 10);
-  const spread = parseInt(m[4], 10);
+  const spread = m[4] === undefined ? 0 : parseInt(m[4], 10);
   const hue = Math.round(parseFloat(m[5]));
   const saturation = Math.round(parseFloat(m[6]));
   const lightness = Math.round(parseFloat(m[7]));

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

@@ -7,11 +7,11 @@ The editor has four views:
 
 - **Tokens**: the design-system primitives (colour, type, spacing, and so on).
   They apply everywhere your site uses them.
-- **Colors**: the harmony wheel, the palette curves, and the story your colours
+- **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**: an effect layer that redraws the page by hand. See
+- **Sketch Style**: an effect layer that redraws the page by hand. See
   [Sketch mode](sketch-mode.md).
 
 This page covers **Tokens**. For components, see

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

@@ -9,7 +9,7 @@ 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** view in the editor and switch **Sketch mode** on. The effect
+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.
 
@@ -63,12 +63,93 @@ your own, alongside the shipped seven, as a file under
   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 effect displaces boxes, so anything drawn some other way is left alone. A
-rule made from a `border` is not a box; make it an element and tell the layer
-what to draw it with:
+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);
@@ -77,13 +158,26 @@ what to draw it with:
 }
 ```
 
-`--sketch-fill`, `--sketch-stroke`, `--sketch-hatch-color` and `--sketch-radius`
-name the fill, the outline, the hatching ink and the corners for one element and
-everything inside it. Since the layer blanks the real background, an element
-whose fill matters under Sketch mode should name it here as well as paint it.
-
 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. To keep the icons in a subtree crisp, set
-`--sketch-icon-off: none` on its root. It inherits, so one declaration covers
-everything under it.
+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.