@motion-proto/live-tokens 0.21.0 → 0.21.2

package/README.md

@@ -231,6 +231,33 @@ This generates a Svelte + Vite app that **depends on** the package — `vite.con
 
 (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
 
 The shipped components are first-party by default, but you can author your own and get the same real-time editing experience. Co-locate runtime and editor files in `src/components/` (or `src/system/components/`, both are scanned by default) and pass them to `bootLiveTokens`:

package/bin/create.mjs

@@ -11,6 +11,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 // npm strips dotfiles from published tarballs, so the template ships them
 // renamed; `create` restores the leading dot on scaffold.
@@ -87,3 +88,12 @@ export function formatCreateResult({ appName, targetDir }, targetArg) {
     `Then open http://localhost:5173 and edit src/pages/Home.svelte.`,
   ].join('\n');
 }
+
+// Entry point for the `@motion-proto/create-live-tokens` initializer: it
+// derives pkgRoot from this module's own location (i.e. wherever this package
+// is installed), so the template + seed CSS always come from this exact
+// version. The initializer stays a thin shim with no template of its own.
+export function createApp({ targetDir, force = false } = {}) {
+  const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  return runCreate({ targetDir, pkgRoot, force });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -42,6 +42,7 @@
       "types": "./src/editor/index.ts",
       "default": "./src/editor/index.ts"
     },
+    "./create": "./bin/create.mjs",
     "./component-editor": {
       "svelte": "./src/editor/component-editor/index.ts",
       "types": "./src/editor/component-editor/index.ts",

package/template/README.md

@@ -11,6 +11,8 @@ 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.