@motion-proto/live-tokens 0.1.1 → 0.3.1

package/README.md

@@ -1,40 +1,179 @@
 # Live Tokens
 
-A starter Svelte + Vite site with a full design-token system and an in-browser editor.
+A Svelte + Vite design-token system with an in-browser editor. It ships two ways:
+
+1. **Starter.** Clone the repo, replace `Home.svelte` with your app, edit tokens live.
+2. **Library.** `npm install @motion-proto/live-tokens` into an existing Svelte app and import the overlay plus the editor.
+
+Both modes are supported and maintained together.
 
 ## What you get
 
-- **Design-token admin panel** at `/admin` (dev-only). Edit colors, typography, spacing, radii, shadows, and motion, and see the whole site update live.
-- **Live editor overlay** pinned to the top-right of every page in dev. Opens the token editor in a side panel or floating window without leaving the page you're styling.
-- **Page Source** button — jumps straight to the current page's Svelte file in VS Code (`vscode://` link).
-- **Component library** at `/components`: Button, Card, Dialog, Badge, Tabs, Tooltip, Toggle, and more.
-- **Token persistence**: each saved palette is a JSON file in `tokens/`. The active palette syncs into `src/styles/variables.css` on save, so production builds ship pure CSS.
+- **Design-token editor** at `/editor` (dev-only). Edit colors, typography, spacing, radii, shadows, and motion; the whole site updates live.
+- **Live editor overlay** pinned to the top-right in dev. Opens the editor in a side panel or a floating window without leaving the page you're styling.
+- **Page Source button.** Jumps straight to the current page's Svelte file in VS Code (`vscode://` link).
+- **Component library** at `/components`: Button, Card, Dialog, Badge, Tabs, Tooltip, Toggle, and more. Extendable with your own sections.
+- **Theme persistence.** Each saved palette is a JSON file in `themes/`. The active palette syncs into `src/styles/tokens.css` on save, so production builds ship pure CSS. No editor code, no JSON lookups in the prod bundle.
 
-## Quick start
+## Use as a starter
 
 ```bash
+npx degit motionproto/live-tokens my-app
+cd my-app
 npm install
 npm run dev
 ```
 
