@motion-proto/live-tokens 0.1.1 → 0.3.2

package/src/component-editor/TabBarEditor.svelte

@@ -0,0 +1,137 @@
+<script context="module" lang="ts">
+  import { buildTypeGroupColorTokens } from './scaffolding/buildTypeGroupTokens';
+  import type { Token, TypeGroupConfig } from './scaffolding/types';
+
+  export const component = 'tabbar';
+
+  // The tab object — four states (default/hover/active/disabled) of the same tab button.
+  const tabStateNames = ['default', 'hover', 'active', 'disabled'] as const;
+  type TabState = typeof tabStateNames[number];
+  function tabStateTokens(s: TabState): Token[] {
+    return [
+      { label: 'icon size', canBeLinked: true, groupKey: 'icon-size', variable: `--tabbar-${s}-icon-size` },
+      { label: 'padding', canBeLinked: true, groupKey: 'padding', variable: `--tabbar-${s}-padding` },
+      { label: 'surface color', groupKey: 'surface', variable: `--tabbar-${s}-surface` },
+      { label: 'top radius', canBeLinked: true, groupKey: 'tab-top-radius', variable: `--tabbar-${s}-tab-top-radius` },
+      { label: 'bottom radius', canBeLinked: true, groupKey: 'tab-bottom-radius', variable: `--tabbar-${s}-tab-bottom-radius` },
+      { label: 'border color', canBeLinked: true, groupKey: 'tab-border-color', variable: `--tabbar-${s}-tab-border-color` },
+      { label: 'border width', canBeLinked: true, groupKey: 'tab-border-width', variable: `--tabbar-${s}-tab-border-width` },
+    ];
+  }
+  function tabStateTypeGroups(s: TabState): TypeGroupConfig[] {
+    return [{
+      legend: 'tab text',
+      colorVariable: `--tabbar-${s}-text`,
+      familyVariable: `--tabbar-${s}-text-font-family`,
+      sizeVariable: `--tabbar-${s}-text-font-size`,
+      weightVariable: `--tabbar-${s}-text-font-weight`,
+      lineHeightVariable: `--tabbar-${s}-text-line-height`,
+    }];
+  }
+
+  // One VariantGroup with the bar exposed as a state alongside the three tab
+  // states (mirrors SegmentedControl's "control bar" + per-option states layout).
+  const states: Record<string, Token[]> = {
+    bar: [
+      { label: 'divider color', groupKey: 'bar-divider', variable: '--tabbar-bar-divider' },
+      { label: 'divider thickness', groupKey: 'bar-divider-thickness', variable: '--tabbar-bar-divider-thickness' },
+      { label: 'indicator thickness', groupKey: 'bar-indicator-thickness', variable: '--tabbar-bar-indicator-thickness' },
+      { label: 'space above', groupKey: 'bar-top-margin', variable: '--tabbar-bar-top-margin' },
+      { label: 'space below tabs', groupKey: 'bar-bottom-padding', variable: '--tabbar-bar-bottom-padding' },
+      { label: 'space under divider', groupKey: 'bar-bottom-margin', variable: '--tabbar-bar-bottom-margin' },
+      { label: 'tab gap', groupKey: 'tab-gap', variable: '--tabbar-tab-gap' },
+    ],
+    ...Object.fromEntries(tabStateNames.map((s) => [`${s} tab`, tabStateTokens(s)])),
+  };
+  states['active tab'] = [
+    ...states['active tab'],
+    { label: 'indicator color', groupKey: 'indicator-color', variable: '--tabbar-active-border' },
+  ];
+  const typeGroups: Record<string, TypeGroupConfig[]> = Object.fromEntries(
+    tabStateNames.map((s) => [`${s} tab`, tabStateTypeGroups(s)]),
+  );
+  const tabTypeGroupTokens: Token[] = tabStateNames.flatMap((s) => [
+    { label: 'font family', canBeLinked: true, groupKey: 'font-family', variable: `--tabbar-${s}-text-font-family` },
+    { label: 'font size', canBeLinked: true, groupKey: 'font-size', variable: `--tabbar-${s}-text-font-size` },
+    { label: 'font weight', canBeLinked: true, groupKey: 'font-weight', variable: `--tabbar-${s}-text-font-weight` },
+    { label: 'line height', canBeLinked: true, groupKey: 'line-height', variable: `--tabbar-${s}-text-line-height` },
+  ]);
+  export const allTokens: Token[] = [
+    ...Object.values(states).flat(),
+    ...buildTypeGroupColorTokens(typeGroups),
+    ...tabTypeGroupTokens,
+  ];
+
+  // Linking: shape props across tab states (same tab object).
+  const linkableContexts = new Map<string, string>([
+    [`--tabbar-active-border`, `active tab`] as const,
+    ...tabStateNames.flatMap((s) => [
+    [`--tabbar-${s}-tab-border-color`, `${s} tab`] as const,
+    [`--tabbar-${s}-tab-border-width`, `${s} tab`] as const,
+    [`--tabbar-${s}-tab-top-radius`, `${s} tab`] as const,
+    [`--tabbar-${s}-tab-bottom-radius`, `${s} tab`] as const,
+    [`--tabbar-${s}-padding`, `${s} tab`] as const,
+    [`--tabbar-${s}-icon-size`, `${s} tab`] as const,
+    [`--tabbar-${s}-text-font-family`, `${s} tab`] as const,
+    [`--tabbar-${s}-text-font-size`, `${s} tab`] as const,
+    [`--tabbar-${s}-text-font-weight`, `${s} tab`] as const,
+    [`--tabbar-${s}-text-line-height`, `${s} tab`] as const,
+  ]),
+  ]);
+</script>
+
+<script lang="ts">
+  import TabBar from '../components/TabBar.svelte';
+  import VariantGroup from './scaffolding/VariantGroup.svelte';
+  import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
+  import { editorState } from '../lib/editorStore';
+  import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
+
+  let selectedDemoTab = 'overview';
+  const demoTabs = [
+    { id: 'overview', label: 'Overview', icon: 'fas fa-home' },
+    { id: 'details', label: 'Details', icon: 'fas fa-info-circle' },
+    { id: 'settings', label: 'Settings', icon: 'fas fa-cog' },
+    { id: 'disabled', label: 'Disabled', icon: 'fas fa-ban', disabled: true },
+  ];
+
+  $: linked = computeLinkedBlock(component, linkableContexts, allTokens, $editorState);
+
+  $: visibleStates = Object.fromEntries(
+    Object.entries(states).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+  ) as Record<string, Token[]>;
+</script>
+
+<ComponentEditorBase {component} title="Tab Bar" description="Tab navigation with icon support and disabled state. Import from <code>components/TabBar.svelte</code>" tokens={allTokens} {linked}>
+  <VariantGroup
+    name="tabbar"
+    title="Tab Bar"
+    states={visibleStates}
+    {typeGroups}
+    {component}
+    let:activeState
+  >
+    {@const forceClass = activeState === 'hover tab' ? 'force-hover' : ''}
+    <TabBar tabs={demoTabs} selectedTab={selectedDemoTab} class={forceClass} on:tabChange={(e) => (selectedDemoTab = e.detail)} />
+    <div class="tab-content-demo">
+      {#if selectedDemoTab === 'overview'}
+        <p style="margin: 0;">Overview tab content</p>
+      {:else if selectedDemoTab === 'details'}
+        <p style="margin: 0;">Details tab content</p>
+      {:else if selectedDemoTab === 'settings'}
+        <p style="margin: 0;">Settings tab content</p>
+      {/if}
+    </div>
+  </VariantGroup>
+</ComponentEditorBase>
+
+<style>
+  .tab-content-demo {
+    padding: var(--space-16);
+    color: var(--ui-text-secondary);
+    background: var(--ui-surface-low);
+    border: 1px solid var(--ui-border-faint);
+    border-top: none;
+    border-radius: 0 0 var(--radius-md) var(--radius-md);
+  }
+</style>

package/src/component-editor/TableEditor.svelte

@@ -0,0 +1,128 @@
+<script context="module" lang="ts">
+  import type { Token, TypeGroupConfig } from './scaffolding/types';
+
+  export const component = 'table';
+
+  // Border colors and widths are linkable across wrapper/header/row/column so
+  // a user can lock "all lines on the table" to the same swatch + weight with
+  // one move, then break out individual surfaces when needed. Every other
+  // groupKey is slot-unique so header/cell/stripe stay independent — header bg
+  // vs zebra stripe, header pad vs cell pad, header text vs cell text all
+  // serve different visual roles. (Sharing a groupKey would silently declare
+  // them as siblings without surfacing the link in the LinkedBlock.)
+  const states: Record<string, Token[]> = {
+    wrapper: [
+      { label: 'border color', canBeLinked: true, groupKey: 'border', variable: '--table-default-border' },
+      { label: 'border width', canBeLinked: true, groupKey: 'width', variable: '--table-default-border-width' },
+      { label: 'corner radius', groupKey: 'radius', variable: '--table-default-radius' },
+      { label: 'table shadow', groupKey: 'shadow', variable: '--table-default-shadow' },
+    ],
+    header: [
+      { label: 'surface color', groupKey: 'header-surface', variable: '--table-default-header-surface' },
+      { label: 'border color', canBeLinked: true, groupKey: 'border', variable: '--table-default-header-border' },
+      { label: 'border width', canBeLinked: true, groupKey: 'width', variable: '--table-default-header-border-width' },
+      { label: 'padding', groupKey: 'header-padding', variable: '--table-default-header-padding' },
+    ],
+    cell: [
+      { label: 'padding', groupKey: 'cell-padding', variable: '--table-default-cell-padding' },
+    ],
+    row: [
+      { label: 'divider color', canBeLinked: true, groupKey: 'border', variable: '--table-default-row-divider' },
+      { label: 'divider width', canBeLinked: true, groupKey: 'width', variable: '--table-default-row-divider-width' },
+      { label: 'stripe surface', groupKey: 'row-stripe-surface', variable: '--table-default-row-stripe-surface' },
+    ],
+    column: [
+      { label: 'divider color', canBeLinked: true, groupKey: 'border', variable: '--table-default-column-divider' },
+      { label: 'divider width', canBeLinked: true, groupKey: 'width', variable: '--table-default-column-divider-width' },
+    ],
+  };
+
+  // State name is the context label so the LinkageChart rows read as
+  // wrapper/header/row/column for each shared groupKey.
+  const linkableContexts = new Map<string, string>(
+    Object.entries(states).flatMap(([state, tokens]) =>
+      tokens
+        .filter((t) => t.canBeLinked)
+        .map((t) => [t.variable, state] as [string, string]),
+    ),
+  );
+
+  const typeGroups: Record<string, TypeGroupConfig[]> = {
+    header: [{
+      legend: 'header text',
+      colorVariable: '--table-default-header-text',
+      familyVariable: '--table-default-header-font-family',
+      sizeVariable: '--table-default-header-font-size',
+      weightVariable: '--table-default-header-font-weight',
+      lineHeightVariable: '--table-default-header-line-height',
+    }],
+    cell: [{
+      legend: 'cell text',
+      colorVariable: '--table-default-cell-text',
+      familyVariable: '--table-default-cell-font-family',
+      sizeVariable: '--table-default-cell-font-size',
+      weightVariable: '--table-default-cell-font-weight',
+      lineHeightVariable: '--table-default-cell-line-height',
+    }],
+  };
+  // Slot-unique groupKeys keep header text and cell text independent. The
+  // generic `buildTypeGroupColorTokens` helper isn't used here because it
+  // derives groupKey from the variable's last-dash suffix, which collapses
+  // both `--table-...-header-text` and `--table-...-cell-text` onto a shared
+  // `text` groupKey — phantom-linking the two slots.
+  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' },
+  ];
+
+  export const allTokens: Token[] = [
+    ...Object.values(states).flat(),
+    ...typeGroupColorTokens,
+    ...typeGroupTokens,
+  ];
+</script>
+
+<script lang="ts">
+  import Table from '../components/Table.svelte';
+  import VariantGroup from './scaffolding/VariantGroup.svelte';
+  import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
+  import { editorState } from '../lib/editorStore';
+  import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
+
+  $: linked = computeLinkedBlock(component, linkableContexts, allTokens, $editorState);
+  $: visibleStates = Object.fromEntries(
+    Object.entries(states).map(([state, tokens]) => [state, withLinkedDisabled(tokens, linked.varSet)]),
+  ) as Record<string, Token[]>;
+</script>
+
+<ComponentEditorBase {component} title="Table" description="Styled wrapper around <code>&lt;table&gt;</code> with horizontal scroll on narrow viewports. Import from <code>components/Table.svelte</code>" tokens={allTokens} {linked}>
+  <VariantGroup name="table" title="Table" states={visibleStates} {typeGroups} {component}>
+    <Table>
+      <table>
+        <thead>
+          <tr>
+            <th>Resource</th>
+            <th>Yield</th>
+            <th>Tier</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr><td>Farmland</td><td>2 Food</td><td>I</td></tr>
+          <tr><td>Quarry</td><td>1 Stone</td><td>II</td></tr>
+          <tr><td>Mine</td><td>1 Ore</td><td>II</td></tr>
+          <tr><td>Forest</td><td>2 Lumber</td><td>I</td></tr>
+        </tbody>
+      </table>
+    </Table>
+  </VariantGroup>
+</ComponentEditorBase>

