@motion-proto/live-tokens 0.56.1 → 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-pair-fonts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: live-tokens-pair-fonts
-description: Choose and apply a Google Fonts pairing for a live-tokens theme by binding families to the --font-display, --font-sans, --font-serif and --font-mono stacks. Use whenever the user asks to pair fonts, pick a typeface, change or set the fonts, or describes type by voice: give me a font pairing, what font should the headings use, make the type more editorial, friendlier, more technical, more elegant, a serif for headings, a display font for this theme, less generic type, match the fonts to the theme. Also invoked by live-tokens-generate-theme for the type half of a whole look. Changes type only, never color. Not for a single token (use the editor) or for color (see live-tokens-generate-theme).
+description: Choose and apply a Google Fonts pairing for a live-tokens theme by binding families to the --font-display, --font-sans, --font-serif, --font-mono and --font-editorial stacks. Use whenever the user asks to pair fonts, pick a typeface, change or set the fonts, or describes type by voice: give me a font pairing, what font should the headings use, make the type more editorial, friendlier, more technical, more elegant, a serif for headings, a display font for this theme, less generic type, match the fonts to the theme. Also invoked by live-tokens-generate-theme for the type half of a whole look. Changes type only, never color. Not for a single token (use the editor) or for color (see live-tokens-generate-theme).
 ---
 
 # Pairing fonts for a theme
