@motion-proto/live-tokens 0.52.1 → 0.54.0

package/.claude/skills/live-tokens-adjust-shape-space/SKILL.md

@@ -11,7 +11,7 @@ You translate the request into a small ops file; the CLI resolves each matching
 
 1. Write the ops file to a temp path (not the project tree), e.g. `/tmp/adjust-ops.json`.
 2. Run `npx live-tokens adjust /tmp/adjust-ops.json`. It writes `component-configs/<id>/_working.json` for every component the ops change, which is the buffer the page already runs. `--dry-run` prints the report without writing.
-3. Read the report card: every changed alias old → new, plus skips (raw value, off the ladder, already at the ladder end, pill preserved). Exit 1 means the run was rejected; the message names the offending op or the missing input, so fix it and re-run.
+3. Read the report card: every changed alias old → new, plus skips (raw value, off the ladder, already at the ladder end, pill preserved). Exit 1 means the run was rejected; the message names the offending op or the missing input, so fix it and re-run. Read where the controls landed, not only that the run succeeded: a button, badge, input, or tab padding sitting at `--space-6` is on its floor, and one that also carries `--radius-full` wants a targeted lift.
 4. Tell the user to reload the app and look. Offer the inverse op as the undo, and say the edit is unsaved until they save the open theme.
 
 Each run reads the LIVE config (buffer, else the open theme, else the shipped default), so "a bit more" and "back one" compound naturally.
@@ -40,7 +40,7 @@ Targeted, absolute:
 
 | Request | Ops |
 |---|---|
-| pill, capsule | radius `set: "--radius-full"` |
+| pill, capsule | radius `set: "--radius-full"`, plus the padding the pill needs (see below) |
 | sharp, square corners | radius `set: "--radius-none"`, or `--radius-sm` for "mostly sharp" |
 | rounded (a named component) | radius `shift: 2` |
 | softer, rounder (global) | radius `shift: 1` to `2`, no `full` |
@@ -52,9 +52,33 @@ Targeted, absolute:
 
 Magnitude words: "slightly" or "a bit" is 1 step, unqualified is 1 to 2, "much", "way", or "really" is 2 to 3. Mood words often mean both axes: "softer" is rounder plus airier, "compact" is tighter padding plus smaller gaps.
 
+## Controls squeeze before containers
+
+A global op spends the same number of steps everywhere, but a step costs a control far more than a container. `padding shift: -2` takes a card from a 16px inset to 10px and it is still a card. It takes a button from 8 to 4, doubled to 8px at each end, around an 18px line. The button stops reading as a button.
+
+So a global compaction is `shift: -1`. When the brief wants more, spend the extra steps on the containers by name (`card`, `dialog`, `panel`, `sidenavigation`, `table`, `codesnippet`) and leave the controls alone. Loosening is not symmetric: airier is safe globally, because nothing breaks by growing.
+
+A pill needs the room most. `--radius-full` bends the corner in over the first and last glyph, so a capsule wants more horizontal inset than a square-cornered control, never less. `--space-8` is the floor for a large-text pill, which is where compact Midnight Study sits; the roomier pill presets (Ocean, Sunset, Royal Velvet) run `--space-10` to `--space-12`. Pair the radius op with a padding `set` on the same target, placed after any global compaction so it wins outright:
+
+```json
+{ "ops": [
+  { "kind": "padding", "shift": -1 },
+  { "target": "button", "kind": "radius", "set": "--radius-full" },
+  { "target": "button", "kind": "padding", "set": "--space-10" }
+] }
+```
+
 ## Ladders
 