package/src/component-editor/TooltipEditor.svelte

@@ -0,0 +1,122 @@
+<script context="module" lang="ts">
+  import { buildTypeGroupColorTokens } from './scaffolding/buildTypeGroupTokens';
+  import type { Token, TypeGroupConfig } from './scaffolding/types';
+
+  export const component = 'tooltip';
+
+  // Tooltip is a single object — surface/border/padding/radius/shadow live together.
+  const states: Record<string, Token[]> = {
+    tooltip: [
+      { label: 'surface color', variable: '--tooltip-surface' },
+      { label: 'border color', variable: '--tooltip-border' },
+      { label: 'border width', groupKey: 'width', variable: '--tooltip-border-width' },
+      { label: 'corner radius', variable: '--tooltip-radius' },
+      { label: 'padding', variable: '--tooltip-padding' },
+      { label: 'tooltip shadow', variable: '--tooltip-shadow' },
+    ],
+  };
+
+  const typeGroups: Record<string, TypeGroupConfig[]> = {
+    tooltip: [{
+      legend: 'tooltip text',
+      colorVariable: '--tooltip-text',
+      familyVariable: '--tooltip-text-font-family',
+      sizeVariable: '--tooltip-text-font-size',
+      weightVariable: '--tooltip-text-font-weight',
+      lineHeightVariable: '--tooltip-text-line-height',
+    }],
+  };
+  const typeGroupTokens: Token[] = [
+    { label: 'font family', groupKey: 'family', variable: '--tooltip-text-font-family' },
+    { label: 'font size', groupKey: 'size', variable: '--tooltip-text-font-size' },
+    { label: 'font weight', groupKey: 'weight', variable: '--tooltip-text-font-weight' },
+    { label: 'line height', groupKey: 'height', variable: '--tooltip-text-line-height' },
+  ];
+  export const allTokens: Token[] = [
+    ...Object.values(states).flat(),
+    ...buildTypeGroupColorTokens(typeGroups),
+    ...typeGroupTokens,
+  ];
+</script>
+
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import Tooltip from '../components/Tooltip.svelte';
+  import VariantGroup from './scaffolding/VariantGroup.svelte';
+  import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
+  import ShadowBackdrop from './scaffolding/ShadowBackdrop.svelte';
+  import UIPaletteSelector from '../ui/UIPaletteSelector.svelte';
+  import { setCssVar } from '../lib/cssVarSync';
+
+  const bgVar = '--backdrop-tooltip-surface';
+  const hintText = 'Helpful Hint';
+
+  onMount(() => {
+    if (!document.documentElement.style.getPropertyValue(bgVar)) {
+      setCssVar(bgVar, 'var(--surface-canvas)');
+    }
+  });
+</script>
+
+<ComponentEditorBase {component} title="Tooltip" description="Hover tooltip with configurable position. Import from <code>components/Tooltip.svelte</code>" tokens={allTokens}>
+  <svelte:fragment slot="config">
+    <label class="backdrop-config">
+      <span>Sample background</span>
+      <div class="picker-slot">
+        <UIPaletteSelector variable={bgVar} />
+      </div>
+    </label>
+  </svelte:fragment>
+  <VariantGroup
+    name="tooltip"
+    title="Tooltip"
+    {states}
+    {typeGroups}
+    {component}
+  >
+    <ShadowBackdrop mode="color" colorVariable={bgVar}>
+      <div class="tooltip-demo-row">
+        <Tooltip text={hintText} open>
+          <span class="tooltip-demo-target">Helpful Hint</span>
+        </Tooltip>
+        <Tooltip text={hintText} position="bottom">
+          <span class="tooltip-demo-target">Hover me</span>
+        </Tooltip>
+      </div>
+    </ShadowBackdrop>
+  </VariantGroup>
+</ComponentEditorBase>
+
+<style>
+  .tooltip-demo-row {
+    display: flex;
+    gap: var(--space-48);
+    align-items: flex-start;
+    justify-content: center;
+    padding: var(--space-48) 0;
+  }
+
+  .tooltip-demo-target {
+    display: inline-block;
+    padding: var(--space-8) var(--space-16);
+    color: var(--ui-text-secondary);
+    font-size: var(--font-size-sm);
+    border: 1px dashed var(--ui-border-subtle);
+    border-radius: var(--radius-sm);
+    background: transparent;
+  }
+
+  .backdrop-config {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ui-space-8);
+  }
+
+  .picker-slot {
+    min-width: 8rem;
+  }
+
+  .picker-slot :global(.ui-token-selector) {
+    width: 100%;
+  }
+</style>

