@motion-proto/live-tokens 0.38.0 → 0.40.0

package/src/editor/core/palettes/paletteDerivation.ts

@@ -17,14 +17,14 @@ import { hexToOklch, oklchToHex, gamutClamp } from './oklch';
 import { type CurveAnchor, sampleCurve, makeAnchor } from '../../ui/curveEngine';
 import type { PaletteConfig } from '../themes/themeTypes';
 
-export type PaletteMode = 'chromatic' | 'gray';
-
 export interface PaletteSpec {
   label: string;
   cssNamespace: string;
-  mode: PaletteMode;
   emptySelector?: boolean;
   initialColor: string;
+  /** Seed-default role only: neutrals start with a calm low-chroma base and
+   *  the neutral lightness ramp. The derivation path is identical for all. */
+  neutral?: boolean;
 }
 
 /**
@@ -33,16 +33,16 @@ export interface PaletteSpec {
  * here lets the store seed boot-time vars without depending on the UI tree.
  */
 export const PALETTE_SPECS: readonly PaletteSpec[] = [
-  { label: 'Neutral',    cssNamespace: 'neutral',   mode: 'gray',      initialColor: '#808080' },
-  { label: 'Alternate',  cssNamespace: 'alternate', mode: 'gray',      initialColor: '#808080' },
-  { label: 'Background', cssNamespace: 'canvas',    mode: 'chromatic', emptySelector: true, initialColor: '#1a1a2e' },
-  { label: 'Brand',      cssNamespace: 'brand',     mode: 'chromatic', initialColor: '#c93636' },
-  { label: 'Accent',     cssNamespace: 'accent',    mode: 'chromatic', initialColor: '#f49e0b' },
-  { label: 'Special',    cssNamespace: 'special',   mode: 'chromatic', initialColor: '#8b5cf6' },
-  { label: 'Info',       cssNamespace: 'info',      mode: 'chromatic', initialColor: '#3077e8' },
-  { label: 'Success',    cssNamespace: 'success',   mode: 'chromatic', initialColor: '#21c45d' },
-  { label: 'Warning',    cssNamespace: 'warning',   mode: 'chromatic', initialColor: '#e66e1a' },
-  { label: 'Danger',     cssNamespace: 'danger',    mode: 'chromatic', initialColor: '#e8304f' },
+  { label: 'Neutral',    cssNamespace: 'neutral',   neutral: true, initialColor: '#70787e' },
+  { label: 'Alternate',  cssNamespace: 'alternate', neutral: true, initialColor: '#817b78' },
+  { label: 'Background', cssNamespace: 'canvas',    emptySelector: true, initialColor: '#1a1a2e' },
+  { label: 'Brand',      cssNamespace: 'brand',     initialColor: '#c93636' },
+  { label: 'Accent',     cssNamespace: 'accent',    initialColor: '#f49e0b' },
+  { label: 'Special',    cssNamespace: 'special',   initialColor: '#8b5cf6' },
+  { label: 'Info',       cssNamespace: 'info',      initialColor: '#3077e8' },
+  { label: 'Success',    cssNamespace: 'success',   initialColor: '#21c45d' },
+  { label: 'Warning',    cssNamespace: 'warning',   initialColor: '#e66e1a' },
+  { label: 'Danger',     cssNamespace: 'danger',    initialColor: '#e8304f' },
 ] as const;
 
 const PALETTE_STEPS = [
@@ -51,12 +51,6 @@ const PALETTE_STEPS = [
   { label: '850' }, { label: '900' }, { label: '950' },
 ];
 
-const GRAY_STEPS = [
-  { label: '100' }, { label: '200' }, { label: '300' }, { label: '400' },
-  { label: '500' }, { label: '600' }, { label: '700' }, { label: '800' },
-  { label: '850' }, { label: '900' }, { label: '950' },
-];
-
 interface ScaleStep { name: string; position: number; }
 interface Scale { title: string; isText: boolean; steps: ScaleStep[]; }
 
@@ -97,9 +91,6 @@ const SCALES: readonly Scale[] = [
 
 export const DEFAULT_PALETTE_LIGHTNESS = (): CurveAnchor[] => [makeAnchor(0, 95, 5), makeAnchor(100, 8, 5)];
 export const DEFAULT_PALETTE_SATURATION = (): CurveAnchor[] => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)];
