@motion-proto/live-tokens 0.66.0 → 0.67.1

package/CHANGELOG.md

@@ -1,5 +1,159 @@
 # Changelog
 
+## 0.67.1 — The Napkin you tuned is the Napkin that ships
+
+### Changed
+
+- **Napkin's shipped dials match the look it was tuned to.** Four dials moved on
+  a theme's own copy of the sketchstyle and never reached the file the package
+  ships, so a project loading Napkin from the shipped set got a paler, softer
+  ballpoint than the one on screen. The ink floor lifts to 0.62 over a harder
+  mask edge, coverage runs to full, and instances vary a little less in size.
+
+- **Pencil's blurb says what the grain does.** It is drawn long and on the
+  diagonal, the way a pencil shades, which the old sentence left out.
+
+### Documentation
+
+- **The README covers sketch mode.** What the layer is, the seven shipped looks
+  with the blurb each one carries, seeding a built site from a theme, registering
+  your own sketchstyles at boot, building a picker, and the four classes the
+  layer reserves for elements you draw yourself. A test pins each blurb to the
+  README, so a look renamed or reworded here fails the suite until the page
+  catches up.
+
+## 0.67.0 — Every sketchstyle is a file
+
+### Added
+
+- **A saved sketchstyle ships with your site.** 0.66.0 carried the look a theme
+  holds into a build, which covers one look per theme. Everything else a project
+  saved in the Sketchstyle view stayed behind: the files live in
+  `src/live-tokens/data/sketch-styles/` and only the dev server could read them,
+  so a picker on a built site silently listed the shipped seven and nothing
+  else. Hand them to `bootLiveTokens` and they are real everywhere:
+
+  ```ts
+  const files = import.meta.glob('./live-tokens/data/sketch-styles/*.json', {
+    eager: true,
+    import: 'default',
+  });
+
+  await bootLiveTokens(App, '#app', {
+    sketchLooks: Object.entries(files).map(([path, file]) => {
+      const id = path.split('/').pop().replace('.json', '');
+      return { id, label: file.name || id, settings: file.settings };
+    }),
+  });
+  ```
+
+  Unlike `components`, these register in a build as well as in dev. Reaching a
+  published site is the whole point of them.
+
+  `create` writes this into `src/main.ts`, so a new project publishes what it
+  saves without wiring anything.
+
+- **A Save pill in the Sketchstyle view**, which writes the dials back over the
+  sketchstyle you have selected. Updating a saved sketchstyle used to run
+  through the naming form: open it, accept the pre-filled label, submit, and
+  nothing on screen said a file had been replaced rather than created. Save
+  lights as soon as the dials leave the sketchstyle they name. On one of your
+  own it writes that file; on a shipped one it writes your project's own copy
+  under the same name, which takes its place in the list, and deleting that file
+  brings the shipped look back. **Save As** always creates, and starts its form
+  empty to say so.
+
+### Changed
+
+- **Every sketchstyle ships as a file.** The seven looks were a constant in
+  `sketchStyles.ts`. The Sketchstyle view could save over one, but the thing it
+  saved over had no file to read, copy or compare against, so "restore the
+  shipped Pencil" meant trusting that a deleted file fell back to something
+  nobody could open. They now ship as JSON under
+  `src/live-tokens/data/sketch-styles/`, one per look, and the module reads
+  them: the file is the look.
+
+  A shipped sketchstyle behaves like a shipped colors-and-type. Save over one
+  and your project gets its own copy that shadows it; delete that copy and the
+  packaged file comes back. The listing marks which is which (`isPackage`), and
+  deleting a look that only the package ships answers 403 rather than reporting
+  success and leaving it on screen.
+
+  Pencil, Marker and Whiteboard ship with reworked ink coverage. Pencil's grain
+  is now stretched and turned rather than square (`maskBlobX` 40 to 525 at 67
+  degrees, on turbulence), Marker's blobs are twice the size over a much higher
+  floor with the softness off, and Whiteboard's streak is finer and harder with
+  more rotation on the jitter. The other four are unchanged.
+
+- **Primary and secondary buttons rest one rung lower.**
+  `--button-primary-surface` moves from `--surface-brand-high` to
+  `--surface-brand` and `--button-secondary-surface` from
+  `--surface-neutral-high` to `--surface-neutral`, with `--iconbutton-*`
+  following. The border scale runs at the same lightness as the `-high` surface
+  rung, so a filled button was outlined in its own fill colour: the sketch
+  effect's hatch, which inks itself from the part's stroke, came out invisible
+  on exactly these two variants while Danger, Success, and Warning shaded
+  normally. Those three already rest on `-low`. This puts Primary and Secondary
+  on the rung Badge and CornerBadge already use, and lifts white text off the
+  surface by a further step. The eight preset themes carry the new value.
+
+- **Ink coverage scales on two axes, and the px it states are the px it
+  paints.** The Scale dial fitted a whole number of blobs to a fixed 600px tile,
+  so it could only reach the sizes that divide 600: it read 250px at the top of
+  its travel and painted 300px, there was nothing above that at all, and every
+  reading in between was the nearest fit rather than the number on the dial. The
+  tile is now painted at whatever the dial says, which makes the px exact and
+  opens the travel to 8px speckle and 600px patches.
+
+  The dial is a pair, **Scale across** and **Scale down**, held together by a
+  chain. Click it and the two part company: blobs wider than they are tall read
+  as ink dragged sideways, taller than wide as a vertical grain, and the fill
+  keeps the same field underneath either way. Sketchstyles stored before the
+  split come back square and linked, which is the look they had.
+
+  Unlinked, a **Rotation** dial appears with them and points the stretch
+  wherever you like. It is offered only there because a field the same in every
+  direction is the same field turned. The tile still meets itself at every
+  setting: a turned pattern repeats seamlessly only at the angles that land the
+  page's own axes back on whole noise cells, so the dial takes the nearest of
+  those and reads back the turn it landed on, usually within a degree or two of
+  the one you asked for.
+
+- **Shipped and saved sketchstyles are one list, in one id namespace.** A
+  sketchstyle named after a shipped one replaces it and keeps its place, so a
+  project that wants its own Pencil saves one. The Sketchstyle view shows a
+  single grid; the ✕ marks the rows your project owns.
+
+### Fixed
+
+- **Saving no longer reloads the page.** A project registers its saved
+  sketchstyles with `import.meta.glob`, which is what `create` writes into
+  `main.ts`, so writing one invalidated the entry module and Vite answered with
+  a full reload. The Sketchstyle view the save came from was torn down and
+  rebuilt mid-edit, which read as the editor closing itself every time you
+  pressed Save. The dev server now keeps every JSON under the data directory off
+  its watcher: the editor reads that directory over its own API and re-lists
+  after each write, so the page already holds what the reload would fetch.
+  `tokens.generated.css` and `fonts.css` stay watched, since the page really
+  does import them and CSS updates without a reload. A data file changed from
+  outside the editor, by a CLI run or a branch switch, now needs the page
+  reloaded by hand.
+
+### Breaking
+
+Pre-1.0, and the sketch API is days old. Every consumer we know of is in this
+repo or in a site we own.
+
+- `SKETCH_LOOKS` is now the `sketchLooks` store, since looks register after the
+  module is imported and a constant array would be stale. A picker reads
+  `$sketchLooks` the way it already reads `$themeSketchLook`.
+- `USER_STYLE_PREFIX` and `selectSavedSketchStyle` are gone. A saved
+  sketchstyle's id is its file slug, so `setSketch(id)` and
+  `selectSketchStyle(id)` take it like any other.
+- A `user:` id already in a browser's storage is stripped on read, so no
+  migration is needed and nobody loses their selection. Themes need nothing at
+  all: a theme has always stored its `sketchStyle` by value, never by id.
+
 ## 0.66.0 — A theme's sketchstyle reaches the built site
 
 ### Added

