@motion-proto/live-tokens 0.24.0 → 0.24.2

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

@@ -24,7 +24,7 @@ For pattern reference, read any shipped component's source directly from the con
 ## 4-step recipe
 
 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). In the runtime `<script>` block, mount `ComponentEditorBase` with one `VariantGroup` per variant.
+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, ...)`:
    ```ts
    import { registerComponent } from '@motion-proto/live-tokens';
@@ -462,6 +462,65 @@ Toggle's tokens are flat per state. Most multi-variant components (Badge, Card,
 
 Single-variant components with multi-state linked tokens still set `canBeLinked` + `linkableContexts`, but skip `buildSiblings` and the `{#each}` loop. Components with no linked tokens (Toggle, SectionDivider) skip all five steps — `ComponentEditorBase` renders fine without a `{linked}` prop.
 
+## Extension: intrinsics
+
+Some components expose **structural or display choices** that aren't token values: an alignment (start / center), an element's visibility (show / hide), a layout position. These ride a bespoke `<select>` or checkbox you author in an editor snippet, not the generic token grid, so they don't belong in `allTokens`. Toggle and most components have none. SectionDivider is the worked example (alignment, hairline position, eyebrow / description visibility).
+
+An intrinsic still cascades through a CSS custom property with a default in the runtime `:global(:root)`. The trap: that default now lives in two places, the runtime `:global(:root)` AND the editor's read-back getter. When they disagree the control displays a state the page never renders, and a native `<select>` won't even fire `onchange` to write the "change" the user thinks they made. `:global(:root)` is the source of truth.
+
+Declare intrinsics so the editor and the contract test stay honest:
+
+1. **Runtime `:global(:root)`** carries the per-variant default like any other variable:
+
+   ```css
+   --mywidget-lg-align: start;
+   --mywidget-lg-eyebrow-display: block;
+   ```
+
+2. **Editor `<script module>`** exports `intrinsics: IntrinsicSpec[]`, one entry per structural property, each `default` mirroring `:global(:root)` per variant:
+
+   ```ts
+   import type { IntrinsicSpec } from '@motion-proto/live-tokens/component-editor';
+
+   export const intrinsics: IntrinsicSpec[] = [
+     {
+       key: 'align',
+       variants: ['lg', 'md', 'sm'],
+       variable: (v) => `--mywidget-${v}-align`,
+       values: ['start', 'center'],
+       default: { lg: 'start', md: 'start', sm: 'start' },
+     },
+   ];
+   ```
+
+3. **Read-back getters fall back to the spec default**, never a hard-coded constant. This is the rule that keeps the control's displayed default in step with what an unedited instance renders:
+
+   ```ts
+   const byKey = new Map(intrinsics.map((i) => [i.key, i]));
+   function readIntrinsic(key: string, v: string): string {
+     const spec = byKey.get(key)!;
+     const raw = readLiteral(spec.variable(v)) ?? spec.default[v];   // store override, else runtime default
+     return spec.normalize ? spec.normalize(raw) : raw;
+   }
+   function getAlign(v: string) {
+     return readIntrinsic('align', v) === 'center' ? 'center' : 'start';
+   }
+   ```
+
+   Writes go through `setComponentAlias(component, spec.variable(v), { kind: 'literal', value })` so the choice cascades to `:root` like any token.
+
+4. **Pass `intrinsics` to `registerComponent`** so the contract test can see it:
+
+   ```ts
+   registerComponent({
+     id: 'mywidget',
+     // ...label, icon, sourceFile, editorComponent, schema...
+     intrinsics: myWidgetIntrinsics,
+   });
+   ```
+
+Use `normalize` only when two raw values render identically and the dropdown lists just one (SectionDivider folds `above-description` into `below-label`). Properties that look like intrinsics but aren't: preview-only props with no persistence (a size selector that only changes the demo), `setComponentConfig` editor metadata (Dialog's button variants), and token-valued selects (a control choosing between two tokens). None carry a duplicated runtime default, so none need an `IntrinsicSpec`.
+
 ## Verification checklist
 
 After saving, run the static validator first:
@@ -483,6 +542,8 @@ It enforces the file layout, the `:global(:root)` block, token-suffix vocabulary
 
 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).
 
+**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.
+
 Finally navigate to `/components` and confirm the runtime behaviours no static check can see:
 
 - [ ] The new component appears in the nav rail under the **CUSTOM** group (system entries above, custom below the labeled divider).

package/package.json

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

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

@@ -1,6 +1,6 @@
 <script module lang="ts">
   import { buildSiblings } from './scaffolding/siblings';
-  import type { Token, TypeGroupConfig } from './scaffolding/types';
+  import type { Token, TypeGroupConfig, IntrinsicSpec } from './scaffolding/types';
 
   export const component = 'sectiondivider';
 
@@ -149,6 +149,57 @@
     | 'above-description'
     | 'through-description'
     | 'below-description';
+
+  // Structural/display properties driven by the bespoke selects + element
+  // toggles below, not the token grid. Each `default` mirrors the runtime
+  // SectionDivider's `:global(:root)`; the read-back getters fall back to it
+  // when a variant is unedited, and intrinsicsContract.test pins the two
+  // copies together. Defaults are per-variant: lg ships eyebrow + description
+  // + a description-anchored hairline; md/sm ship the title alone.
+  const HAIRLINE_POSITIONS = [
+    'above-label', 'through-label', 'below-label', 'through-description', 'below-description',
+  ] as const;
+  export const intrinsics: IntrinsicSpec[] = [
+    {
+      key: 'align',
+      variants: ['lg', 'md', 'sm'],
+      variable: (v) => `--sectiondivider-${v}-align`,
+      values: ['start', 'center'],
+      default: { lg: 'start', md: 'start', sm: 'start' },
+    },
+    {
+      key: 'eyebrow-display',
+      variants: ['lg', 'md', 'sm'],
+      variable: (v) => `--sectiondivider-${v}-eyebrow-display`,
+      values: ['block', 'none'],
+      default: { lg: 'block', md: 'none', sm: 'none' },
+    },
+    {
+      key: 'description-display',
+      variants: ['lg', 'md', 'sm'],
+      variable: (v) => `--sectiondivider-${v}-description-display`,
+      values: ['flex', 'none'],
+      default: { lg: 'flex', md: 'none', sm: 'none' },
+    },
+    {
+      key: 'eyebrow-text-transform',
+      variants: ['lg', 'md', 'sm'],
+      variable: (v) => `--sectiondivider-${v}-eyebrow-text-transform`,
+      values: ['uppercase', 'none'],
+      default: { lg: 'none', md: 'none', sm: 'none' },
+    },
+    {
+      key: 'hairline',
+      variants: ['lg', 'md', 'sm'],
+      variable: (v) => `--sectiondivider-${v}-hairline`,
+      values: ['none', ...HAIRLINE_POSITIONS],
+      default: { lg: 'below-description', md: 'below-label', sm: 'below-label' },
+      // '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),
+    },
+  ];
+  const INTRINSIC_BY_KEY = new Map(intrinsics.map((i) => [i.key, i]));
 </script>
 
 <script lang="ts">
@@ -191,8 +242,19 @@
     return ref.value;
   }
 
