@motion-proto/live-tokens 0.26.0 → 0.28.0

package/.claude/skills/live-tokens-build-page/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: live-tokens-build-page
-description: Apply the @motion-proto/live-tokens project conventions when building a page: use shipped components from the catalogue, reference theme tokens (never hex/pixel literals), mount routes dynamically, register pageSources, and import site.css per-page. Use when the user asks to build / create / lay out a page, route, hero, marketing page, landing page, dashboard, settings screen, or pricing page; add a route; place / drop / use an existing component on a page; or assemble a screen from the live-tokens catalogue. For component-choice decisions, see live-tokens-pick-component. For authoring a brand-new component, see live-tokens-create-component.
+description: Apply the @motion-proto/live-tokens project conventions when building a page: use shipped components from the catalogue, reference theme tokens (never hex/pixel literals), mount routes dynamically, register each route's page source, and import site.css per-page. Use when the user asks to build / create / lay out a page, route, hero, marketing page, landing page, dashboard, settings screen, or pricing page; add a route; place / drop / use an existing component on a page; or assemble a screen from the live-tokens catalogue. For component-choice decisions, see live-tokens-pick-component. For authoring a brand-new component, see live-tokens-create-component.
 ---
 
 # Building pages in a live-tokens project
@@ -18,8 +18,10 @@ To place children at specific page-column positions, span the parent grid (`grid
 
 ## Wiring
 
-- Mount routes dynamically in `App.svelte` with `$derived.by(() => import(...))`. Static top-level imports evaluate every page module at boot and leak page CSS into editor routes.
-- Register each route in `<LiveEditorOverlay pageSources={...} />` so the "Page Source" button opens the file in VS Code.
+- Add the route the way `App.svelte` already wires routes:
+  - **`<LiveTokensRouter pages={...}>`** (the usual case): add a `pages` entry as `lazy: () => import('./YourPage.svelte')` with a `source: 'src/...'` (and a `label`/`icon` to show it in the nav rail). For a route you can't enumerate (a `/:id`, a path prefix, a gated page), add a `resolve(path) => RouteEntry | null` instead of a `pages` key; same entry shape, so `props` and `source` (hence "Page Source") work identically.
+  - **Manual `<LiveEditorOverlay>`**: dispatch with `$derived.by(() => import(...))` and register the route's source in `pageSources={...}`.
+  Either way use `lazy`, not a static top-level import: static imports evaluate every page module at boot and leak page CSS into the editor routes.
 - Import `site.css` from each page's `<script>` block, never from `main.ts` (would leak into editor routes).
 
 ## Avoid
@@ -32,4 +34,4 @@ To place children at specific page-column positions, span the parent grid (`grid
 
 ## Verify
 
-In dev: change a colour in `/editor` and confirm your page repaints (proves token usage). The overlay's "Page Source" button on the new route opens the page in VS Code (proves the `pageSources` entry). `ColumnsOverlay` (Cmd+G) shows content sitting inside `--columns-max-width`.
+In dev: change a colour in `/editor` and confirm your page repaints (proves token usage). The overlay's "Page Source" button on the new route opens the page in VS Code (proves the route's `source`). `ColumnsOverlay` (Cmd+G) shows content sitting inside `--columns-max-width`.

package/README.md