package/README.md

@@ -8,15 +8,16 @@ npm install @motion-proto/live-tokens
 
 The editor is dev-only. Production builds get plain CSS variables and the components you used.
 
-## What you get
+## Features
 
 - **Live token editing.** Colors, typography, spacing, radii, shadows, motion, palettes, and gradients. Every input writes a CSS variable, so the page repaints with no reload and no build step.
 - **Live component editing.** 25 shipped Svelte components (Button, IconButton, Input, Card, Dialog, Badge, Callout, Table, Tooltip, Toggle, TabBar, SegmentedControl, RadioButton, MenuSelect, ProgressBar, CornerBadge, SectionDivider, CollapsibleSection, Notification, Image, ImageLightbox, CodeSnippet, SideNavigation, Panel, InlineEditActions) declare their design-token aliases in a `:global(:root)` block. Rewire an alias from the component's editor and it updates everywhere that component is used, on your real pages.
 - **Four dev-only routes.** `/live-tokens/editor` for tokens, `/live-tokens/colors` for palettes, `/live-tokens/components` for per-component aliases, `/live-tokens/docs` for the user guide.
 - **Editor overlay.** Pins to the top right of every dev page and opens the editor in a side panel or floating window, so you edit on the page you are styling. Its "Page Source" button opens the current page's `.svelte` file in VS Code.
 - **Themes.** A theme is a whole look in one file: colors and type plus a config for every component, stored by value. Loading one changes a single pointer file, and nothing your site ships changes until you Adopt. Export a theme and import it into another project to restore the look in one step.