-Open http://localhost:5173. The editor overlay sits in the top-right corner. Click **Editor** to expand it, or hit **Fullscreen** to jump to `/admin`.
+Open http://localhost:5173. Replace `src/pages/Home.svelte` with your own landing page. Keep or delete `src/pages/Demo.svelte` (the `/demo` route) depending on whether you want the demo around as a reference.
+
+### Starter layout
+
+- `src/pages/Home.svelte`. Your app's `/` route. **Replace this with your content.**
+- `src/pages/Demo.svelte`. `/demo` route. Marketing/demo page for the kit itself. Safe to delete once you don't need it.
+- `src/pages/Editor.svelte`. `/editor` route. Design-system editor.
+- `src/pages/ComponentEditorPage.svelte`. `/components` route. Component editor.
+- `src/App.svelte`. Top-level router and overlay wiring.
+- `src/components/`. Reusable components.
+- `src/component-editor/`. Per-component editors plus shared scaffolding.
+- `src/ui/`. Neutral editor UI primitives and the design-system editor surfaces.
+- `src/lib/`. Overlay, router, token persistence, color helpers.
+- `src/styles/tokens.css`. The generated CSS variables (source of truth at runtime).
+- `themes/`. Persisted theme files. `_active.json` is the theme loaded on dev. `_production.json` is the theme synced to CSS on "promote."
+
+### How the editor ships changes to prod (starter)
+
+1. Edit in `/editor`. The overlay writes to the active theme file in `themes/`.
+2. Promote a theme to "production." Its variables are written into `src/styles/tokens.css` and backed up under `src/styles/_backups/`.
+3. `npm run build` bundles that CSS file as-is.
+
+## Use as a library
+
+Install into an existing Svelte 4 + Vite project:
+
+```bash
+npm install @motion-proto/live-tokens
+```
+
+### Wire it into your Vite config
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import { themeFileApi } from '@motion-proto/live-tokens/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    svelte(),
+    themeFileApi({
+      themesDir: 'themes',
+      tokensCssPath: 'src/styles/tokens.css',
+    }),
+  ],
+  optimizeDeps: {
+    exclude: ['@motion-proto/live-tokens'],
+  },
+});
+```
+
+The `themeFileApi` plugin:
+- Seeds `themes/` with a default theme on first dev-server start.
+- Hosts the `/api/*` routes the editor uses to save and load themes.
+- Auto-injects `__PROJECT_ROOT__` so the overlay's "Page Source" link can open files in VS Code. You don't need a `define` entry for this.
+
+### Bootstrap in `main.ts`
+
+```ts
+import { configureEditor, initializeTheme } from '@motion-proto/live-tokens';
+import App from './App.svelte';
+
+configureEditor({ storagePrefix: 'my-app-' });
+
+async function boot() {
+  if (import.meta.env.DEV) {
+    await initializeTheme();
+  }
+  new App({ target: document.getElementById('app')! });
+}
+
+boot();
+```
+
+### Mount the overlay + editor route
+
+```svelte
+<!-- App.svelte -->
+<script lang="ts">
+  import { LiveEditorOverlay, ColumnsOverlay } from '@motion-proto/live-tokens';
+  import Editor from '@motion-proto/live-tokens/editor';
+  import { route } from './router';
+</script>
+
+<LiveEditorOverlay
+  navLinks={[
+    { path: '/', label: 'Home', icon: 'fa-home' },
+    { path: '/components', label: 'Components', icon: 'fa-puzzle-piece' },
+  ]}
+  pageSources={{
+    '/': 'src/pages/Home.svelte',
+    '/components': 'src/pages/ComponentsPage.svelte',
+  }}
+/>
+<ColumnsOverlay />
+
+{#if $route === '/editor'}
+  <Editor />
+{:else}
+  <!-- your routes -->
+{/if}
+```
+
+`<LiveEditorOverlay />` self-gates: it only renders in dev, never inside an iframe, and never when the user is on `editorPath` (defaults to `/editor`). You don't need to wrap it in `{#if import.meta.env.DEV}` guards.
+
+### Styles
+
+```ts
+// main.ts — or wherever you import global styles
+import '@motion-proto/live-tokens/styles/ui-editor.css';
+import '@motion-proto/live-tokens/styles/form-controls.css';
+import '@motion-proto/live-tokens/styles/fonts.css';
+```
+
+### Add your own components to the editor
+
+```svelte
+<!-- src/pages/ComponentsPage.svelte -->
+<script lang="ts">
+  import { ComponentsTab, defaultSections, type ComponentSection } from '@motion-proto/live-tokens/component-editor';
+  import '@motion-proto/live-tokens/styles/ui-editor.css';
+  import MyWidgetEditor from '../components/MyWidgetEditor.svelte';
+
+  const mySections: ComponentSection[] = [
+    { id: 'myWidget', label: 'My Widget', component: MyWidgetEditor },
+  ];
+  const allSections = [...defaultSections, ...mySections];
+</script>
+
+<ComponentsTab sections={allSections} />
+```
+
+## Publishing
+
+The package is published to npm as `@motion-proto/live-tokens`.
 
-## Layout
+1. Bump the version in `package.json`.
+2. Verify the tarball contents: `npm pack --dry-run`.
+3. `npm publish --access public`. `prepublishOnly` rebuilds `dist-plugin/`.
+4. Tag and push: `git tag v0.2.0 && git push origin main --tags`.
 
-- `src/pages/Landing.svelte` — the welcome page (replace this with your site)
-- `src/pages/Admin.svelte` — design-system editor
-- `src/pages/ShowcasePage.svelte` — component showcase
-- `src/components/` — the reusable components
-- `src/showcase/` — the editor UI (tabs, palette editors, curve editor, backup browser)
-- `src/lib/` — the overlay, router glue, token persistence, and color helpers
-- `src/styles/variables.css` — the generated CSS variables (this is the source of truth at runtime)
-- `tokens/` — persisted palette files; `_active.json` selects the palette loaded on dev, `_production.json` selects the palette synced to CSS
+**What ships:**
 
-## How the editor ships changes to prod
+- `src/lib/`, `src/ui/`, `src/component-editor/`, `src/components/`
+- `src/pages/Editor.svelte` + `Editor.svelte.d.ts`
+- `src/styles/ui-editor.css`, `src/styles/form-controls.css`, `src/styles/fonts.css`, `src/styles/fonts/`
+- `dist-plugin/`. Compiled Vite plugin.
 
-1. Edit in `/admin` → the overlay writes to the active JSON file in `tokens/`.
-2. When you promote a palette to "production", its variables are written into `src/styles/variables.css` and backed up under `src/styles/_backups/`.
-3. `npm run build` bundles that CSS file as-is. No token-editor code or JSON lookups in the prod bundle.
+**What doesn't ship** (starter-only): `src/App.svelte`, `src/main.ts`, `src/pages/Home.svelte`, `src/pages/Demo.svelte`, `src/pages/ComponentEditorPage.svelte`, `index.html`, `themes/`.
 
 ## License