@motion-proto/live-tokens 0.26.0 → 0.28.0

package/src/editor/docs/chapters.ts

@@ -0,0 +1,44 @@
+export interface Chapter {
+  id: string;
+  title: string;
+}
+
+/* The user-facing guide, shipped with the package so consumers reference it in
+   the editor while building. Markdown lives in ./content/; the original
+   developer-reference chapters stay in the repo's docs/archive/ and don't
+   ship. */
+export const chapters: Chapter[] = [
+  { id: '01-overview',         title: 'Overview' },
+  { id: 'getting-started',     title: 'Getting started' },
+  { id: 'editing-tokens',      title: 'Editing tokens' },
+  { id: 'themes-workflow',     title: 'Themes' },
+  { id: 'creating-components', title: 'Creating components' },
+];
+
+export const chapterIds = chapters.map((c) => c.id);
+
+/* Vite resolves this glob at build time. The `?raw` query loads each .md
+   file as a string, so the markdown lives next to the runtime page module
+   and reloads on edit via HMR. */
+const docModules = import.meta.glob<string>(
+  './content/*.md',
+  { query: '?raw', import: 'default' },
+);
+
+export async function loadChapter(id: string): Promise<string> {
+  const key = `./content/${id}.md`;
+  const loader = docModules[key];
+  if (!loader) {
+    throw new Error(`Chapter not found: ${id} (expected at ${key}).`);
+  }
+  return loader();
+}
+
+export function chapterNeighbours(id: string): { prev: Chapter | null; next: Chapter | null } {
+  const idx = chapterIds.indexOf(id);
+  if (idx < 0) return { prev: null, next: null };
+  return {
+    prev: idx > 0 ? chapters[idx - 1] : null,
+    next: idx < chapters.length - 1 ? chapters[idx + 1] : null,
+  };
+}

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

@@ -0,0 +1,31 @@
+# Overview
+
+Live Tokens is a design system for building Svelte microsites quickly. You
+style your site by editing tokens and components in a live editor. When it looks right, you save the manifest and ship it.
+
+## How it works
+
+- The editor runs in your dev server, on top of your real pages. You style in
+  context, not in a separate sandbox.
+- Every change updates a CSS variable, so the page repaints instantly. No
+  reload, no build step.
+- Saving writes a small JSON file into your project. Shipping bakes your chosen
+  theme into a plain CSS file that the build bundles.
+- The editor is dev-only. Production ships plain CSS variables and the
+  components you used, nothing else.
+
+## What you can edit
+
+- **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.
+
+## Where to go next
+
+- **[Getting started](getting-started.md)**: scaffold a project and make your
+  first edit.
+- **[Editing tokens](editing-tokens.md)**: a tour of the editor.
+- **[Themes](themes-workflow.md)**: save, switch, and ship.
+- **[Creating components](creating-components.md)**: make your own components
+  editable.

package/src/editor/docs/content/creating-components.md

@@ -0,0 +1,40 @@
+# Creating components
+
+The package ships about 25 editable components. When you need one it doesn't
+have, you can make your own Svelte component editable, so anyone using the
+editor can re-point its colours, type, and spacing without touching code.
+
+The simplest way is to ask Claude. The package bundles a Claude Code skill that
+knows the conventions, writes the files, and checks the result for you.
+
+## Install the skills
+
+```bash
+npx @motion-proto/live-tokens setup-claude
+```
+
+This copies the bundled skills into your project's `.claude/skills/`. Once
+they're there, Claude Code picks them up automatically.
+
+## Ask for a component
+
+Describe what you want in plain English. Phrases like these trigger the skill:
+
+- "Add a Toggle component to live-tokens"
+- "Make this Svelte component editable in the live-tokens editor"
+- "Create a Stat component with a value and a label"
+
+Claude asks any clarifying questions it needs (which variants, which states,
+which parts), then writes the component, registers it with the editor, and runs
+its verification checklist. When it finishes, open `/components` to see your new
+component in the editor and confirm everything works.
+
+## What you get
+
+- A runtime component whose editable properties default to your theme tokens.
+- An editor entry that appears under **Custom** in the `/components` view.
+- The naming and wiring handled for you, so the component fits the system.
+
+Advanced authors who want to write a component by hand can read the naming and
+state-model conventions shipped in the package
+(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).