+  // Resolved raw intrinsic value: the stored override, else the spec's
+  // per-variant default (which mirrors the runtime :root). Normalized so the
+  // getters below branch on a canonical value. Falling back to the spec
+  // default — not a hard-coded constant — is what keeps each control's
+  // displayed default in step with what the unedited divider actually renders.
+  function readIntrinsic(key: string, v: Variant): string {
+    const spec = INTRINSIC_BY_KEY.get(key)!;
+    const raw = readLiteral(spec.variable(v)) ?? spec.default[v];
+    return spec.normalize ? spec.normalize(raw) : raw;
+  }
+
   function getAlign(v: Variant): Align {
-    return readLiteral(`--sectiondivider-${v}-align`) === 'start' ? 'start' : 'center';
+    return readIntrinsic('align', v) === 'center' ? 'center' : 'start';
   }
   function getColorFamily(v: Variant): string {
     const raw = cfg[`--sectiondivider-${v}-color-family`];
@@ -201,13 +263,9 @@
   }
   /** Active hairline position OR `'none'` (= hidden). */
   function getHairlineValue(v: Variant): HairlinePosition | 'none' {
-    const raw = readLiteral(`--sectiondivider-${v}-hairline`);
-    if (raw === undefined || raw === 'none') return 'none';
-    // 'above-description' renders identically to 'below-label' — coerce on read
-    // so the dropdown's option list (which omits 'above-description') stays valid.
-    if (raw === 'above-description') return 'below-label';
-    const positions: HairlinePosition[] = ['above-label', 'through-label', 'below-label', 'through-description', 'below-description'];
-    return (positions as string[]).includes(raw) ? (raw as HairlinePosition) : 'none';
+    const raw = readIntrinsic('hairline', v);
+    if (raw === 'none') return 'none';
+    return (HAIRLINE_POSITIONS as readonly string[]).includes(raw) ? (raw as HairlinePosition) : 'none';
   }
   function getShowHairline(v: Variant): boolean {
     return getHairlineValue(v) !== 'none';
@@ -220,17 +278,13 @@
     return val === 'none' ? 'above-label' : val;
   }
   function getShowEyebrow(v: Variant): boolean {
-    return readLiteral(`--sectiondivider-${v}-eyebrow-display`) === 'block';
+    return readIntrinsic('eyebrow-display', v) === 'block';
   }
   function getEyebrowUppercase(v: Variant): boolean {
-    return readLiteral(`--sectiondivider-${v}-eyebrow-text-transform`) === 'uppercase';
+    return readIntrinsic('eyebrow-text-transform', v) === 'uppercase';
   }
   function getShowDescription(v: Variant): boolean {
-    const raw = readLiteral(`--sectiondivider-${v}-description-display`);
-    // Default: shown (flex) when unset. Matches the :root default and the
-    // legacy `getShowDescription` semantics for files that never set the key.
-    if (raw === undefined) return true;
-    return raw === 'flex';
+    return readIntrinsic('description-display', v) !== 'none';
   }
   /** Write an intrinsic to the aliases bucket as a literal so it cascades
    *  through cssVarSync to `:root` on both the editor iframe and host page. */
@@ -391,8 +445,8 @@
             value={getAlign(v.key)}
             onchange={(e) => setIntrinsic(v.key, 'align', (e.currentTarget as HTMLSelectElement).value)}
           >
-            <option value="center">Center</option>
             <option value="start">Start</option>
+            <option value="center">Center</option>
           </select>
         </div>
         <div class="property-row sd-intrinsic-row">

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

@@ -18,3 +18,7 @@ export { buildTypeGroupTokens } from './scaffolding/buildTypeGroupTokens';
 
 // Token schema type — the shape of an entry in an editor's `allTokens` array.
 export type { Token } from './scaffolding/types';
+
+// Intrinsic spec — structural/display props an editor drives outside the token
+// grid (alignment, visibility). Pass an array as `registerComponent({ intrinsics })`.
+export type { IntrinsicSpec } from './scaffolding/types';

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

@@ -1,5 +1,5 @@
 import type { Component } from 'svelte';
-import type { Token } from './scaffolding/types';
+import type { Token, IntrinsicSpec } from './scaffolding/types';
 import { registerComponentSchema } from '../core/store/editorStore';
 
 import BadgeEditor, { allTokens as badgeTokens } from './BadgeEditor.svelte';