-- **Seven example looks.** Autumn, Halloween, Midnight Study, Ocean, Royal Velvet, Spring Meadow, and Sunset each ship as a full theme: colors, a Google Fonts pairing, and a shape personality of radius, padding, gap, and border-width aliases. They ship inside the package, so trying one needs no local files. Load Motion Proto to return to the default. Saving over a preset writes a local copy that shadows the shipped one; delete the copy and the shipped version returns.
-- **Vite plugin.** Hosts the `/api/live-tokens/{colors-and-type,component-configs,themes}/*` routes the editor reads and writes through. The single namespace keeps these routes clear of anything your app serves under `/api`.
+- **Eight example looks.** Autumn, Halloween, Midnight Study, Ocean, Royal Velvet, Sketchy, Spring Meadow, and Sunset each ship as a full theme: colors, a Google Fonts pairing, and a shape personality of radius, padding, gap, and border-width aliases. They ship inside the package, so trying one needs no local files. Load Motion Proto to return to the default. Saving over a preset writes a local copy that shadows the shipped one; delete the copy and the shipped version returns.
+- **Sketch mode.** Redraws the page as if it had been drawn by hand. Seven looks ship as files, and the effect is a layer over your tokens rather than a change to them. See [Sketch mode](#sketch-mode).
+- **Vite plugin.** Hosts the `/api/live-tokens/{colors-and-type,component-configs,themes,sketch-styles}/*` routes the editor reads and writes through. The single namespace keeps these routes clear of anything your app serves under `/api`.
 - **Claude Code skills.** Six bundled skills that drive the package from plain English. See [Claude Code skills](#claude-code-skills).
 
 ## Install
@@ -84,7 +85,7 @@ bootLiveTokens(App, '#app');
 
 For routes you cannot enumerate ahead of time (a `/:id`, a path prefix, a page shown only under some condition), add a `resolve` function from the current path to a `RouteEntry` and return `null` to fall through. Resolution order is `pages[path]`, then `resolve(path)`, then the `pages['/']` fallback, so adding `resolve` never changes how existing entries match. A resolved entry can carry `props`, letting one component serve many paths, and its `source` gives the dynamic route a working "Page Source" button.
 
-Link-click interception follows the same route table. A left-click becomes an in-app `navigate()` only when the anchor asks for ordinary same-tab navigation — no `target`, `download`, `rel="external"`, or modifier key — and `pages` or `resolve` claims the path. Anything else keeps the browser's own handling, so a link to a PDF or an image under `public/`, to a download, or to a path no route declares loads for real. Note that the `pages['/']` fallback renders an unmatched path without claiming it: link to a path no route declares and you get a page load, not a client-side swap.
+Link-click interception follows the same route table. A left-click becomes an in-app `navigate()` only when the anchor asks for ordinary same-tab navigation (no `target`, `download`, `rel="external"`, or modifier key) and `pages` or `resolve` claims the path. Anything else keeps the browser's own handling, so a link to a PDF or an image under `public/`, to a download, or to a path no route declares loads for real. Note that the `pages['/']` fallback renders an unmatched path without claiming it: link to a path no route declares and you get a page load, not a client-side swap.
 
 ```svelte
 <LiveTokensRouter
@@ -131,11 +132,11 @@ Or copy `node_modules/@motion-proto/live-tokens/src/system/styles/tokens.css` in
 
 `bootLiveTokens` and `<LiveTokensRouter>` are wrappers. The individual init functions (`initCssVarSync`, `initRouter`, `initColumnsOverlay`, `initEditorStore`, `initializeTheme`), `<LiveEditorOverlay>`, `<ColumnsOverlay>`, and the editor page exports (`@motion-proto/live-tokens/editor`, `@motion-proto/live-tokens/component-editor-page`) are all exported. Use them to build a custom shell: arbitrary markup per route, a foreign matcher, or your own overlay wiring. Dynamic and gated routes do not need this; use `resolve` above, which keeps the overlay, nav rail, and page source intact.
 
-## Where data lands, and how to move it
+## The data directory
 
-The plugin reads and writes under one folder, `src/live-tokens/data/`, which holds three subdirectories it owns: `colors-and-type/`, `themes/`, and `component-configs/`.
+The plugin reads and writes under one folder, `src/live-tokens/data/`, which holds four subdirectories it owns: `colors-and-type/`, `themes/`, `component-configs/`, and `sketch-styles/`.
 
-`themes/` holds one file per whole look, plus `_active.json` naming the one the editor has open and `_production.json` naming the one your site ships. `colors-and-type/` and `component-configs/{comp}/` hold each layer's `default.json` baseline, any preset you save by name, and the `_working.json` buffer for edits you have not saved into the active theme. A buffer is a delta from the open theme, so ordinary theme switching leaves none behind.
+`themes/` holds one file per whole look, plus `_active.json` naming the one the editor has open and `_production.json` naming the one your site ships. `colors-and-type/` and `component-configs/{comp}/` hold each layer's `default.json` baseline, any preset you save by name, and the `_working.json` buffer for edits you have not saved into the active theme. A buffer is a delta from the open theme, so ordinary theme switching leaves none behind. `sketch-styles/` holds one file per look, shipped and your own alike.
 
 To move the data, create `live-tokens.config.json` at your project root:
 
@@ -256,6 +257,62 @@ bootLiveTokens(App, '#app', {
 
 The component appears on `/live-tokens/components` under a **CUSTOM** group. Token rows, linked-block sharing, per-component config persistence, and reset-to-default behave exactly as they do for the built-in set. Import only from `@motion-proto/live-tokens` or `@motion-proto/live-tokens/component-editor`; never deep-import from `src/`.
 
+## Sketch mode
+
+Sketch mode redraws the page as if it had been drawn by hand. Every component keeps its own colors, spacing, and corners; what changes is the line it is drawn with. The effect is a layer over your tokens and never touches a value, so switching it off returns every component to exactly what its tokens say.
+
+Seven looks ship with the package. Each is a full set of dials, and each ships as a file under `src/live-tokens/data/sketch-styles/`.
+
+- **Pencil.** Two graphite passes on their own seeds, so the outline disagrees with itself the way a hand coming back round does. The grain is drawn long and on the diagonal, the way a pencil shades.
+- **Marker.** Broad translucent nib gone round twice on the same line, so the overlap darkens and the ink pools where it slows.
+- **Whiteboard.** The fattest nib on glass. One long smooth undulation, and a veined mask that streaks the fill like a half-wiped board.
+- **Hatched.** An etching. The fill is angled shading, the outline a single hard-edged scratch that chatters along its length. No mask: the hatch is the texture.
+- **Dashed.** A drafting outline. One slow drift along the ruler, broken into strokes, with jitter, mask and pressure all off. The clean pole.
+- **Napkin.** Ballpoint in a hurry. Everything loose at once: a square wave sends every edge to full travel, and the second pass lands wherever it lands.
+- **Dry marker.** Ink that ran out. One scratchy pass that breaks up along its length, over a fill the mask has worn nearly through in patches.
+
+Open the Sketchstyle view in the editor, move whatever you like, and Save writes your dials to a file. Saving over a shipped look writes a local copy that shadows it; delete the copy and the shipped file returns, the same way presets work.
+
+A theme carries a sketchstyle of its own, so a look travels with the theme that uses it.
+
+### Ship the layer with your site
+
+The dev server reads the open theme and paints what it carries. A built site has no server to ask, so hand it the field before mounting:
+
+```ts
+import { seedSketchFromTheme } from '@motion-proto/live-tokens/sketch';
+import theme from './live-tokens/data/themes/sketchy.json';
+
+seedSketchFromTheme(theme.sketchStyle);
+await bootLiveTokens(App, '#app');
+```
+
+Register your own sketchstyles at boot the way you register components:
+
+```ts
+const files = import.meta.glob('./live-tokens/data/sketch-styles/*.json', {
+  eager: true,
+  import: 'default',
+});
+
+await bootLiveTokens(App, '#app', {
+  sketchLooks: Object.entries(files).map(([path, file]) => {
+    const id = path.split('/').pop().replace('.json', '');
+    return { id, label: file.name || id, settings: file.settings };
+  }),
+});
+```
+
+The file's slug is the look's id, so a sketchstyle picked in the editor keeps working once the site is built. `create` writes this into `main.ts` already.
+
+### Build a picker
+
+`sketchLooks` is a store holding every look on offer, shipped and your own in one list. Give each row `setSketch(look.id)`, and add a None row yourself: off is a state of the effect rather than one of the looks. `themeSketchLook` carries the theme's own look as one more row, and reads null when the theme carries none.
+
+### Draw your own elements
+
+The layer redraws the shipped components and four classes it reserves for you: `sketch-surface` for a box, `sketch-container` for a large one, `sketch-chip` for a small one, and `sketch-rule` for a line. Pick by size, not by kind. The class opts an element in but names no colors, so state them yourself with `--sketch-fill`, `--sketch-stroke`, and `--sketch-radius`. The in-app guide at `/live-tokens/docs` covers every dial and the rules for images and icons.
+
 ## CLI
 
 ```bash
@@ -348,13 +405,13 @@ npx @motion-proto/live-tokens check-component <id>
 
 The validator checks the file layout, the `:global(:root)` block, the token-suffix vocabulary, the state-before-property rule, the no-raw-color-defaults rule, the public-imports rule, and the `registerComponent({ id })` call. Exit code 0 means the static contract is met. Use it after Claude generates a component, and as a pre-commit guard on hand-authored ones.
 
-## How the editor ships changes to production
+## From edit to production
 
 1. Edit on `/live-tokens/editor`, `/live-tokens/colors`, or `/live-tokens/components`. Edits sit in the working buffer (`_working.json`). **Save** in the Theme panel captures the buffer into the open theme at `<dataDir>/themes/{name}.json`.
 2. **Adopt** the theme. It becomes the production theme, and its variables are baked into `tokens.generated.css` next to your authored `tokens.css`. Nothing else writes that file, so trying a look never changes what you ship.
 3. `npm run build` bundles both as plain CSS. No editor code, no JSON lookups, no dev surfaces reach production.
 
-## File ownership: what the plugin writes
+## File ownership
 
 Knowing which files the plugin touches matters when you upgrade the package or work in a repo you do not want overwritten. For how a saved look stays safe across upgrades while `tokens.css` holds the building blocks, see [TOKENS.md](./TOKENS.md).
 
@@ -377,6 +434,7 @@ Knowing which files the plugin touches matters when you upgrade the package or w
 - `<dataDir>/colors-and-type/_working.json` and `<dataDir>/component-configs/{comp}/_working.json`, the buffers, written as you edit and cleared when a theme you open does not carry them.
 - `<dataDir>/themes/{name}.json`, on every Save and Save As in the Theme panel.
 - `<dataDir>/colors-and-type/{name}.json` and `<dataDir>/component-configs/{comp}/{name}.json`, only when you save a preset by name.
+- `<dataDir>/sketch-styles/{name}.json`, on every Save and Save As in the Sketchstyle view. Saving over a shipped look writes this project's own copy under the same name; deleting it restores the shipped file.
 - `tokens.generated.css` and `fonts.css`, regenerated from the production theme when you Adopt.
 
 The plugin never writes your authored `tokens.css`. It holds defaults you are free to hand-edit, and the editor's overrides land in `tokens.generated.css`, which the app imports immediately after it.