package/src/editor/docs/content/editing-tokens.md

@@ -0,0 +1,74 @@
+# Editing tokens
+
+A tour of the editor. The page behind it repaints on every change; saving
+writes a theme file you can reload later.
+
+The editor has two views:
+
+- **Tokens**: the design-system primitives (colour, type, spacing, and so on).
+  They apply everywhere your site uses them.
+- **Components**: per-component editors. Re-Assign what tokens a component uses
+  without changing the underlying system.
+
+This page covers **Tokens**. For components, see
+[Creating components](creating-components.md).
+
+## Palettes
+
+Most colour work happens here. Each palette (Brand, Accent, Neutral, Canvas,
+Success, Warning, Info, Danger, and a few more) has:
+
+- **Base colour.** Pick a hex; the palette derives an 11-step ramp (100 to 950)
+  from it.
+- **Curves.** Two curves shape how lightness and saturation fall off across the
+  ramp. Drag the handles to bias it darker, lighter, or more saturated.
+- **Overrides.** Lock a single step to a hand-picked hex when the curve doesn't
+  land where you want.
+
+Editing a palette base ripples through every colour that depends on it, in real
+time. Colours use OKLCH, so the ramp stays perceptually even across hues
+without muddy mid-tones.
+
+## Type
+
+- **Fonts.** Add sources from Google Fonts, Adobe (Typekit), a CSS URL, or an
+  inline `@font-face`. The font loads in the page as soon as you add it.
+- **Stacks.** Named font cascades you reference by token, such as a display
+  stack and a body stack.
+- **Sizes and weights.** A t-shirt scale (xs, sm, md, lg, xl, 2xl…) for size and
+  a numeric scale (100 to 900) for weight.
+
+## Spacing, radius, shadow
+
+Numeric scales with a slider per step.
+
+- **Spacing**: the padding, gap, and margin scale.
+- **Radius**: none through full.
+- **Shadow**: colour, offset, blur, spread, and opacity per step, with stacked
+  shadows supported.
+
+Change a step and every element using it repaints.
+
+## Overlays and gradients
+
+- **Overlays** are translucent tints layered over surfaces, like the subtle
+  tint a card gets on hover. Set a colour and opacity per state.
+- **Gradients** are reusable gradient tokens with a stop list and direction, for
+  hero panels and accent backgrounds.
+
+## Columns
+
+The page-grid overlay. Set column count, gutter, and outer margin, and toggle
+the visual guide with `Cmd/Ctrl+G`. Pages built on the column system reflow
+live.
+
+## Saving
+
+The editor saves to your browser continuously, so work survives a reload
+mid-edit. **Save** is a separate step: it writes a named theme file under
+`src/live-tokens/data/themes/`.
+
+The header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`) and a file
+menu for New, Save, Save as, Switch, and Delete. You can keep many themes side
+by side; one is active at a time. See [Themes](themes-workflow.md) for the full
+lifecycle.

package/src/editor/docs/content/getting-started.md

@@ -0,0 +1,67 @@
+# Getting started
+
+Scaffold a live token site in a moments. You need Node 20 or later, a
+package manager (npm, pnpm, or yarn), and a browser. Open claude code in your repo and start building.
+
+## Scaffold a new app
+
+```bash
+npm create @motion-proto/live-tokens@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Open the URL Vite prints (usually `http://localhost:5173`). You get a
+one-page Svelte + Vite app that depends on the published package, with the
+editor wired up and the full component set ready to import.
+
+`npx @motion-proto/live-tokens create my-app` runs the same scaffold without
+the initialiser package.
+
+### What the scaffold gives you
+
+Every editable file lives under `src/` and is committed, so `npm install` and
+version upgrades never touch your styles. The package code stays in
+`node_modules`.
+
+| Path | What it is |
+|------|------------|
+| `src/pages/Home.svelte` | The starter page. Replace it with your own content. |
+| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds the dev-only `/editor`, `/components`, and `/docs` routes. |
+| `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |
+| `src/styles/site.css` | Themed page typography, yours to edit. |
+
+## Your first edit
+
+1. Run `npm run dev` and open the home page.
+2. Click **Open Token Editor**, or visit `/editor`. The editor opens beside
+   the page.
+3. Open **Palettes**, pick **Brand**, and change the base hex. The page
+   repaints as you type.
+4. Open the file menu and choose **Save as**. A theme appears as JSON under
+   `src/live-tokens/data/themes/`.
+5. Reload. Your saved theme is the active theme, so the page returns as you
+   left it.
+
+## What you just changed
+
+Every edit sets a CSS custom property on `:root`. Your components read those
+properties through `var(--...)`. There is no token build step and no
+preprocessor rewriting your code: the page renders against plain CSS variables
+the editor swaps live.
+
+To ship, promote a theme to production in the editor. That bakes the theme's
+variables into `src/live-tokens/data/tokens.generated.css`, which your build
+bundles alongside `tokens.css`. The editor itself never reaches production.
+
+Already have a Svelte 5 + Vite app? The
+[README](https://github.com/motionproto/live-tokens#readme) covers installing
+into an existing project.
+
+## Where to go next
+
+- **[Editing tokens](editing-tokens.md)**: a tour of the editor.
+- **[Themes](themes-workflow.md)**: save, switch, and ship.
+- **[Creating components](creating-components.md)**: make your own component
+  editable.

package/src/editor/docs/content/themes-workflow.md

@@ -0,0 +1,60 @@
+# Themes
+
+Save your work, switch between themes, and ship one to production.
+
+## How themes work
+
+- **Your live edits** are what the page shows right now. They save to your
+  browser automatically and survive a reload, but they are not yet a file.
+- **A saved theme** is a named JSON file in `src/live-tokens/data/themes/`. You
+  create one with **Save as**.
+- **The active theme** is the saved theme the page loads at startup. Exactly one
+  at a time.
+- **The production theme** is the one that ships. Promoting sets it.
+
+## Saving
+
+In the editor header:
+
+- **Save** updates the current theme.
+- **Save as** names a new theme. Use it for your first save and for forking.
+
+Names are tidied to lowercase with underscores, so "My Brand!" becomes
+`my_brand`. There is a built-in `default` theme you can always return to; the
+editor never overwrites it.
+
+## Switching
+
+The file menu lists every saved theme. Pick one to make it active; the page
+reloads with it applied. Your current edits are saved to the previous theme
+first, so you don't lose work.
+
+## Shipping
+
+**Promote to production** is the "ship it" step. It bakes the theme's variables
+into `src/live-tokens/data/tokens.generated.css`, which your build bundles
+alongside `tokens.css`. Fonts regenerate to match.
+
+Production builds (`npm run build`) ship only that plain CSS and your
+components. No editor, no JSON loading, no runtime indirection. If you save
+while the production theme is active, the generated CSS updates immediately,
+with no separate promote step.
+
+## Manifests
+
+A **manifest** bundles one theme plus a config for each component into a single
+named set. Useful when you run several brands and want each to apply its theme
+and component tweaks in one move. There is a protected default and an active
+manifest; applying one swaps everything at once.
+
+## Keeping your work safe
+
+Everything under `src/live-tokens/data/` is plain JSON, so commit it. Themes
+show up as readable diffs you can review per branch. There are no automatic
+backups: git is your safety net. To experiment freely, **Save as** a new name
+first, then edit.
+
+## Where to go next
+
+- **[Creating components](creating-components.md)**: make your own components
+  editable in the same editor.

package/src/editor/overlay/LiveTokensRouter.svelte

@@ -11,10 +11,15 @@
    * for any page that side-effect-imports a stylesheet at the top of its
    * module, so those imports only evaluate when the route is visited and
    * don't leak into unrelated routes (most importantly the editor pages).
+   *
+   * `props` lets one page component serve many paths: a `resolve()` match can
+   * hand the page the matched segment (an id or slug) so a single component
+   * renders each dynamic route.
    */
   export interface RouteEntry {
     component?: Component<any, any, any>;
     lazy?: () => Promise<{ default: Component<any, any, any> }>;
+    props?: Record<string, unknown>;
     label?: string;
     icon?: string;
     source?: string;
@@ -23,13 +28,37 @@
   }
 
   /**
-   * Override the default editor routes (`/editor`, `/components`). Pass a
-   * string to relocate the route; pass `false` to disable it entirely (no
-   * dispatch and, for `components`, no auto-injected nav-rail entry).
+   * Override the default editor routes (`/editor`, `/components`, `/docs`).
+   * Pass a string to relocate the route; pass `false` to disable it entirely
+   * (no dispatch and, for `components`/`docs`, no auto-injected nav-rail entry).
    */
   export interface EditorRouteOverrides {
     editor?: string | false;
     components?: string | false;
+    docs?: string | false;
+  }
+
+  /**
+   * Resolve a path to the single entry that renders it. Precedence, after the
+   * package-owned routes (`/editor`, `/components`, `/docs`) have already been
+   * matched by the component:
+   *
+   *   1. `pages[route]` — exact static match.
+   *   2. `resolve(route)` — consumer code, where params / prefixes / gating
+   *      live; returning `null` means "not mine" and resolution falls through.
+   *   3. `pages['/']` — final fallback (return your own entry from `resolve`
+   *      for a real 404 instead).
+   *
+   * With only `pages` passed this is exactly today's `pages[route] ?? pages['/']`.
+   * One resolved entry drives both dispatch and "Page Source", so a dynamic
+   * route's source can never desync from its page.
+   */
+  export function resolveRoute(
+    pages: Record<string, RouteEntry>,
+    resolve: ((route: string) => RouteEntry | null) | undefined,
+    route: string,
+  ): RouteEntry | null {
+    return pages[route] ?? resolve?.(route) ?? pages['/'] ?? null;
   }
 </script>
 
@@ -40,23 +69,42 @@
 
   interface Props {
     pages: Record<string, RouteEntry>;
+    /**
+     * Compute an entry for paths not in `pages` — this is where params,
+     * prefixes, and conditional gating live. See `resolveRoute` for the full
+     * precedence: `pages` wins over `resolve`, and `pages['/']` is the final
+     * fallback.
+     */
+    resolve?: (route: string) => RouteEntry | null;
     editorRoutes?: EditorRouteOverrides;
   }
 
-  let { pages, editorRoutes = {} }: Props = $props();
+  let { pages, resolve, editorRoutes = {} }: Props = $props();
 
   let editorEnabled = $derived(editorRoutes.editor !== false);
   let componentsEnabled = $derived(editorRoutes.components !== false);
+  let docsEnabled = $derived(editorRoutes.docs !== false);
   let editorPath = $derived(typeof editorRoutes.editor === 'string' ? editorRoutes.editor : '/editor');
   let componentsPath = $derived(typeof editorRoutes.components === 'string' ? editorRoutes.components : '/components');
+  let docsPath = $derived(typeof editorRoutes.docs === 'string' ? editorRoutes.docs : '/docs');
 
   const isDev = import.meta.env.DEV;
   let isEditor = $derived(isDev && editorEnabled && $route === editorPath);
   let isComponentEditor = $derived(isDev && componentsEnabled && $route === componentsPath);
+  let isDocs = $derived(isDev && docsEnabled && $route === docsPath);
+
+  // The single entry that renders the current route. Owned routes are handled
+  // by the isEditor/isComponentEditor/isDocs branches, so they resolve to null
+  // here; everything else flows through resolveRoute and drives both dispatch
+  // (component + props) and page-source from this one value.
+  let resolvedEntry = $derived(
+    isEditor || isComponentEditor || isDocs ? null : resolveRoute(pages, resolve, $route),
+  );
 
   // Pages with a label show up in the nav rail, in declaration order. In dev,
-  // the components-editor route is auto-appended so it's reachable from every
-  // page (the convention every existing live-tokens consumer has settled on).
+  // the components-editor and docs routes are auto-appended so they're reachable
+  // from every page. Docs ship from the package, so consumers reference the
+  // guide in the editor while building without vendoring a copy.
   let navLinks = $derived([
     ...Object.entries(pages)
       .filter(([, e]) => !!e.label)
@@ -64,23 +112,32 @@
     ...(isDev && componentsEnabled
       ? [{ path: componentsPath, label: 'Components', icon: 'fa-puzzle-piece' }]
       : []),
+    ...(isDev && docsEnabled
+      ? [{ path: docsPath, label: 'Docs', icon: 'fa-book' }]
+      : []),
   ]);
 
-  let pageSources = $derived(
-    Object.fromEntries(
+  // Static-page sources, plus the resolved entry's source for the current
+  // route — so a resolve()-matched dynamic route gets "Page Source" too, keyed
+  // on the live path ($route) the overlay looks up.
+  let pageSources = $derived({
+    ...Object.fromEntries(
       Object.entries(pages)
         .filter(([, e]) => !!e.source)
         .map(([path, e]) => [path, e.source!]),
     ),
-  );
+    ...(resolvedEntry?.source ? { [$route]: resolvedEntry.source } : {}),
+  });
 
-  // Components-editor route always hides the page-source button (matches the
-  // convention from the original consumer pattern).
+  // The package-owned components and docs routes hide the page-source button
+  // (no consumer source file backs them).
   let hidePageSourceOn = $derived([
     ...Object.entries(pages)
       .filter(([, e]) => e.hidePageSource)
       .map(([path]) => path),
+    ...(resolvedEntry?.hidePageSource ? [$route] : []),
     ...(componentsEnabled ? [componentsPath] : []),
+    ...(docsEnabled ? [docsPath] : []),
   ]);
 
   // Dispatch the current route. Editor pages are dynamically imported so they
@@ -90,7 +147,8 @@
   let pagePromise = $derived.by(() => {
     if (isEditor) return import('../pages/Editor.svelte');
     if (isComponentEditor) return import('../pages/ComponentEditorPage.svelte');
-    const entry = pages[$route] ?? pages['/'];
+    if (isDocs) return import('../docs/Docs.svelte');
+    const entry = resolvedEntry;
     if (!entry) return Promise.resolve({ default: null as unknown as Component<any, any, any> });
     if (entry.lazy) return entry.lazy();
     if (entry.component) return Promise.resolve({ default: entry.component });
@@ -124,7 +182,7 @@
   {#await pagePromise then m}
     {@const PageComponent = m.default}
     {#if PageComponent}
-      <PageComponent />
+      <PageComponent {...resolvedEntry?.props ?? {}} />
     {/if}
   {/await}
 </div>

package/src/editor/pages/ComponentEditorPage.svelte

@@ -20,11 +20,6 @@
 
   let drawerOpen = $state(true);
 
-  // Demo page is statically imported from `./Demo.svelte` in App.svelte; the
-  // glob resolves to an empty object if the file has been deleted, in which
-  // case we hide the demo option from the page-switcher.
-  const demoExists = Object.keys(import.meta.glob('./Demo.svelte')).length > 0;
-
   let pageMenuOpen = $state(false);
   let pageMenuRoot: HTMLElement | undefined = $state();
 
@@ -138,12 +133,6 @@
             <i class="fas fa-home"></i>
             <span>Main site</span>
           </button>
-          {#if demoExists}
-            <button class="page-menu-item" role="menuitem" onclick={() => selectPage('/demo')}>
-              <i class="fas fa-box-open"></i>
-              <span>Demo page</span>
-            </button>
-          {/if}
         </div>
       {/if}
     </div>

package/template/README.md

@@ -15,7 +15,8 @@ This project follows the package's [recommended layout](https://github.com/motio
 
 - `src/pages/Home.svelte` — the starter page. Replace it with your own content.
 - `src/App.svelte` — your routes. `<LiveTokensRouter>` adds the dev-only
-  `/editor` (theme tokens) and `/components` (per-component aliases) routes.
+  `/editor` (theme tokens), `/components` (per-component aliases), and `/docs`
+  (the user guide) routes.
 - `src/system/styles/tokens.css` — your theme token vocabulary. The dev server
   writes edits here when you use the in-browser editor.
 - `src/styles/site.css` — themed page typography. Yours to edit.