@motion-proto/live-tokens 0.11.0 → 0.12.1

package/README.md

@@ -7,12 +7,13 @@ A foundational design system for quickly styling and building Svelte + Vite micr
 ## What you get
 
 - **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.
-- **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.
+- **Real-time component editing.** Each of ~24 shipped Svelte components (Button, Input, Card, Dialog, Badge, Callout, Table, Tooltip, Toggle, TabBar, SegmentedControl, RadioButton, MenuSelect, ProgressBar, CornerBadge, SectionDivider, CollapsibleSection, Notification, Image, ImageLightbox, CodeSnippet, SideNavigation, 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.
 - **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.
 - **Per-component editor** (`/components` route, dev-only) — the home of real-time component-alias editing. Pick token aliases per component without writing CSS.
 - **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.
 - **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.
 - **Vite plugin** — hosts the `/api/live-tokens/{themes,component-configs,manifests}/*` routes that persist your edits to disk as you make them. The single namespace keeps live-tokens' routes from colliding with anything your app serves under `/api`.
+- **Claude Code skill suite** — three bundled skills so you can drive the package in plain English. `build-page` composes pages from the shipped components. `pick-component` decides between confusing pairs (TabBar vs SegmentedControl, Card vs CollapsibleSection). `create-component` authors a new editable component against the project's naming, state-model, and import rules. One command to install all three: `npx @motion-proto/live-tokens setup-claude`. See [Claude Code skills](#claude-code-skills) below.
 
 ## Quick install
 
@@ -236,16 +237,39 @@ registerComponent({
 
 The component appears in the `/components` page under a **CUSTOM** group in the nav rail. Token rows, linked-block sharing, per-component config persistence, and reset-to-default work identically to the built-in set. All imports must come from `@motion-proto/live-tokens` or `@motion-proto/live-tokens/component-editor`; never deep-import from `src/`.
 
-### Skill (Claude-assisted authoring)
+## Claude Code skills
 
-The package bundles a Claude Code skill at `node_modules/@motion-proto/live-tokens/.claude/skills/live-tokens-add-component/`. It teaches the token-naming conventions, state model, editor patterns, and the public-imports rule. To make it active in your project, copy or symlink it into your `.claude/skills/` directory:
+The package ships a suite of Claude Code skills that encode the project's conventions so Claude can drive the package in plain English. They cover the three jobs the README itself can't carry well: deciding which shipped component fits a need, composing a page from the catalogue, and (for the long-tail case) authoring a new editable component. Each skill auto-triggers from natural-language requests — no slash commands. (Plain `npm install` plus the README handle first-time setup.)
+
+| Skill                          | Triggers on                                                          | What it knows                                                                                                                  |
+|--------------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
+| `live-tokens-build-page`       | "build a pricing page using live-tokens components"                  | shipped-component catalogue, column grid, `pageSources` registration, token-only styling rule                                   |
+| `live-tokens-pick-component`   | "what's the difference between TabBar and SegmentedControl?"         | decision tables for each confusable family (selection, container, messaging, on/off); when to author a new one instead         |
+| `live-tokens-create-component` | "author a new Toggle component for my live-tokens project"           | runtime + editor + `registerComponent()` recipe, naming scheme, state model, public-imports rule, verification checklist        |
+
+### Install
+
+```bash
+npx @motion-proto/live-tokens setup-claude
+```
+
+Copies every bundled skill into `./.claude/skills/` in the current directory. Re-run after upgrading the package to pick up new or updated skills (pass `--force` to overwrite). macOS/Linux only.
+
+If you'd rather avoid the CLI, the equivalent one-liner:
+
+```bash
+mkdir -p .claude/skills && cp -R node_modules/@motion-proto/live-tokens/.claude/skills/. .claude/skills/
+```
+
+### Validate authored components
+
+The same CLI ships a static validator that turns the `create-component` skill's verification checklist into a runnable command:
 
 ```bash
-mkdir -p .claude/skills
-ln -s ../../node_modules/@motion-proto/live-tokens/.claude/skills/live-tokens-add-component .claude/skills/
+npx @motion-proto/live-tokens check-component <id>
 ```
 
-Once linked, asking Claude to "add a Stat component to my live-tokens project" triggers the skill, which walks the runtime file, editor file, and registration step.
+It enforces the file layout, `:global(:root)` block, token-suffix vocabulary, the state-before-property rule, the no-raw-colour-defaults rule, the public-imports rule, and the `registerComponent({ id })` call. Exit code 0 means the static contract is met. Useful both as a self-check after Claude generates a component and as a pre-commit guard on human-authored ones.
 
 ## How the editor ships changes to prod
 

package/bin/check-component.mjs

@@ -0,0 +1,244 @@
+// Static validator for a live-tokens component.
+//
+// Asserts that an authored component (runtime + editor + registration) satisfies
+// the contract described in the live-tokens-create-component skill:
+//
+//   - runtime file at src/system/components/<Id>.svelte with :global(:root) block
+//   - editor file at src/system/components/<Id>Editor.svelte exporting `component` + `allTokens`
+//   - registerComponent({ id: '<id>', ... }) call somewhere in src/
+//   - all imports in the three files use public live-tokens paths only
+//   - token names match --<id>-<part>[-<state>][-<element>]-<property>
+//     with the property being one of the recognised suffixes,
+//     and state coming before property (never after)
+//   - :global(:root) defaults reference theme tokens (no raw colour literals)
+//
+// Returns { errors: string[], warnings: string[] }.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+
+// Property suffixes the editor picker recognises (KIND_PATTERNS in the editor).
+// Keep in sync with the skill's suffix vocabulary.
+const KNOWN_SUFFIXES = [
+  'surface', 'border', 'text', 'icon', 'label', 'fill',
+  'radius', 'border-width', 'font-family', 'font-weight',
+  'font-size', 'line-height', 'letter-spacing', 'padding',
+  'thickness', 'width', 'color', 'size', 'gap', 'opacity',
+  'shadow', 'blur', 'divider',
+];
+
+// State tokens that must come *before* the property, never after.
+const STATE_TOKENS = ['hover', 'disabled', 'selected', 'focus', 'active', 'focused'];
+
+// Deep imports into the package internals are not a supported API.
+const DEEP_IMPORT_PATTERNS = [
+  /^@motion-proto\/live-tokens\/src\//,
+  /node_modules\/@motion-proto\/live-tokens/,
+];
+
+function capitalize(id) {
+  return id.charAt(0).toUpperCase() + id.slice(1);
+}
+
+function extractImports(source) {
+  const out = [];
+  const re = /import\s+(?:[^'"]*\s+from\s+)?['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    out.push(m[1]);
+  }
+  return out;
+}
+
+function extractGlobalRootBlocks(source) {
+  const blocks = [];
+  const re = /:global\(:root\)\s*\{([^}]*)\}/g;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    blocks.push(m[1]);
+  }
+  return blocks;
+}
+
+function extractTokensForId(blocks, id) {
+  const tokens = new Set();
+  const re = new RegExp(`--${id}-[a-z0-9-]+`, 'g');
+  for (const block of blocks) {
+    const matches = block.match(re) ?? [];
+    for (const t of matches) tokens.add(t);
+  }
+  return [...tokens];
+}
+
+function tokenSuffix(token) {
+  for (const suffix of KNOWN_SUFFIXES) {
+    if (token.endsWith(`-${suffix}`)) return suffix;
+  }
+  return null;
+}
+
+function detectStateAfterProperty(token) {
+  // e.g. --comp-part-surface-hover (wrong) vs --comp-part-hover-surface (right)
+  for (const state of STATE_TOKENS) {
+    if (token.endsWith(`-${state}`)) {
+      const head = token.slice(0, -(state.length + 1));
+      if (tokenSuffix(head)) return state;
+    }
+  }
+  return null;
+}
+
+function findFilesRecursive(dir, exts) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    if (ent.name === 'node_modules' || ent.name.startsWith('.')) continue;
+    const full = join(dir, ent.name);
+    if (ent.isDirectory()) {
+      out.push(...findFilesRecursive(full, exts));
+    } else if (exts.includes(extname(ent.name))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+export function checkComponent(id, root = process.cwd()) {
+  const errors = [];
+  const warnings = [];
+
+  if (!/^[a-z][a-z0-9]*$/.test(id)) {
+    errors.push(`id "${id}" is invalid; must be lowercase letters/digits, no dashes`);
+    return { errors, warnings };
+  }
+
+  const Id = capitalize(id);
+  const runtimePath = join(root, 'src/system/components', `${Id}.svelte`);
+  const editorPath = join(root, 'src/system/components', `${Id}Editor.svelte`);
+
+  if (!existsSync(runtimePath)) {
+    errors.push(`runtime missing: ${relative(root, runtimePath)}`);
+  }
+  if (!existsSync(editorPath)) {
+    errors.push(`editor missing: ${relative(root, editorPath)}`);
+  }
+  if (errors.length) return { errors, warnings };
+
+  const runtime = readFileSync(runtimePath, 'utf8');
+  const editor = readFileSync(editorPath, 'utf8');
+
+  // Runtime: :global(:root) block present.
+  const blocks = extractGlobalRootBlocks(runtime);
+  if (blocks.length === 0) {
+    errors.push(`${relative(root, runtimePath)}: missing :global(:root) declaration block`);
+  }
+
+  // Runtime: at least one --<id>-* token.
+  const tokens = extractTokensForId(blocks, id);
+  if (blocks.length > 0 && tokens.length === 0) {
+    errors.push(`${relative(root, runtimePath)}: no --${id}-* tokens declared in :global(:root)`);
+  }
+
+  // Runtime: state-after-property anti-pattern. Report this first; if it fires
+  // for a token, skip the unknown-suffix error for the same token (the state-
+  // suffix wouldn't be in the suffix list anyway, so it's the same root cause).
+  const stateAfterTokens = new Set();
+  for (const token of tokens) {
+    const trailingState = detectStateAfterProperty(token);
+    if (trailingState) {
+      stateAfterTokens.add(token);
+      errors.push(
+        `${relative(root, runtimePath)}: ${token} has '${trailingState}' after the property; ` +
+          `state must come before property (e.g. -${trailingState}-surface, not -surface-${trailingState})`,
+      );
+    }
+  }
+
+  // Runtime: every token ends in a known suffix.
+  for (const token of tokens) {
+    if (stateAfterTokens.has(token)) continue;
+    if (!tokenSuffix(token)) {
+      errors.push(`${relative(root, runtimePath)}: ${token} doesn't end in a known suffix`);
+    }
+  }
+
+  // Runtime: defaults inside :global(:root) reference theme tokens, not raw colours.
+  for (const block of blocks) {
+    const rawColours = block.match(/:\s*#[0-9a-fA-F]{3,8}\b/g) ?? [];
+    if (rawColours.length > 0) {
+      errors.push(
+        `${relative(root, runtimePath)}: :global(:root) contains ${rawColours.length} raw colour literal(s); ` +
+          `defaults must reference theme tokens (e.g. var(--surface-primary))`,
+      );
+    }
+  }
+
+  // Editor: declares `const component = '<id>'` (module block).
+  const componentDecl = new RegExp(`\\bconst\\s+component\\s*=\\s*['"]${id}['"]`);
+  if (!componentDecl.test(editor)) {
+    errors.push(`${relative(root, editorPath)}: missing 'const component = "${id}"' in <script module>`);
+  }
+
+  // Editor: exports allTokens.
+  if (!/\bexport\s+const\s+allTokens\b/.test(editor)) {
+    errors.push(`${relative(root, editorPath)}: missing 'export const allTokens'`);
+  }
+
+  // Imports across runtime + editor: reject deep imports into the package.
+  for (const [path, source] of [[runtimePath, runtime], [editorPath, editor]]) {
+    for (const imp of extractImports(source)) {
+      for (const pattern of DEEP_IMPORT_PATTERNS) {
+        if (pattern.test(imp)) {
+          errors.push(`${relative(root, path)}: deep import not supported: ${imp}`);
+        }
+      }
+    }
+  }
+
+  // Registration: registerComponent({ id: '<id>', ... }) somewhere under src/.
+  const srcFiles = findFilesRecursive(join(root, 'src'), ['.ts', '.js', '.svelte', '.mjs']);
+  const regPattern = new RegExp(`registerComponent\\s*\\(\\s*\\{[^}]*id\\s*:\\s*['"]${id}['"]`, 's');
+  let registrationFile = null;
+  for (const file of srcFiles) {
+    try {
+      if (regPattern.test(readFileSync(file, 'utf8'))) {
+        registrationFile = file;
+        break;
+      }
+    } catch {
+      // ignore unreadable files
+    }
+  }
+  if (!registrationFile) {
+    errors.push(`registerComponent({ id: '${id}', ... }) not found anywhere under src/`);
+  } else {
+    // Check the registration file's imports too.
+    const regSource = readFileSync(registrationFile, 'utf8');
+    for (const imp of extractImports(regSource)) {
+      for (const pattern of DEEP_IMPORT_PATTERNS) {
+        if (pattern.test(imp)) {
+          errors.push(`${relative(root, registrationFile)}: deep import not supported: ${imp}`);
+        }
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export function formatReport(id, result) {
+  const lines = [];
+  if (result.errors.length === 0 && result.warnings.length === 0) {
+    lines.push(`✓ ${id}: passes the live-tokens-create-component contract.`);
+  } else {
+    if (result.errors.length > 0) {
+      lines.push(`✗ ${id}: ${result.errors.length} error(s)`);
+      for (const e of result.errors) lines.push(`  - ${e}`);
+    }
+    if (result.warnings.length > 0) {
+      lines.push(`! ${id}: ${result.warnings.length} warning(s)`);
+      for (const w of result.warnings) lines.push(`  - ${w}`);
+    }
+  }
+  return lines.join('\n');
+}

package/bin/cli.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// CLI for @motion-proto/live-tokens.
+// Subcommands:
+//   setup-claude [--force]   Copy bundled Claude Code skills into ./.claude/skills/.
+//   check-component <id>     Validate a component against the add-component skill contract.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import { checkComponent, formatReport } from './check-component.mjs';
+
+const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
+
+Commands:
+  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
+`;
+
+function fail(message, code = 1) {
+  console.error(message);
+  process.exit(code);
+}
+
+const [, , command, ...rest] = process.argv;
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+if (command === 'check-component') {
+  const id = rest[0];
+  if (!id) fail(`Usage: npx @motion-proto/live-tokens check-component <id>`);
+  const result = checkComponent(id);
+  console.log(formatReport(id, result));
+  process.exit(result.errors.length === 0 ? 0 : 1);
+}
+
+if (command !== 'setup-claude') {
+  fail(`Unknown command: ${command}\n\n${USAGE}`);
+}
+
+if (process.platform === 'win32') {
+  fail('setup-claude is macOS/Linux only.');
+}
+
+const force = rest.includes('--force');
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const srcSkills = join(pkgRoot, '.claude', 'skills');
+
+if (!existsSync(srcSkills)) {
+  fail(`No bundled skills found at ${srcSkills}. Is the package installed correctly?`);
+}
+
+const skills = readdirSync(srcSkills).filter((name) =>
+  statSync(join(srcSkills, name)).isDirectory(),
+);
+
+if (skills.length === 0) {
+  fail('No bundled skills to install.');
+}
+
+const destSkills = join(process.cwd(), '.claude', 'skills');
+mkdirSync(destSkills, { recursive: true });
+
+let installed = 0;
+let skipped = 0;
+for (const skill of skills) {
+  const src = join(srcSkills, skill);
+  const dest = join(destSkills, skill);
+  if (existsSync(dest) && !force) {
+    console.log(`  skip  ${skill}  (already exists; pass --force to overwrite)`);
+    skipped++;
+    continue;
+  }
+  cpSync(src, dest, { recursive: true });
+  console.log(`  ok    ${skill}`);
+  installed++;
+}
+
+console.log(`\n${installed} installed, ${skipped} skipped → ${destSkills}`);
+
+const SAMPLE_PROMPTS = {
+  'live-tokens-build-page': 'build a pricing page using live-tokens components',
+  'live-tokens-pick-component': "what's the difference between TabBar and SegmentedControl?",
+  'live-tokens-create-component': 'author a new Toggle component for my live-tokens project',
+};
+
+const installedSamples = skills
+  .map((s) => SAMPLE_PROMPTS[s] && [s, SAMPLE_PROMPTS[s]])
+  .filter(Boolean);
+
+if (installedSamples.length > 0) {
+  console.log(`\nIn Claude Code, prompts like these auto-trigger the matching skill:`);
+  for (const [skill, prompt] of installedSamples) {
+    console.log(`  • "${prompt}"\n    → ${skill}`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 6/7.",
   "keywords": [
@@ -24,12 +24,16 @@
     "src/app/site.css",
     "dist-plugin",
     ".claude/skills",
+    "bin",
     "!**/*.test.ts",
     "!**/*.spec.ts",
     "!**/__tests__/**",
     "!src/system/components/Stat.svelte",
     "!src/system/components/StatEditor.svelte"
   ],
+  "bin": {
+    "live-tokens": "./bin/cli.mjs"
+  },
   "exports": {
     ".": {
       "svelte": "./src/editor/index.ts",

package/src/editor/component-editor/CodeSnippetEditor.svelte

@@ -0,0 +1,61 @@
+<script module lang="ts">
+  import type { Token } from './scaffolding/types';
+
+  export const component = 'codesnippet';
+
+  // Single variant. Default carries every container, code, and icon token;
+  // hover layers a single icon-color override on top.
+  const states: Record<string, Token[]> = {
+    default: [
+      { label: 'surface',          variable: '--codesnippet-surface' },
+      { label: 'border',           variable: '--codesnippet-border' },
+      { label: 'border width',     variable: '--codesnippet-border-width' },
+      { label: 'corner radius',    variable: '--codesnippet-radius' },
+      { label: 'padding',          variable: '--codesnippet-padding' },
+      { label: 'gap',              variable: '--codesnippet-gap' },
+      { label: 'code text',        variable: '--codesnippet-code-text' },
+      { label: 'code font family', variable: '--codesnippet-code-font-family' },
+      { label: 'code font size',   variable: '--codesnippet-code-font-size' },
+      { label: 'code font weight', variable: '--codesnippet-code-font-weight' },
+      { label: 'code line height', variable: '--codesnippet-code-line-height' },
+      { label: 'icon color',       variable: '--codesnippet-icon' },
+      { label: 'icon size',        variable: '--codesnippet-icon-size' },
+    ],
+    hover: [
+      { label: 'icon color', variable: '--codesnippet-hover-icon' },
+    ],
+  };
+
+  export const allTokens: Token[] = Object.values(states).flat();
+</script>
+
+<script lang="ts">
+  import CodeSnippet from '../../system/components/CodeSnippet.svelte';
+  import VariantGroup from './scaffolding/VariantGroup.svelte';
+  import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
+</script>
+
+<ComponentEditorBase
+  {component}
+  title="Code Snippet"
+  description="Single-line code display with a copy button. Shows a brief confirmation popover on copy."
+  tokens={allTokens}
+>
+  <VariantGroup name="codesnippet" title="Code Snippet" {states} {component}>
+    {#snippet children({ activeState })}
+      <div class="codesnippet-preview">
+        <CodeSnippet
+          code="npx @motion-proto/live-tokens setup-claude"
+          class={activeState === 'hover' ? 'force-hover' : ''}
+        />
+      </div>
+    {/snippet}
+  </VariantGroup>
+</ComponentEditorBase>
+
+<style>
+  .codesnippet-preview {
+    display: flex;
+    padding: var(--ui-space-16);
+  }
+</style>

package/src/editor/component-editor/ToggleEditor.svelte

@@ -0,0 +1,93 @@
+<script module lang="ts">
+  import type { Token } from './scaffolding/types';
+
+  export const component = 'toggle';
+
+  // Single variant: the default carries the off baseline plus all geometry and
+  // label typography. The other states layer hover, on, on+hover, and disabled
+  // on top of that baseline.
+  const states: Record<string, Token[]> = {
+    default: [
+      { label: 'track surface',     variable: '--toggle-track-surface' },
+      { label: 'track border',      variable: '--toggle-track-border' },
+      { label: 'track border width',variable: '--toggle-track-border-width' },
+      { label: 'track radius',      variable: '--toggle-track-radius' },
+      { label: 'track width',       variable: '--toggle-track-width' },
+      { label: 'track thickness',   variable: '--toggle-track-thickness' },
+      { label: 'thumb surface',     variable: '--toggle-thumb-surface' },
+      { label: 'thumb border',      variable: '--toggle-thumb-border' },
+      { label: 'thumb size',        variable: '--toggle-thumb-size' },
+      { label: 'label text',        variable: '--toggle-label-text' },
+      { label: 'label font family', variable: '--toggle-label-font-family' },
+      { label: 'label font size',   variable: '--toggle-label-font-size' },
+      { label: 'label font weight', variable: '--toggle-label-font-weight' },
+      { label: 'label gap',         variable: '--toggle-gap' },
+    ],
+    hover: [
+      { label: 'track surface', variable: '--toggle-hover-track-surface' },
+      { label: 'thumb surface', variable: '--toggle-hover-thumb-surface' },
+    ],
+    on: [
+      { label: 'track surface', variable: '--toggle-on-track-surface' },
+      { label: 'track border',  variable: '--toggle-on-track-border' },
+      { label: 'thumb surface', variable: '--toggle-on-thumb-surface' },
+      { label: 'thumb border',  variable: '--toggle-on-thumb-border' },
+    ],
+    'on hover': [
+      { label: 'track surface', variable: '--toggle-on-hover-track-surface' },
+      { label: 'thumb surface', variable: '--toggle-on-hover-thumb-surface' },
+    ],
+    disabled: [
+      { label: 'track surface', variable: '--toggle-disabled-track-surface' },
+      { label: 'thumb surface', variable: '--toggle-disabled-thumb-surface' },
+      { label: 'label text',    variable: '--toggle-disabled-label-text' },
+    ],
+  };
+
+  export const allTokens: Token[] = Object.values(states).flat();
+</script>
+
+<script lang="ts">
+  import Toggle from '../../system/components/Toggle.svelte';
+  import VariantGroup from './scaffolding/VariantGroup.svelte';
+  import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
+
+  // Preview reflects the state being edited: "on" / "on hover" show checked;
+  // hover variants apply force-hover; disabled is terminal.
+  function previewProps(activeState: string) {
+    return {
+      checked: activeState === 'on' || activeState === 'on hover',
+      disabled: activeState === 'disabled',
+      forceClass: activeState === 'hover' || activeState === 'on hover' ? 'force-hover' : '',
+    };
+  }
+</script>
+
+<ComponentEditorBase
+  {component}
+  title="Toggle"
+  description="On/off switch with a sliding thumb. The default state is off; on is a state with its own track and thumb colors."
+  tokens={allTokens}
+>
+  <VariantGroup
+    name="toggle"
+    title="Toggle"
+    {states}
+    {component}
+  >
+    {#snippet children({ activeState })}
+      {@const p = previewProps(activeState)}
+      <div class="toggle-preview">
+        <Toggle checked={p.checked} disabled={p.disabled} class={p.forceClass} label="Enable feature" />
+      </div>
+    {/snippet}
+  </VariantGroup>
+</ComponentEditorBase>
+
+<style>
+  .toggle-preview {
+    display: flex;
+    gap: var(--ui-space-16);
+    padding: var(--ui-space-16);
+  }
+</style>

package/src/editor/component-editor/registry.ts

@@ -7,6 +7,7 @@ import CalloutEditor, { allTokens as calloutTokens } from './CalloutEditor.svelt
 import CornerBadgeEditor, { allTokens as cornerBadgeTokens } from './CornerBadgeEditor.svelte';
 import ButtonEditor, { allTokens as buttonTokens } from './ButtonEditor.svelte';
 import CardEditor, { allTokens as cardTokens } from './CardEditor.svelte';
+import CodeSnippetEditor, { allTokens as codeSnippetTokens } from './CodeSnippetEditor.svelte';
 import CollapsibleSectionEditor, { allTokens as collapsibleSectionTokens } from './CollapsibleSectionEditor.svelte';
 import DialogEditor, { allTokens as dialogTokens } from './DialogEditor.svelte';
 import ImageEditor, { allTokens as imageTokens } from './ImageEditor.svelte';
@@ -22,6 +23,7 @@ import SegmentedControlEditor, { allTokens as segmentedControlTokens } from './S
 import SideNavigationEditor, { allTokens as sideNavigationTokens } from './SideNavigationEditor.svelte';
 import TableEditor, { allTokens as tableTokens } from './TableEditor.svelte';
 import TabBarEditor, { allTokens as tabBarTokens } from './TabBarEditor.svelte';
+import ToggleEditor, { allTokens as toggleTokens } from './ToggleEditor.svelte';
 import TooltipEditor, { allTokens as tooltipTokens } from './TooltipEditor.svelte';
 
 /** Internal narrowed union of the first-party component ids. Not exposed publicly. */
@@ -34,6 +36,7 @@ type BuiltInComponentId =
   | 'card'
   | 'badge'
   | 'callout'
+  | 'codesnippet'
   | 'cornerbadge'
   | 'image'
   | 'imagelightbox'
@@ -45,6 +48,7 @@ type BuiltInComponentId =
   | 'sidenavigation'
   | 'table'
   | 'tabbar'
+  | 'toggle'
   | 'tooltip'
   | 'progressbar';
 
@@ -152,6 +156,15 @@ const builtInRegistry: Readonly<Record<BuiltInComponentId, RegistryEntry>> = Obj
     schema: calloutTokens,
     origin: 'system',
   },
+  codesnippet: {
+    id: 'codesnippet',
+    label: 'Code Snippet',
+    icon: 'fas fa-code',
+    sourceFile: 'src/system/components/CodeSnippet.svelte',
+    editorComponent: CodeSnippetEditor,
+    schema: codeSnippetTokens,
+    origin: 'system',
+  },
   cornerbadge: {
     id: 'cornerbadge',
     label: 'Corner Badge',
@@ -251,6 +264,15 @@ const builtInRegistry: Readonly<Record<BuiltInComponentId, RegistryEntry>> = Obj
     schema: tabBarTokens,
     origin: 'system',
   },
+  toggle: {
+    id: 'toggle',
+    label: 'Toggle',
+    icon: 'fas fa-toggle-on',
+    sourceFile: 'src/system/components/Toggle.svelte',
+    editorComponent: ToggleEditor,
+    schema: toggleTokens,
+    origin: 'system',
+  },
   tooltip: {
     id: 'tooltip',
     label: 'Tooltip',