@motion-proto/live-tokens 0.50.0 → 0.53.0

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

@@ -54,7 +54,13 @@ Magnitude words: "slightly" or "a bit" is 1 step, unqualified is 1 to 2, "much",
 
 ## 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.
+
+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
 

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # Changelog
 
+## 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
+
+- **The Notification editor can show a header action.** The four
+  `--notification-*-action-surface` tokens paint the backdrop behind a
+  header-slot button, and no preview ever rendered one, so nothing in the
+  editor could show what they do. A "Header button" checkbox in the preview
+  toolbar turns the slot on.
+
+## 0.52.0 — A third palette curve
+
+### Added
+
+- **Palettes gain a third curve, for hue.** Alongside Saturation and
+  Lightness, a Hue curve offsets each step by up to ±45 degrees, so a
+  palette can drift warmer or cooler across its ramp without moving
+  contrast. OKLCH keeps hue rotation close to lightness-preserving, which
+  makes that possible. The curve is closed by default, and existing
+  themes are unaffected: an absent hue curve renders as flat zero, exactly
+  as before.
+
+## 0.51.0 — OKLCH end to end
+
+### Changed (breaking)
+
+- **Color tokens are written as `oklch()`, not hex.** The editor already
+  stored, edited, and computed color in OKLCH; only the final CSS string was
+  hex, which quantized every value to 8 bits on the way out. Derived colors now
+  serialize as `oklch()` in the live `:root` and in `tokens.generated.css`, and
+  `tokens.css` ships its 283 primitives in the same form. Values are still
+  clamped into the sRGB gamut before serialization, so nothing changes color.
+  Hex remains the readout and text-field format in the editor, and is still
+  what you copy out.
+
+  This sets a browser floor of Chrome 111, Safari 15.4, and Firefox 113
+  (2023). Run `npx live-tokens migrate` to convert a vendored `tokens.css`; the
+  transform is idempotent and touches values only, never names. Because it
+  rewrites values rather than renaming them, it never auto-applies — the dev
+  plugin will not touch your file.
+
+  Any code of your own that parses these tokens as hex needs updating. Inside
+  the package, the generator's contrast gate, the Color Story readouts, and the
+  runtime background-contrast picker were the three such readers.
+
 ## 0.50.0 — Live editing stays in sync
 
 ### Added

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