@@ -122,7 +122,7 @@ bootLiveTokens(App, '#app', {
 ```
 
 `<LiveTokensRouter>` owns the dev overlay (`<LiveEditorOverlay>` +
-`<ColumnsOverlay>`), the editor routes (`/editor`, `/components`), the
+`<ColumnsOverlay>`), the editor routes (`/editor`, `/components`, `/docs`), the
 in-app link-click interception, and the nav-rail/page-source plumbing the
 overlay needs. Each entry in `pages` is one of your routes; entries with a
 `label` appear in the overlay's nav rail. Pass pages as `lazy: () => import('./Page.svelte')`
@@ -131,6 +131,28 @@ visited; pass `component: PageComponent` instead for an eagerly-imported
 page. The editor routes are dispatched internally, so you don't have to
 dynamic-import the library's editor pages yourself.
 
+For routes you can't enumerate ahead of time (a `/:id` or `/:slug`, a path
+prefix, or a page shown only when some condition holds), add a `resolve`
+function from the current path to a `RouteEntry`; return `null` to fall
+through. It's plain code, so params, prefixes, and gating are a regex and an
+`if`, and the package ships no route syntax of its own. Resolution order is
+`pages[path]`, then `resolve(path)`, then the `pages['/']` fallback, so adding
+`resolve` never changes how existing `pages` entries match. A resolved entry
+can carry `props`, letting one page component serve many paths (such as the
+matched id), and its `source` gives the dynamic route a working "Page Source"
+button just like a static one.
+
+```svelte
+<LiveTokensRouter
+  pages={{ '/': { lazy: () => import('./Home.svelte'), label: 'Home' } }}
+  resolve={(path) => {
+    const m = path.match(/^\/module\/(.+)$/);
+    if (!m) return null;
+    return { lazy: () => import('./ModulePage.svelte'), props: { id: m[1] }, source: 'src/ModulePage.svelte' };
+  }}
+/>
+```
+
 You can also relocate or disable a default editor route via the
 `editorRoutes` prop: `<LiveTokensRouter pages={…} editorRoutes={{ editor: '/admin/editor', components: false }} />`.
 Pass a string to move a route; pass `false` to remove the route entirely
@@ -147,7 +169,10 @@ individual init functions (`initCssVarSync`, `initRouter`,
 `<LiveEditorOverlay>`, `<ColumnsOverlay>`, and the editor page exports
 (`@motion-proto/live-tokens/editor`,
 `@motion-proto/live-tokens/component-editor-page`) all stay exported. Use
-them directly if you need a custom shell or non-standard route dispatch.
+them directly to build a custom shell: render arbitrary markup per route, host
+a foreign matcher, or drive the overlay yourself. You do **not** need this for
+dynamic or gated routes; reach for `resolve` above, which keeps the overlay,
+nav rail, and page-source intact.
 
 ### Use components
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -65,6 +65,11 @@
       "svelte": "./src/editor/pages/ComponentEditorPage.svelte",
       "default": "./src/editor/pages/ComponentEditorPage.svelte"
     },
+    "./docs": {
+      "types": "./src/editor/docs/Docs.svelte.d.ts",
+      "svelte": "./src/editor/docs/Docs.svelte",
+      "default": "./src/editor/docs/Docs.svelte"
+    },
     "./components/*": {
       "svelte": "./src/system/components/*",
       "default": "./src/system/components/*"
@@ -110,8 +115,6 @@
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@types/node": "^25.9.1",
     "happy-dom": "^20.9.0",
-    "highlight.js": "^11.11.1",
-    "marked": "^18.0.4",
     "sass": "^1.98.0",
     "svelte": "^5.55.5",
     "svelte-check": "^4.4.8",
@@ -121,6 +124,8 @@
     "vitest": "^4.1.4"
   },
   "dependencies": {
-    "@fortawesome/fontawesome-free": "^7.2.0"
+    "@fortawesome/fontawesome-free": "^7.2.0",
+    "highlight.js": "^11.11.1",
+    "marked": "^18.0.4"
   }
 }

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

@@ -65,6 +65,28 @@ function migrateGradients(state: EditorState): EditorState {
   return { ...state, gradients: { tokens: makeDefaultGradients() } };
 }
 
+// `hydrate` shallow-merges the persisted `components` bag over the default, so
+// a slice serialized by an older build can lack fields added since (e.g.
+// `config`, added with the two-field alias/config split). `componentsToVars`
+// calls `Object.entries(slice.config)` unconditionally, so backfill the
+// required fields and drop any non-object slice before the state reaches the
+// renderer. Spread preserves optional fields like `unlinked`.
+export function normalizeComponents(state: EditorState): EditorState {
+  const raw = state.components;
+  if (!raw || typeof raw !== 'object') return { ...state, components: {} };
+  const components: EditorState['components'] = {};
+  for (const [name, slice] of Object.entries(raw)) {
+    if (!slice || typeof slice !== 'object') continue;
+    components[name] = {
+      ...slice,
+      activeFile: typeof slice.activeFile === 'string' ? slice.activeFile : 'default',
+      aliases: slice.aliases && typeof slice.aliases === 'object' ? slice.aliases : {},
+      config: slice.config && typeof slice.config === 'object' ? slice.config : {},
+    };
+  }
+  return { ...state, components };
+}
+
 export function hydrate(): void {
   // Corrupt state, missing key, or unavailable storage all return null;
   // the editor falls through to the empty default in that case.
@@ -73,7 +95,7 @@ export function hydrate(): void {
     // Shallow-merge onto default shape so older persisted state missing
     // newly-added domain fields still loads.
     const merged = { ...emptyStateFactory(), ...(parsed as object) } as EditorState;
-    store.set(migrateGradients(merged));
+    store.set(normalizeComponents(migrateGradients(merged)));
   }
   // m13 fix: seed shadows from the DOM at hydrate time so the editor
   // captures the tokens.css baseline regardless of whether the user opens

package/src/editor/docs/CodeBlock.svelte

@@ -0,0 +1,92 @@
+<script lang="ts">
+  import hljs from 'highlight.js/lib/core';
+
+  interface Props {
+    lang?: string;
+    text: string;
+  }
+  let { lang, text }: Props = $props();
+
+  function escapeHtml(s: string): string {
+    return s
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+
+  let resolvedLang = $derived(lang && hljs.getLanguage(lang) ? lang : null);
+  let highlighted = $derived.by(() => {
+    if (!resolvedLang) return escapeHtml(text);
+    try {
+      return hljs.highlight(text, { language: resolvedLang, ignoreIllegals: true }).value;
+    } catch {
+      return escapeHtml(text);
+    }
+  });
+</script>
+
+<div class="code-block">
+  <pre><code class="hljs">{@html highlighted}</code></pre>
+  {#if lang}
+    <span class="lang-tag">{lang}</span>
+  {/if}
+</div>
+
+<style>
+  .code-block {
+    position: relative;
+    margin: 0 0 var(--space-20, 1.25rem);
+    background: var(--surface-neutral-lower, #162027);
+    border: var(--border-width-1, 1px) solid var(--border-neutral-subtle, #3a4146);
+    border-radius: var(--radius-xl, 0.5rem);
+    overflow: hidden;
+  }
+
+  pre {
+    margin: 0;
+    padding: var(--space-16, 1rem) var(--space-20, 1.25rem);
+    overflow-x: auto;
+    font-size: var(--font-size-sm, 0.875rem);
+    line-height: var(--line-height-md, 1.6);
+  }
+
+  pre code {
+    font-family: var(--font-mono, ui-monospace, monospace);
+    background: none;
+    color: var(--text-primary, #fff);
+    padding: 0;
+    border: 0;
+    white-space: pre;
+  }
+
+  .lang-tag {
+    position: absolute;
+    top: 0;
+    right: 0;
+    padding: var(--space-4, 0.25rem) var(--space-12, 0.75rem);
+    font-family: var(--font-mono, ui-monospace, monospace);
+    font-size: var(--font-size-xs, 0.75rem);
+    color: var(--text-tertiary, #7e8285);
+    text-transform: uppercase;
+    letter-spacing: var(--letter-spacing-wider, 0.06em);
+    background: color-mix(in srgb, var(--surface-neutral-lowest, #040c13) 60%, transparent);
+    border-left: var(--border-width-1, 1px) solid var(--border-neutral-faint, #1c2327);
+    border-bottom: var(--border-width-1, 1px) solid var(--border-neutral-faint, #1c2327);
+    border-radius: 0 var(--radius-xl, 0.5rem) 0 var(--radius-md, 0.25rem);
+    pointer-events: none;
+  }
+
+  /* highlight.js token overrides keyed to design-system tokens */
+  pre code :global(.hljs-keyword),
+  pre code :global(.hljs-built_in) { color: var(--text-brand, #ff75b1); }
+  pre code :global(.hljs-string)   { color: var(--text-accent, #009d9a); }
+  pre code :global(.hljs-comment)  { color: var(--text-tertiary, #7e8285); font-style: italic; }
+  pre code :global(.hljs-number)   { color: var(--text-brand-secondary, #df2d88); }
+  pre code :global(.hljs-title),
+  pre code :global(.hljs-title.function_),
+  pre code :global(.hljs-attr)     { color: var(--text-secondary, #c2cacf); }
+  pre code :global(.hljs-name),
+  pre code :global(.hljs-variable) { color: var(--text-primary, #fff); }
+  pre code :global(.hljs-tag),
+  pre code :global(.hljs-meta)     { color: var(--text-accent-secondary, #1f7673); }
+</style>