package/src/component-editor/editorTokens.test.ts

@@ -0,0 +1,93 @@
+// @vitest-environment node
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildTokenRegistry, extractGlobalRootBody } from '../lib/tokenRegistry';
+import { componentRegistryEntries } from './registry';
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const TOKENS_CSS = join(TEST_DIR, '..', 'styles', 'tokens.css');
+const COMPONENTS_DIR = join(TEST_DIR, '..', 'components');
+
+// Vitest's CSS plugin swallows `?raw` imports for .css files, so we build the
+// registry from an fs-loaded snapshot rather than going through the default
+// module export. Layer-2 tokens now live in each component's <style> block
+// under `:global(:root)`; merge those bodies with tokens.css to match the
+// runtime registry.
+const tokensSource = readFileSync(TOKENS_CSS, 'utf8');
+const componentTokenCss = readdirSync(COMPONENTS_DIR)
+  .filter((f) => f.endsWith('.svelte'))
+  .map((f) => extractGlobalRootBody(readFileSync(join(COMPONENTS_DIR, f), 'utf8')))
+  .join('\n');
+const registry = buildTokenRegistry(tokensSource + '\n' + componentTokenCss);
+
+/** Test whether a variable name fits a layer-1 design-token naming pattern. */
+function isLayer1TokenName(name: string): boolean {
+  // Color ramps: --color-<palette>-<step>  OR semantic color primitives: --color-<name>
+  if (/^--color-[a-z]+(-\d{3})?$/.test(name)) return true;
+  if (/^--surface-[a-z]+(-[a-z]+)?$/.test(name)) return true;
+  if (/^--border-[a-z]+(-[a-z]+)?$/.test(name)) return true;
+  if (/^--text-[a-z]+(-[a-z]+)?$/.test(name)) return true;
+  if (/^--(radius|space|font|line-height|shadow|ring|transition|overlay|hover|page-bg|border-width|gradient|icon-size|blur|dot-size)(-[a-z0-9]+)*$/.test(name)) return true;
+  return false;
+}
+
+// Drives both describe blocks: one entry per (component, variable) pair pulled
+// from each editor's exported `allTokens`. This is the authoritative surface —
+// includes template-literal-built tokens (Button, SegmentedControl, etc.) and
+// typography colorVariables that the previous source-regex approach silently
+// missed. See registry.ts for how each editor exports its full token list via
+// `<script context="module">`.
+const editorTokenCases: Array<{ editor: string; variable: string }> = [];
+for (const entry of componentRegistryEntries) {
+  for (const t of entry.schema) {
+    // `hidden: true` tokens are optional override slots (e.g. split-padding's
+    // per-side overrides used as `var(--x, fallback)` by the themed-padding
+    // mixin) — they don't need a default declaration in tokens.css.
+    if ((t as { hidden?: boolean }).hidden) continue;
+    editorTokenCases.push({ editor: entry.id, variable: t.variable });
+  }
+}
+
+describe('design-token architecture', () => {
+  it('has editor schemas to inspect', () => {
+    expect(editorTokenCases.length).toBeGreaterThan(0);
+  });
+
+  describe('every editor-exposed variable resolves to a design token', () => {
+    for (const { editor, variable } of editorTokenCases) {
+      it(`${editor}: ${variable} resolves via alias chain to a layer-1 token`, () => {
+        const chain = registry.resolveAliasChain(variable);
+        const terminal = chain[chain.length - 1];
+        expect(
+          isLayer1TokenName(terminal),
+          `${variable} → [${chain.join(' → ')}]; terminal "${terminal}" is not a design-token name. ` +
+            `Either rename the target or add a var() alias declaration in tokens.css.`,
+        ).toBe(true);
+      });
+    }
+  });
+
+  // Every variable an editor binds must be declared in tokens.css (or a
+  // component <style> :global(:root) block) as a var() alias — not a literal,
+  // not a raw primitive. Component properties bind to component-scoped Layer-2
+  // aliases so editing one component never rebinds a shared primitive used
+  // elsewhere.
+  describe('every editor follows the component-token pattern', () => {
+    for (const { editor, variable } of editorTokenCases) {
+      it(`${editor}: ${variable} is a layer-2 component token (declared as var() alias)`, () => {
+        const declared = registry.getDeclaredValue(variable);
+        expect(
+          declared,
+          `${variable} is referenced by ${editor} but not declared in tokens.css`,
+        ).not.toBeNull();
+        expect(
+          declared!.startsWith('var('),
+          `${variable} should be a component-scoped alias declared as var(--primitive); got "${declared}". ` +
+            `Component properties must not rebind shared primitives directly.`,
+        ).toBe(true);
+      });
+    }
+  });
+});

