@motion-proto/live-tokens 0.69.0 → 0.70.0

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

@@ -7,7 +7,7 @@ description: Apply the @motion-proto/live-tokens project conventions when buildi
 
 Two rules above all else:
 
-1. **Use a shipped component if one fits.** Import from `@motion-proto/live-tokens/components/<Name>.svelte`. See **live-tokens-pick-component** for the catalogue and the confusing-pair decisions. Pass only the props its `interface Props` declares, with variant and size values from its union: a prop it does not declare is dropped silently at runtime, and the checker reports it. Author custom markup only when nothing fits, and then consider **live-tokens-create-component** so the new piece is editable too.
+1. **Use a shipped component if one fits.** Import from `@motion-proto/live-tokens/components/<Name>.svelte`. See **live-tokens-pick-component** for the catalogue and the confusing-pair decisions. Pass only the props it declares, with variant and size values from its union: `npx live-tokens components <id>` prints them (`--json` for data), and the list includes the project's own components beside the shipped ones. A prop a component does not declare is dropped silently at runtime, and the checker reports it. Author custom markup only when nothing fits, and then consider **live-tokens-create-component** so the new piece is editable too.
 2. **Use theme tokens for every value.** Every color, spacing, radius, font-size, and font-family in page CSS is a `var(--token-*)`, whether it sits in the `<style>` block, an inline `style=` attribute, or a `style:` directive. No colour literals in any notation, `white` and `rgb()` included. No px or rem in spacing, stroke, radius, or shadow: that is the geometry the theme owns and `adjust` moves. Sizing is layout, not theme: a hero's height, a max content width, or a column's minimum width stays a literal. A change in `/live-tokens/editor` should repaint your page.
 
 For text, reach for a whole text style rather than assembling one: `--heading-xl` through `--heading-sm`, `--body-md`, `--body-sm`, `--editorial-xl` through `--editorial-sm`, `--eyebrow`, and `--code` each carry a `-font-family`, `-font-size`, `-font-weight`, `-line-height`, and `-letter-spacing`. A heading set from `--heading-lg-*` retypes when the theme's fonts change; one set from a raw `font-size` does not.

package/.claude/skills/live-tokens-create-component/SKILL.md

@@ -15,11 +15,10 @@ For pattern reference, read any shipped component's source directly from the con
   - Simplest reads (no state, no linked-block): `Card` (single variant with parts), `Badge` and `Callout` (multi-variant).
   - Multi-state (hover, disabled, focus): `Button`, `Input`.
   - Multi-part (overlay / header / body / footer): `Dialog`.
-  - Multi-variant with linked siblings (`canBeLinked` + `groupKey`): `SegmentedControl`, `TabBar`.
-  - Composes another shipped component: `CodeSnippet` (renders a `Tooltip` for the copy-confirmation popover).
+  - Multi-variant with linked siblings (`canBeLinked` + `groupKey`): `SegmentedControl`, `TabBar`. Composes another shipped component: `CodeSnippet`.
 - Editor files: `node_modules/@motion-proto/live-tokens/src/editor/component-editor/<Name>Editor.svelte`.
 
-**File-location note.** Shipped editors live in `src/editor/component-editor/` because they're library-internal. For *your* component, **co-locate** both files in `src/system/components/` per the recipe below. Read the shipped files for pattern, ignore their location.
+**File-location note.** Shipped editors live in `src/editor/component-editor/` because they're library-internal. For *your* component, **co-locate** both files in `src/system/components/`. Read the shipped files for pattern, ignore their location.
 
 ## The recipe
 
