@motion-proto/live-tokens 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +86 -78
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,60 +1,26 @@
1
1
  # Live Tokens
2
2
 
3
- A Svelte + Vite design-token system with an in-browser editor. It ships two ways:
3
+ A foundational design system for quickly styling and building Svelte 4 + Vite microsites. **Edit your tokens and components in real time** — colors, typography, spacing, per-component aliases — and see the site update as you drag the slider. Save the result as a portable configuration you can carry from project to project.
4
4
 
5
- 1. **Starter.** Clone the repo, replace `Home.svelte` with your app, edit tokens live.
6
- 2. **Library.** `npm install @motion-proto/live-tokens` into an existing Svelte app and import the overlay plus the editor.
7
-
8
- Both modes are supported and maintained together.
5
+ `npm install @motion-proto/live-tokens` into your app — install once, style fast. The editor is dev-only; production builds get plain CSS variables and your chosen components, nothing else.
9
6
 
10
7
  ## What you get
11
8
 
12
- - **Design-token editor** at `/editor` (dev-only). Edit colors, typography, spacing, radii, shadows, and motion; the whole site updates live.
13
- - **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.
14
- - **Page Source button.** Jumps straight to the current page's Svelte file in VS Code (`vscode://` link).
15
- - **Component library** at `/components`: Button, Card, Dialog, Badge, Tabs, Tooltip, Toggle, and more. Extendable with your own sections.
16
- - **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.
17
-
18
- ## Use as a starter
19
-
20
- ```bash
21
- npx degit motionproto/live-tokens my-app
22
- cd my-app
23
- npm install
24
- npm run dev
25
- ```
26
-
27
- 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.
28
-
29
- ### Starter layout
9
+ - **Real-time token editing.** Pick a color, drag a hue slider, retype a font size — the page repaints on every input event via CSS-variable writes. No reload, no save-and-refresh, no build step. Works across colors, typography, spacing, radii, shadows, motion, palettes, and gradients.
10
+ - **Real-time component editing.** Each of ~19 shipped Svelte components (Button, Card, Dialog, Badge, Callout, Table, Tooltip, Toggle, Tabs, SegmentedControl, ProgressBar, CornerBadge, SectionDivider, CollapsibleSection, and more) declares its own design-token aliases in a `:global(:root)` block. Rewire any alias from a per-component picker and see that component update everywhere it's used — live, on your real pages, not in a Storybook sandbox.
11
+ - **Theme editor** (`/editor` route, dev-only) — the home of real-time token editing. Save themes to disk as JSON, promote one to "production" to bake it into a static `tokens.css` for the build.
12
+ - **Per-component editor** (`/components` route, dev-only) — the home of real-time component-alias editing. Pick token aliases per component without writing CSS.
13
+ - **Live editor overlay** — pins to the top-right of every dev page. Opens the editor in a side panel or floating window so you edit *on the page you're styling*, not in a separate tab. Includes a "Page Source" button that opens the current page's `.svelte` file in VS Code.
14
+ - **Preset bundles** — capture a whole site configuration (active theme + every component's active config) as a single portable artifact. Drop a preset into a new project to restore the full styling in one step.
15
+ - **Vite plugin** — hosts the `/api/themes/*`, `/api/component-configs/*`, and `/api/presets/*` routes that persist your edits to disk as you make them.
30
16
 
31
- - `src/pages/Home.svelte`. Your app's `/` route. **Replace this with your content.**
32
- - `src/pages/Demo.svelte`. `/demo` route. Marketing/demo page for the kit itself. Safe to delete once you don't need it.
33
- - `src/pages/Editor.svelte`. `/editor` route. Design-system editor.
34
- - `src/pages/ComponentEditorPage.svelte`. `/components` route. Component editor.
35
- - `src/App.svelte`. Top-level router and overlay wiring.
36
- - `src/components/`. Reusable components.
37
- - `src/component-editor/`. Per-component editors plus shared scaffolding.
38
- - `src/ui/`. Neutral editor UI primitives and the design-system editor surfaces.
39
- - `src/lib/`. Overlay, router, token persistence, color helpers.
40
- - `src/styles/tokens.css`. The generated CSS variables (source of truth at runtime).
41
- - `themes/`. Persisted theme files. `_active.json` is the theme loaded on dev. `_production.json` is the theme synced to CSS on "promote."
42
-
43
- ### How the editor ships changes to prod (starter)
44
-
45
- 1. Edit in `/editor`. The overlay writes to the active theme file in `themes/`.
46
- 2. Promote a theme to "production." Its variables are written into `src/styles/tokens.css` and backed up under `src/styles/_backups/`.
47
- 3. `npm run build` bundles that CSS file as-is.
48
-
49
- ## Use as a library
50
-
51
- Install into an existing Svelte 4 + Vite project:
17
+ ## Quick install
52
18
 
53
19
  ```bash
54
20
  npm install @motion-proto/live-tokens
55
21
  ```
56
22
 
57
- ### Wire it into your Vite config
23
+ ### Vite config
58
24
 
59
25
  ```ts
60
26
  // vite.config.ts
@@ -78,18 +44,31 @@ export default defineConfig({
78
44
 
79
45
  The `themeFileApi` plugin:
80
46
  - Seeds `themes/` with a default theme on first dev-server start.
81
- - Hosts the `/api/*` routes the editor uses to save and load themes.
82
- - 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.
47
+ - Discovers components at `src/components/*.svelte` and seeds `component-configs/{comp}/default.json` from each component's `:global(:root)` block.
48
+ - Hosts the `/api/*` routes the editor uses to save and load themes + per-component configs.
49
+ - Auto-injects `__PROJECT_ROOT__` for the overlay's "Page Source" link.
83
50
 
84
51
  ### Bootstrap in `main.ts`
85
52
 
86
53
  ```ts
87
- import { configureEditor, initializeTheme } from '@motion-proto/live-tokens';
54
+ import './styles/tokens.css';
55
+ import {
56
+ configureEditor,
57
+ initializeTheme,
58
+ initCssVarSync,
59
+ initRouter,
60
+ initColumnsOverlay,
61
+ initEditorStore,
62
+ } from '@motion-proto/live-tokens';
88
63
  import App from './App.svelte';
89
64
 
90
65
  configureEditor({ storagePrefix: 'my-app-' });
91
66
 
92
67
  async function boot() {
68
+ initCssVarSync();
69
+ initRouter();
70
+ initColumnsOverlay();
71
+ initEditorStore();
93
72
  if (import.meta.env.DEV) {
94
73
  await initializeTheme();
95
74
  }
@@ -99,13 +78,14 @@ async function boot() {
99
78
  boot();
100
79
  ```
101
80
 
102
- ### Mount the overlay + editor route
81
+ ### Mount overlay + editor pages
103
82
 
104
83
  ```svelte
105
84
  <!-- App.svelte -->
106
85
  <script lang="ts">
107
86
  import { LiveEditorOverlay, ColumnsOverlay } from '@motion-proto/live-tokens';
108
87
  import Editor from '@motion-proto/live-tokens/editor';
88
+ import ComponentEditorPage from '@motion-proto/live-tokens/component-editor-page';
109
89
  import { route } from './router';
110
90
  </script>
111
91
 
@@ -116,64 +96,92 @@ boot();
116
96
  ]}
117
97
  pageSources={{
118
98
  '/': 'src/pages/Home.svelte',
119
- '/components': 'src/pages/ComponentsPage.svelte',
120
99
  }}
121
100
  />
122
101
  <ColumnsOverlay />
123
102
 
124
103
  {#if $route === '/editor'}
125
104
  <Editor />
105
+ {:else if $route === '/components'}
106
+ <ComponentEditorPage />
126
107
  {:else}
127
108
  <!-- your routes -->
128
109
  {/if}
129
110
  ```
130
111
 
131
- `<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.
112
+ `<LiveEditorOverlay />` self-gates: it only renders in dev, never inside an iframe, and never on the editor route. No need to wrap in `{#if import.meta.env.DEV}` guards.
113
+
114
+ ### Use components
115
+
116
+ ```svelte
117
+ <script lang="ts">
118
+ import Button from '@motion-proto/live-tokens/components/Button.svelte';
119
+ import Callout from '@motion-proto/live-tokens/components/Callout.svelte';
120
+ </script>
121
+
122
+ <Callout variant="info">Read this.</Callout>
123
+ <Button variant="primary">Save</Button>
124
+ ```
125
+
126
+ The components carry their own design-token aliases (declared inside each `.svelte` file). They'll pick up your `tokens.css` overrides automatically. Strip out the ones you don't use; nothing is forced.
132
127
 
133
128
  ### Styles
134
129
 
135
130
  ```ts
136
- // main.ts — or wherever you import global styles
137
131
  import '@motion-proto/live-tokens/styles/ui-editor.css';
138
132
  import '@motion-proto/live-tokens/styles/form-controls.css';
139
133
  import '@motion-proto/live-tokens/styles/fonts.css';
140
134
  ```
141
135
 
142
- ### Add your own components to the editor
136
+ You'll also need your own `src/styles/tokens.css` declaring your design tokens as CSS variables on `:root`. Start from the package's default (`node_modules/@motion-proto/live-tokens/src/styles/tokens.css`) and overlay your overrides — or let the editor seed `themes/default.json` on first run and promote it.
143
137
 
144
- ```svelte
145
- <!-- src/pages/ComponentsPage.svelte -->
146
- <script lang="ts">
147
- import { ComponentsTab, defaultSections, type ComponentSection } from '@motion-proto/live-tokens/component-editor';
148
- import '@motion-proto/live-tokens/styles/ui-editor.css';
149
- import MyWidgetEditor from '../components/MyWidgetEditor.svelte';
150
-
151
- const mySections: ComponentSection[] = [
152
- { id: 'myWidget', label: 'My Widget', component: MyWidgetEditor },
153
- ];
154
- const allSections = [...defaultSections, ...mySections];
155
- </script>
138
+ ## Greenfield? Use the starter
139
+
140
+ 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.
156
141
 
157
- <ComponentsTab sections={allSections} />
142
+ ```bash
143
+ npx degit motionproto/live-tokens my-app
144
+ cd my-app
145
+ npm install
146
+ npm run dev
158
147
  ```
159
148
 
160
- ## Publishing
149
+ Open http://localhost:5173 and replace `src/pages/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.
161
150
 
162
- The package is published to npm as `@motion-proto/live-tokens`.
151
+ ## How the editor ships changes to prod
163
152
 
164
- 1. Bump the version in `package.json`.
165
- 2. Verify the tarball contents: `npm pack --dry-run`.
166
- 3. `npm publish --access public`. `prepublishOnly` rebuilds `dist-plugin/`.
167
- 4. Tag and push: `git tag v0.2.0 && git push origin main --tags`.
153
+ 1. Edit in `/editor` or `/components`. Saves write to `themes/{name}.json` and `component-configs/{comp}/{name}.json`.
154
+ 2. Promote a theme to "production." Its variables are written into `src/styles/tokens.css` and backed up under `src/styles/_backups/`.
155
+ 3. `npm run build` bundles `tokens.css` as plain CSS. No editor code, no JSON lookups, no dev surfaces ship to prod.
156
+
157
+ ## File ownership — what the plugin writes
158
+
159
+ Knowing which files the plugin touches matters when upgrading the package or working in a repo you don't want overwritten.
160
+
161
+ **On `npm install` or `npm update`: nothing outside `node_modules/`.** No install hooks. Upgrading versions never touches your `themes/`, `component-configs/`, `presets/`, or any file in `src/`.
168
162
 
169
- **What ships:**
163
+ **At dev-server startup, the plugin only fills gaps — it never overwrites authored files:**
170
164
 
171
- - `src/lib/`, `src/ui/`, `src/component-editor/`, `src/components/`
172
- - `src/pages/Editor.svelte` + `Editor.svelte.d.ts`
173
- - `src/styles/ui-editor.css`, `src/styles/form-controls.css`, `src/styles/fonts.css`, `src/styles/fonts/`
174
- - `dist-plugin/`. Compiled Vite plugin.
165
+ - `themes/default.json` — written **only if missing**.
166
+ - `themes/_active.json` and `themes/_production.json` — written **only if missing**.
167
+ - `component-configs/{comp}/_active.json` and `_production.json` — same: only if missing.
168
+ - `component-configs/{comp}/default.json` — regenerated from the component's `:global(:root)` block **only when the `.svelte` source is newer than the existing default**. This file is a build artifact of the source; don't hand-edit it.
175
169
 
176
- **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/`.
170
+ **At dev-time editor actions, these files get rewritten by your explicit save/promote:**
171
+
172
+ - `themes/{name}.json` — every save in the editor.
173
+ - `src/styles/tokens.css` — fully regenerated when you save or promote the production theme. **Treat this as a build artifact.** Hand-edits get clobbered next time the production theme is saved; promote a theme instead.
174
+ - `src/styles/fonts.css` — same rule: regenerated from the theme's font sources.
175
+ - `component-configs/{comp}/{name}.json` — every save of a per-component config.
176
+
177
+ ## Maintainer notes — publishing
178
+
179
+ The package publishes to npm as `@motion-proto/live-tokens`.
180
+
181
+ 1. Bump the version in `package.json`.
182
+ 2. Verify tarball contents: `npm pack --dry-run`.
183
+ 3. `npm publish`. `prepublishOnly` rebuilds `dist-plugin/`.
184
+ 4. Tag and push: `git tag vX.Y.Z && git push origin main vX.Y.Z`.
177
185
 
178
186
  ## License
179
187
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@motion-proto/live-tokens",
3
- "version": "0.3.1",
3
+ "version": "0.3.2",
4
4
  "type": "module",
5
5
  "description": "Design token editor with live CSS variable editing. Svelte 4 + Vite.",
6
6
  "keywords": [