@@ -24,7 +24,7 @@ Flags: `--dry-run` reports without writing. `--no-verify` skips the network and
 { "display": "Fraunces", "body": "Nunito Sans" }
 ```
 
-Every slot is optional and an omitted slot is left exactly as it is. `display` is `--font-display`, `body` is `--font-sans`; `serif` and `mono` exist when a theme needs them. A slot may be `{ "name": "...", "url": "..." }` to pin an exact URL. Spell families as Google does; the CLI reports the canonical spelling back.
+Every slot is optional and an omitted slot is left exactly as it is. `display` is `--font-display`, `body` is `--font-sans`; `serif`, `mono` and `editorial` exist when a theme needs them. `editorial` is `--font-editorial`, the long-reading face behind the `--editorial-*` text style: it tracks the body face until a theme repoints it, so set it only when essays and articles should not carry the body face. A slot may be `{ "name": "...", "url": "..." }` to pin an exact URL. Spell families as Google does; the CLI reports the canonical spelling back.
 
 ## Choose the body face first
 

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,197 @@
 # 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
+
+- **Sketch mode: a fourth editor view, beside Tokens, Colors and Components.**
+  It is an effect layer over the active theme, not a set of theme values. It
+  reads nothing from the theme and writes nothing back. Each component's fill
+  and outline are repainted onto `::before`/`::after` from the tokens that
+  component already owns (`--<component>-<variant>-surface`, `-border`,
+  `-radius`), the real background and border are hidden behind them, and both
+  are pushed around one shared noise field. Turning it off removes every trace.
+  While it is on it applies to the page behind the editor as well as to the
+  preview, because the layer is injected into every document `cssVarSync`
+  tracks. Scope is the `data-sketch` attribute, so it switches on for a whole
+  document root or for one preview container.
+- **Seven shipped looks, and every dial behind them.** Pencil, Marker,
+  Whiteboard, Hatched, Dashed, Napkin and Dry marker, each a complete set of
+  settings with a blurb naming what it is. The dials sit under five headings:
+  **Border** (travel, wavelength, width, ink, pressure, pooling, dashes, a
+  second pass that either copies the first line or runs it through the pen again
+  on its own seed), **Fill** (solid or hatched, travel, per-instance offset,
+  rotation and scale), **Shape** (corner spread, and a corner travel that leans
+  the drawn box into a quadrilateral with no two sides parallel), **Icons and
+  SVG** (glyph travel and wavelength on their own scale, because a glyph is all
+  curves and needs more travel than a card's long straight edge), and **Noise**
+  (the shared displacement field's wavelength, roughness and waveform).
+- **Ink coverage as a generated field.** The mask that thins a fill is a tiling
+  Perlin field rasterised to a greyscale PNG and applied with `mask-mode:
+  luminance`, rather than an `feTurbulence` primitive. Turbulence lands in a
+  narrow band around its own midpoint, so a dial walking a cut across 0 to 1
+  spends most of its travel outside the field and the rest reads as flat grey.
+  Generated, the tile is stretched onto its own measured range first, so Min and
+  Max always mean levels at every grain and octave count. The panel previews the
+  field at each stage: noise, output, blur.
+- **Saved sketch presets.** Any set of dials saves under a name and reloads
+  later, as files under `<dataDir>/sketch-presets/` served by a new
+  `/api/sketch-presets` route on the dev plugin. A sketch look is a draft
+  effect, never part of a theme: it has no active/production pointer, it is not
+  adopted, and it never reaches `tokens.generated.css`. The shipped seven stay
+  in code, so the directory holds nothing but your own files.
+- **A page can hand the layer its own elements.** The effect displaces boxes, so
+  a rule drawn as a `border` is not one of them. `--sketch-fill`,
+  `--sketch-stroke`, `--sketch-hatch-color` and `--sketch-radius` name what an
+  element should be drawn with, and `--sketch-icon-off: none` opts a subtree
+  out. The demo app's kit section draws its rules this way; the editor's own
+  overlay bar opts out, because the effect is for the page being designed and
+  not for the tool looking at it.
+- **A Sketch mode chapter in the user guide.** It sits after Editing tokens and
+  covers the presets, the dials, and the `--sketch-*` properties a page uses to
+  hand the layer its own elements. Editing tokens itself now names all four
+  views; it had been describing two since the Colors view landed.
+- **Sketches ships as an eighth preset theme.** A whole look built on the
+  effect: Cabin Sketch over Shantell Sans, square corners, and component
+  aliases tuned for a page that is drawn rather than rendered. Load it from the
+  Theme panel like any other preset. It stands on its own with Sketch mode off,
+  and the effect is what it was designed under.
+- **The gradient library is open-ended.** `--gradient-N` was a fixed four-slot
+  scale; the Gradients section now has Add and Remove, and any number of
+  numbered slots loads from a theme file. A new slot seeds from the last one, so
+  it lands as a gradient you edit rather than an invisible transparent one.
+- **A gradient can point at a corner.** Alongside degrees, a linear gradient
+  takes CSS's `to top right` and its seven neighbours. A keyword angles the
+  gradient line off the box's own diagonal, so it tracks the element's aspect
+  where a fixed angle cannot: `to bottom right` reads as about 95deg across a
+  wide heading and about 111deg once that heading wraps. The degrees underneath
+  are kept, so clearing the keyword lands on the nearest angle rather than
+  snapping to 0deg.
+- **`--gradient-N-stops`.** Each slot now also emits its stop list on its own,
+  so a consumer can keep the theme's colours and supply their own geometry:
+  `linear-gradient(to top, var(--gradient-5-stops))`. One set of stops then
+  serves every direction a design needs, instead of a token per angle.
+- **The editorial type role.** A fifth font stack (`--font-editorial`) and a
+  ninth text-style bundle (`--editorial-*`), for the long-reading surfaces that
+  should not carry the body face under an expressive display face. Both default
+  to indirections rather than literals: the stack resolves to `var(--font-sans)`
+  and the bundle mirrors `--body-md-*`, so a project that never mentions
+  editorial renders byte-identically. `live-tokens set-fonts` gained a matching
+  `editorial` slot, and the stack is editable in the editor beside the other
+  four.
+
+### Changed
+
+- **Derived palette values serialize unclamped.** A palette's basis is OKLCH,
+  and clamping every derived step into sRGB on the way out threw away chroma a
+  wide-gamut display can show. Values already inside sRGB serialize identically,
+  so nothing moves in an existing theme; intent authored beyond sRGB now
+  survives to the browser, which does its own gamut mapping at paint. The hex
+  readouts still show the clamped projection, which is what a hex readout is
+  for.
+- **The product is spelled LiveTokens.** One word, in the README, the docs and
+  the demo app. The package name is unchanged.
+- **A test fails on any engine load at module top.** `bin/engineLoadsLazily.test.ts`
+  follows every `.mjs` module a test suite can reach, transitively, and rejects
+  a top-level import of the compiled engine. CI runs the suite before it builds
+  the plugin, so such a load is a publish failure rather than a test failure.
+  This is the bug that took down 0.56.0.
+
+### Fixed
+
+- **A session persisted before the OKLCH palette basis no longer throws on
+  hydrate.** Such a session holds hex strings where every palette color is now
+  `{ l, c, h }`. `loadFromFile` migrated those on the way in and `hydrate` did
+  not, so the session reached the renderer with an undefined hue and threw on
+  the first serialization.
+- **The overlay panel's chrome keeps its own font.** `tokens.css` sets the theme
+  font on `:where(*)`, and a matching rule beats inheritance, so the panel's
+  font-family never reached its children. The editor page already restored
+  inheritance for its chrome; the overlay now does the same.
+
+### Migration
+
+- Two **tokens.css migrations** ship here, both additive: `--font-editorial`
+  with the `--editorial-*` bundle, and a `--gradient-N-stops` companion per
+  gradient slot. Each companion is read out of the slot it belongs to rather
+  than hardcoded, so a retuned gradient does not get a stop list contradicting
+  it. Run `npx live-tokens migrate` to apply them to a vendored `tokens.css`, or
+  set the plugin's `autoMigrate` option and let it apply additive migrations on
+  boot. Until then the dev plugin warns on the gap and the new names simply
+  resolve to nothing.
+- The **editorial font stack** is added to a theme file on load, cloned from
+  that theme's `--font-sans`. It is presence-based and idempotent, so there is
+  no schema step and a theme that never touches editorial keeps rendering as it
+  did.
+
 ## 0.56.1 — Release fix
 
 ### Fixed

package/README.md

@@ -1,4 +1,4 @@
-# Live Tokens
+# LiveTokens
 
 A design system for styling and building Svelte + Vite microsites. Edit tokens and components in a dev-only editor and watch the running site repaint on every input. Save the result as a theme file and carry it between projects.
 

package/bin/cli.mjs

@@ -56,7 +56,8 @@ Commands:
                               the report without writing.
   set-fonts <brief.json> [--dry-run] [--no-verify]
                               Bind Google Fonts families to --font-display,
-                              --font-sans, --font-serif and --font-mono (see
+                              --font-sans, --font-serif, --font-mono and
+                              --font-editorial (see
                               the live-tokens-pair-fonts skill). Each family is
                               verified against the Google Fonts API and the URL
                               is negotiated from the weights it actually has.

package/dist-plugin/adjust/index.cjs

@@ -270,6 +270,7 @@ function resolveDataDirs(opts = {}) {
     colorsAndTypeDir: opts.colorsAndTypeDir ? import_path.default.resolve(opts.colorsAndTypeDir) : fileConfig.colorsAndTypeDir ? import_path.default.resolve(fileConfig.colorsAndTypeDir) : sub("colors-and-type"),
     componentConfigsDir: opts.componentConfigsDir ? import_path.default.resolve(opts.componentConfigsDir) : fileConfig.componentConfigsDir ? import_path.default.resolve(fileConfig.componentConfigsDir) : sub("component-configs"),
     themesDir: opts.themesDir ? import_path.default.resolve(opts.themesDir) : fileConfig.themesDir ? import_path.default.resolve(fileConfig.themesDir) : sub("themes"),
+    sketchPresetsDir: sub("sketch-presets"),
     legacyManifestsDir: fileConfig.manifestsDir ? import_path.default.resolve(fileConfig.manifestsDir) : void 0
   };
 }

package/dist-plugin/adjust/index.d.cts

@@ -1,5 +1,5 @@
-import { A as AliasDiskValue, a as ComponentConfig } from '../themeTypes-BAqtv4XO.cjs';
-export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-DBN0RPuT.cjs';
+import { A as AliasDiskValue, a as ComponentConfig } from '../themeTypes-DSV3Zisf.cjs';
+export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-CRfD1LdA.cjs';
 export { C as CURRENT_COMPONENT_SCHEMA_VERSION } from '../index-4N-Orzzi.cjs';
 
 type AdjustKind = 'radius' | 'padding' | 'gap' | 'border-width';

package/dist-plugin/adjust/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AliasDiskValue, a as ComponentConfig } from '../themeTypes-BAqtv4XO.js';
-export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-DBN0RPuT.js';
+import { A as AliasDiskValue, a as ComponentConfig } from '../themeTypes-DSV3Zisf.js';
+export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-CRfD1LdA.js';
 export { C as CURRENT_COMPONENT_SCHEMA_VERSION } from '../index-4N-Orzzi.js';
 
 type AdjustKind = 'radius' | 'padding' | 'gap' | 'border-width';

package/dist-plugin/adjust/index.js

@@ -4,7 +4,7 @@ import {
 import {
   readLiveTokensConfig,
   resolveDataDirs
-} from "../chunk-D3ZVKOR4.js";
+} from "../chunk-Y5CNFSSV.js";
 
 // src/editor/core/components/aliasKinds.ts
 var KIND_PATTERNS = [

package/dist-plugin/{chunk-TKZBVIW5.js → chunk-E5QYON4L.js}

@@ -1,7 +1,7 @@
 import {
   hexToOklch,
   oklchToCss
-} from "./chunk-YR6GPXW2.js";
+} from "./chunk-XWXIMTWZ.js";
 
 // src/editor/core/themes/parsers/globalRootBlock.ts
 function extractGlobalRootBody(source) {
@@ -375,6 +375,61 @@ var tokensCssMigration_2026_08_19_oklchColorValues = {
   }
 };
 
+// vite-plugin/tokensCssMigrations/migrations/2026-08-25-editorial-type-role.ts
+var STACK = [{ name: "--font-editorial", value: "var(--font-sans)" }];
+var BUNDLE2 = [
+  { name: "--editorial-font-family", value: "var(--font-editorial)" },
+  { name: "--editorial-font-size", value: "var(--font-size-md)" },
+  { name: "--editorial-font-weight", value: "var(--font-weight-normal)" },
+  { name: "--editorial-line-height", value: "var(--line-height-normal)" },
+  { name: "--editorial-letter-spacing", value: "var(--letter-spacing-normal)" }
+];
+var tokensCssMigration_2026_08_25_editorialTypeRole = {
+  id: "2026-08-25-editorial-type-role",
+  kind: "additive",
+  description: "Add the editorial type role (--font-editorial and the --editorial-* bundle)",
+  apply(css) {
+    const withStack = ensureScale(css, {
+      anchorPrefixes: ["--font-mono", "--font-serif", "--font-sans", "--font-display"],
+      entries: STACK
+    });
+    return ensureScale(withStack, {
+      sectionComment: "Editorial \u2014 the long-reading role, body face until repointed",
+      anchorPrefixes: [
+        "--eyebrow-",
+        "--code-",
+        "--body-",
+        "--heading-",
+        "--letter-spacing-",
+        "--line-height-",
+        "--font-weight-",
+        "--font-size-",
+        "--font-"
+      ],
+      entries: BUNDLE2
+    });
+  }
+};
+
+// vite-plugin/tokensCssMigrations/migrations/2026-08-26-gradient-stops.ts
+var STOPS_RE = /^(?:linear|radial)-gradient\(\s*[^,]+,\s*(.+)\)$/i;
+var tokensCssMigration_2026_08_26_gradientStops = {
+  id: "2026-08-26-gradient-stops",
+  kind: "additive",
+  description: "Add --gradient-N-stops companions to the gradient slots",
+  apply(css) {
+    const values = collectTokenValues(css);
+    const entries = [];
+    for (const [name, value] of values) {
+      if (!/^--gradient-\d+$/.test(name)) continue;
+      const stops = value.match(STOPS_RE);
+      if (stops) entries.push({ name: `${name}-stops`, value: stops[1].trim() });
+    }
+    if (entries.length === 0) return css;
+    return ensureScale(css, { anchorPrefixes: ["--gradient-"], entries });
+  }
+};
+
 // vite-plugin/tokensCssMigrations/index.ts
 var TOKENS_CSS_MIGRATIONS = [
   tokensCssMigration_2026_05_29_typographyScaleAdditions,
@@ -384,7 +439,9 @@ var TOKENS_CSS_MIGRATIONS = [
   tokensCssMigration_2026_06_04_easingColorAndTypescaleAdditions,
   tokensCssMigration_2026_07_20_lineHeightRename,
   tokensCssMigration_2026_07_20_semanticTextStyles,
-  tokensCssMigration_2026_08_19_oklchColorValues
+  tokensCssMigration_2026_08_19_oklchColorValues,
+  tokensCssMigration_2026_08_25_editorialTypeRole,
+  tokensCssMigration_2026_08_26_gradientStops
 ];
 function runTokensCssMigrations(css) {
   return foldMigrations(css, () => true);