@motion-proto/live-tokens 0.57.0 → 0.59.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,122 @@
 # Changelog
 
+## 0.59.0 — The shadow traces the art
+
+### Added
+
+- **`shadow` on `ImageLightbox`.** The tile cast its shadow from its own
+  rectangle and offered no way out, so a PNG or WebP with transparency sat on a
+  phantom slab: the shadow drew the box, and the box was not the picture. Art
+  cut out against the page — a device mockup, a logo, a chart on no background —
+  showed a hard rounded rectangle behind it. `shadow` now picks where that
+  shadow falls. `box` is the old behaviour and stays the default. `content`
+  casts from the image's own alpha, so the shadow follows the silhouette.
+  `none` drops it. All three read the one `--imagelightbox-tile-shadow` the
+  theme already sets — the mode moves the shadow, it does not restyle it. The
+  open modal keeps its shadow only under `box`: it casts against a near-opaque
+  scrim where nothing reads, and filtering the pan-and-zoom surface would
+  repaint it every frame.
+
+### Changed
+
+- **A shadow token writes its spread slot only when the spread is set.**
+  `--shadow-md` read `3px 3px 6px 0px hsla(…)`, and that fourth length was the
+  reason a shadow token could not also be a filter: `drop-shadow()` has no
+  spread slot, so the declaration was invalid and dropped. Every shipped theme
+  carries a zero spread, so the slot said nothing and cost the scale half its
+  reach. The zero-spread form is now three lengths, which `box-shadow` reads
+  identically and `drop-shadow()` accepts — one token, both properties, no
+  second scale to keep in step. The spread control is untouched: dial one and
+  the token grows its fourth length back, still a shadow but no longer a
+  filter, so a theme with a real spread has no shadow under `content`.
+  Four-length values still parse, and normalise on the next save.
+
+### Fixed
+
+- **The colour edit panel wears editor chrome again.** Its confirm, cancel and
+  "Remove override" buttons were the shipped `Button` and `InlineEditActions`
+  components, which read the theme's own tokens — so the controls you edit a
+  theme *with* restyled themselves as you edited, and a saturated success or
+  danger palette turned three small chrome buttons into slabs. They are now
+  `UIInlineEditActions` and `UIPillButton`, drawn from the theme-immune `--ui-*`
+  scale like the rest of the editor. `UIInlineEditActions` is the editor's
+  check/cross pair, sized to the 1.5rem chrome buttons it sits beside.
+- **The base colour panel offers a confirm and a cancel.** Opening a palette's
+  editor showed the base panel with no way to accept or discard — every slider
+  wrote straight through, and only the docked step panel carried the pair. The
+  panel now shows both, greyed until an edit is pending; the first touch of a
+  slider, a hex field or the eyedropper opens the same session the step panel
+  uses, so cancel restores the colour the panel opened with and confirm keeps
+  the drag as one undo step.
+
+## 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/dist-plugin/generateColorsAndType/index.cjs

@@ -719,15 +719,16 @@ function computeAngleDistance(x, y) {
   return { angle: Math.round(angle), distance };
 }
 function shadowTokenCss(t) {
-  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})`;
 }
 function parseShadowCss(variable, raw) {
-  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] === void 0 ? 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/dist-plugin/generateColorsAndType/index.js

@@ -105,15 +105,16 @@ function computeAngleDistance(x, y) {
   return { angle: Math.round(angle), distance };
 }
 function shadowTokenCss(t) {
-  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})`;
 }
 function parseShadowCss(variable, raw) {
-  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] === void 0 ? 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.57.0",
+  "version": "0.59.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/component-editor/ImageLightboxEditor.svelte

@@ -44,12 +44,13 @@
   ];
 
   let multiple = $state(true);
+  let shadow = $state<'box' | 'content' | 'none'>('box');
 </script>
 
 <ComponentEditorBase
   {component}
   title="Image Lightbox"
-  description="Click an inline image to expand it into a centered modal with a backdrop. Pass multiple images for a gallery (chevrons + counter). Extended mode adds zoom controls and drag panning."
+  description="Click an inline image to expand it into a centered modal with a backdrop. Pass multiple images for a gallery (chevrons + counter). Extended mode adds zoom controls and drag panning. `shadow` picks where the one tile-shadow token falls: `box` casts it from the tile rectangle, `content` from the image's own alpha, or `none`."
   tokens={allTokens}
 >
   <VariantGroup name="imagelightbox" title="Image Lightbox" {states} {component}>
@@ -58,9 +59,17 @@
         <input type="checkbox" checked={multiple} onchange={(e) => (multiple = e.currentTarget.checked)} />
         <span>Multiple images</span>
       </label>
+      <label class="preview-toggle">
+        <span>Shadow</span>
+        <select value={shadow} onchange={(e) => (shadow = e.currentTarget.value as typeof shadow)}>
+          <option value="box">Box</option>
+          <option value="content">Content</option>
+          <option value="none">None</option>
+        </select>
+      </label>
     {/snippet}
     <div class="preview-frame">
-      <ImageLightbox images={multiple ? demoImages : [demoImages[0]]} extended />
+      <ImageLightbox images={multiple ? demoImages : [demoImages[0]]} {shadow} extended />
     </div>
   </VariantGroup>
 </ComponentEditorBase>

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