-Radius runs `none, sm, md, lg, xl, 2xl, 3xl, 4xl`, with `full` as the gated ninth rung. Space (padding and gap) is the editor picker's subset: `0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 48`, so every written value stays re-editable by hand. Border width is the full `--border-width-*` scale. `set` values must be on the ladder (`--space-64` is rejected); an alias sitting off the subset snaps to the nearest rung when shifted, and the report marks a snap that lands against the requested direction.
+Radius runs `none, sm, md, lg, xl, 2xl, 3xl, 4xl`, with `full` as the gated ninth rung. Space (padding and gap) is the editor picker's subset: `0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 48`, so every written value stays re-editable by hand. Border width is the full `--border-width-*` scale. `set` values must be on the ladder (`--space-64` is rejected).
+
+Content insets stop at `--space-4`. Below it the text sits against its own edge, so `--space-0` and `--space-2` are destinations a person picks on purpose, not ones a relative "tighter" hands you. Both stay available through the editor picker and through `set`. An alias already below the floor still moves up, and a shift that would push one under `--space-4` reports as clamped and writes nothing.
+
+Padding that wraps a line of type stops a rung higher, at `--space-6`. The engine spots it in the config itself: a variant that also declares a `-text-font-size` is holding text, and the components that hold text double their padding horizontally, so `--space-4` there is 4px over an 18px line and 8px at each end. No shipped default puts text below `--space-6`.
+
+The floor guards `-padding` only. Outer space is exempt, because a 2px gap between an icon and its label, or a 2px margin under a bar, is ordinary design rather than a mistake. Note that `-margin` rides the `padding` kind, so a padding op moves margins too; it just does not floor them.
+
+An alias sitting off the subset spends its first step reaching the rung the shift points at, so `--space-2` with `shift: 1` lands on `--space-4` rather than jumping past it.
 
 ## Scope
 
@@ -64,5 +88,6 @@ Every value written is an existing token; nothing new is minted. `tokens.css`, s
 
 - The CLI exits 0 and the report card lists the changes you expected, with no surprising skips.
 - The app (dev server running) shows the new shape on each changed component after a reload.
+- Buttons still read as buttons: the label has room at both ends, and a pill has more of it than a square-cornered control had.
 - `component-configs/<id>/_working.json` exists for every component the report listed. That buffer is the whole change: it stays until the open theme is saved or another theme is loaded.
 - To revert, run the inverse ops, or load a theme in the Theme panel to discard every unsaved edit.

package/.claude/skills/live-tokens-generate-theme/SKILL.md

@@ -130,6 +130,21 @@ A sky needs a committed canvas: when the Canvas seed anchors at the ramp edge
 side and the engine skips the sky, saying so in the report. An atmospheric
 brief that wants one should already be at canvas commitment level 2–3.
 
+## Shadow weight follows the canvas
+
+The engine sets the opacity of the `--shadow-*` scale from the Canvas seed's
+lightness and carries each shadow's geometry and color through untouched. A
+near-black shadow at 0.9 opacity is what a dark ground needs to show any
+shadow at all, and it punches a hole in paper, so opacity holds at 0.9 up to
+canvas L 0.5 and eases to 0.2 by L 0.9. There is nothing to choose: the report
+prints the derived value, and every regeneration re-derives it, so a brief
+iterated from a light canvas to a dark one gets its weight back.
+
+When the user says the shadows read heavy, muddy, or dirty, the canvas is the
+lever. Raise the Canvas seed's lightness and the shadows lighten with it. A
+one-off override lives in the editor's Shadows tab and survives regeneration
+in everything except opacity.
+
 ## Named themes (canonical OKLCH anchors)
 
 Holiday briefs are statement briefs — default to commitment level 2–3 above, not cream. The named colors go on the *ground*, not just the buttons.
@@ -143,7 +158,7 @@ Holiday briefs are statement briefs — default to commitment level 2–3 above,
 
 ## Scope
 
