@motion-proto/live-tokens 0.24.1 → 0.25.0

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

@@ -25,21 +25,24 @@ For pattern reference, read any shipped component's source directly from the con
 
 1. **Runtime file** — `src/system/components/MyWidget.svelte`. Declare every editable slot as a CSS custom property inside `:global(:root)`, defaulting to a theme token (never a raw value). The plugin parses `:global(:root)` to seed `component-configs/<id>/default.json`; variables declared anywhere else can't be edited.
 2. **Editor file** — `src/system/components/MyWidgetEditor.svelte`. In a `<script module>` block, declare `const component = 'mywidget'`, build a `states: Record<string, Token[]>` for each VariantGroup, and export the flat union as `allTokens: Token[]`. Components with linked siblings also build a `linkableContexts: Map<string, string>` (see the linked-siblings extension below). Components with structural/display controls that aren't token values (alignment, element visibility, layout position) also export an `intrinsics: IntrinsicSpec[]` (see the intrinsics extension below). In the runtime `<script>` block, mount `ComponentEditorBase` with one `VariantGroup` per variant.
-3. **Register** — in `src/main.ts` before `mount(App, ...)`:
+3. **Register** — pass the component to `bootLiveTokens` in `src/main.ts`. This is the standard boot the scaffold generates and the README documents; `bootLiveTokens` calls `registerComponent` internally at the right point — after its editor init hooks (`cssVarSync.init`, `editorStore.init`), before it seeds configs and mounts the app:
    ```ts
-   import { registerComponent } from '@motion-proto/live-tokens';
+   import { bootLiveTokens } from '@motion-proto/live-tokens';
+   import App from './App.svelte';
    import MyWidgetEditor, { allTokens as myWidgetTokens } from './system/components/MyWidgetEditor.svelte';
 
-   registerComponent({
-     id: 'mywidget',
-     label: 'My Widget',
-     icon: 'fas fa-magic',
-     sourceFile: 'src/system/components/MyWidget.svelte',
-     editorComponent: MyWidgetEditor,
-     schema: myWidgetTokens,
+   bootLiveTokens(App, '#app', {
+     components: [{
+       id: 'mywidget',
+       label: 'My Widget',
+       icon: 'fas fa-magic',
+       sourceFile: 'src/system/components/MyWidget.svelte',
+       editorComponent: MyWidgetEditor,
+       schema: myWidgetTokens,
+     }],
    });
    ```
-   The schema side-effect happens inside `registerComponent`, so you don't call `registerComponentSchema` separately.
+   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).
 5. **Verify** — open `/components` and run the verification checklist at the bottom of this file.
 