@@ -43,7 +42,15 @@ For pattern reference, read any shipped component's source directly from the con
    });
    ```
    The schema side-effect happens inside `registerComponent` (which `bootLiveTokens` calls for you), so you don't call `registerComponentSchema` separately. **Do not place a standalone `registerComponent(...)` *before* `bootLiveTokens`** — that registers before the editor's init hooks run, which is the wrong window and can leave editor changes disconnected from the live page. Only call `registerComponent` directly if your app mounts manually (no `bootLiveTokens`), in which case call it before `mount(App, ...)`.
-4. **Tell the picker** — open `.claude/skills/live-tokens-pick-component/SKILL.md` and add your new component to the **Catalogue** line under the family it belongs to (Action / Input / Selection / Containers / Messaging / Display). If it's confusable with an existing component (a second selection control, a competing container), add a row to that family's decision table explaining the use-case it owns. Without this step, the component exists but **live-tokens-pick-component** can't recommend it when a user asks "which component should I use?" — the same rule applies whether the component is first-party (update the picker shipped in this package) or consumer-authored (update the local copy at `.claude/skills/live-tokens-pick-component/SKILL.md` that `setup-claude` placed in your project).
+4. **Say what it is for.** The runtime file's leading HTML comment is the
+   component's description. `npx live-tokens components` prints it beside the
+   id with the variants and props read from `interface Props` (`--json` for
+   data); that is how **live-tokens-pick-component** weighs a project's own
+   component against the shipped set, so no skill file is edited and nothing
+   is lost when `setup-claude` refreshes the skills. Name the job it does and
+   what it is not for. A directory other than `src/system/components` goes in
+   `"componentDirs"` in `live-tokens.config.json`; a first-party component is
+   also added to the picker's **Catalogue** line, which `check:skills` holds.
 5. **Join the sketch layer** — the effect draws a fixed set of parts, so a new
    component stays crisp while the page around it goes hand-drawn until it opts
    in. A consumer component carries one of four reserved classes on its root and
@@ -223,15 +230,9 @@ It *warns* (non-fatal) when a token-backed default still carries a px or rem ter
 
 Exit code 0 means the static contract is met. Resolve warnings before shipping, or run with `--strict` to make them fail. `--json` prints findings with a stable `rule` id, so you can work through one rule at a time and re-run.
 
-**Then run the registry contract test.** If you're authoring inside the package itself, `src/editor/component-editor/registryContract.test.ts` runs `describe.each(getComponentRegistryEntries())` and verifies, per component:
+**Then run the registry contract test.** If you're authoring inside the package itself, `src/editor/component-editor/registryContract.test.ts` runs `describe.each(getComponentRegistryEntries())` and verifies, per component, that the registration resolves to a real `sourceFile` and a non-empty schema, that schema variables are unique, that every editable token (excluding `hidden: true`, `kind: 'gradient'`, and padding-side suffixes) is declared in the runtime `<style>` block and seeded in `src/live-tokens/data/component-configs/<id>/default.json`, and that `setComponentAlias` round-trips the alias through the slice.
 
-1. Registration resolves to a real `sourceFile` and a non-empty schema.
-2. Schema variables are unique within the component.
-3. Every editable token (excluding `hidden: true`, `kind: 'gradient'`, and padding-side suffixes) is declared in the runtime `<style>` block.
-4. Every editable token is seeded in `src/live-tokens/data/component-configs/<id>/default.json`.
-5. `setComponentAlias` round-trips the alias through the slice.
-
-A new first-party component is auto-covered the moment it lands in `builtInRegistry` — `npm test` will fail if any of the five checks miss. For a consumer-authored component, mirror this pattern in your own test suite if you want the same drift protection (the same test logic works against any `registerComponent` registration; iterate `getComponentRegistryEntries()` after your `main.ts` has run).
+A new first-party component is auto-covered the moment it lands in `builtInRegistry` — `npm test` will fail if any of the five checks miss. For a consumer-authored component, mirror this pattern in your own test suite if you want the same drift protection: `getComponentRegistryEntries` is exported from `@motion-proto/live-tokens` and returns every registration, shipped and custom, once your `main.ts` has run.
 
 **If your component declares `intrinsics`, the intrinsics contract test covers it too.** `src/editor/component-editor/intrinsicsContract.test.ts` iterates every entry with an `intrinsics` array and asserts, per (intrinsic, variant), that the runtime `:global(:root)` declares a default, the default is one of the spec's `values`, and the editor's `default` equals the runtime default. This is what would have caught a getter defaulting to `center` while `:global(:root)` says `start`. Same auto-coverage rule: declare `intrinsics` on the registry entry and the test picks it up.
 

package/.claude/skills/live-tokens-fix-findings/SKILL.md

@@ -64,7 +64,9 @@ Three things the loop never does:
 `color-literal` is the finding that takes judgement. The replacement is the
 token for what the colour *does*, not the token that happens to be closest in
 hue, because the theme will move every role together and the page must move
-with it. Read `tokens.css` for the names; the families are fixed.
+with it. `npx live-tokens tokens --family surface` prints a family's names and
+values (`text`, `border`, `scrim`, `tint` likewise; `--json` for data); the
+families are fixed.
 
 | The literal is | Token family | Notes |
 | --- | --- | --- |
@@ -89,7 +91,7 @@ and is never reported, so leave it.
 
 | The literal is | Token | Notes |
 | --- | --- | --- |
-| Padding, margin, gap, an offset | `--space-<px>` | Steps: 0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 64, 96, 128. Round to the nearest step and name the shift. |
+| Padding, margin, gap, an offset | `--space-<px>` | `npx live-tokens tokens --family space` prints the steps. Round to the nearest one and name the shift. |
 | A stroke width | `--border-width-1`, `-2`, `-4` | Also for `outline`. |
 | A corner | `--radius-sm` through `-4xl`, `--radius-full` | |
 | A shadow | `--shadow-sm` through `-xl` | Replace the whole value, never one offset. |
@@ -105,7 +107,7 @@ though no rule reports them, and a `blur()` takes `--blur-*`.
 | `unknown-token` | A typo or a rename. Search `tokens.css` for the stem. A contract-family name (`--surface-…`, `--text-…`) that is gone was renamed: `npx live-tokens migrate --check` names the migration. |
 | `raw-text-axis` | Set the whole axis set from one text style: `--heading-xl` through `-sm`, `--body-md`, `--body-sm`, `--editorial-*`, `--eyebrow`, `--code`, each carrying `-font-family`, `-font-size`, `-font-weight`, `-line-height`, `-letter-spacing`. A `font:` shorthand is rewritten the same way. `em`, `%`, and a unitless line-height are relative and fine. |
 | `unknown-component` | Not in the catalogue. Read **live-tokens-pick-component** for the shipped one that fits, or author it with **live-tokens-create-component**. |
-| `unknown-prop` | The component drops it at runtime. Read its `interface Props` in `node_modules/@motion-proto/live-tokens/src/system/components/<Name>.svelte` and either map it to a declared prop or delete it. A `class` on a component that declares none does nothing. |
+| `unknown-prop` | The component drops it at runtime. `npx live-tokens components <id>` prints the props it declares and the values each union accepts; map the prop to one of them or delete it. A `class` on a component that declares none does nothing. |
 | `unknown-prop-value` | Pick a value from the union the message lists. |
 | `hardcoded-columns` | `repeat(var(--columns-count), 1fr)` for the page grid; `calc(var(--columns-count) - 2)` for a sub-grid spanning fewer page columns. A two-up or three-up is a layout and is not reported. |
 | `site-css-in-main` | Delete the import from `main.ts` and add it to each page's `<script>`, so page CSS never reaches the editor routes. |

package/.claude/skills/live-tokens-pick-component/SKILL.md

@@ -13,6 +13,14 @@ For composing a page once you've picked components, see **live-tokens-build-page
 
 Action: `Button`, `IconButton`, `InlineEditActions`. Input: `Input`, `Slider`. Selection: `SegmentedControl`, `TabBar`, `RadioButton`, `MenuSelect`, `Toggle`. Containers: `Card`, `CollapsibleSection`, `Dialog`, `Panel`. Messaging: `Callout`, `Notification`, `Tooltip`, `Badge`, `CornerBadge`. Display: `Table`, `Image`, `ImageLightbox`, `ProgressBar`, `SectionDivider`, `SideNavigation`, `CodeSnippet`.
 
+That line is the shipped set. A project can register components of its own,
+and those never appear in this file: run `npx live-tokens components` before
+choosing. It lists every component the project has, shipped and custom, with
+the variants each takes and the purpose its header comment states, so a custom
+component is weighed against the shipped set on the same footing.
+`npx live-tokens components <id>` prints one component's props, the values each
+union accepts, and its tokens with defaults; `--json` returns the same as data.
+
 ## Action family: Button vs IconButton
 
 Both trigger an action and share the same six variants (primary, secondary, outline, success, danger, warning), three states (default, hover, disabled) and two sizes (default, small). They differ only in content.

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.70.0 — The registry is a query
+
+### Added
+
+- **The registry is a query.** `npx live-tokens components` lists every
+  component a project has, shipped and its own, with the variants and props
+  read from each `interface Props` and the purpose its header comment states;
+  `components <id>` prints one component's props, unions, tokens, and
+  defaults. `npx live-tokens tokens` lists every theme token the project's
+  `tokens.css` declares by family with its value, `--family <name>` for one
+  scale. Both take `--json`. A project's components in a directory other than
+  `src/system/components` are found through `"componentDirs"` in
+  `live-tokens.config.json`. The same vocabulary the checkers read answers the
+  query, so a skill sees exactly what the checkers will hold it to.
+
+- **`getComponentRegistryEntries` is exported from the package**, so a
+  project's own test suite can run the registry contract over every
+  registration, shipped and custom. The create-component skill pointed at it
+  before it was public.
+
+### Changed
+
+- **The skills read the registry instead of carrying it.** The picker's
+  catalogue line is the shipped set only; a project's own component is found
+  by `live-tokens components`, weighed by the description its header comment
+  states, and never written into a skill file, so `setup-claude --force` no
+  longer loses anything. build-page and fix-findings read a component's props
+  from the same query, and fix-findings reads a token scale from `tokens`.
+
 ## 0.69.0 — Every value reads a token, and the build says so
 
 ### Changed

package/README.md

@@ -323,6 +323,8 @@ npx @motion-proto/live-tokens <command>
 |---|---|
 | `create <dir> [--force]` | Scaffold a new Svelte + Vite app wired up with live-tokens. |
 | `setup-claude [--force]` | Install the bundled Claude Code skills into `./.claude/skills/`. |
+| `components [id] [--json]` | List every component the project has, shipped and its own, with the props each takes; with an id, its props, variants, tokens, and defaults. |
+| `tokens [--family <name>] [--json]` | List every theme token the project's `tokens.css` declares, by family, with its value. |
 | `check-component [id]` | Validate a component's runtime, editor, and registration against the authoring contract; with no id, every component authored under `src/system/components`. |
 | `check-page [paths...]` | Validate pages against the build-page contract: catalogue components and their props, theme tokens over literals, route wiring. |
 | `generate-theme <brief.json> [--no-activate] [--dry-run] [--carry-from <name>]` | Build a full theme from a 10-seed OKLCH brief, enforce AA contrast, write `themes/<slug>.json`, and open it. |

package/bin/cli.mjs

@@ -3,6 +3,8 @@
 // Subcommands:
 //   create <dir>             Scaffold a new app that depends on this package.
 //   setup-claude [--force]   Copy bundled Claude Code skills into ./.claude/skills/.
+//   components [id]          List every component the project has, shipped and its own, with props and tokens.
+//   tokens [--family <name>] List every theme token by family, with its value.
 //   check-component [id]     Validate a component (or every authored one) against the create-component skill contract.
 //   check-page [paths...]    Validate pages against the build-page skill contract.
 //   generate-theme <brief>   Build a theme from a 10-seed OKLCH brief and open it.
@@ -10,12 +12,14 @@
 //   set-fonts <brief.json>   Bind Google Fonts families to the theme's font stacks.
 //   migrate [...]            Reconcile tokens.css, the data tree, and route references.
 
-import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync, writeSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { COMPONENT_RULES, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
 import { PAGE_RULES, checkPages, discoverPages } from './check-page.mjs';
+import { describeComponents, describeTokens, formatComponents, formatTokens } from './lib/catalogue.mjs';
+import { loadVocabulary } from './lib/tokenVocabulary.mjs';
 import {
   applySeverity,
   countBySeverity,
@@ -42,6 +46,14 @@ 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/
+  components [id] [--json]    List every component the project has, shipped and
+                              its own (src/system/components plus any
+                              "componentDirs" in live-tokens.config.json), with
+                              the props each takes; with an id, that component's
+                              props, variants, tokens, and defaults
+  tokens [--family <name>] [--json]
+                              List every theme token the project's tokens.css
+                              declares, by family, with its value
   check-component [id]        Validate <id>'s runtime, editor, and registration
                               against the live-tokens-create-component contract
   check-page [paths...]       Validate pages against the live-tokens-build-page
@@ -101,6 +113,20 @@ Both check commands accept:
                               either is pending; route findings are advisory).
 `;
 