-Fonts are never touched (they carry forward from the live look, as do shadows and component aliases). Swatch gradients (`--gradient-1..4`) carry forward when user-tuned; if they are absent or still stock, the engine rebuilds them from the new theme's families — you never author them. Radius is out of scope for generation. Shipping the theme stays a human action: Adopt, in the editor.
+Fonts are never touched (they carry forward from the live look, as do component aliases and shadow geometry; shadow opacity is derived, see above). Swatch gradients (`--gradient-1..4`) carry forward when user-tuned; if they are absent or still stock, the engine rebuilds them from the new theme's families — you never author them. Radius is out of scope for generation. Shipping the theme stays a human action: Adopt, in the editor.
 
 ## Verify
 

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## 0.54.0 — Shadow weight and text insets follow their context
+
+### Fixed
+
+- **Padding that holds text stops at `--space-6`.** One floor for every inset
+  treated a card and a button alike, but the components that hold text double
+  their padding horizontally, so `--space-4` on a button is 4px over an 18px
+  line and 8px at each end. `adjust` now reads which floor applies off the
+  config itself: a variant that also declares a `-text-font-size` is holding
+  type. Containers keep the `--space-4` floor, `-margin` and `-gap` stay
+  exempt, and both rungs stay reachable by `set` and by the editor picker.
+  Midnight Study shipped with every text inset on the old floor, its pill
+  buttons worst of all; its controls move up, and the six full-size button
+  variants to `--space-8` so the capsule has room for its label.
+
+### Changed
+
+- **Shadow weight follows the canvas.** The `--shadow-*` scale was one fixed
+  near-black at 0.9 opacity in every theme, which is what a dark ground needs
+  and what puts a smudge under every card on a light one. `generate-theme` now
+  derives the opacity from the Canvas seed's lightness: 0.9 holds up to L 0.5
+  and eases to 0.2 by L 0.9. Geometry and color carry forward untouched, so a
+  hand-tuned elevation ramp survives regeneration. The three light presets
+  (Ocean, Spring Meadow, Autumn) ship with the derived values; the dark presets
+  and the default theme are unchanged.
+
+## 0.53.0 — Themes are complete documents
+
+### Fixed
+
+- **The editor no longer imports build tooling.** `themeService.ts` and
+  `themeTypes.ts` read `THEME_SCHEMA_VERSION` from
+  `vite-plugin/themes/normalizeTheme`, a path that resolves in this repository
+  and in no installed copy, because the tarball ships no tooling. Any consumer
+  building the editor failed on an unresolved import. The constant now lives in
+  `themeTypes.ts` and the plugin re-exports it. `check:no-tooling-imports`
+  gates the direction.
+
+### Changed
+
+- **Content insets stop at `--space-4`.** Below it the text sits against its
+  own edge, so a relative "tighter" no longer deposits a `-padding` alias on
+  `--space-0` or `--space-2`. Both stay available in the editor picker and
+  through an explicit `set` op, which is where that call belongs. A shift that
+  would push an alias under the floor reports as clamped and writes nothing.
+  Outer space is exempt: a 2px gap between an icon and its label, or a 2px
+  margin under a bar, is ordinary design.
+
+- **An off-ladder value spends its first step reaching the ladder.** Shifting
+  such a value used to snap it to the nearest rung and then apply the full
+  shift on top, so a one-step request moved two visible steps, and an
+  above-ladder value could be quietly pulled *down* by a request to go up.
+  The snap now follows the shift's direction and counts as its opening step.
+  This retires the report card's `!` marker, which existed only to flag that
+  backwards case.
+
+- **Themes are complete documents.** A theme now stores every component and
+  every alias, by value, at `schemaVersion` 4. Boot migrates and fills a
+  local theme once; an incomplete imported theme still loads with whatever
+  components it carries, filled from the current defaults, and the fill is
+  reported in the Theme panel. The preset generator that re-derived the
+  seven shipped presets on every run is gone. `seed-preset-theme.mjs <slug>`
+  seeds a new preset once and `check:preset-themes` guards the shipped seven
+  against drift.
+
+### Fixed
+
+- **`generate-theme` no longer inherits gaps from an incomplete open theme.**
+  The live resolution path gained the missing default layer, so a theme
+  missing a component no longer leaves the generator working from a hole.
+- **A pre-rename alias key in an old theme is migrated before the bake**,
+  instead of being emitted verbatim into `tokens.generated.css`.
+- **A component's gradient default survives a fresh checkout.** The dev
+  server derives `component-configs/<comp>/default.json` from the component's
+  `:global(:root)` block, and it could not read a baked gradient back. On a
+  tree with no prior file it dropped the alias. It now parses the gradient
+  into its structured form, so the derivation covers every value the bake
+  emits.
+- **A radial gradient bakes the shape the editor shows.** The production bake
+  carried its own copy of the gradient renderer, which ignored the centre and
+  both aspect factors and wrote `circle … at center` for every radial. Both
+  sides now share one renderer.
+- **The shipped `panel` aliases sit in derivation order.** `Panel.svelte`
+  declares `--panel-stage-surface` before the stage spacing, but every
+  committed copy carried it last. On a fresh checkout, where the component
+  source is newer than the data tree, boot re-derived `default.json` into
+  source order while the seven presets kept the old one, and the preset gate
+  read two different key orders. The committed data now matches the source.
+
 ## 0.52.1 — Notification header actions are previewable
 
 ### Fixed

package/bin/adjust.mjs

