@motion-proto/live-tokens 0.57.0 → 0.58.0

package/.claude/skills/live-tokens-create-component/SKILL.md

@@ -44,7 +44,15 @@ For pattern reference, read any shipped component's source directly from the con
    ```
    The schema side-effect happens inside `registerComponent` (which `bootLiveTokens` calls for you), so you don't call `registerComponentSchema` separately. **Do not place a standalone `registerComponent(...)` *before* `bootLiveTokens`** — that registers before the editor's init hooks run, which is the wrong window and can leave editor changes disconnected from the live page. Only call `registerComponent` directly if your app mounts manually (no `bootLiveTokens`), in which case call it before `mount(App, ...)`.
 4. **Tell the picker** — open `.claude/skills/live-tokens-pick-component/SKILL.md` and add your new component to the **Catalogue** line under the family it belongs to (Action / Input / Selection / Containers / Messaging / Display). If it's confusable with an existing component (a second selection control, a competing container), add a row to that family's decision table explaining the use-case it owns. Without this step, the component exists but [[live-tokens-pick-component]] can't recommend it when a user asks "which component should I use?" — the same rule applies whether the component is first-party (update the picker shipped in this package) or consumer-authored (update the local copy at `.claude/skills/live-tokens-pick-component/SKILL.md` that `setup-claude` placed in your project).
-5. **Verify** with the checklist at the bottom of this file.
+5. **Join the sketch layer** — the effect draws a fixed set of parts, so a new
+   component stays crisp while the page around it goes hand-drawn until it opts
+   in. A consumer component carries one of four reserved classes on its root and
+   names the five `--sketch-*` colours it is drawn with; a first-party component
+   adds a `PartSpec` row instead. The layer also takes `background`,
+   `border-color`, `box-shadow`, `overflow`, `position` and both pseudo-elements
+   away from the element it draws, which constrains where the class can go. Read
+   `references/sketch-mode.md`.
+6. **Verify** with the checklist at the bottom of this file.
 
 ## Token discipline
 
@@ -123,6 +131,7 @@ The authoritative recognised list lives in `bin/check-component.mjs` (`KNOWN_SUF
 
   The helper strips the `--<component>-` prefix and those segments, keeping the rest: `--mywidget-header-default-text` → `header-text`, `--mywidget-header-default-text-font-family` → `header-text-font-family`. Two parts ending in the same word stay distinct; one slot across variants collapses to one key. To override a single derived key, set `colorGroupKey` on that type-group config — it wins and is never recomputed, so your fix survives. There is no name-based fallback: a bare `buildTypeGroupColorTokens` call emits un-grouped (solo) colors rather than guessing, and a bare *font* helper across multiple slots is a `check-component` warning (its default `font-family`/… keys would merge the slots' fonts).
 
+
 ## State model
 
 Components *can* have two state axes. Many don't: container and messaging components (Card, Badge, Callout, CollapsibleSection) have only variants, no hover/disabled. Skip the rest of this section for those.
@@ -194,10 +203,11 @@ For your own component, copy the pattern and substitute your id. Registering aga
 
 ## Extensions
 
-Read the one you need; most components need neither.
+Read the sketch reference for every component; the other two only when they apply.
 
 - `references/linked-siblings.md`: variants that share base properties and should move together (Badge, Card, SegmentedControl).
 - `references/intrinsics.md`: structural or display choices that are not token values (an alignment, an element's visibility), where the runtime default and the editor's read-back must agree.
+- `references/sketch-mode.md`: joining the sketch layer. **Every component needs this.** One class on the root, the five `--sketch-*` values the layer draws with, and the list of what it takes over from the element. Skip it and the component stays crisp while the page around it goes hand-drawn.
 
 ## Verification checklist
 
@@ -230,3 +240,4 @@ Finally navigate to `/live-tokens/components` and confirm the runtime behaviours
 - [ ] `component-configs/<id>/default.json` is derived from the `:global(:root)` block at boot. Save writes `_working.json`, the unsaved buffer the open theme captures; Save As also writes a named preset.
 - [ ] Reset returns each variable to its `:global(:root)` default.
 - [ ] Boot validation is clean (no warnings about the component being missing from the server scan, or about disk-vs-registry drift).
+- [ ] Switch Sketch mode on in the editor and walk the checklist at the end of `references/sketch-mode.md`. The component is drawn in every variant and on hover, in its own colours, not crisp and not wearing another part's palette. Switch it off again and the component is unchanged.

package/.claude/skills/live-tokens-create-component/references/sketch-mode.md

@@ -0,0 +1,202 @@
+# Joining the sketch layer
+
+Sketch mode blanks each part's real background and border and repaints them onto
+`::before`/`::after` through a shared noise field. It draws a fixed set of
+selectors: the shipped components, plus four classes reserved for everyone else.
+Your component is skipped until it opts in, so it stays crisp while the page
+around it goes hand-drawn.
+
+The whole contract is CSS. There is nothing to import and no function to call:
+the layer exports no runtime API, and a component joins it by carrying a class
+and naming five custom properties.
+
+## What the layer takes over
+
+An opted-in element is no longer painting itself. On every drawn part the layer
+forces:
+
+| It forces                                    | So you must                                              |
+|----------------------------------------------|----------------------------------------------------------|
+| `background: transparent !important`          | Name the fill again as `--sketch-fill`                    |
+| `border-color: transparent !important`        | Name the outline again as `--sketch-stroke`               |
+| `box-shadow: none !important`                 | Name the shadow again as `--sketch-shadow`                |
+| `overflow: visible !important`                | Never put the class on a box whose clip carries meaning   |
+| `position: relative`                          | Never put the class on an absolutely-positioned root      |
+| `z-index: 0`                                  | Expect a new stacking context on that element             |
+| `::before` (the fill), `::after` (the stroke) | Never own either pseudo-element on that element           |
+
+`::after` survives on `sketch-rule` alone, which draws no outline. `::before` is
+claimed on all four.
+
+## Opting in
+
+Put one class on the runtime component's root, chosen by **size, not by kind**.
+A card and a modal are both containers; a badge and a pill are both chips.
+
+| 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.       |
+
+The class opts you in and nothing more. It names no colour, so the layer emits
+no rule for it and whatever your component declares survives.
+
+```svelte
+<div class="mywidget sketch-container {variant}">…</div>
+
+<style>
+  .mywidget {
+    background: var(--mywidget-surface);
+    border: var(--mywidget-border-width) solid var(--mywidget-border);
+    border-radius: var(--mywidget-radius);
+    box-shadow: var(--mywidget-shadow);
+
+    /* The layer hides all four above. These are what it draws instead. */
+    --sketch-fill: var(--mywidget-surface);
+    --sketch-stroke: var(--mywidget-border);
+    --sketch-hatch-color: var(--mywidget-border);
+    --sketch-radius: var(--mywidget-radius);
+    --sketch-shadow: var(--mywidget-shadow);
+  }
+</style>
+```
+
+State all five. `--sketch-radius` is registered as an inheriting `<length>`, and
+the other four inherit as ordinary custom properties, so a part that states
+nothing is drawn with its **ancestor's** value: a badge inside a hatched card
+stripes itself in the card's ink, and a square header inside a rounded card
+picks up the card's corners.
+
+## Variants, states and inner parts
+
+Nothing competes with you for these values, so every case is one more
+declaration at the specificity you already use.
+
+```css
+.mywidget.danger      { --sketch-fill: var(--mywidget-danger-surface); }
+.mywidget:hover,
+.mywidget.force-hover { --sketch-stroke: var(--mywidget-hover-border); }
+```
+
+Pair every `:hover` with `.force-hover`, as elsewhere: that is the editor's
+preview of the hover state, and a hover the sketch layer cannot paint reads as
+no hover at all once the real background is transparent.
+
+An inner part that carries its own surface (a header strip, a footer) takes its
+own class and its own five values. Where such a part draws no outline, bind the
+hatch ink to the ink its **parent** is outlined in, so the component reads as one
+drawing rather than a shaded panel dropped into a box:
+
+```css
+.mywidget-header {
+  --sketch-fill: var(--mywidget-header-surface);
+  --sketch-stroke: transparent;
+  --sketch-hatch-color: var(--mywidget-border);
+  --sketch-radius: 0px;
+}
+```
+
+A part with a visible stroke needs no `--sketch-hatch-color`; it falls back to
+the stroke and follows it into hover. A part with no fill wants none, because
+there is no surface there to shade.
+
+A gradient is a valid fill. The `background` shorthand's last layer takes a
+colour or an image, so `--sketch-fill` accepts either.
+
+## Where the class does not go
+
+- **A positioned root.** The layer forces `position: relative` on parts that sit
+  in flow, which drops an absolutely or fixed-positioned element back to its
+  flow position. Put the class on an inner box instead.
+- **A box that clips something real.** `overflow` is forced visible so the ink
+  can travel past the border box, and there is no consumer opt-out. A scroller,
+  a fill bar held to its track, or a picture held to its frame keeps its clip by
+  keeping the class off that element and carrying it on a wrapper.
+- **An element that owns `::before` or `::after`.** The layer claims both. A
+  shimmer, a caret or a decorative arrow on the opted-in element is gone.
+- **A shipped part's selector** (`.card`, `.panel`). Borrowing one to get drawn
+  works, but it hands your component that part's colours and its damping, and it
+  is package-internal. The reserved classes are the contract.
+
+## Rules, which are not boxes
+
+A `border` cannot be displaced: the effect moves boxes, and a border is not one.
+Make the rule an element, give it `sketch-rule`, and name its ink as the fill.
+
+```svelte
+<span class="mywidget-rule sketch-rule" aria-hidden="true"></span>
+```
+```css
+.mywidget-rule {
+  height: var(--border-width-2);
+  background: var(--mywidget-divider);
+  --sketch-fill: var(--mywidget-divider);
+}
+```
+
+## Media inside your component
+
+A drawn part's `overflow` is visible so the fill and outline can travel past the
+box. A background that bleeds is the effect working. An image that bleeds is
+not, since it keeps square corners while the part around it turns. Media running
+to your component's edge has to carry the corners itself:
+
+```css
+.mywidget-cover {
+  overflow: hidden;
+  border-top-left-radius: var(--sketch-radius, var(--mywidget-radius));
+  border-top-right-radius: var(--sketch-radius, var(--mywidget-radius));
+}
+```
+
+`--sketch-radius` is the radius the layer drew and it inherits, so the fallback
+covers the effect being off. 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.
+
+## Icons and SVG
+
+Icons and inline SVG take the wobble directly, since a glyph has no box to
+redraw. Body type is left alone deliberately: an icon is a shape and survives a
+wobble, a paragraph is not. You opt into none of this; it applies to every
+`[class*="fa-"]` and every `svg` under the scope.
+
+`--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. */
+.mywidget-toolbar { --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. */
+.mywidget-mark { --sketch-icon-off: var(--sketch-icon-soft); }
+```
+
+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. Reach for the
+soft bank before reaching for `none`. The shipped `SectionDivider` is the worked
+example.
+
+## First-party components
+
+A component authored inside the package does not use the reserved classes. Add a
+`PartSpec` row to `PART_SPECS` in `src/editor/core/sketch/sketchLayer.ts`
+instead, which is keyed to the component's own token stem and gets the shipped
+damping. `sketchPartTokens.test.ts` then holds you to it: every colour the layer
+paints must be one the component itself assigns to that same element, checked
+against the compiled `<style>` block.
+
+## Verify
+
+Switch Sketch mode on from the editor's **Sketch Style** view, then check the
+component in place:
+
+- [ ] Drawn, not crisp, in every variant.
+- [ ] Wearing its own colours, not its parent's, including inner parts.
+- [ ] Hover repaints. The wobble holds still while it does.
+- [ ] Hatched fill uses ink that belongs to the component.
+- [ ] Media at the component's edge turns with the drawn corners.
+- [ ] Nothing that has to stay exact is torn: icons, clipped content, overlays.
+- [ ] Switch it off. Every trace is gone and the component is unchanged.

package/.claude/skills/live-tokens-pick-component/SKILL.md

@@ -49,7 +49,7 @@ All four pick one option from a set. The right one depends on **option count**,
 | `Dialog`              | Modal, blocks page  | Confirmations, focused tasks the page can't continue around |
 | `Panel`               | Inline, fixed stage | A demo or preview surface whose height must not reflow     |
 
-- Default to `Card`. It's the workhorse.
+- Default to `Card`. It's the workhorse. For full-bleed media — cover art, a poster, a chart that reaches its own border — pass `flush` (with `prose={false}`) rather than zeroing its padding tokens from the page.
 - Reach for `CollapsibleSection` only when the content is *legitimately secondary* (advanced users open it; most skip). Don't use collapse as a styling choice when the content matters.
 - `Panel` is a stage, not a content container. It pins its own height so what it shows can resize without moving the page, which is what a component preview or a live example needs and what article content does not. Content goes in `Card`.
 - **Don't use `Dialog` for routine forms.** Reach for it only when the page cannot meaningfully continue until the user decides (destructive confirmations, payment, sign-in). Routine forms go inline in a `Card`.

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 0.58.0 — The sketch layer states its contract
+
+### Added
+
+- **`flush` on `Card`.** A card holding full-bleed media has to reach its own
+  border, but the body's inset stood in the way and the only way around it was
+  for the page to zero the five `--card-default-body-padding*` tokens at its own
+  scope — reaching around the component to undo something the component did, and
+  repeating it at every such card. `flush` drops the inset from the body alone,
+  outweighs `size="compact"` so it holds at either size, and pairs with
+  `prose={false}`: a flush body is a frame, not a column of text.
+- **`sketch-container` and `sketch-chip`, beside the existing `sketch-surface`
+  and `sketch-rule`.** The sketch layer draws a fixed set of selectors, so a
+  consumer-authored component stayed crisp while the page around it went
+  hand-drawn. The four reserved classes are now a size ladder — a container
+  tilts less than the type inside it can tolerate, a chip is smaller than one
+  blob of the fill mask — and a consumer picks the band its part belongs to
+  instead of inheriting the middle treatment or borrowing a shipped part's
+  selector to get drawn at all. The classes name no colours, so the element's
+  own `--sketch-fill` / `--sketch-stroke` survive untouched.
+
+### Changed
+
+- **The `Sketches` preset theme is now `Sketchy`.** The old name read as a
+  collection of sketches rather than as the look itself, which is the one thing
+  a preset name has to do. The theme's files move to
+  `themes/sketchy.json` and `colors-and-type/sketchy.json`. Presets are served
+  read-through from the package, so a consumer who never opened it sees only the
+  new name; one whose active or production pointer names `sketches` has to
+  repoint it at `sketchy`.
+- **The editor's `Sketch` and `Colors` views are now `Sketch Style` and
+  `Color Wheel`,** and the condensed rail cycles Tokens, Components, Sketch
+  Style, Color Wheel. `Sketch` named the mode and the view identically while
+  `Colors` said less than the view does; the flow order now runs from the
+  narrowest edit to the widest.
+- **The sketch layer's contract is now documented from both sides.** The guide
+  and the component-authoring skill each described what an element has to
+  declare to be drawn, and neither said what the layer takes away from it: the
+  element's `background`, `border-color` and `box-shadow` are forced off, its
+  `overflow` is forced visible, it is given a stacking context, and both its
+  pseudo-elements are claimed. That is what decides where the opt-in class can
+  go, so a component that owned a `::before`, clipped its content or positioned
+  its root failed in a way neither document accounted for. The skill reference
+  now carries the full contract, including the icon controls, the hatch-ink
+  fallback for a part with no outline, and the `PART_SPECS` path a first-party
+  component takes instead of the reserved classes. The guide gains a short
+  section on where the dials live, since nothing said they are held in the
+  browser rather than in the theme.
+
+### Fixed
+
+- **Sketch mode's "Drawing your own elements" section showed the custom
+  properties without the class that opts an element in**, so the example it gave
+  drew nothing. It now documents all four reserved classes, how to pick one, and
+  that variants, states and gradients are all just further declarations of
+  `--sketch-fill` / `--sketch-stroke`.
+- **Nothing said how to keep an image inside a drawn part from bleeding.** A
+  part's `overflow` is forced visible so the fill and outline can travel past
+  the box, which is right for a background and wrong for a photo: it kept square
+  corners while the card around it turned. `--sketch-radius` was already the
+  radius the layer drew and already inherited, so the fix was a documentation
+  one. Both the Sketch mode chapter and the component-authoring reference now
+  show media reading it, with a fallback for the effect being off.
+- **`live-tokens-create-component` never mentioned sketch mode.** Joining the
+  layer is now step 5 of the recipe, with `references/sketch-mode.md` behind it
+  and a line on the verification checklist. A component authored to the old
+  recipe was invisible to the effect and nothing said so.
+
 ## 0.57.0 — A theme can be drawn by hand
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -30,7 +30,7 @@
     "src/live-tokens/data/colors-and-type/midnight-study.json",
     "src/live-tokens/data/colors-and-type/ocean.json",
     "src/live-tokens/data/colors-and-type/royal-velvet.json",
-    "src/live-tokens/data/colors-and-type/sketches.json",
+    "src/live-tokens/data/colors-and-type/sketchy.json",
     "src/live-tokens/data/colors-and-type/spring-meadow.json",
     "src/live-tokens/data/colors-and-type/sunset.json",
     "src/live-tokens/data/themes/autumn.json",
@@ -38,7 +38,7 @@
     "src/live-tokens/data/themes/midnight-study.json",
     "src/live-tokens/data/themes/ocean.json",
     "src/live-tokens/data/themes/royal-velvet.json",
-    "src/live-tokens/data/themes/sketches.json",
+    "src/live-tokens/data/themes/sketchy.json",
     "src/live-tokens/data/themes/spring-meadow.json",
     "src/live-tokens/data/themes/sunset.json",
     "dist-plugin",

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

@@ -155,10 +155,14 @@ function normalise(f: Float32Array): Float32Array {
 
 /* ------------------------------------------------------------- levelling --- */
 
-/** Output levels. The field's darkest point lands at Min and its brightest at
-    Max, so nothing is barer than the low handle or denser than the high one.
-    Input levels cut the field instead, and since the field is stretched to run
-    from black, any low handle above zero punched a hole through the fill. */
+/** Output levels. The field is stretched into the gap between the handles, so
+    the pair states the range the mask paints: nothing is barer than Min or
+    denser than Max, and the field keeps its own shape in between.
+
+    Clamping instead makes Min the value most of the field sits AT rather than
+    its rare floor, because the field arrives centred on its own middle: half of
+    it is below 0.5, so a floor of 0.6 piles that half onto 0.6 and the fill
+    comes out a flat wash at the floor with a thin bright tail above it. */
 function applyOutput(f: Float32Array, min: number, max: number): Float32Array {
   const span = max - min;
   for (let i = 0; i < f.length; i++) f[i] = min + f[i] * span;
@@ -239,8 +243,8 @@ export function buildMaskField(
   const raw = cachedRaw(s, seed);
   if (through === 'noise') return { field: raw, raster: RASTER };
 
-  const levelled = posterise(
-    applyOutput(Float32Array.from(raw), s.maskOutputMin, s.maskOutputMax), s.maskPosterize,
+  const levelled = applyOutput(
+    posterise(Float32Array.from(raw), s.maskPosterize), s.maskOutputMin, s.maskOutputMax,
   );
   if (through === 'output') return { field: levelled, raster: RASTER };
 

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);