package/src/component-editor/groupKeySlots.test.ts

@@ -0,0 +1,67 @@
+// @vitest-environment node
+//
+// Slot-collision invariant for editor schemas.
+//
+// A groupKey declares a sibling set: tokens that share a groupKey are linked
+// peers (`getComponentPropertySiblings`, `isComponentPropertyLinked`,
+// `setComponentAliasLinked`). The codebase convention (src/styles/CONVENTIONS.md)
+// requires shared groupKeys to cross only a VARIANT axis — never a slot/part
+// axis. Crossing slots produces "phantom siblings": the schema reports header
+// and cell as linked peers, but the linked block can't surface them because
+// the editor's `linkableContexts` (correctly) treats them as independent.
+//
+// `registerComponentSchema` already warns at runtime when a typography
+// groupKey covers multiple slots (e.g. one groupKey holding both
+// `--card-...-title-font-family` and `--card-...-body-font-family`). This
+// test asserts the invariant instead of relying on a console warning that
+// nothing fails on.
+//
+// Caught the TableEditor regression where `header` and `cell` typography
+// shared `family`/`size`/`weight`/`height` groupKeys (and `surface`/`padding`
+// shared groupKeys across header/stripe and header/cell respectively). See
+// the commit that introduced this test for context.
+
+import { describe, it, expect } from 'vitest';
+import { componentRegistryEntries } from './registry';
+
+const TYPOGRAPHY_PROP_SUFFIXES = ['font-family', 'font-size', 'font-weight', 'line-height'] as const;
+
+/** Mirror of `typographySlotOf` in `lib/slices/components.ts`. */
+function typographySlotOf(varName: string): string | null {
+  for (const suffix of TYPOGRAPHY_PROP_SUFFIXES) {
+    if (!varName.endsWith('-' + suffix)) continue;
+    const head = varName.slice(0, -(suffix.length + 1));
+    const lastDash = head.lastIndexOf('-');
+    if (lastDash < 0) return null;
+    return head.slice(lastDash + 1);
+  }
+  return null;
+}
+
+describe('editor groupKey slot invariant', () => {
+  for (const entry of componentRegistryEntries) {
+    it(`${entry.id}: no typography groupKey straddles multiple slots`, () => {
+      const byKey = new Map<string, string[]>();
+      for (const t of entry.schema as Array<{ variable: string; groupKey?: string }>) {
+        if (!t.groupKey) continue;
+        const list = byKey.get(t.groupKey) ?? [];
+        list.push(t.variable);
+        byKey.set(t.groupKey, list);
+      }
+      const violations: string[] = [];
+      for (const [gk, vars] of byKey) {
+        const slots = new Set<string>();
+        for (const v of vars) {
+          const slot = typographySlotOf(v);
+          if (slot) slots.add(slot);
+        }
+        if (slots.size > 1) {
+          violations.push(
+            `groupKey "${gk}" spans typography slots {${[...slots].join(', ')}}: ${vars.join(', ')}`,
+          );
+        }
+      }
+      expect(violations, violations.join('\n')).toEqual([]);
+    });
+  }
+});

