@motion-proto/live-tokens 0.20.1 → 0.21.1

package/README.md

@@ -216,18 +216,47 @@ export default defineConfig({
 
 No `css: 'injected'` workaround, no `optimizeDeps` excludes — `vite build` works as-is. (You'll want the full `themeFileApi` plugin and `bootLiveTokens` / `<LiveTokensRouter>` from the Quick install section above when you're ready to persist edits to disk and ship a real app.)
 
-## Greenfield? Use the starter
+## Greenfield? Scaffold a new app
 
-If you're starting from scratch, skip the manual wiring and clone the repo as a template — `App.svelte`, `main.ts`, the router, and a placeholder `Home.svelte` saying "put your content here" are all pre-wired.
+If you're starting from scratch, skip the manual wiring:
 
 ```bash
-npx degit motionproto/live-tokens my-app
+npx @motion-proto/live-tokens create my-app
 cd my-app
 npm install
 npm run dev
 ```
 
-Open http://localhost:5173 and replace `src/app/Home.svelte` with your content. The rest of the wiring is already done — it's the same code the npm package ships, just with the App-shell scaffolding included.
+This generates a Svelte + Vite app that **depends on** the package — `vite.config.ts`, `main.ts`, `App.svelte`, the `themeFileApi` plugin, and a placeholder `src/pages/Home.svelte` are all pre-wired. The token CSS is seeded from the version you scaffolded against, so it never drifts. Open http://localhost:5173 and replace `Home.svelte` with your content; upgrade the package later with `npm update`.
+
+(The older `npx degit motionproto/live-tokens` route cloned this whole repo as your app — the package's source, tests, and all. `create` gives you a thin consumer app instead.)
+
+## Recommended project layout
+
+`create` scaffolds the preferred integration surface. Whether you scaffolded or wired up by hand, conforming to this layout keeps upgrades non-destructive and consistent across projects.
+
+```
+src/
+  main.ts                         # token CSS chain → bootLiveTokens(App, '#app')
+  App.svelte                      # routes (e.g. <LiveTokensRouter {pages} />)
+  pages/                          # your pages
+  styles/site.css                 # your themed page typography (yours to edit)
+  system/styles/tokens.css        # vendored Layer-1 tokens — committed
+  live-tokens/data/               # editor state — committed
+    tokens.generated.css          #   editor output
+    themes/ manifests/ component-configs/
+    **/_backups/                  #   gitignored (local-only snapshots)
+vite.config.ts                    # svelte({ preprocess: vitePreprocess() }) + themeFileApi
+svelte.config.js                  # vitePreprocess()
+```
+
+Conventions that make this work:
+
+- **Vendor `tokens.css` into `src/` and commit it.** Point `themeFileApi({ tokensCssPath })` at that file, not at one inside `node_modules`. The dev server writes your edits there; a copy under `node_modules` is wiped on every `npm install`.
+- **All editable state lives under `src/` and is committed** — `tokens.css`, `tokens.generated.css`, and everything in `live-tokens/data/`. This is the invariant that makes upgrades safe: `npm install` only ever touches `node_modules` + `package.json` + the lockfile, never your `src/`.
+- **`_backups/` is gitignored.** The dev server snapshots a file before overwriting it; those snapshots are local working state, not source.
+- **Preprocess with `vitePreprocess()`** (bundled in `@sveltejs/vite-plugin-svelte`), keeping `sass` installed for the components' `scss`. No `svelte-preprocess`, no `legacy-peer-deps` `.npmrc` — the dependency tree resolves cleanly on its own (since 0.19.1).
+- **Import only from the public surface** — `@motion-proto/live-tokens`, `/components/*`, `/vite-plugin`, `/app/*`.
 
 ## Consumer-authored components
 

package/bin/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // CLI for @motion-proto/live-tokens.
 // Subcommands:
+//   create <dir>             Scaffold a new app that depends on this package.
 //   setup-claude [--force]   Copy bundled Claude Code skills into ./.claude/skills/.
 //   check-component <id>     Validate a component against the add-component skill contract.
 
@@ -10,10 +11,13 @@ import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { checkComponent, formatReport } from './check-component.mjs';
 import { runMigrate, formatMigrateResult } from './migrate.mjs';
+import { runCreate, formatCreateResult } from './create.mjs';
 
 const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
 
 Commands:
+  create <dir> [--force]      Scaffold a new Svelte + Vite app wired up with
+                              live-tokens (editor, components, theme tokens)
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
   check-component <id>        Validate <id>'s runtime, editor, and registration
                               against the live-tokens-create-component contract
@@ -35,6 +39,24 @@ if (!command || command === '--help' || command === '-h') {
   process.exit(0);
 }
 
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+if (command === 'create' || command === 'init') {
+  const targetArg = rest.find((a) => !a.startsWith('-'));
+  if (!targetArg) {
+    fail(`Usage: npx @motion-proto/live-tokens create <project-directory>`);
+  }
+  const force = rest.includes('--force');
+  const targetDir = resolve(process.cwd(), targetArg);
+  try {
+    const result = runCreate({ targetDir, pkgRoot, force });
+    console.log(formatCreateResult(result, targetArg));
+    process.exit(0);
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+}
+
 if (command === 'check-component') {
   const id = rest[0];
   if (!id) fail(`Usage: npx @motion-proto/live-tokens check-component <id>`);
@@ -70,7 +92,6 @@ if (process.platform === 'win32') {
 
 const force = rest.includes('--force');
 
-const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const srcSkills = join(pkgRoot, '.claude', 'skills');
 
 if (!existsSync(srcSkills)) {

package/bin/create.mjs

@@ -0,0 +1,89 @@
+// `create` subcommand: scaffold a new Svelte + Vite app that depends on the
+// published package. Extracted from cli.mjs so it can be unit-tested.
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+// npm strips dotfiles from published tarballs, so the template ships them
+// renamed; `create` restores the leading dot on scaffold.
+const DOTFILES = [['_gitignore', '.gitignore']];
+
+// Seeded from THIS installed package (src → scaffold) so the generated app's
+// token/theme CSS never drifts from the version it was created against.
+const SEEDS = [
+  ['src/system/styles/tokens.css', 'src/system/styles/tokens.css'],
+  ['src/live-tokens/data/tokens.generated.css', 'src/live-tokens/data/tokens.generated.css'],
+  ['src/app/site.css', 'src/styles/site.css'],
+];
+
+const PLACEHOLDER_FILES = ['package.json', 'index.html', 'README.md'];
+
+export function appNameFrom(targetDir) {
+  return (
+    (targetDir.split(/[/\\]/).filter(Boolean).pop() || '')
+      .replace(/[^a-z0-9._-]+/gi, '-')
+      .replace(/^[-.]+|[-.]+$/g, '')
+      .toLowerCase() || 'live-tokens-app'
+  );
+}
+
+export function runCreate({ targetDir, pkgRoot, force = false }) {
+  const templateDir = join(pkgRoot, 'template');
+  if (!existsSync(templateDir)) {
+    throw new Error(`Template not found at ${templateDir}. Is the package installed correctly?`);
+  }
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !force) {
+    throw new Error(`${targetDir} is not empty. Pass --force to scaffold into it anyway.`);
+  }
+
+  const appName = appNameFrom(targetDir);
+  const ltVersion = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+
+  cpSync(templateDir, targetDir, { recursive: true });
+
+  for (const [from, to] of DOTFILES) {
+    const src = join(targetDir, from);
+    if (existsSync(src)) renameSync(src, join(targetDir, to));
+  }
+
+  for (const [srcRel, destRel] of SEEDS) {
+    const src = join(pkgRoot, srcRel);
+    const dest = join(targetDir, destRel);
+    mkdirSync(dirname(dest), { recursive: true });
+    if (existsSync(src)) cpSync(src, dest);
+    else writeFileSync(dest, '');
+  }
+
+  for (const rel of PLACEHOLDER_FILES) {
+    const p = join(targetDir, rel);
+    if (!existsSync(p)) continue;
+    const filled = readFileSync(p, 'utf8')
+      .replaceAll('__APP_NAME__', appName)
+      .replaceAll('__LT_VERSION__', `^${ltVersion}`);
+    writeFileSync(p, filled);
+  }
+
+  return { appName, targetDir: resolve(targetDir), ltVersion };
+}
+
+export function formatCreateResult({ appName, targetDir }, targetArg) {
+  return [
+    ``,
+    `Scaffolded ${appName} → ${targetDir}`,
+    ``,
+    `Next steps:`,
+    `  cd ${targetArg}`,
+    `  npm install`,
+    `  npm run dev`,
+    ``,
+    `Then open http://localhost:5173 and edit src/pages/Home.svelte.`,
+  ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -26,6 +26,7 @@
     "dist-plugin",
     ".claude/skills",
     "bin",
+    "template",
     "!**/*.test.ts",
     "!**/*.spec.ts",
     "!**/__tests__/**",
@@ -89,7 +90,8 @@
     "check:no-style-imports": "node scripts/check-no-style-imports.mjs",
     "check:editor-font-isolation": "node scripts/check-editor-font-isolation.mjs",
     "check:smoke-install": "bash scripts/smoke-install.sh",
-    "prepublishOnly": "npm run check:no-style-imports && npm run check:editor-font-isolation && npm run build:lib && npm run check:smoke-install"
+    "check:smoke-create": "bash scripts/smoke-create.sh",
+    "prepublishOnly": "npm run check:no-style-imports && npm run check:editor-font-isolation && npm run build:lib && npm run check:smoke-install && npm run check:smoke-create"
   },
   "peerDependencies": {
     "@sveltejs/vite-plugin-svelte": "^7.0",

package/template/README.md

@@ -0,0 +1,38 @@
+# __APP_NAME__
+
+Scaffolded with [`@motion-proto/live-tokens`](https://github.com/motionproto/live-tokens).
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:5173.
+
+## What you have
+
+This project follows the package's [recommended layout](https://github.com/motionproto/live-tokens#recommended-project-layout): all editable state lives under `src/` and is committed, so `npm install` and upgrades never touch your styles.
+
+- `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.
+- `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.
+
+## Editing live
+
+Run `npm run dev`, then click **Open Token Editor** on the home page (or visit
+`/editor`). Changes persist to `src/system/styles/tokens.css` and the JSON under
+`src/live-tokens/data/`. The editor is dev-only — `npm run build` ships plain
+CSS variables and the components you used, nothing else.
+
+## Adding components
+
+The package ships ~25 editable components (Button, Card, Table, Dialog, …).
+Import them from `@motion-proto/live-tokens/components/<Name>.svelte`. To author
+your own editable component, install the Claude Code skills:
+
+```bash
+npx @motion-proto/live-tokens setup-claude
+```

package/template/_gitignore

@@ -0,0 +1,15 @@
+node_modules
+dist
+dist-ssr
+*.local
+*.log
+
+# Editor-written backups stay local to each machine; the live JSON/CSS commit.
+src/live-tokens/data/themes/_backups/
+src/live-tokens/data/manifests/_backups/
+src/live-tokens/data/component-configs/*/_backups/
+src/system/styles/_backups/
+
+.DS_Store
+.vscode/*
+!.vscode/extensions.json

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__APP_NAME__</title>
+  </head>
+  <body style="margin: 0;">
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-check --tsconfig ./tsconfig.json"
+  },
+  "dependencies": {
+    "@motion-proto/live-tokens": "__LT_VERSION__"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@types/node": "^25.9.1",
+    "sass": "^1.98.0",
+    "svelte": "^5.55.5",
+    "svelte-check": "^4.4.8",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.14"
+  }
+}

package/template/src/App.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+  import { LiveTokensRouter } from '@motion-proto/live-tokens';
+
+  // <LiveTokensRouter> owns the dev-only /editor and /components routes.
+  // Declare your own pages here. Lazy imports keep each page's CSS
+  // side-effects out of the editor routes; omit `label` to keep a route
+  // reachable by URL but hidden from the overlay nav rail.
+  const pages = {
+    '/': {
+      lazy: () => import('./pages/Home.svelte'),
+      label: 'Home',
+      icon: 'fa-home',
+      source: 'src/pages/Home.svelte',
+    },
+  };
+</script>
+
+<LiveTokensRouter {pages} />

package/template/src/main.ts

@@ -0,0 +1,12 @@
+// Token CSS order matters: defaults → editor overrides → fonts. The first two
+// are project-local (the dev plugin writes to them); fonts ship with the package.
+import './system/styles/tokens.css';
+import './live-tokens/data/tokens.generated.css';
+import '@motion-proto/live-tokens/app/fonts.css';
+
+import { bootLiveTokens, configureEditor } from '@motion-proto/live-tokens';
+import App from './App.svelte';
+
+configureEditor({ storagePrefix: 'app-' });
+
+bootLiveTokens(App, '#app');

package/template/src/pages/Home.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+  // site.css carries themed page typography (bare h1/p/a rules that consume
+  // theme tokens). Imported per-page, not globally, so the editor routes stay
+  // theme-immune. It's yours to edit — see src/styles/site.css.
+  import '../styles/site.css';
+  import Card from '@motion-proto/live-tokens/components/Card.svelte';
+  import Button from '@motion-proto/live-tokens/components/Button.svelte';
+  import { navigate } from '@motion-proto/live-tokens';
+
+  const isDev = import.meta.env.DEV;
+</script>
+
+<div class="home">
+  <section class="stub">
+    <Card>
+      <span class="eyebrow">Your app lives here</span>
+      <h1>Home</h1>
+      <p>
+        Replace this with your own content. Edit <code>src/pages/Home.svelte</code>
+        to get started, or add routes in <code>src/App.svelte</code>. Components
+        and theme tokens are editable live while <code>npm run dev</code> is running.
+      </p>
+      {#if isDev}
+        <div class="actions">
+          <Button on:click={() => navigate('/editor')}>Open Token Editor</Button>
+          <Button variant="secondary" on:click={() => navigate('/components')}>Components</Button>
+        </div>
+      {/if}
+    </Card>
+  </section>
+</div>
+
+<style>
+  .home {
+    display: grid;
+    grid-template-columns: repeat(var(--columns-count), 1fr);
+    column-gap: var(--columns-gutter);
+    max-width: var(--columns-max-width);
+    margin: 0 auto;
+    padding: var(--space-48) var(--space-32);
+    min-height: 100vh;
+    align-content: center;
+  }
+
+  .stub {
+    grid-column: 4 / span 6;
+  }
+
+  .eyebrow {
+    display: block;
+    font-size: var(--font-size-sm);
+    font-weight: var(--font-weight-normal);
+    text-transform: uppercase;
+    color: var(--text-tertiary);
+    margin-bottom: var(--space-8);
+  }
+
+  h1 {
+    font-family: var(--font-display);
+    font-size: var(--font-size-4xl);
+    color: var(--text-primary);
+    margin: 0 0 var(--space-12);
+  }
+
+  p {
+    color: var(--text-secondary);
+    line-height: 1.6;
+  }
+
+  code {
+    background: var(--surface-neutral-high);
+    padding: 2px 6px;
+    border-radius: var(--radius-sm);
+    font-family: var(--font-mono, monospace);
+    font-size: 0.9em;
+  }
+
+  .actions {
+    display: flex;
+    gap: var(--space-12);
+    flex-wrap: wrap;
+    margin-top: var(--space-20);
+  }
+</style>

package/template/src/vite-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="svelte" />
+/// <reference types="vite/client" />

package/template/svelte.config.js

@@ -0,0 +1,6 @@
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import("@sveltejs/vite-plugin-svelte").SvelteConfig} */
+export default {
+  preprocess: vitePreprocess(),
+};

package/template/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.svelte"]
+}

package/template/vite.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vite';
+import { svelte, vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+import { themeFileApi } from '@motion-proto/live-tokens/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    svelte({ preprocess: vitePreprocess() }),
+    // Dev-only: persists editor changes to src/system/styles/tokens.css and
+    // the JSON under src/live-tokens/data/. No effect on `vite build`.
+    themeFileApi({ tokensCssPath: 'src/system/styles/tokens.css' }),
+  ],
+});