@@ -18,7 +18,6 @@ const packageThemesDir = join(pkgRoot, 'src/live-tokens/data/themes');
 const SOURCE_LABELS = {
   working: 'your unsaved edits',
   theme: 'the open theme',
-  default: 'the shipped default',
 };
 
 const SKIP_LABELS = [
@@ -46,35 +45,6 @@ function readJsonIfExists(path) {
   return existsSync(path) ? readJson(path) : null;
 }
 
-function numericRung(token) {
-  const match = /-(\d+)$/.exec(token);
-  return match ? Number(match[1]) : null;
-}
-
-/** Net direction the ops asked for on this alias. An explicit `set` owns the
- *  value outright, so it reports no direction. */
-function requestedDirection(ops, matchesKind, component, variable) {
-  let total = 0;
-  for (const op of ops) {
-    if (op.target !== undefined && op.target !== component) continue;
-    if (!matchesKind(variable, op.kind)) continue;
-    if (op.shift === undefined) return 0;
-    total += op.shift;
-  }
-  return Math.sign(total);
-}
-
-/** A shift can land below where it started: an off-subset value (`--space-64`)
- *  snaps to its nearest writable rung first. Those changes are marked, never
- *  listed as an ordinary shift. */
-function opposesShift(ops, matchesKind, component, change) {
-  const from = numericRung(change.from);
-  const to = numericRung(change.to);
-  if (from === null || to === null) return false;
-  const direction = requestedDirection(ops, matchesKind, component, change.variable);
-  return direction !== 0 && Math.sign(to - from) !== direction;
-}
-
 /** Successive ops can touch the same alias (soften, then pill the buttons);
  *  the report shows one entry per alias, first `from` to last `to`. */
 function collapseChanges(changes) {
@@ -98,9 +68,11 @@ function readActiveTheme(themesDir) {
   return theme ? { slug, theme } : null;
 }
 
-/** Each component's live config and where it came from: the buffer, else the
- *  open theme's embedded copy, else the shipped default. Mirrors the dev
- *  server's `resolveLiveComponentConfig`, so the CLI adjusts what the page runs. */
+/** Each component's live config, and whether a buffer or the open document
+ *  answered. The document's own copy falls back to the shipped default for a
+ *  component it somehow lacks, which reports as the document either way.
+ *  Mirrors the dev server's `resolveLiveComponentConfig`, so the CLI adjusts
+ *  what the page runs. */
 function readLiveConfigs(dir, active) {
   const configs = {};
   const sources = {};
@@ -109,13 +81,19 @@ function readLiveConfigs(dir, active) {
     const comp = entry.name;
     const componentDir = join(dir, comp);
     const working = readJsonIfExists(join(componentDir, '_working.json'));
-    const embedded = active?.theme?.componentConfigs?.[comp];
-    const config = working ?? embedded ?? readJsonIfExists(join(componentDir, 'default.json'));
+    // Every theme carries every component by value, but this CLI reads the
+    // file straight off disk, ahead of any server-side fill — a theme
+    // written before this component existed can still omit it, so a missing
+    // entry falls back to the shipped default the same way the theme's own
+    // fill would.
+    const embedded =
+      active?.theme?.componentConfigs?.[comp] ?? readJsonIfExists(join(componentDir, 'default.json'));
+    const config = working ?? embedded;
     if (!config) {
       throw new Error(`component "${comp}": default.json is missing`);
     }
     configs[comp] = { ...config, component: comp };
-    sources[comp] = working ? 'working' : embedded ? 'theme' : 'default';
+    sources[comp] = working ? 'working' : 'theme';
   }
   return { configs, sources };
 }
@@ -173,7 +151,7 @@ export async function runAdjust({
     components.push({
       component,
       source: sources[component],
-      changes: changes.map((c) => ({ ...c, snapped: opposesShift(ops, matchesKind, component, c) })),
+      changes,
       skips,
     });
   }
@@ -228,8 +206,7 @@ export function formatAdjustResult(result) {
 
     const width = Math.max(0, ...entry.changes.map((c) => c.variable.length));
     for (const c of entry.changes) {
-      const note = c.snapped ? '   ← snapped to the nearest editor rung, against the requested shift' : '';
-      lines.push(`  ${c.snapped ? '!' : ' '} ${c.variable.padEnd(width)}  ${c.from} → ${c.to}${note}`);
+      lines.push(`    ${c.variable.padEnd(width)}  ${c.from} → ${c.to}`);
     }
 
     for (const [reason, label] of SKIP_LABELS) {

package/bin/generate-theme.mjs

@@ -21,7 +21,9 @@ import { fileURLToPath } from 'node:url';
 const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const ENGINE = resolve(pkgRoot, 'dist-plugin/generateColorsAndType/index.js');
 const packageDataDir = join(pkgRoot, 'src/live-tokens/data');
-const THEME_SCHEMA_VERSION = 3;
+// Source of truth: vite-plugin/themes/normalizeTheme.ts. This copy cannot
+// import TS, so `check:preset-themes` (Wave 5) is what catches a drift.
+const THEME_SCHEMA_VERSION = 4;
 
 async function loadEngine() {
   if (!existsSync(ENGINE)) {
@@ -69,11 +71,18 @@ function stripMarkers(value) {
   return rest;
 }
 
+/** A component's derived default, local tree first, then the installed
+ *  package's shipped copy — same fallback order every other read here uses. */
+function defaultComponentConfig(componentConfigsDir, comp) {
+  return readData(join(componentConfigsDir, comp), `component-configs/${comp}`, 'default');
+}
+
 /**
  * The look the new theme carries forward. Without --carry-from that is the LIVE
  * state — buffer first, then the open theme, then the shipped default — because
  * what the user sees is what they expect to keep. With it, the named theme,
- * read by value.
+ * then the shipped default for anything that theme omits, so an incomplete
+ * source never produces an incomplete result.
  */
 function resolveCarrySource({ carryFrom, colorsAndTypeDir, componentConfigsDir, themesDir }) {
   const comps = componentNames(componentConfigsDir);
@@ -83,7 +92,7 @@ function resolveCarrySource({ carryFrom, colorsAndTypeDir, componentConfigsDir,
     if (!theme) throw new Error(`--carry-from theme "${carryFrom}" not found`);
     const componentConfigs = {};
     for (const comp of comps) {
-      const cfg = theme.componentConfigs?.[comp];
+      const cfg = theme.componentConfigs?.[comp] ?? defaultComponentConfig(componentConfigsDir, comp);
       if (cfg) componentConfigs[comp] = stripMarkers(cfg);
     }
     return { colorsAndType: stripMarkers(theme.colorsAndType), componentConfigs };
@@ -98,12 +107,15 @@ function resolveCarrySource({ carryFrom, colorsAndTypeDir, componentConfigsDir,
   );
 
   // A working buffer is an unsaved delta from the active theme; absent theme
-  // component entries fall through to the component defaults.
+  // component entries fall through to the component defaults. Mirrors
+  // `bin/adjust.mjs`'s `readLiveConfigs` and the dev server's
+  // `resolveLiveComponentConfig` — all three layers, in the same order.
   const componentConfigs = {};
   for (const comp of comps) {
     const live =
       readJsonIfExists(join(componentConfigsDir, comp, '_working.json')) ??
-      activeTheme?.componentConfigs?.[comp];
+      activeTheme?.componentConfigs?.[comp] ??
+      defaultComponentConfig(componentConfigsDir, comp);
     if (live) componentConfigs[comp] = stripMarkers(live);
   }
   return { colorsAndType, componentConfigs };
@@ -121,7 +133,8 @@ export async function runGenerateTheme({
   themesDir,
   engine,
 } = {}) {
-  const { buildColorsAndTypeFromSeeds, resolveDataDirs } = engine ?? (await loadEngine());
+  const { buildColorsAndTypeFromSeeds, resolveDataDirs, CURRENT_COMPONENT_SCHEMA_VERSION } =
+    engine ?? (await loadEngine());
 
   const briefFull = resolve(root, briefPath);
   if (!existsSync(briefFull)) {
@@ -162,6 +175,7 @@ export async function runGenerateTheme({
     schemaVersion: THEME_SCHEMA_VERSION,
     colorsAndType,
     componentConfigs: carry.componentConfigs,
+    componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
   };
 
   if (!dryRun) {
@@ -227,6 +241,7 @@ export function formatGenerateThemeResult(result) {
       ? '\nGradients: kept your tuned swatch gradients.'
       : '\nGradients: swatch tokens rebuilt from the theme families.',
   );
+  lines.push(`Shadows: ${result.report.shadows}; carried geometry kept.`);
   if (result.report.canvasGradient) {
     lines.push(`Canvas sky: ${result.report.canvasGradient}.`);
   }