package/src/component-editor/groupKeySnapshot.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Locks the per-component sibling-group topology in place during the migration
+ * away from `getGroupKey`'s last-dash fallback.
+ *
+ * Workflow:
+ *   1. Snapshot current behavior: `UPDATE_SNAPSHOT=1 pnpm test groupKeySnapshot`
+ *      writes `temp/groupkey-snapshot.json` (groupKey → variables, per component).
+ *   2. Migrate: add explicit `groupKey` to every token that previously relied on
+ *      the legacy fallback; delete the fallback branch in `getGroupKey`.
+ *   3. Re-run this test (no env var) — must produce the same JSON.
+ *
+ * Once the migration is complete and verified, delete this file.
+ */
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { componentRegistryEntries } from './registry';
+
+const SNAPSHOT_PATH = path.resolve(__dirname, '../../temp/groupkey-snapshot.json');
+
+/** Mirrors the *post-migration* getGroupKey logic — schema only, no fallback. */
+function effectiveGroupKey(_component: string, _variable: string, explicit: string | undefined): string | null {
+  return explicit ?? null;
+}
+
+function computeSnapshot(): Record<string, Record<string, string[]>> {
+  const out: Record<string, Record<string, string[]>> = {};
+  for (const entry of componentRegistryEntries) {
+    const groups: Record<string, string[]> = {};
+    for (const t of entry.schema as Array<{ variable: string; groupKey?: string }>) {
+      const gk = effectiveGroupKey(entry.id, t.variable, t.groupKey);
+      if (!gk) continue;
+      (groups[gk] ||= []).push(t.variable);
+    }
+    for (const k of Object.keys(groups)) groups[k].sort();
+    out[entry.id] = Object.fromEntries(Object.entries(groups).sort(([a], [b]) => a.localeCompare(b)));
+  }
+  return out;
+}
+
+describe('groupKey topology snapshot', () => {
+  it('matches the committed snapshot', () => {
+    const computed = computeSnapshot();
+    if (process.env.UPDATE_SNAPSHOT === '1') {
+      fs.mkdirSync(path.dirname(SNAPSHOT_PATH), { recursive: true });
+      fs.writeFileSync(SNAPSHOT_PATH, JSON.stringify(computed, null, 2) + '\n');
+      return;
+    }
+    const expected = JSON.parse(fs.readFileSync(SNAPSHOT_PATH, 'utf-8'));
+    expect(computed).toEqual(expected);
+  });
+});

package/src/component-editor/index.ts

@@ -0,0 +1,5 @@
+export { default as ComponentsTab } from './scaffolding/ComponentsTab.svelte';
+export type { ComponentSection } from './scaffolding/componentSectionType';
+export { defaultSections } from './scaffolding/defaultSections';
+
+export { default as TokenLayout } from './scaffolding/TokenLayout.svelte';