@@ -107,7 +110,17 @@ The authoritative recognised list lives in `bin/check-component.mjs` (`KNOWN_SUF
 - **Defaults reference theme tokens, never raw values.** `var(--surface-primary)` ✓ — `#6a4ce8` ✗.
 - **No abbreviations.** `bg` → `surface`; `fg` → `text`; component ids are never abbreviated.
 - **Text aliases.** Neutral scale is `--text-primary` / `--text-secondary` / `--text-tertiary` / `--text-muted` / `--text-disabled`. Family-tinted is `--text-primary-color`, `--text-accent`, `--text-success`. There is no `--text-neutral`.
-- **Typography `groupKey` on multi-slot components must include the slot prefix.** `groupKey: 'value-font-family'` and `groupKey: 'label-font-family'` ✓ — bare `groupKey: 'font-family'` silently merges them into one link tree ✗. Single-slot components can use a bare typography `groupKey`; add the slot prefix the moment a second slot appears.
+- **Typography `groupKey` on multi-slot components must include the slot prefix.** `groupKey: 'value-font-family'` and `groupKey: 'label-font-family'` ✓ — bare `groupKey: 'font-family'` silently merges them into one link tree ✗. Single-slot components can use a bare typography `groupKey`; add the slot prefix the moment a second slot appears. The same trap applies to type-group **colors** (two slots ending in `-text` collapsing to one `text` key). Let the helpers handle both: see "Deriving groupKeys" below.
+- **Let the type-group helpers derive slot-scoped keys; never rely on the bare last-dash default.** When you build typography tokens with `buildTypeGroupColorTokens` / `buildTypeGroupTokens` / `buildTypeGroupFontTokens`, **pass `{ component, variants }`** so each slot gets a distinct, structural `groupKey`:
+
+  ```ts
+  // variants = the variant/state segment strings as they appear in the variable name
+  const VARIANTS = ['default', 'hover'] as const;
+  ...buildTypeGroupColorTokens(typeGroups, { component, variants: [...VARIANTS] }),
+  ...buildTypeGroupFontTokens(typeGroups, { component, variants: [...VARIANTS] }),
+  ```
+
+  The helper strips the `--<component>-` prefix and those segments, keeping the rest: `--mywidget-header-default-text` → `header-text`, `--mywidget-header-default-text-font-family` → `header-text-font-family`. Two parts ending in the same word stay distinct; one slot across variants collapses to one key. To override a single derived key, set `colorGroupKey` on that type-group config — it wins and is never recomputed, so your fix survives. There is no name-based fallback: a bare `buildTypeGroupColorTokens` call emits un-grouped (solo) colors rather than guessing, and a bare *font* helper across multiple slots is a `check-component` warning (its default `font-family`/… keys would merge the slots' fonts).
 
 ### Linked siblings
 
@@ -158,7 +171,7 @@ import {
 import type { Token } from '@motion-proto/live-tokens/component-editor';
 ```
 
-That covers everything the worked examples use. Additional primitives (`LinkedBlock`, `TypeEditor`, `TokenLayout`, `buildTypeGroupTokens`, more types) are exported from the same paths for advanced cases.
+That covers everything the worked examples use. Additional primitives (`LinkedBlock`, `TypeEditor`, `TokenLayout`, `buildTypeGroupTokens`, `buildTypeGroupColorTokens`, `buildTypeGroupFontTokens`, `buildTypeGroupShareableContexts`, the `TypeGroupConfig` type, more types) are exported from the same paths for advanced cases.
 
 **Never deep-import `node_modules/@motion-proto/live-tokens/src/...`.** Reading those files for pattern reference is fine; importing them at runtime is not. If you need something not exported, file an issue rather than reaching in.
 
@@ -376,22 +389,23 @@ What to notice:
 ### Register: `src/main.ts`
 
 ```ts
-import { registerComponent } from '@motion-proto/live-tokens';
+import { bootLiveTokens } from '@motion-proto/live-tokens';
+import App from './App.svelte';
 import ToggleEditor, { allTokens as toggleTokens } from './system/components/ToggleEditor.svelte';
 
-registerComponent({
-  id: 'mytoggle',                                // unique id; don't reuse 'toggle'
-  label: 'My Toggle',
-  icon: 'fas fa-toggle-on',
-  sourceFile: 'src/system/components/Toggle.svelte',
-  editorComponent: ToggleEditor,
-  schema: toggleTokens,
+bootLiveTokens(App, '#app', {
+  components: [{
+    id: 'mytoggle',                                // unique id; don't reuse 'toggle'
+    label: 'My Toggle',
+    icon: 'fas fa-toggle-on',
+    sourceFile: 'src/system/components/Toggle.svelte',
+    editorComponent: ToggleEditor,
+    schema: toggleTokens,
+  }],
 });
-
-// then mount(App, ...)
 ```
 
-If you do this with `id: 'toggle'`, the consumer's component wins over the built-in (with a console warning). The collision rule protects you, but for a fresh component pick an id that doesn't collide.
+If your app mounts manually instead of via `bootLiveTokens`, call `registerComponent({ id: 'mytoggle', ... })` yourself before `mount(App, ...)`. If you reuse `id: 'toggle'`, the consumer's component wins over the built-in (with a console warning). The collision rule protects you, but for a fresh component pick an id that doesn't collide.
 
 ## Extension: linked siblings
 
@@ -530,7 +544,7 @@ npx live-tokens check-component <id>
 # or: npx @motion-proto/live-tokens check-component <id>
 ```
 
-It enforces the file layout, the `:global(:root)` block, token-suffix vocabulary, state-before-property rule, theme-token defaults (no raw colour literals), public-imports rule, and the `registerComponent({ id })` call. Exit code 0 means the static contract is met.
+It enforces the file layout, the `:global(:root)` block, token-suffix vocabulary, state-before-property rule, theme-token defaults (no raw colour literals), public-imports rule, and that the id is registered — via either `bootLiveTokens({ components: [{ id }] })` or a direct `registerComponent({ id })` call. It also *warns* (non-fatal) when a type-group font helper is called bare across multiple slots, which would merge their fonts into one link tree. Exit code 0 means the static contract is met; resolve warnings before shipping.
 
 **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:
 

package/bin/check-component.mjs

@@ -88,6 +88,28 @@ function detectStateAfterProperty(token) {
   return null;
 }
 
+// True if `source` calls `fnName(` at least once with a single argument (no
+// top-level comma before the matching close paren). Brackets/braces are balanced
+// so commas inside nested objects/arrays/calls don't count.
+function hasBareCall(source, fnName) {
+  const needle = fnName + '(';
+  let idx = 0;
+  while ((idx = source.indexOf(needle, idx)) !== -1) {
+    let i = idx + needle.length;
+    let depth = 1;
+    let topComma = false;
+    for (; i < source.length && depth > 0; i++) {
+      const c = source[i];
+      if (c === '(' || c === '[' || c === '{') depth++;
+      else if (c === ')' || c === ']' || c === '}') depth--;
+      else if (c === ',' && depth === 1) topComma = true;
+    }
+    if (!topComma) return true;
+    idx = i;
+  }
+  return false;
+}
+
 function findFilesRecursive(dir, exts) {
   if (!existsSync(dir)) return [];
   const out = [];
@@ -184,6 +206,27 @@ export function checkComponent(id, root = process.cwd()) {
     errors.push(`${relative(root, editorPath)}: missing 'export const allTokens'`);
   }
 
+  // Editor: phantom-link guard. The font type-group helpers fall back to bare
+  // `font-family`/`font-size`/… keys when called with a single argument (no
+  // derivation). Across more than one slot that silently links every slot's fonts
+  // into one tree. Passing `{ component, variants }` (a second arg) opts into
+  // distinct, structural keys and suppresses the check, so this only fires on the
+  // silent inference path. (The color helper no longer infers — a bare call there
+  // emits solo, un-grouped colors, which can't phantom-link.)
+  const colorPatterns = new Set();
+  for (const m of editor.matchAll(/colorVariable\s*:\s*[`'"]([^`'"]+)[`'"]/g)) {
+    colorPatterns.add(m[1].replace(/\$\{[^}]*\}/g, '*'));
+  }
+  const slots = colorPatterns.size;
+  const fontBare =
+    hasBareCall(editor, 'buildTypeGroupFontTokens') || hasBareCall(editor, 'buildTypeGroupTokens');
+  if (slots > 1 && fontBare) {
+    warnings.push(
+      `${relative(root, editorPath)}: a type-group font helper is called across ${slots} slots without a derivation; ` +
+        `its bare font-family/font-size/… keys would phantom-link every slot's fonts. Pass { component, variants } to buildTypeGroupTokens/buildTypeGroupFontTokens.`,
+    );
+  }
+
   // 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)) {
@@ -195,13 +238,18 @@ export function checkComponent(id, root = process.cwd()) {
     }
   }
 
-  // Registration: registerComponent({ id: '<id>', ... }) somewhere under src/.
+  // Registration: either a direct registerComponent({ id }) call or the id
+  // passed through bootLiveTokens({ components: [{ id }] }) — the standard
+  // scaffold boot. Accept both, 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');
+  const idLiteral = `id\\s*:\\s*['"]${id}['"]`;
+  const directPattern = new RegExp(`registerComponent\\s*\\(\\s*\\{[^}]*${idLiteral}`, 's');
+  const bootPattern = new RegExp(`bootLiveTokens\\s*\\([\\s\\S]*?components\\s*:\\s*\\[[\\s\\S]*?${idLiteral}`, 's');
   let registrationFile = null;
   for (const file of srcFiles) {
     try {
-      if (regPattern.test(readFileSync(file, 'utf8'))) {
+      const src = readFileSync(file, 'utf8');
+      if (directPattern.test(src) || bootPattern.test(src)) {
         registrationFile = file;
         break;
       }
@@ -210,7 +258,7 @@ export function checkComponent(id, root = process.cwd()) {
     }
   }
   if (!registrationFile) {
-    errors.push(`registerComponent({ id: '${id}', ... }) not found anywhere under src/`);
+    errors.push(`no registration for '${id}' under src/ — expected registerComponent({ id: '${id}', ... }) or bootLiveTokens({ components: [{ id: '${id}', ... }] })`);
   } else {
     // Check the registration file's imports too.
     const regSource = readFileSync(registrationFile, 'utf8');

package/dist-plugin/index.cjs

@@ -1114,6 +1114,13 @@ ${lines.join("\n")}
       } catch {
       }
     }
+    if (existingAliases) {
+      for (const [token, val] of Object.entries(existingAliases)) {
+        if (val !== null && typeof val === "object" && !(token in aliases)) {
+          aliases[token] = val;
+        }
+      }
+    }
     const aliasesUnchanged = existingAliases !== void 0 && JSON.stringify(existingAliases) === JSON.stringify(aliases);
     const defaultConfig = {
       name: "default",

package/dist-plugin/index.js

@@ -854,6 +854,13 @@ ${lines.join("\n")}
       } catch {
       }
     }
+    if (existingAliases) {
+      for (const [token, val] of Object.entries(existingAliases)) {
+        if (val !== null && typeof val === "object" && !(token in aliases)) {
+          aliases[token] = val;
+        }
+      }
+    }
     const aliasesUnchanged = existingAliases !== void 0 && JSON.stringify(existingAliases) === JSON.stringify(aliases);
     const defaultConfig = {
       name: "default",

package/package.json

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

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

@@ -54,7 +54,7 @@
   }
   export const allTokens: Token[] = variants.flatMap((v) => [
     ...variantTokens(v),
-    ...buildTypeGroupColorTokens(variantTypeGroups(v)),
+    ...buildTypeGroupColorTokens(variantTypeGroups(v), { component, variants: [...variants] }),
     ...variantTypeGroupTokens(v),
   ]);
 

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

@@ -80,7 +80,7 @@
   ]);
   export const allTokens: Token[] = [
     ...Object.values(states).flat(),
-    ...buildTypeGroupColorTokens(typeGroups),
+    ...buildTypeGroupColorTokens(typeGroups, { component, variants: ['default'] }),
     ...typeGroupTokens,
   ];
 </script>

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

@@ -93,7 +93,7 @@
 
   export const allTokens: Token[] = [
     ...VARIANTS.flatMap((v) => Object.values(variantStates(v)).flat()),
-    ...VARIANTS.flatMap((v) => buildTypeGroupColorTokens(variantTypeGroups(v))),
+    ...VARIANTS.flatMap((v) => buildTypeGroupColorTokens(variantTypeGroups(v), { component, variants: [...VARIANTS, ...HEADER_STATES] })),
     ...headerTypeGroupTokens,
   ];
 

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

@@ -78,7 +78,7 @@
 
   export const allTokens: Token[] = [
     ...Object.values(frameStates).flat(),
-    ...buildTypeGroupColorTokens(frameTypeGroups),
+    ...buildTypeGroupColorTokens(frameTypeGroups, { component }),
     ...frameTypeGroupTokens,
   ];
 

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

@@ -0,0 +1,81 @@
+<script module lang="ts">
+  import type { Token } from './scaffolding/types';
+  export const component = 'panel';
+
+  // Frame + the non-surface stage props render as ordinary token rows. The
+  // stage surface is a structured (tokenized) gradient edited via the
+  // GradientEditor below, so it lives outside the row list — `kind: 'gradient'`
+  // marks it as a structured payload and folds it back into `allTokens` for the
+  // schema without rendering a flat color row for it.
+  const states: Record<string, Token[]> = {
+    default: [
+      { label: 'border color',  variable: '--panel-frame-border',       element: 'frame' },
+      { label: 'border width',  variable: '--panel-frame-border-width', element: 'frame' },
+      { label: 'corner radius', variable: '--panel-frame-radius',       element: 'frame' },
+
+      { label: 'vertical padding', variable: '--panel-stage-padding',        splittable: false, element: 'stage' },
+      { label: 'side padding',     variable: '--panel-stage-inline-padding', splittable: false, element: 'stage' },
+      { label: 'content gap',      variable: '--panel-stage-gap',                               element: 'stage' },
+    ],
+  };
+  const surfaceToken: Token = {
+    label: 'surface',
+    variable: '--panel-stage-surface',
+    kind: 'gradient',
+    family: 'neutral',
+    element: 'stage',
+  };
+  export const allTokens: Token[] = [...Object.values(states).flat(), surfaceToken];
+</script>
+
+<script lang="ts">
+  import Panel from '../../system/components/Panel.svelte';
+  import VariantGroup from './scaffolding/VariantGroup.svelte';
+  import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
+  import GradientEditor from '../ui/GradientEditor.svelte';
+  import { componentGradientSource } from '../core/store/gradientSource';
+
+  const surfaceGradient = componentGradientSource(component, surfaceToken.variable);
+</script>
+
+<ComponentEditorBase
+  {component}
+  title="Panel"
+  description="Framed container with a tokenized border and gradient surface."
+  tokens={allTokens}
+>
+  <VariantGroup name="panel" title="Panel" {states} {component} elementOrder={['frame', 'stage']}>
+    {#snippet compositeControls(_stateName)}
+      <div class="panel-surface-section">
+        <GradientEditor
+          sectionLabel="Surface"
+          source={surfaceGradient}
+          stopIdPrefix="panel-surface"
+          familyFilter="neutral"
+        />
+      </div>
+    {/snippet}
+    {#snippet children()}
+      <div class="panel-demo">
+        <Panel minHeight="6rem">
+          <span class="demo-chip">Stage content</span>
+          <span class="demo-chip">Stage content</span>
+        </Panel>
+      </div>
+    {/snippet}
+  </VariantGroup>
+</ComponentEditorBase>
+
+<style>
+  .panel-demo {
+    width: 100%;
+    max-width: 34rem;
+  }
+  .demo-chip {
+    padding: var(--ui-space-4) var(--ui-space-8);
+    border: 1px solid var(--ui-border);
+    border-radius: var(--ui-radius-sm);
+    font-size: var(--ui-font-size-sm);
+    color: var(--ui-text-secondary);
+  }
+</style>

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

@@ -68,7 +68,7 @@
 
   export const allTokens: Token[] = [
     ...Object.values(states).flat(),
-    ...buildTypeGroupColorTokens(typeGroups),
+    ...buildTypeGroupColorTokens(typeGroups, { component }),
     ...typeGroupTokens,
   ];
 </script>

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

@@ -76,7 +76,7 @@
   ]);
   export const allTokens: Token[] = [
     ...Object.values(states).flat(),
-    ...buildTypeGroupColorTokens(typeGroups),
+    ...buildTypeGroupColorTokens(typeGroups, { component, variants: Object.keys(states) }),
     ...typeGroupTokens,
   ];
 </script>

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

@@ -165,7 +165,7 @@
       variants: ['lg', 'md', 'sm'],
       variable: (v) => `--sectiondivider-${v}-align`,
       values: ['start', 'center'],
-      default: { lg: 'start', md: 'start', sm: 'start' },
+      default: { lg: 'start', md: 'start', sm: 'center' },
     },
     {
       key: 'eyebrow-display',
@@ -193,7 +193,7 @@
       variants: ['lg', 'md', 'sm'],
       variable: (v) => `--sectiondivider-${v}-hairline`,
       values: ['none', ...HAIRLINE_POSITIONS],
-      default: { lg: 'below-description', md: 'below-label', sm: 'below-label' },
+      default: { lg: 'below-description', md: 'below-label', sm: 'none' },
       // 'above-description' renders identically to 'below-label'; the position
       // dropdown omits it, so coerce on read to keep the control's value valid.
       normalize: (raw) => (raw === 'above-description' ? 'below-label' : raw),

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

@@ -40,9 +40,9 @@
 
   // --- Title --------------------------------------------------------------
   // Title is a flex card containing the label box + toggle box. Per-state
-  // tokens drive the card chrome (surface, border, padding); stateless gap
-  // and radius live in `titleLayoutTokens` since they don't vary across
-  // default/hover/active.
+  // tokens drive the card chrome (surface, border, padding); the stateless
+  // bar + label-box structure lives in `titleBlockTokens` since it doesn't
+  // vary across default/hover/active.
   function titleStateTokens(s: StatefulState): Token[] {
     return [
       { label: 'surface color', groupKey: 'title-surface', variable: `--sidenavigation-title-${s}-surface` },
@@ -51,9 +51,16 @@
       { label: 'padding', canBeLinked: true, groupKey: 'title-padding', variable: `--sidenavigation-title-${s}-padding` },
     ];
   }
-  const titleLayoutTokens: Token[] = [
+  // Stateless title-bar structure ("Title Block" tab): the bar's own geometry
+  // plus the inner label box. Separate from the stateful Title tab because
+  // these don't vary by interaction state. Label-box rows are prefixed "label"
+  // to disambiguate from the bar's own corner radius.
+  const titleBlockTokens: Token[] = [
     { label: 'gap', canBeLinked: true, groupKey: 'title-gap', variable: '--sidenavigation-title-gap' },
     { label: 'corner radius', canBeLinked: true, groupKey: 'title-radius', variable: '--sidenavigation-title-radius' },
+    { label: 'label surface color', groupKey: 'title-label-surface', variable: '--sidenavigation-title-label-surface' },
+    { label: 'label corner radius', canBeLinked: true, groupKey: 'title-label-radius', variable: '--sidenavigation-title-label-radius' },
+    { label: 'label padding', canBeLinked: true, groupKey: 'title-label-padding', variable: '--sidenavigation-title-label-padding' },
   ];
   function titleStateTypeGroups(s: StatefulState): TypeGroupConfig[] {
     return [{
@@ -65,14 +72,6 @@
       lineHeightVariable: `--sidenavigation-title-${s}-label-line-height`,
     }];
   }
-  // Title label — structural inner box (stateless, like Panel). Sits inside
-  // the title bar so the header reads as: outer bar → [label box] [toggle box].
-  const titleLabelTokens: Token[] = [
-    { label: 'surface color', groupKey: 'title-label-surface', variable: '--sidenavigation-title-label-surface' },
-    { label: 'corner radius', canBeLinked: true, groupKey: 'title-label-radius', variable: '--sidenavigation-title-label-radius' },
-    { label: 'padding', canBeLinked: true, groupKey: 'title-label-padding', variable: '--sidenavigation-title-label-padding' },
-  ];
-
   const titleTypographyTokens: Token[] = STATEFUL_STATES.flatMap((s) => [
     { label: 'font family', canBeLinked: true, groupKey: 'title-label-font-family', variable: `--sidenavigation-title-${s}-label-font-family` },
     { label: 'font size', canBeLinked: true, groupKey: 'title-label-font-size', variable: `--sidenavigation-title-${s}-label-font-size` },
@@ -182,8 +181,7 @@
   const states: Record<string, Token[]> = {
     'Panel': panelTokens,
     ...Object.fromEntries(STATEFUL_STATES.map((s) => [`Title / ${STATE_LABELS[s]}`, titleStateTokens(s)])),
-    'Title Layout': titleLayoutTokens,
-    'Title Label': titleLabelTokens,
+    'Title Block': titleBlockTokens,
     ...Object.fromEntries(TOGGLE_STATES.map((s) => [`Toggle / ${STATE_LABELS[s]}`, toggleStateTokens(s)])),
     ...Object.fromEntries(STATEFUL_STATES.map((s) => [`Section / ${STATE_LABELS[s]}`, sectionStateTokens(s)])),
     ...Object.fromEntries(STATEFUL_STATES.map((s) => [`Item / ${STATE_LABELS[s]}`, itemStateTokens(s)])),
@@ -197,9 +195,14 @@
     ...Object.fromEntries(STATEFUL_STATES.map((s) => [`Footer / ${STATE_LABELS[s]}`, footerStateTypeGroups(s)])),
   };
 
+  // Color groupKeys derive structurally from the part+role: stripping the
+  // `--sidenavigation-` prefix and the state segment leaves `section-text`,
+  // `item-text`, `footer-text`, `title-label` — so the per-part text colors stay
+  // distinct instead of collapsing into one inferred `text` link group (which
+  // would phantom-link parts the per-part font groupKeys deliberately keep apart).
   export const allTokens: Token[] = [
     ...Object.values(states).flat(),
-    ...buildTypeGroupColorTokens(typeGroups),
+    ...buildTypeGroupColorTokens(typeGroups, { component, variants: [...STATEFUL_STATES] }),
     ...titleTypographyTokens,
     ...sectionTypographyTokens,
     ...itemTypographyTokens,

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

@@ -65,7 +65,7 @@
   ]);
   export const allTokens: Token[] = [
     ...Object.values(states).flat(),
-    ...buildTypeGroupColorTokens(typeGroups),
+    ...buildTypeGroupColorTokens(typeGroups, { component, variants: [...tabStateNames] }),
     ...tabTypeGroupTokens,
   ];
 

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

@@ -1,4 +1,5 @@
 <script module lang="ts">
+  import { buildTypeGroupColorTokens, buildTypeGroupFontTokens } from './scaffolding/buildTypeGroupTokens';
   import type { Token, TypeGroupConfig } from './scaffolding/types';
 
   export const component = 'table';
@@ -60,26 +61,16 @@
       lineHeightVariable: '--table-default-cell-line-height',
     }],
   };
-  // Hand-rolled (not buildTypeGroupColorTokens) because its suffix-derived groupKey would phantom-link header-text and cell-text.
-  const typeGroupColorTokens: Token[] = [
-    { label: 'color', groupKey: 'header-text', variable: '--table-default-header-text' },
-    { label: 'color', groupKey: 'cell-text', variable: '--table-default-cell-text' },
-  ];
-  const typeGroupTokens: Token[] = [
-    { label: 'font family', groupKey: 'header-font-family', variable: '--table-default-header-font-family' },
-    { label: 'font size', groupKey: 'header-font-size', variable: '--table-default-header-font-size' },
-    { label: 'font weight', groupKey: 'header-font-weight', variable: '--table-default-header-font-weight' },
-    { label: 'line height', groupKey: 'header-line-height', variable: '--table-default-header-line-height' },
-    { label: 'font family', groupKey: 'cell-font-family', variable: '--table-default-cell-font-family' },
-    { label: 'font size', groupKey: 'cell-font-size', variable: '--table-default-cell-font-size' },
-    { label: 'font weight', groupKey: 'cell-font-weight', variable: '--table-default-cell-font-weight' },
-    { label: 'line height', groupKey: 'cell-line-height', variable: '--table-default-cell-line-height' },
-  ];
+  // Structural derivation keeps header / cell text apart: stripping the `--table-`
+  // prefix and the `default` state segment leaves `header-text` / `cell-text` (and
+  // `header-font-family`, `cell-line-height`, …). A bare last-dash key would
+  // phantom-link header-text and cell-text into one `text` group.
+  const derivation = { component, variants: ['default'] } as const;
 
   export const allTokens: Token[] = [
     ...Object.values(states).flat(),
-    ...typeGroupColorTokens,
-    ...typeGroupTokens,
+    ...buildTypeGroupColorTokens(typeGroups, derivation),
+    ...buildTypeGroupFontTokens(typeGroups, derivation),
   ];
 </script>
 

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

@@ -35,7 +35,7 @@
   ];
   export const allTokens: Token[] = [
     ...Object.values(states).flat(),
-    ...buildTypeGroupColorTokens(typeGroups),
+    ...buildTypeGroupColorTokens(typeGroups, { component }),
     ...typeGroupTokens,
   ];
 </script>

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

@@ -14,7 +14,14 @@ export { buildSiblings } from './scaffolding/siblings';
 export type { Sibling } from './scaffolding/siblings';
 export { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
 export type { LinkedToken, LinkedGroup, LinkedBlockResult } from './scaffolding/linkedBlock';
-export { buildTypeGroupTokens } from './scaffolding/buildTypeGroupTokens';
+export {
+  buildTypeGroupTokens,
+  buildTypeGroupColorTokens,
+  buildTypeGroupFontTokens,
+  buildTypeGroupShareableContexts,
+  structuralGroupKey,
+} from './scaffolding/buildTypeGroupTokens';
+export type { TypeGroupConfig } from './scaffolding/types';
 
 // Token schema type — the shape of an entry in an editor's `allTokens` array.
 export type { Token } from './scaffolding/types';

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

@@ -16,6 +16,7 @@ import InlineEditActionsEditor, { allTokens as inlineEditActionsTokens } from '.
 import InputEditor, { allTokens as inputTokens } from './InputEditor.svelte';
 import MenuSelectEditor, { allTokens as menuSelectTokens } from './MenuSelectEditor.svelte';
 import NotificationEditor, { allTokens as notificationTokens } from './NotificationEditor.svelte';
+import PanelEditor, { allTokens as panelTokens } from './PanelEditor.svelte';
 import ProgressBarEditor, { allTokens as progressBarTokens } from './ProgressBarEditor.svelte';
 import RadioButtonEditor, { allTokens as radioButtonTokens } from './RadioButtonEditor.svelte';
 import SectionDividerEditor, { allTokens as sectionDividerTokens, intrinsics as sectionDividerIntrinsics } from './SectionDividerEditor.svelte';
@@ -43,6 +44,7 @@ type BuiltInComponentId =
   | 'inlineeditactions'
   | 'input'
   | 'menuselect'
+  | 'panel'
   | 'sectiondivider'
   | 'collapsiblesection'
   | 'sidenavigation'
@@ -223,6 +225,15 @@ const builtInRegistry: Readonly<Record<BuiltInComponentId, RegistryEntry>> = Obj
     schema: menuSelectTokens,
     origin: 'system',
   },
+  panel: {
+    id: 'panel',
+    label: 'Panel',
+    icon: 'fas fa-window-maximize',
+    sourceFile: 'src/system/components/Panel.svelte',
+    editorComponent: PanelEditor,
+    schema: panelTokens,
+    origin: 'system',
+  },
   sectiondivider: {
     id: 'sectiondivider',
     label: 'Section Divider',