-export const DEFAULT_GRAY_LIGHTNESS = (): CurveAnchor[] => [makeAnchor(0, 92, 5), makeAnchor(100, 3, 5)];
-export const DEFAULT_GRAY_SATURATION = (): CurveAnchor[] => [makeAnchor(0, 20, 30), makeAnchor(100, 20, 30)];
-export const DEFAULT_TINT_CHROMA = 0.04;
 
 export const defaultScaleCurves = {
   Surfaces: {
@@ -117,7 +108,6 @@ export const defaultScaleCurves = {
 } as const;
 
 function paletteStepKey(label: string): string { return `Palette-${label}`; }
-function grayStepKey(label: string): string { return `gray-${label}`; }
 function stepKey(scaleTitle: string, stepName: string): string { return `${scaleTitle}-${stepName}`; }
 
 function stepIndexToX(index: number, total: number): number {
@@ -140,24 +130,6 @@ function computePaletteColor(
   return oklchToHex(clamped.l, clamped.c, clamped.h);
 }
 
-function computeGrayColor(
-  index: number,
-  hue: number,
-  chroma: number,
-  grayLightnessCurve: CurveAnchor[],
-  graySaturationCurve: CurveAnchor[],
-  curveOffset: Record<string, number>,
-): string {
-  const xPos = stepIndexToX(index, GRAY_STEPS.length);
-  const lOff = curveOffset['gray-lightness'] ?? 0;
-  const sOff = curveOffset['gray-saturation'] ?? 0;
-  const targetL = Math.max(0, Math.min(100, sampleCurve(grayLightnessCurve, xPos) + lOff)) / 100;
-  const satMul = Math.max(0, Math.min(2, (sampleCurve(graySaturationCurve, xPos) + sOff) / 100));
-  const targetC = chroma * satMul;
-  const clamped = gamutClamp(targetL, targetC, hue);
-  return oklchToHex(clamped.l, clamped.c, clamped.h);
-}
-
 function computeDerivedColor(
   step: ScaleStep,
   base: string,
@@ -212,43 +184,22 @@ export function derivePaletteVars(spec: PaletteSpec, config: PaletteConfig | und
   const overrides = config.overrides ?? {};
   const curveOffset = config.curveOffset ?? {};
   const scaleCurves = config.scaleCurves ?? {};
+  const lightnessCurve = config.lightnessCurve ?? DEFAULT_PALETTE_LIGHTNESS();
+  const saturationCurve = config.saturationCurve ?? DEFAULT_PALETTE_SATURATION();
 
-  let baseForScales: string;
-
-  if (spec.mode === 'gray') {
-    const grayLightnessCurve = config.grayLightnessCurve ?? DEFAULT_GRAY_LIGHTNESS();
-    const graySaturationCurve = config.graySaturationCurve ?? DEFAULT_GRAY_SATURATION();
-    const tintHue = config.tintHue ?? 240;
-    const tintChroma = config.tintChroma ?? DEFAULT_TINT_CHROMA;
-
-    let gray500 = '#808080';
-    GRAY_STEPS.forEach((step, index) => {
-      const k = grayStepKey(step.label);
-      const hex = computeGrayColor(index, tintHue, tintChroma, grayLightnessCurve, graySaturationCurve, curveOffset);
-      const effective = (k in overrides) ? overrides[k] : hex;
-      out[`--color-${spec.cssNamespace}-${step.label}`] = effective;
-      if (step.label === '500') gray500 = hex;
-    });
-    baseForScales = gray500;
-  } else {
-    const lightnessCurve = config.lightnessCurve ?? DEFAULT_PALETTE_LIGHTNESS();
-    const saturationCurve = config.saturationCurve ?? DEFAULT_PALETTE_SATURATION();
-
-    PALETTE_STEPS.forEach((ps, index) => {
-      const k = paletteStepKey(ps.label);
-      const hex = computePaletteColor(index, baseColor, lightnessCurve, saturationCurve, curveOffset);
-      const effective = (k in overrides) ? overrides[k] : hex;
-      out[`--color-${spec.cssNamespace}-${ps.label}`] = effective;
-    });
-    baseForScales = baseColor;
-  }
+  PALETTE_STEPS.forEach((ps, index) => {
+    const k = paletteStepKey(ps.label);
+    const hex = computePaletteColor(index, baseColor, lightnessCurve, saturationCurve, curveOffset);
+    const effective = (k in overrides) ? overrides[k] : hex;
+    out[`--color-${spec.cssNamespace}-${ps.label}`] = effective;
+  });
 
   for (const scale of SCALES) {
     for (const step of scale.steps) {
       const k = stepKey(scale.title, step.name);
       const hex = (k in overrides)
         ? overrides[k]
-        : computeDerivedColor(step, baseForScales, scale.title, scaleCurves, curveOffset);
+        : computeDerivedColor(step, baseColor, scale.title, scaleCurves, curveOffset);
       const varName = scaleToCssVar(scale.title, step.name, spec.cssNamespace);
       if (varName) out[varName] = hex;
     }
@@ -307,12 +258,11 @@ const HEX_RE = /^#[0-9a-f]{6}$/i;
  *
  *   - **Snap** (gated by `_imported`): for any palette whose `_imported` flag
  *     is true, the imported `--color-{ns}-500` value is treated as the
- *     authoritative anchor. Chromatic palettes get `baseColor` snapped to it;
- *     gray palettes (Neutral/Alternate) get `tintHue` + `tintChroma` derived
- *     from it via OKLCH. The flag is then cleared. Editor-authored palettes
- *     (no `_imported`) are left untouched — see `temp/manifest-robustness-plan.md`
- *     §9 for why "snap on any divergence" was wrong: it would have flipped
- *     `themes/default.json`'s accent from teal to olive on first read.
+ *     authoritative anchor and `baseColor` is snapped to it. The flag is then
+ *     cleared. Editor-authored palettes (no `_imported`) are left untouched —
+ *     see `temp/manifest-robustness-plan.md` §9 for why "snap on any
+ *     divergence" was wrong: it would have flipped `themes/default.json`'s
+ *     accent from teal to olive on first read.
  *
  *   - **Consume** (always): every variable the palette's derivation produces
  *     is reported in `consumed` so the caller can strip it from
@@ -345,12 +295,7 @@ export function reconcilePalettesFromCssVars(
       const anchorHex = cssVars[`--color-${spec.cssNamespace}-500`];
       if (anchorHex && HEX_RE.test(anchorHex.trim())) {
         const hex = anchorHex.trim();
-        if (spec.mode === 'gray') {
-          const { c, h } = hexToOklch(hex);
-          next[spec.label] = { ...current, tintHue: h, tintChroma: c, _imported: false };
-        } else {
-          next[spec.label] = { ...current, baseColor: hex, _imported: false };
-        }
+        next[spec.label] = { ...current, baseColor: hex, _imported: false };
         snapped.add(spec.label);
       } else {
         // No anchor in cssVariables to snap to — flag has nothing to do; clear

package/src/editor/core/store/editorStore.ts

@@ -28,6 +28,7 @@ import {
   runMigrations,
 } from '../themes/migrations';
 import { renamePrimaryPaletteKey } from '../themes/migrations/2026-05-13-primary-to-brand';
+import { unifyGrayPalettes } from '../themes/migrations/2026-06-05-palette-unification';
 import { __resetRendererCacheForTests, installRenderer } from './editorRenderer';
 import {
   store,
@@ -511,7 +512,7 @@ const domainLoaders: Record<string, DomainLoader> = {
  */
 export function loadFromFile(theme: Theme): void {
   const next = emptyState();
-  next.palettes = renamePrimaryPaletteKey(structuredClone(theme.editorConfigs ?? {}));
+  next.palettes = unifyGrayPalettes(renamePrimaryPaletteKey(structuredClone(theme.editorConfigs ?? {})));
   next.fonts.sources = structuredClone(theme.fontSources ?? []);
   next.fonts.stacks  = structuredClone(theme.fontStacks  ?? []);
   const rawVars = runMigrations(

package/src/editor/core/store/gradientSource.ts

@@ -84,6 +84,31 @@ function readComponentGradient(component: string, varName: string): GradientAlia
   return ref?.kind === 'gradient' ? ref.value : undefined;
 }
 
+const TRANSPARENT_TOKEN = '--color-transparent';
+
+/** The flat colour an alias resolves to, or `null` when it reads as "no fill"
+ *  (a transparent token/literal, or no alias at all). */
+function flatAliasColor(ref: CssVarRef | undefined): { color: string; opacity: number } | null {
+  if (ref === undefined) return null;
+  if (ref.kind === 'token') {
+    return ref.name === TRANSPARENT_TOKEN ? null : { color: ref.name, opacity: ref.opacity ?? 100 };
+  }
+  if (ref.kind === 'literal') {
+    return ref.value === 'transparent' ? null : { color: ref.value, opacity: 100 };
+  }
+  return null; // gradient refs are handled by the caller
+}
+
+/** Lift a flat-colour (or empty) alias into a single-stop gradient payload so
+ *  the editor renders — a flat fill reads as `solid`, an empty/transparent one
+ *  as `none`. The user can then promote it to a real gradient. */
+function flatAliasToGradient(ref: CssVarRef | undefined): GradientAliasValue {
+  const flat = flatAliasColor(ref);
+  return flat
+    ? { type: 'solid', angle: 135, stops: [{ position: 50, color: flat.color, opacity: flat.opacity }] }
+    : { type: 'none', angle: 135, stops: [{ position: 50, color: TRANSPARENT_TOKEN, opacity: 0 }] };
+}
+
 function writeComponentGradient(component: string, varName: string, value: GradientAliasValue): void {
   const ref: CssVarRef = { kind: 'gradient', value };
   setComponentAlias(component, varName, ref);
@@ -93,14 +118,18 @@ function writeComponentGradient(component: string, varName: string, value: Gradi
 export function componentGradientSource(component: string, varName: string): GradientSource {
   const current = derived(editorState, ($s) => {
     const ref = $s.components[component]?.aliases[varName];
-    if (ref?.kind !== 'gradient') return undefined;
+    // A flat-colour (or absent) alias still yields a snapshot — synthesised as
+    // a solid/none single-stop fill — so the editor always renders and offers
+    // the type picker. Without this the whole section vanished for any
+    // non-gradient background (e.g. the default transparent divider fill).
+    const value = ref?.kind === 'gradient' ? ref.value : flatAliasToGradient(ref);
     return {
-      type: ref.value.type,
-      angle: ref.value.angle,
-      centerX: ref.value.centerX,
-      aspectX: ref.value.aspectX,
-      aspectY: ref.value.aspectY,
-      stops: ref.value.stops.map((s) => ({ ...s })),
+      type: value.type,
+      angle: value.angle,
+      centerX: value.centerX,
+      aspectX: value.aspectX,
+      aspectY: value.aspectY,
+      stops: value.stops.map((s) => ({ ...s })),
     };
   });
   /** Read-modify-write through `mutate` so each edit is one history entry
@@ -110,6 +139,9 @@ export function componentGradientSource(component: string, varName: string): Gra
     mutate(label, (s) => {
       const slice = s.components[component] ?? (s.components[component] = { activeFile: 'default', aliases: {}, config: {} });
       const ref = slice.aliases[varName];
+      // Seed the editable base from the existing gradient, or lift the current
+      // flat-colour alias into one so the first edit promotes (rather than
+      // discards) whatever fill was already there.
       const base: GradientAliasValue =
         ref?.kind === 'gradient'
           ? {
@@ -120,7 +152,7 @@ export function componentGradientSource(component: string, varName: string): Gra
               ...(ref.value.aspectY !== undefined ? { aspectY: ref.value.aspectY } : {}),
               stops: ref.value.stops.map((st) => ({ ...st })),
             }
-          : { type: 'linear', angle: 135, stops: [] };
+          : flatAliasToGradient(ref);
       mutator(base);
       slice.aliases[varName] = { kind: 'gradient', value: base };
     });
@@ -135,7 +167,15 @@ export function componentGradientSource(component: string, varName: string): Gra
       ...(next.aspectY !== undefined ? { aspectY: next.aspectY } : {}),
       stops: next.stops.map((s) => ({ ...s })),
     }),
-    setType: (t) => update(`set gradient type ${varName}`, (g) => { g.type = t; }),
+    setType: (t) => update(`set gradient type ${varName}`, (g) => {
+      // Linear/radial need two endpoints; a flat fill carries only one, so
+      // mirror it into a 0→100 pair the user can then shape.
+      if ((t === 'linear' || t === 'radial') && g.stops.length < 2) {
+        const seed = g.stops[0] ?? { position: 0, color: TRANSPARENT_TOKEN, opacity: 100 };
+        g.stops = [{ ...seed, position: 0 }, { ...seed, position: 100 }];
+      }
+      g.type = t;
+    }),
     setAngle: (a) => update(`set gradient angle ${varName}`, (g) => { g.angle = a; }),
     setCenterX: (x) => update(`set gradient center ${varName}`, (g) => { g.centerX = x; }),
     setAspect: (a) => update(`set gradient aspect ${varName}`, (g) => {

package/src/editor/core/themes/migrations/2026-06-05-palette-unification.ts

@@ -0,0 +1,90 @@
+/**
+ * Palette unification: drop the gray palette "mode".
+ *
+ * Lives outside the `runMigrations` framework (whose contract is the flat
+ * `Record<string, string>` cssVariables bag) because it transforms the
+ * structured `editorConfigs` map, exactly like `renamePrimaryPaletteKey`.
+ * Applied unconditionally in `loadFromFile`; idempotent and self-sunsetting —
+ * once every saved theme has been resaved without the gray fields, this file
+ * is dead code and can be deleted.
+ *
+ * Two cases:
+ *   - Neutral / Alternate (the former gray palettes): close-map to the unified
+ *     shape. The picked base becomes the effective gray-500 (subtle tint +
+ *     lightness preserved), the lightness curve keeps the neutral ramp, and the
+ *     saturation curve flattens to 100 — chroma now flows from the base, not a
+ *     flat-20 multiplier. Hand-shaped gray saturation curves are not reproduced
+ *     (owner accepted approximate + manual retune).
+ *   - Every other palette: the gray fields were always vestigial; drop them.
+ */
+
+import { type CurveAnchor, sampleCurve } from '../../../ui/curveEngine';
+import { hexToOklch, oklchToHex, gamutClamp } from '../../palettes/oklch';
+import { DEFAULT_PALETTE_SATURATION } from '../../palettes/paletteDerivation';
+import type { PaletteConfig } from '../themeTypes';
+
+const NEUTRAL_LABELS = new Set(['Neutral', 'Alternate']);
+
+const GRAY_STEP_COUNT = 11;
+const GRAY_500_X = (4 / (GRAY_STEP_COUNT - 1)) * 100;
+
+/** Legacy shape: the gray fields union'd onto every saved palette config. */
+type LegacyGrayFields = {
+  tintHue?: number;
+  tintChroma?: number;
+  grayLightnessCurve?: CurveAnchor[];
+  graySaturationCurve?: CurveAnchor[];
+};
+type LegacyPaletteConfig = PaletteConfig & LegacyGrayFields;
+
+/** Reproduces the deleted `computeGrayColor` at step 500. */
+function effectiveGray500(cfg: LegacyPaletteConfig): string {
+  const hue = cfg.tintHue ?? 240;
+  const chroma = cfg.tintChroma ?? 0.04;
+  const lCurve = cfg.grayLightnessCurve ?? [];
+  const sCurve = cfg.graySaturationCurve ?? [];
+  const lOff = cfg.curveOffset?.['gray-lightness'] ?? 0;
+  const sOff = cfg.curveOffset?.['gray-saturation'] ?? 0;
+  const targetL = Math.max(0, Math.min(100, sampleCurve(lCurve, GRAY_500_X) + lOff)) / 100;
+  const satMul = Math.max(0, Math.min(2, (sampleCurve(sCurve, GRAY_500_X) + sOff) / 100));
+  const clamped = gamutClamp(targetL, chroma * satMul, hue);
+  return oklchToHex(clamped.l, clamped.c, clamped.h);
+}
+
+function stripGrayFields(cfg: LegacyPaletteConfig): PaletteConfig {
+  const { tintHue, tintChroma, grayLightnessCurve, graySaturationCurve, ...rest } = cfg;
+  return rest;
+}
+
+/** Precondition: `cfg.grayLightnessCurve` is defined (caller-guarded). */
+function unifyNeutral(cfg: LegacyPaletteConfig): PaletteConfig {
+  const {
+    'gray-lightness': grayLightnessOffset,
+    'gray-saturation': _graySaturationOffset,
+    lightness: _lightness,
+    saturation: _saturation,
+    ...scaleOffsets
+  } = cfg.curveOffset ?? {};
+
+  return {
+    ...stripGrayFields(cfg),
+    baseColor: effectiveGray500(cfg),
+    lightnessCurve: cfg.grayLightnessCurve!,
+    saturationCurve: DEFAULT_PALETTE_SATURATION(),
+    curveOffset: { ...scaleOffsets, lightness: grayLightnessOffset ?? 0, saturation: 0 },
+    anchorToBase: true,
+  };
+}
+
+export function unifyGrayPalettes(
+  editorConfigs: Record<string, PaletteConfig>,
+): Record<string, PaletteConfig> {
+  const out: Record<string, PaletteConfig> = {};
+  for (const [label, cfg] of Object.entries(editorConfigs)) {
+    const legacy = cfg as LegacyPaletteConfig;
+    out[label] = NEUTRAL_LABELS.has(label) && legacy.grayLightnessCurve !== undefined
+      ? unifyNeutral(legacy)
+      : stripGrayFields(legacy);
+  }
+  return out;
+}

package/src/editor/core/themes/themeTypes.ts

@@ -9,12 +9,8 @@ export interface GradientStop {
 
 export interface PaletteConfig {
   baseColor: string;
-  tintHue: number;
-  tintChroma?: number;
   lightnessCurve: CurveAnchor[];
   saturationCurve: CurveAnchor[];
-  grayLightnessCurve: CurveAnchor[];
-  graySaturationCurve: CurveAnchor[];
   scaleCurves: Record<string, { lightness: CurveAnchor[]; saturation: CurveAnchor[] }>;
   curveOffset: Record<string, number>;
   overrides: Record<string, string>;
@@ -30,10 +26,9 @@ export interface PaletteConfig {
   /**
    * Set to true by importers when they overlay `cssVariables[--color-{ns}-*]`
    * without owning the typed-state curves. The storage-layer reconciler uses
-   * it as an opt-in switch: snap `baseColor` (or `tintHue`+`tintChroma` for
-   * gray palettes) to the imported `--color-{ns}-500` anchor and clear the
-   * flag. Editor-authored themes never set this, so the reconciler is a
-   * strict no-op for them.
+   * it as an opt-in switch: snap `baseColor` to the imported
+   * `--color-{ns}-500` anchor and clear the flag. Editor-authored themes
+   * never set this, so the reconciler is a strict no-op for them.
    *
    * Persists on disk for first-load reconciliation. After reconcile strips
    * the palette-derived keys from `cssVariables`, subsequent reconciles find

package/src/editor/docs/content/01-overview.md

@@ -18,8 +18,9 @@ style your site by editing tokens and components in a live editor. When it looks
 
 - **Tokens**: the design-system primitives, colour palettes, type, spacing,
   radius, shadow, and gradients, that apply across your whole site.
-- **Components**: the package ships about 25 editable components (Button, Card,
-  Dialog, Table, and more).You style components by changing the tokens assigned to each property.
+- **Components**: the package ships about 25 editable components (Button,
+  IconButton, Card, Dialog, Table, and more). You style components by changing
+  the tokens assigned to each property.
 
 ## Where to go next
 

package/src/editor/docs/content.generated.ts

@@ -2,7 +2,7 @@
 // Source of truth: src/editor/docs/content/*.md  ·  regenerate: npm run sync:docs
 
 export const docContent: Record<string, string> = {
-  "01-overview": "# Overview\n\nLive Tokens is a design system for building Svelte microsites quickly. You\nstyle your site by editing tokens and components in a live editor. When it looks right, you save the manifest and ship it.\n\n## How it works\n\n- The editor runs in your dev server, on top of your real pages. You style in\n  context, not in a separate sandbox.\n- Every change updates a CSS variable, so the page repaints instantly. No\n  reload, no build step.\n- Saving writes a small JSON file into your project. Shipping bakes your chosen\n  theme into a plain CSS file that the build bundles.\n- The editor is dev-only. Production ships plain CSS variables and the\n  components you used, nothing else.\n\n## What you can edit\n\n- **Tokens**: the design-system primitives, colour palettes, type, spacing,\n  radius, shadow, and gradients, that apply across your whole site.\n- **Components**: the package ships about 25 editable components (Button, Card,\n  Dialog, Table, and more).You style components by changing the tokens assigned to each property.\n\n## Where to go next\n\n- **[Getting started](getting-started.md)**: scaffold a project and make your\n  first edit.\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own components\n  editable.\n",
+  "01-overview": "# Overview\n\nLive Tokens is a design system for building Svelte microsites quickly. You\nstyle your site by editing tokens and components in a live editor. When it looks right, you save the manifest and ship it.\n\n## How it works\n\n- The editor runs in your dev server, on top of your real pages. You style in\n  context, not in a separate sandbox.\n- Every change updates a CSS variable, so the page repaints instantly. No\n  reload, no build step.\n- Saving writes a small JSON file into your project. Shipping bakes your chosen\n  theme into a plain CSS file that the build bundles.\n- The editor is dev-only. Production ships plain CSS variables and the\n  components you used, nothing else.\n\n## What you can edit\n\n- **Tokens**: the design-system primitives, colour palettes, type, spacing,\n  radius, shadow, and gradients, that apply across your whole site.\n- **Components**: the package ships about 25 editable components (Button,\n  IconButton, Card, Dialog, Table, and more). You style components by changing\n  the tokens assigned to each property.\n\n## Where to go next\n\n- **[Getting started](getting-started.md)**: scaffold a project and make your\n  first edit.\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own components\n  editable.\n",
   "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/live-tokens/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/live-tokens/components` view.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
   "editing-tokens": "# Editing tokens\n\nA tour of the editor. The page behind it repaints on every change; saving\nwrites a theme file you can reload later.\n\nThe editor has two views:\n\n- **Tokens**: the design-system primitives (colour, type, spacing, and so on).\n  They apply everywhere your site uses them.\n- **Components**: per-component editors. Re-Assign what tokens a component uses\n  without changing the underlying system.\n\nThis page covers **Tokens**. For components, see\n[Creating components](creating-components.md).\n\n## Palettes\n\nMost colour work happens here. Each palette (Brand, Accent, Neutral, Canvas,\nSuccess, Warning, Info, Danger, and a few more) has:\n\n- **Base colour.** Pick a hex; the palette derives an 11-step ramp (100 to 950)\n  from it.\n- **Curves.** Two curves shape how lightness and saturation fall off across the\n  ramp. Drag the handles to bias it darker, lighter, or more saturated.\n- **Overrides.** Lock a single step to a hand-picked hex when the curve doesn't\n  land where you want.\n\nEditing a palette base ripples through every colour that depends on it, in real\ntime. Colours use OKLCH, so the ramp stays perceptually even across hues\nwithout muddy mid-tones.\n\n## Type\n\n- **Fonts.** Add sources from Google Fonts, Adobe (Typekit), a CSS URL, or an\n  inline `@font-face`. The font loads in the page as soon as you add it.\n- **Stacks.** Named font cascades you reference by token, such as a display\n  stack and a body stack.\n- **Sizes and weights.** A t-shirt scale (xs, sm, md, lg, xl, 2xl…) for size and\n  a numeric scale (100 to 900) for weight.\n\n## Spacing, radius, shadow\n\nNumeric scales with a slider per step.\n\n- **Spacing**: the padding, gap, and margin scale.\n- **Radius**: none through full.\n- **Shadow**: colour, offset, blur, spread, and opacity per step, with stacked\n  shadows supported.\n\nChange a step and every element using it repaints.\n\n## Overlays and gradients\n\n- **Overlays** are translucent tints layered over surfaces, like the subtle\n  tint a card gets on hover. Set a colour and opacity per state.\n- **Gradients** are reusable gradient tokens with a stop list and direction, for\n  hero panels and accent backgrounds.\n\n## Columns\n\nThe page-grid overlay. Set column count, gutter, and outer margin, and toggle\nthe visual guide with `Cmd/Ctrl+G`. Pages built on the column system reflow\nlive.\n\n## Saving\n\nThe editor saves to your browser continuously, so work survives a reload\nmid-edit. **Save** is a separate step: it writes a named theme file under\n`src/live-tokens/data/themes/`.\n\nThe header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`) and a file\nmenu for New, Save, Save as, Switch, and Delete. You can keep many themes side\nby side; one is active at a time. See [Themes](themes-workflow.md) for the full\nlifecycle.\n",
   "getting-started": "# Getting started\n\nScaffold a live token site in a moments. You need Node 20 or later, a\npackage manager (npm, pnpm, or yarn), and a browser. Open claude code in your repo and start building.\n\n## Scaffold a new app\n\n```bash\nnpm create @motion-proto/live-tokens@latest my-app\ncd my-app\nnpm install\nnpm run dev\n```\n\nOpen the URL Vite prints (usually `http://localhost:5173`). You get a\none-page Svelte + Vite app that depends on the published package, with the\neditor wired up and the full component set ready to import.\n\n`npx @motion-proto/live-tokens create my-app` runs the same scaffold without\nthe initialiser package.\n\n### What the scaffold gives you\n\nEvery editable file lives under `src/` and is committed, so `npm install` and\nversion upgrades never touch your styles. The package code stays in\n`node_modules`.\n\n| Path | What it is |\n|------|------------|\n| `src/pages/Home.svelte` | The starter page. Replace it with your own content. |\n| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds dev-only routes under a reserved `/live-tokens/*` namespace: `/live-tokens/editor`, `/live-tokens/components`, and `/live-tokens/docs`. |\n| `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |\n| `src/styles/site.css` | Themed page typography, yours to edit. |\n\n## Your first edit\n\n1. Run `npm run dev` and open the home page.\n2. Click **Open Token Editor**, or visit `/live-tokens/editor`. The editor opens beside\n   the page.\n3. Open **Palettes**, pick **Brand**, and change the base hex. The page\n   repaints as you type.\n4. Open the file menu and choose **Save as**. A theme appears as JSON under\n   `src/live-tokens/data/themes/`.\n5. Reload. Your saved theme is the active theme, so the page returns as you\n   left it.\n\n## What you just changed\n\nEvery edit sets a CSS custom property on `:root`. Your components read those\nproperties through `var(--...)`. There is no token build step and no\npreprocessor rewriting your code: the page renders against plain CSS variables\nthe editor swaps live.\n\nTo ship, promote a theme to production in the editor. That bakes the theme's\nvariables into `src/live-tokens/data/tokens.generated.css`, which your build\nbundles alongside `tokens.css`. The editor itself never reaches production.\n\nAlready have a Svelte 5 + Vite app? The\n[README](https://github.com/motionproto/live-tokens#readme) covers installing\ninto an existing project.\n\n## Where to go next\n\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own component\n  editable.\n",