+// A large body written through console.log is cut at the pipe buffer when the
+// process exits before stdout drains, so a query writes synchronously.
+function writeOut(text) {
+  const buf = Buffer.from(`${text}\n`);
+  let offset = 0;
+  while (offset < buf.length) {
+    try {
+      offset += writeSync(1, buf, offset, buf.length - offset);
+    } catch (error) {
+      if (error.code !== 'EAGAIN') throw error;
+    }
+  }
+}
+
 function fail(message, code = 1) {
   console.error(message);
   process.exit(code);
@@ -141,6 +167,29 @@ function reportChecks(label, findings, checked, rules, opts) {
   process.exit(countBySeverity(resolved).errors === 0 ? 0 : 1);
 }
 
+if (command === 'components') {
+  const opts = parseCheckFlags(rest);
+  const list = describeComponents(loadVocabulary());
+  const id = opts.rest[0];
+  if (id && !list.some((c) => c.id === id)) fail(formatComponents(list, { id }));
+  writeOut(opts.json ? JSON.stringify(id ? list.find((c) => c.id === id) : list, null, 2) : formatComponents(list, { id }));
+  process.exit(0);
+}
+
+if (command === 'tokens') {
+  const opts = parseCheckFlags(rest);
+  const at = opts.rest.indexOf('--family');
+  const family = at >= 0 ? opts.rest[at + 1] : undefined;
+  const desc = describeTokens(loadVocabulary());
+  if (family && !desc.families.some((f) => f.family === family)) fail(formatTokens(desc, { family }));
+  writeOut(
+    opts.json
+      ? JSON.stringify(family ? desc.families.find((f) => f.family === family) : desc, null, 2)
+      : formatTokens(desc, { family }),
+  );
+  process.exit(0);
+}
+
 if (command === 'check-component') {
   const opts = parseCheckFlags(rest);
   const ids = opts.rest.length > 0 ? [opts.rest[0]] : discoverComponents();

package/bin/lib/catalogue.mjs

@@ -0,0 +1,123 @@
+// The registry as a query. Every component a project has, shipped or its own,
+// with the props each takes and the tokens each declares, and every theme token
+// grouped by family. Read from files through the same vocabulary the checkers
+// use, so a skill or a script sees exactly what the checkers will hold it to.
+
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { CONTRACT_FAMILIES } from './tokenVocabulary.mjs';
+
+/** The runtime file's leading HTML comment, which is where a component says what it is for. */
+function descriptionOf(source) {
+  const m = source.match(/^\s*<!--([\s\S]*?)-->/);
+  if (!m) return '';
+  return m[1]
+    .split('\n')
+    .map((line) => line.trim())
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^\S+\.svelte\s*[—–-]+\s*/, '');
+}
+
+function familyOf(name) {
+  const stem = name.replace(/^--/, '');
+  const hit = CONTRACT_FAMILIES
+    .filter((f) => stem === f || stem.startsWith(`${f}-`))
+    .sort((a, b) => b.length - a.length)[0];
+  return hit ?? stem.split('-')[0];
+}
+
+export function describeComponents(vocab, { root = process.cwd() } = {}) {
+  const out = [];
+  for (const entry of vocab.components.values()) {
+    const source = readFileSync(entry.file, 'utf8');
+    const props = entry.props
+      ? [...entry.props.props].map((name) => ({
+          name,
+          type: entry.props.types.get(name) ?? '',
+          values: entry.props.enums.has(name) ? [...entry.props.enums.get(name)] : undefined,
+        }))
+      : [];
+    out.push({
+      id: entry.id,
+      name: entry.name,
+      origin: entry.origin,
+      file: relative(root, entry.file),
+      registered: entry.origin === 'shipped' || vocab.registered.has(entry.id),
+      description: descriptionOf(source),
+      variants: entry.props?.enums.get('variant') ? [...entry.props.enums.get('variant')] : [],
+      props,
+      tokens: [...entry.tokens].map(([name, value]) => ({ name, default: value })),
+    });
+  }
+  return out.sort((a, b) => a.origin.localeCompare(b.origin) || a.id.localeCompare(b.id));
+}
+
+export function describeTokens(vocab, { root = process.cwd() } = {}) {
+  const values = new Map();
+  if (vocab.tokensCssPath) {
+    const css = readFileSync(vocab.tokensCssPath, 'utf8').replace(/\/\*[\s\S]*?\*\//g, ' ');
+    for (const m of css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      if (!values.has(m[1])) values.set(m[1], m[2].trim());
+    }
+  }
+  const byFamily = new Map();
+  for (const name of vocab.themeTokens) {
+    const family = familyOf(name);
+    if (!byFamily.has(family)) byFamily.set(family, []);
+    byFamily.get(family).push({ name, value: values.get(name) ?? '' });
+  }
+  return {
+    tokensCss: vocab.tokensCssPath ? relative(root, vocab.tokensCssPath) : null,
+    families: [...byFamily].map(([family, tokens]) => ({ family, tokens })),
+    components: [...vocab.components.values()].map((c) => ({
+      id: c.id,
+      tokens: [...c.tokens].map(([name, value]) => ({ name, default: value })),
+    })),
+  };
+}
+
+export function formatComponents(list, { id } = {}) {
+  const lines = [];
+  if (id) {
+    const c = list.find((x) => x.id === id);
+    if (!c) return `No component "${id}". Run \`live-tokens components\` for the list.`;
+    lines.push(`${c.name} (${c.id}, ${c.origin}${c.registered ? '' : ', NOT registered'})  ${c.file}`);
+    if (c.description) lines.push(`  ${c.description}`);
+    if (c.props.length) {
+      lines.push('  props:');
+      for (const p of c.props) lines.push(`    ${p.name}${p.values ? `: ${p.values.join(' | ')}` : p.type ? `: ${p.type}` : ''}`);
+    }
+    lines.push(`  tokens (${c.tokens.length}):`);
+    for (const t of c.tokens) lines.push(`    ${t.name}: ${t.default}`);
+    return lines.join('\n');
+  }
+  for (const c of list) {
+    const variants = c.variants.length ? `  variants: ${c.variants.join(', ')}` : '';
+    lines.push(`${c.id.padEnd(20)} ${c.origin.padEnd(8)} ${c.name}${c.registered ? '' : '  (NOT registered)'}${variants}`);
+    if (c.description) lines.push(`${''.padEnd(29)} ${c.description}`);
+  }
+  lines.push('');
+  lines.push(`${list.length} component(s). \`live-tokens components <id>\` prints one with its props and tokens.`);
+  return lines.join('\n');
+}
+
+export function formatTokens(desc, { family } = {}) {
+  const lines = [];
+  const families = family ? desc.families.filter((f) => f.family === family) : desc.families;
+  if (family && families.length === 0) {
+    return `No family "${family}". Families: ${desc.families.map((f) => f.family).join(', ')}.`;
+  }
+  lines.push(`Theme tokens from ${desc.tokensCss ?? '(no tokens.css found)'}`);
+  for (const f of families) {
+    lines.push('');
+    lines.push(`${f.family} (${f.tokens.length})`);
+    for (const t of f.tokens) lines.push(`  ${t.name}: ${t.value}`);
+  }
+  if (!family) {
+    lines.push('');
+    lines.push(`Component tokens: ${desc.components.reduce((n, c) => n + c.tokens.length, 0)} across ${desc.components.length} component(s). \`live-tokens components <id>\` lists one component's.`);
+  }
+  return lines.join('\n');
+}

package/bin/lib/tokenVocabulary.mjs

@@ -26,7 +26,7 @@ const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 const SHIPPED_COMPONENTS_DIR = 'src/system/components';
 
 /** Families whose names are governed by the token contract (see TOKENS.md). */
-const CONTRACT_FAMILIES = [
+export const CONTRACT_FAMILIES = [
   'surface', 'text', 'border', 'color', 'space', 'radius', 'font', 'line-height',
   'letter-spacing', 'shadow', 'blur', 'icon-size', 'scrim', 'tint', 'columns',
   'heading', 'body', 'editorial', 'eyebrow', 'code', 'easing', 'duration', 'zoom',
@@ -111,13 +111,26 @@ export function componentProps(source) {
 
   const props = new Set();
   const enums = new Map();
+  const types = new Map();
   const body = iface[1].replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
   for (const m of body.matchAll(/^\s*(?:readonly\s+)?(\w+)\??\s*:\s*([^;\n]+)/gm)) {
     props.add(m[1]);
+    types.set(m[1], m[2].trim());
     const values = resolveEnum(m[2]);
     if (values) enums.set(m[1], new Set(values));
   }
-  return { props, enums };
+  return { props, enums, types };
+}
+
+/** `live-tokens.config.json` at the project root, or nothing. */
+export function readProjectConfig(root) {
+  const path = join(root, 'live-tokens.config.json');
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
 }
 
 function walk(dir, exts, out = []) {
@@ -186,14 +199,28 @@ export function loadVocabulary({ root = process.cwd(), pkgRoot = PKG_ROOT } = {}
 
   const componentTokens = new Set();
   const components = new Map();
-  const dirs = [join(pkgRoot, SHIPPED_COMPONENTS_DIR), join(root, SHIPPED_COMPONENTS_DIR)];
+  // A project's own components sit beside the shipped ones, plus any directory
+  // `componentDirs` in live-tokens.config.json names.
+  const own = [SHIPPED_COMPONENTS_DIR, ...(readProjectConfig(root).componentDirs ?? [])].map((d) => join(root, d));
+  const shippedDir = join(pkgRoot, SHIPPED_COMPONENTS_DIR);
+  const dirs = [shippedDir, ...own];
   for (const file of componentFiles(dirs)) {
     const Id = file.slice(file.lastIndexOf('/') + 1).replace('.svelte', '');
     const src = readFileSync(file, 'utf8');
-    components.set(Id.toLowerCase(), { id: Id.toLowerCase(), name: Id, file, props: componentProps(src) });
+    const tokens = new Map();
     for (const block of extractGlobalRootBlocks(src)) {
-      for (const n of declaredCustomProperties(block)) componentTokens.add(n);
+      const clean = block.replace(/\/\*[\s\S]*?\*\//g, ' ');
+      for (const n of declaredCustomProperties(clean)) componentTokens.add(n);
+      for (const m of clean.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) if (!tokens.has(m[1])) tokens.set(m[1], m[2].trim());
     }
+    components.set(Id.toLowerCase(), {
+      id: Id.toLowerCase(),
+      name: Id,
+      file,
+      origin: file.startsWith(shippedDir) ? 'shipped' : 'custom',
+      props: componentProps(src),
+      tokens,
+    });
   }
   const registered = registeredIds(root);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [

package/src/editor/index.ts

@@ -82,5 +82,5 @@ export type { Oklch } from './core/palettes/oklch';
 
 export { initializeTheme } from './core/themes/themeInit';
 
-export { registerComponent } from './component-editor/registry';
+export { registerComponent, getComponentRegistryEntries } from './component-editor/registry';
 export type { RegisterComponentEntry, RegistryEntry, ComponentId } from './component-editor/registry';