@@ -18,7 +18,7 @@ import MenuSelectEditor, { allTokens as menuSelectTokens } from './MenuSelectEdi
 import NotificationEditor, { allTokens as notificationTokens } from './NotificationEditor.svelte';
 import ProgressBarEditor, { allTokens as progressBarTokens } from './ProgressBarEditor.svelte';
 import RadioButtonEditor, { allTokens as radioButtonTokens } from './RadioButtonEditor.svelte';
-import SectionDividerEditor, { allTokens as sectionDividerTokens } from './SectionDividerEditor.svelte';
+import SectionDividerEditor, { allTokens as sectionDividerTokens, intrinsics as sectionDividerIntrinsics } from './SectionDividerEditor.svelte';
 import SegmentedControlEditor, { allTokens as segmentedControlTokens } from './SegmentedControlEditor.svelte';
 import SideNavigationEditor, { allTokens as sideNavigationTokens } from './SideNavigationEditor.svelte';
 import TableEditor, { allTokens as tableTokens } from './TableEditor.svelte';
@@ -72,6 +72,10 @@ export interface RegistryEntry {
   editorComponent: Component<any, any, any>;
   /** Flat token list — the editor's declarative description of its token surface. */
   schema: Token[];
+  /** Structural/display properties controlled outside the token grid. Optional —
+      most components have none. When present, each spec's per-variant default is
+      pinned to the runtime `:global(:root)` by intrinsicsContract.test. */
+  intrinsics?: IntrinsicSpec[];
   /** `'system'` for first-party entries; `'custom'` for entries added via `registerComponent()`. */
   origin: 'system' | 'custom';
 }
@@ -226,6 +230,7 @@ const builtInRegistry: Readonly<Record<BuiltInComponentId, RegistryEntry>> = Obj
     sourceFile: 'src/system/components/SectionDivider.svelte',
     editorComponent: SectionDividerEditor,
     schema: sectionDividerTokens,
+    intrinsics: sectionDividerIntrinsics,
     origin: 'system',
   },
   collapsiblesection: {

package/src/editor/component-editor/scaffolding/types.ts

@@ -36,6 +36,31 @@ export type Token = {
   family?: string;
 };
 
+/** An intrinsic: a structural/display property (alignment, hairline position,
+    element visibility) driven by a bespoke editor control rather than the
+    generic token grid. Unlike a Token it carries the default twice — once in
+    the runtime component's `:global(:root)` and once in the editor's read-back
+    (`default` below, which the getters fall back to when unset). Those two
+    copies must agree or the control displays a state the page doesn't render
+    (the SectionDivider align bug). The intrinsics contract test pins them. */
+export type IntrinsicSpec = {
+  /** Stable id, used in diagnostics and to key getters off the spec. */
+  key: string;
+  /** Variant keys this intrinsic spans (e.g. ['lg','md','sm']). */
+  variants: string[];
+  /** Per-variant CSS custom property. */
+  variable: (variant: string) => string;
+  /** Allowed raw values; the runtime `:root` default must be one of these. */
+  values: string[];
+  /** Editor's unset-default raw value per variant — the read-back getters
+      source their default from here. Pinned to the runtime `:global(:root)`
+      default by the intrinsics contract test. */
+  default: Record<string, string>;
+  /** Folds render-equivalent raw values to one canonical form before
+      comparison (e.g. SectionDivider's 'above-description' ≡ 'below-label'). */
+  normalize?: (raw: string) => string;
+};
+
 /** Editor type-group: a fieldset containing a coordinated set of typography tokens
     (text color + font-family/size/weight/line-height) for a piece of content
     (e.g. a card title, notification body). Optional outline rows let

package/src/system/components/FloatingTokenTags.css

@@ -183,7 +183,7 @@
     #b1b2b2 62%,
     #626363 100%
   );
-  color: rgba(0, 0, 0, 0.88);
+  color: #000;
   border: 1px solid rgba(255, 255, 255, 0.55);
   border-radius: 9999px;
   font-family: Manrope, system-ui, -apple-system, sans-serif;