@motion-proto/live-tokens 0.6.2 → 0.8.0

package/src/{components → system/components}/SegmentedControl.svelte

@@ -126,7 +126,22 @@
     border-radius: var(--segmentedcontrol-bar-radius);
   }
 
+  /* Font + color properties are declared once on `.segment` and rebound per
+     state via the `--_*` custom properties below. State classes only change
+     the bindings; the actual `font-*` declarations never move. When two
+     states resolve to the same final value the computed font is identical
+     and the browser has no reason to re-shape — which is what kept the
+     selected segment shifting by a whole pixel even after the border was
+     swapped for an outline. */
   .segment {
+    --_text-color: var(--segmentedcontrol-option-text);
+    --_text-family: var(--segmentedcontrol-option-text-font-family);
+    --_text-size: var(--segmentedcontrol-option-text-font-size);
+    --_text-weight: var(--segmentedcontrol-option-text-font-weight);
+    --_text-line-height: var(--segmentedcontrol-option-text-line-height);
+    --_icon-color: var(--segmentedcontrol-option-icon);
+    --_icon-size: var(--segmentedcontrol-option-icon-size);
+
     display: inline-flex;
     align-items: center;
     gap: var(--space-8);
@@ -134,19 +149,19 @@
     background: transparent;
     border: 0;
     border-radius: var(--segmentedcontrol-selected-radius);
-    color: var(--segmentedcontrol-option-text);
-    font-family: var(--segmentedcontrol-option-text-font-family);
-    font-size: var(--segmentedcontrol-option-text-font-size);
-    font-weight: var(--segmentedcontrol-option-text-font-weight);
-    line-height: var(--segmentedcontrol-option-text-line-height);
+    color: var(--_text-color);
+    font-family: var(--_text-family);
+    font-size: var(--_text-size);
+    font-weight: var(--_text-weight);
+    line-height: var(--_text-line-height);
     cursor: pointer;
     transition: background var(--duration-150), color var(--duration-150);
     position: relative;
   }
 
   .segment i {
-    font-size: var(--segmentedcontrol-option-icon-size);
-    color: var(--segmentedcontrol-option-icon);
+    font-size: var(--_icon-size);
+    color: var(--_icon-color);
     transition: color var(--duration-150);
   }
 
@@ -166,52 +181,43 @@
 
   .segment:hover:not(:disabled):not(.selected),
   .segment.force-hover:not(:disabled):not(.selected) {
+    --_text-color: var(--segmentedcontrol-option-hover-text);
+    --_text-family: var(--segmentedcontrol-option-hover-text-font-family);
+    --_text-size: var(--segmentedcontrol-option-hover-text-font-size);
+    --_text-weight: var(--segmentedcontrol-option-hover-text-font-weight);
+    --_text-line-height: var(--segmentedcontrol-option-hover-text-line-height);
+    --_icon-color: var(--segmentedcontrol-option-hover-icon);
+    --_icon-size: var(--segmentedcontrol-option-hover-icon-size);
     background: var(--segmentedcontrol-option-hover-surface);
-    color: var(--segmentedcontrol-option-hover-text);
-    font-family: var(--segmentedcontrol-option-hover-text-font-family);
-    font-size: var(--segmentedcontrol-option-hover-text-font-size);
-    font-weight: var(--segmentedcontrol-option-hover-text-font-weight);
-    line-height: var(--segmentedcontrol-option-hover-text-line-height);
-  }
-
-  .segment:hover:not(:disabled):not(.selected) i,
-  .segment.force-hover:not(:disabled):not(.selected) i {
-    color: var(--segmentedcontrol-option-hover-icon);
-    font-size: var(--segmentedcontrol-option-hover-icon-size);
   }
 
+  /* Outline (not border) so the selection ring sits outside the box model.
+     A real border would force a padding compensation calc, and the resulting
+     sub-pixel flex layout would shift the selected segment by a whole pixel
+     against its neighbors. Outline is paint-only and leaves geometry alone. */
   .segment.selected {
+    --_text-color: var(--segmentedcontrol-selected-text);
+    --_text-family: var(--segmentedcontrol-selected-text-font-family);
+    --_text-size: var(--segmentedcontrol-selected-text-font-size);
+    --_text-weight: var(--segmentedcontrol-selected-text-font-weight);
+    --_text-line-height: var(--segmentedcontrol-selected-text-line-height);
+    --_icon-color: var(--segmentedcontrol-selected-icon);
+    --_icon-size: var(--segmentedcontrol-selected-icon-size);
     background: var(--segmentedcontrol-selected-surface);
-    border: var(--segmentedcontrol-selected-border-width) solid var(--segmentedcontrol-selected-border);
-    border-radius: var(--segmentedcontrol-selected-radius);
-    color: var(--segmentedcontrol-selected-text);
-    font-family: var(--segmentedcontrol-selected-text-font-family);
-    font-size: var(--segmentedcontrol-selected-text-font-size);
-    font-weight: var(--segmentedcontrol-selected-text-font-weight);
-    line-height: var(--segmentedcontrol-selected-text-line-height);
-    /* Account for border so the pill doesn't shift adjacent segments */
-    padding: calc(var(--space-6) - var(--segmentedcontrol-selected-border-width))
-      calc(var(--space-16) - var(--segmentedcontrol-selected-border-width));
-  }
-
-  .segment.selected i {
-    color: var(--segmentedcontrol-selected-icon);
-    font-size: var(--segmentedcontrol-selected-icon-size);
+    outline: var(--segmentedcontrol-selected-border-width) solid var(--segmentedcontrol-selected-border);
+    outline-offset: calc(var(--segmentedcontrol-selected-border-width) * -1);
   }
 
   .segment:disabled {
+    --_text-color: var(--segmentedcontrol-disabled-text);
+    --_text-family: var(--segmentedcontrol-disabled-text-font-family);
+    --_text-size: var(--segmentedcontrol-disabled-text-font-size);
+    --_text-weight: var(--segmentedcontrol-disabled-text-font-weight);
+    --_text-line-height: var(--segmentedcontrol-disabled-text-line-height);
+    --_icon-color: var(--segmentedcontrol-disabled-icon);
+    --_icon-size: var(--segmentedcontrol-disabled-icon-size);
     background: var(--segmentedcontrol-disabled-surface);
-    color: var(--segmentedcontrol-disabled-text);
-    font-family: var(--segmentedcontrol-disabled-text-font-family);
-    font-size: var(--segmentedcontrol-disabled-text-font-size);
-    font-weight: var(--segmentedcontrol-disabled-text-font-weight);
-    line-height: var(--segmentedcontrol-disabled-text-line-height);
     opacity: 0.4;
     cursor: not-allowed;
   }
-
-  .segment:disabled i {
-    color: var(--segmentedcontrol-disabled-icon);
-    font-size: var(--segmentedcontrol-disabled-icon-size);
-  }
 </style>

package/src/{components → system/components}/TabBar.svelte

@@ -140,91 +140,107 @@
     margin-bottom: var(--tabbar-bar-bottom-margin);
   }
 
+  /* Per-state tokens are bound to `--_*` custom properties below. The actual
+     layout-affecting declarations (padding, border, border-radius, font-*)
+     are written exactly once on `.tab`, so a hover/active state change can
+     only repaint, not relayout. When two states resolve to the same value,
+     the computed property is identical and no reshape is triggered. The
+     `transition: all` of the old rule has also been narrowed to paint-only
+     properties — otherwise it would try to animate layout changes between
+     states that happen to differ in tokens. */
   .tab {
+    --_text-color: var(--tabbar-default-text);
+    --_text-family: var(--tabbar-default-text-font-family);
+    --_text-size: var(--tabbar-default-text-font-size);
+    --_text-weight: var(--tabbar-default-text-font-weight);
+    --_text-line-height: var(--tabbar-default-text-line-height);
+    --_icon-size: var(--tabbar-default-icon-size);
+    --_surface: var(--tabbar-default-surface);
+    --_indicator-color: var(--tabbar-default-border);
+    --_padding: var(--tabbar-default-padding);
+    --_border-color: var(--tabbar-default-tab-border-color);
+    --_border-width: var(--tabbar-default-tab-border-width);
+    --_top-radius: var(--tabbar-default-tab-top-radius);
+    --_bottom-radius: var(--tabbar-default-tab-bottom-radius);
+
     display: inline-flex;
     align-items: center;
     gap: var(--space-6);
-    @include themed-padding(--tabbar-default-padding, $h: 2);
-    background: var(--tabbar-default-surface);
-    border: var(--tabbar-default-tab-border-width) solid var(--tabbar-default-tab-border-color);
-    /* indicator accent — owns the bottom edge */
-    border-bottom: var(--tabbar-bar-indicator-thickness) solid var(--tabbar-default-border);
-    border-radius: var(--tabbar-default-tab-top-radius) var(--tabbar-default-tab-top-radius) var(--tabbar-default-tab-bottom-radius) var(--tabbar-default-tab-bottom-radius);
-    color: var(--tabbar-default-text);
-    font-family: var(--tabbar-default-text-font-family);
-    font-size: var(--tabbar-default-text-font-size);
-    font-weight: var(--tabbar-default-text-font-weight);
-    line-height: var(--tabbar-default-text-line-height);
+    padding: var(--_padding) calc(var(--_padding) * 2);
+    background: var(--_surface);
+    border: var(--_border-width) solid var(--_border-color);
+    /* Indicator accent owns the bottom edge. Thickness is constant across
+       states (--tabbar-bar-indicator-thickness), only color rebinds. */
+    border-bottom: var(--tabbar-bar-indicator-thickness) solid var(--_indicator-color);
+    border-radius: var(--_top-radius) var(--_top-radius) var(--_bottom-radius) var(--_bottom-radius);
+    color: var(--_text-color);
+    font-family: var(--_text-family);
+    font-size: var(--_text-size);
+    font-weight: var(--_text-weight);
+    line-height: var(--_text-line-height);
     cursor: pointer;
-    transition: all var(--duration-150);
+    transition:
+      background var(--duration-150),
+      color var(--duration-150),
+      border-color var(--duration-150);
     position: relative;
   }
 
+  .tab i {
+    font-size: var(--_icon-size);
+  }
+
   .tab:hover:not(:disabled):not(.active),
   .tab-bar.force-hover .tab:not(:disabled):not(.active) {
-    color: var(--tabbar-hover-text);
-    background: var(--tabbar-hover-surface);
-    border-color: var(--tabbar-hover-tab-border-color);
-    border-width: var(--tabbar-hover-tab-border-width);
-    /* indicator accent owns the bottom edge */
-    border-bottom: var(--tabbar-bar-indicator-thickness) solid var(--tabbar-hover-border);
-    border-radius: var(--tabbar-hover-tab-top-radius) var(--tabbar-hover-tab-top-radius) var(--tabbar-hover-tab-bottom-radius) var(--tabbar-hover-tab-bottom-radius);
-    font-family: var(--tabbar-hover-text-font-family);
-    font-size: var(--tabbar-hover-text-font-size);
-    font-weight: var(--tabbar-hover-text-font-weight);
-    line-height: var(--tabbar-hover-text-line-height);
-    @include themed-padding(--tabbar-hover-padding, $h: 2);
+    --_text-color: var(--tabbar-hover-text);
+    --_text-family: var(--tabbar-hover-text-font-family);
+    --_text-size: var(--tabbar-hover-text-font-size);
+    --_text-weight: var(--tabbar-hover-text-font-weight);
+    --_text-line-height: var(--tabbar-hover-text-line-height);
+    --_icon-size: var(--tabbar-hover-icon-size);
+    --_surface: var(--tabbar-hover-surface);
+    --_indicator-color: var(--tabbar-hover-border);
+    --_padding: var(--tabbar-hover-padding);
+    --_border-color: var(--tabbar-hover-tab-border-color);
+    --_border-width: var(--tabbar-hover-tab-border-width);
+    --_top-radius: var(--tabbar-hover-tab-top-radius);
+    --_bottom-radius: var(--tabbar-hover-tab-bottom-radius);
   }
 
   .tab.active {
-    color: var(--tabbar-active-text);
-    background: var(--tabbar-active-surface);
-    border-color: var(--tabbar-active-tab-border-color);
-    border-width: var(--tabbar-active-tab-border-width);
-    /* indicator accent owns the bottom edge */
-    border-bottom: var(--tabbar-bar-indicator-thickness) solid var(--tabbar-active-border);
-    border-radius: var(--tabbar-active-tab-top-radius) var(--tabbar-active-tab-top-radius) var(--tabbar-active-tab-bottom-radius) var(--tabbar-active-tab-bottom-radius);
-    font-family: var(--tabbar-active-text-font-family);
-    font-size: var(--tabbar-active-text-font-size);
-    font-weight: var(--tabbar-active-text-font-weight);
-    line-height: var(--tabbar-active-text-line-height);
-    @include themed-padding(--tabbar-active-padding, $h: 2);
+    --_text-color: var(--tabbar-active-text);
+    --_text-family: var(--tabbar-active-text-font-family);
+    --_text-size: var(--tabbar-active-text-font-size);
+    --_text-weight: var(--tabbar-active-text-font-weight);
+    --_text-line-height: var(--tabbar-active-text-line-height);
+    --_icon-size: var(--tabbar-active-icon-size);
+    --_surface: var(--tabbar-active-surface);
+    --_indicator-color: var(--tabbar-active-border);
+    --_padding: var(--tabbar-active-padding);
+    --_border-color: var(--tabbar-active-tab-border-color);
+    --_border-width: var(--tabbar-active-tab-border-width);
+    --_top-radius: var(--tabbar-active-tab-top-radius);
+    --_bottom-radius: var(--tabbar-active-tab-bottom-radius);
   }
 
   .tab:disabled {
-    color: var(--tabbar-disabled-text);
-    background: var(--tabbar-disabled-surface);
-    border-color: var(--tabbar-disabled-tab-border-color);
-    border-width: var(--tabbar-disabled-tab-border-width);
-    /* indicator accent owns the bottom edge */
-    border-bottom: var(--tabbar-bar-indicator-thickness) solid var(--tabbar-disabled-border);
-    border-radius: var(--tabbar-disabled-tab-top-radius) var(--tabbar-disabled-tab-top-radius) var(--tabbar-disabled-tab-bottom-radius) var(--tabbar-disabled-tab-bottom-radius);
-    font-family: var(--tabbar-disabled-text-font-family);
-    font-size: var(--tabbar-disabled-text-font-size);
-    font-weight: var(--tabbar-disabled-text-font-weight);
-    line-height: var(--tabbar-disabled-text-line-height);
-    @include themed-padding(--tabbar-disabled-padding, $h: 2);
+    --_text-color: var(--tabbar-disabled-text);
+    --_text-family: var(--tabbar-disabled-text-font-family);
+    --_text-size: var(--tabbar-disabled-text-font-size);
+    --_text-weight: var(--tabbar-disabled-text-font-weight);
+    --_text-line-height: var(--tabbar-disabled-text-line-height);
+    --_icon-size: var(--tabbar-disabled-icon-size);
+    --_surface: var(--tabbar-disabled-surface);
+    --_indicator-color: var(--tabbar-disabled-border);
+    --_padding: var(--tabbar-disabled-padding);
+    --_border-color: var(--tabbar-disabled-tab-border-color);
+    --_border-width: var(--tabbar-disabled-tab-border-width);
+    --_top-radius: var(--tabbar-disabled-tab-top-radius);
+    --_bottom-radius: var(--tabbar-disabled-tab-bottom-radius);
     cursor: not-allowed;
   }
 
   .tab.icon-only {
     padding: var(--space-8) var(--space-12);
   }
-
-  .tab:hover:not(:disabled):not(.active) i,
-  .tab-bar.force-hover .tab:not(:disabled):not(.active) i {
-    font-size: var(--tabbar-hover-icon-size);
-  }
-
-  .tab.active i {
-    font-size: var(--tabbar-active-icon-size);
-  }
-
-  .tab:disabled i {
-    font-size: var(--tabbar-disabled-icon-size);
-  }
-
-  .tab i {
-    font-size: var(--tabbar-default-icon-size);
-  }
 </style>

package/src/{components → system/components}/Table.svelte

@@ -11,9 +11,12 @@
 </div>
 
 <style lang="scss">
+  @use '../styles/padding' as *;
+
   :global(:root) {
     /* Wrapper */
     --table-default-radius: var(--radius-md);
+    --table-default-surface: var(--color-transparent);
     --table-default-border: var(--border-canvas-subtle);
     --table-default-border-width: var(--border-width-1);
     --table-default-shadow: var(--shadow-md);
@@ -38,9 +41,10 @@
     --table-default-cell-padding: var(--space-8);
 
     /* Row */
+    --table-default-row-surface: var(--color-transparent);
     --table-default-row-divider: var(--border-canvas-faint);
     --table-default-row-divider-width: var(--border-width-1);
-    --table-default-row-stripe-surface: var(--surface-canvas-lower);
+    --table-default-row-stripe-surface: var(--color-transparent);
 
     /* Column */
     --table-default-column-divider: var(--border-canvas-faint);
@@ -51,6 +55,7 @@
     overflow-x: auto;
     margin: var(--space-12) 0;
     -webkit-overflow-scrolling: touch;
+    background: var(--table-default-surface);
     border: var(--table-default-border-width) solid var(--table-default-border);
     border-radius: var(--table-default-radius);
     box-shadow: var(--table-default-shadow);
@@ -70,7 +75,7 @@
     font-size: var(--table-default-header-font-size);
     font-weight: var(--table-default-header-font-weight);
     line-height: var(--table-default-header-line-height);
-    padding: var(--table-default-header-padding);
+    @include themed-padding(--table-default-header-padding);
     text-align: left;
     border-bottom: var(--table-default-header-border-width) solid var(--table-default-header-border);
     border-right: var(--table-default-column-divider-width) solid var(--table-default-column-divider);
@@ -78,6 +83,7 @@
   }
 
   .table-wrapper :global(td) {
+    background: var(--table-default-row-surface);
     color: var(--table-default-cell-text);
     font-family: var(--table-default-cell-font-family);
     font-size: var(--table-default-cell-font-size);
@@ -97,8 +103,16 @@
     border-right: none;
   }
 
+  /* Stripe is layered over the base row surface as a background-image, so a
+     translucent stripe color blends with the base instead of replacing it.
+     An opaque stripe still covers the base (visually identical to the old
+     replacement behavior); a fully transparent stripe leaves the base
+     untouched, which is the default out of the box. */
   .table-wrapper :global(tr:nth-child(even) td) {
-    background: var(--table-default-row-stripe-surface);
+    background-image: linear-gradient(
+      var(--table-default-row-stripe-surface),
+      var(--table-default-row-stripe-surface)
+    );
   }
 
   .table-wrapper :global(tr:last-child td) {

package/src/{components → system/components}/Tooltip.svelte

@@ -23,7 +23,9 @@
   {/if}
 </div>
 
-<style>
+<style lang="scss">
+  @use '../styles/padding' as *;
+
   :global(:root) {
     --tooltip-surface: var(--surface-neutral-highest);
     --tooltip-text: var(--text-primary);
@@ -50,7 +52,7 @@
     transform: translateX(-50%);
     background: var(--tooltip-surface);
     color: var(--tooltip-text);
-    padding: var(--tooltip-padding) calc(var(--tooltip-padding) * 2);
+    @include themed-padding(--tooltip-padding, $h: 2);
     border: var(--tooltip-border-width) solid var(--tooltip-border);
     border-radius: var(--tooltip-radius);
     font-family: var(--tooltip-text-font-family);
@@ -68,7 +70,7 @@
   .tooltip::after {
     content: '';
     position: absolute;
-    bottom: calc(-4px - var(--tooltip-border-width) * 1px);
+    bottom: calc(-4px - var(--tooltip-border-width));
     left: 50%;
     width: 8px;
     height: 8px;
@@ -86,7 +88,7 @@
 
   .tooltip.bottom::after {
     bottom: auto;
-    top: calc(-4px - var(--tooltip-border-width) * 1px);
+    top: calc(-4px - var(--tooltip-border-width));
     border-right: none;
     border-bottom: none;
     border-left: var(--tooltip-border-width) solid var(--tooltip-border);

package/src/system/styles/CONVENTIONS.md

@@ -0,0 +1,178 @@
+# Token naming conventions
+
+This project uses a **two-layer token system**. Read this before adding or renaming a CSS custom property.
+
+## Files in this directory
+
+Each file plays a distinct role. Don't merge them without understanding why they were split.
+
+| File | Scope | Tokens used | Loaded by | Notes |
+|---|---|---|---|---|
+| `tokens.css` | Themed pages | Defines `--color-*`, `--surface-*`, `--text-*`, `--space-*`, … | `main.ts` | **Runtime-edited.** The token editor rewrites this file via the `themeFileApi` Vite plugin. Starter content; consumers replace at will. |
+| `ui-editor.css` | Editor chrome only | Defines `--ui-*` (opaque grayscale, system fonts) | JS-imported by `Editor.svelte` and `ComponentEditorPage.svelte` | Deliberately isolated from the theme system so editor surfaces stay neutral while live theme edits flow through the components being edited. Never load globally. |
+| `ui-form-controls.css` | Editor chrome only | Consumes `--ui-*` only | JS-imported by `Editor.svelte` and `ComponentEditorPage.svelte` | `.ui-form-select` / `.ui-form-input` / `.ui-form-field-*` classes. Used by `ProjectFontsSection`, `FontStackEditor`, `DialogEditor`, `NotificationEditor`. Theme-immune — must not reference `--font-*`, `--surface-*`, etc. |
+| `site.css` | Themed pages | Consumes theme tokens | Page-imported by `Home.svelte` | Consumer-facing starter typography for the landing page (unscoped `h1`, `p`, `a`, …). Never load on editor pages. Replaceable starter content — users edit or replace this file to style their own site. Components that take slot content (Card body, CollapsibleSection content) defend their typography aliases against these global rules via `:global(p) { font: inherit; color: inherit; }`. The demo page no longer imports it; the demo uses scoped classes and component-owned slot typography instead. |
+| `fonts.css` + `fonts/` | Themed pages only | n/a (`@font-face` only) | `main.ts` | Build-special-cased: copied directly to `dist/` without processing so Vite doesn't inline woff2 files as base64. Starter content; editor's font invariant means these never affect chrome. |
+
+### Publishing layout
+
+The library publishes a small set of subpaths:
+
+- `./styles/ui-editor.css` — read-only window onto the editor's `--ui-*` token contract (for theming inspection or debugging). Consumers don't *need* to import this; the editor pages auto-load it.
+- `./starter/tokens.css`, `./starter/site.css`, `./starter/fonts.css` — replaceable starter content. Consumers can import as-is for a working default, or copy + edit.
+
+`ui-form-controls.css` is editor-internal and not exported — the editor pages script-import it themselves.
+
+### Editor font invariant
+
+Editor chrome uses **only** the `--ui-*` font namespace (`--ui-font-sans`, `--ui-font-mono`, `--ui-font-size-*`, etc.), which `ui-editor.css` defines as a pure system stack. No editor-namespace rule may reference `var(--font-sans)`, `var(--font-serif)`, `var(--font-display)`, or `var(--font-mono)` — those are the consumer's theme fonts and must not bleed into chrome. This invariant is what closes the "editor adopts consumer brand fonts" leak.
+
+### When to put a rule where
+
+- It defines a `--color-*` / `--surface-*` / `--space-*` / etc. → `tokens.css`.
+- It defines a `--ui-*` token → `ui-editor.css`.
+- It styles a bare element selector (`h1`, `p`, `blockquote`) on themed pages → `site.css`.
+- It styles editor chrome → put it in the component's own `<style>` block using `--ui-*` tokens; don't add a new global file.
+- It declares an `@font-face` → `fonts.css` (and add the woff2 to `fonts/`).
+
+## Layer 1 — theme tokens (`tokens.css`)
+
+Theme tokens are the design system's vocabulary. They describe colors, sizes, spacing, shadows, and motion: the things a designer reasons about independent of any one component. Components consume them, and themes in `themes/*.json` recolor or re-scale them.
+
+### Category-first naming
+
+Every theme token starts with a **category prefix**. The category tells you what *kind* of value lives at that key:
+
+| Category       | What it holds                                                   |
+|----------------|-----------------------------------------------------------------|
+| `--color-*`    | Primitive color palette (e.g. `--color-accent-500`)             |
+| `--surface-*`  | Fill/background colors, with elevation tiers                    |
+| `--border-*`   | Border colors, with emphasis tiers                              |
+| `--text-*`     | Text colors, with hierarchy tiers                               |
+| `--font-*`     | Font families and weights                                       |
+| `--font-size-*`| Font sizes (explicit subcategory to avoid colliding with families) |
+| `--space-*`    | Spacing scale, values encoded in the name (`--space-8` = 8px)   |
+| `--radius-*`   | Border radii (t-shirt scale)                                    |
+| `--shadow-*`   | Elevation shadows                                               |
+| `--ring-*`     | Focus rings (separate namespace from shadows)                   |
+| `--border-width-*` | Stroke widths                                               |
+| `--transition-*`, `--opacity-*`, `--z-*` | Animation, opacity, z-index scales    |
+| `--overlay-*`, `--hover-*` | Semantic overlay tints                                |
+| `--gradient-*` | Named gradients                                                 |
+| `--columns-*`, `--page-*` | Page-level layout primitives                         |
+
+**Rule: a bare one-word token belongs to *some* category.** If you find yourself writing `--overlay` or `--border`, make sure the category is obvious and it's the canonical default. Otherwise pick a longer name that slots it into its family (e.g. `--border-neutral`).
+
+### Families within a category
+
+Color categories (`--surface-*`, `--border-*`, `--text-*`) partition into **families**: `neutral`, `canvas`, `primary` (*→ brand, rename pending*), `accent`, `success`, `warning`, `danger`, `info`, `special`, `alternate`. Each family carries its own emphasis/elevation scale suited to its role: 7-step elevation for surfaces, 4-step emphasis for borders, 5-step hierarchy for text. They differ on purpose.
+
+### Scales
+
+Two shapes appear:
+
+- **T-shirt scale** (`-xs / -sm / -md / -lg / -xl / -2xl …`). Used for `--radius-*`, `--font-size-*`, `--shadow-*`, `--ring-focus-*`.
+- **Numeric scale.** `--color-*-100` through `--color-*-950` for palettes; `--space-4 / -8 / -16 / …` (value encoded in the name).
+
+Don't invent a third scale shape for a new category.
+
+## Layer 2 — component tokens (`component-configs/*/default.json` + component Svelte files)
+
+Component tokens *reference* theme tokens. They're how a component names its own slots: "my bar's surface color", "my selected option's border width". The config file records which theme alias is currently assigned to each slot.
+
+### The naming scheme
+
+```
+--<componentId>-<part>[-<state>][-<element>]-<property>
+```
+
+- **`componentId`.** The literal component ID. No abbreviations. The ID itself has no dashes (it's the file-system-safe form: `segmentedcontrol`, not `segmented-control`).
+- **`part`.** Which part of the component this slot belongs to: `bar`, `divider`, `option`, `selected`, `track`, `save`, `cancel`, etc.
+- **`state`.** Optional. The interaction state if more than default: `hover`, `disabled`, `active`, `focus`. States come **before** the property, never after.
+- **`element`.** Optional. A sub-element within the part: `dot`, `icon`, `label`, `text`.
+- **`property`.** Always last. Either a **theme role** (`surface`, `border`, `text`, `icon`, `label`, `fill`) or a **CSS property name** (`radius`, `border-width`, `font-weight`, `font-family`, `font-size`).
+
+### No abbreviations
+
+- `bg` → `surface` (matches the theme role name and the theme layer's full-word vocabulary).
+- `fg` → `text`.
+- Component IDs are never abbreviated. Use `--segmentedcontrol-*`, not `--segment-*` or `--sc-*`.
+
+### Property suffix vocabulary
+
+| Suffix         | Meaning                                                      |
+|----------------|--------------------------------------------------------------|
+| `-surface`     | Fill/background color                                        |
+| `-border`      | Border color                                                 |
+| `-text`        | Text color                                                   |
+| `-icon`        | Icon color                                                   |
+| `-label`       | Label text color                                             |
+| `-fill`        | Inner fill (distinct from outer surface)                     |
+| `-radius`      | Corner radius                                                |
+| `-border-width`| Stroke thickness                                             |
+| `-font-family` | Font family reference                                        |
+| `-font-weight` | Font weight reference                                        |
+| `-font-size`   | Font size reference                                          |
+| `-thickness`   | Alternative stroke dimension (used where `-width` would alias another token under name-based fallback grouping) |
+| `-height`      | Explicit height when `-width`'s sibling would collide under name-based fallback grouping |
+| `-color`       | Generic color when none of the role words fits (rare)        |
+
+**Why `thickness` and `height` sometimes stand in for `width`:** when an editor declares no explicit `groupKey` for a token, sibling grouping falls back to matching the final `-<property>` segment. If two unrelated slots both end in `-width` and neither has a `groupKey`, they get auto-linked. Either declare a `groupKey` per token in the editor (preferred) or use an alternative property word. The divider in SegmentedControl uses `--segmentedcontrol-divider-thickness` for legacy parity with the fallback rule, but it now also has `groupKey: 'divider-thickness'` declared in the editor. The `groupKey` is the source of truth.
+
+### State order matters
+
+State comes **before** the property, not after:
+
+```
+--inlineeditactions-save-hover-surface    ✓  state before property; siblings on `-surface`
+--inlineeditactions-save-surface-hover    ✗  breaks sibling matching and reads oddly
+```
+
+### Linked siblings (the link toggle)
+
+Tokens that share a `groupKey` form a **sibling set**. A property declared `canBeLinked: true` in the editor shows a link toggle that lets the user broadcast one value across every sibling. So in SegmentedControl:
+
+- `--segmentedcontrol-bar-border-width` and `--segmentedcontrol-selected-border-width` share `groupKey: 'border-width'`.
+- `--segmentedcontrol-option-text-font-weight`, `--segmentedcontrol-option-disabled-text-font-weight`, and `--segmentedcontrol-selected-text-font-weight` share `groupKey: 'font-weight'`.
+
+Editor authors declare `groupKey` per token in the editor's token list (and call `registerComponentSchema(component, tokens)` once at module load). The store consults the schema first; for unmigrated editors with no schema entry, it falls back to matching the last `-<property>` segment. Tokens with neither a `groupKey` nor a colliding name suffix are solo.
+
+Linkage is **dev-declared** — the editor schema is the source of truth for which variables share a `groupKey`. Users only choose whether to opt out of an existing link (per-property), never to add or reshape one.
+
+The `unlinked` array on a `ComponentSlice` stores the variable names the user has explicitly detached. The remaining declared siblings stay linked to each other; an unlinked variable rejoins via `setComponentAliasLinked` or `relinkComponentProperty`.
+
+### Typography slot scoping
+
+When a component declares more than one typography slot — e.g. a notification with separate `title` and `text` slots — every typography `groupKey` (`font-family`, `font-size`, `font-weight`, `line-height`) **must** include the slot name as a prefix:
+
+```
+groupKey: 'title-font-family', 'text-font-family'   ✓  one link tree per slot
+groupKey: 'font-family'                              ✗  silently links title and text together
+```
+
+A bare typography `groupKey` like `'font-family'` is fine when the component has only one typography slot (Button has only `text`; RadioButton only `label`; CollapsibleSection only `label`). Add a slot prefix the moment the component grows a second slot.
+
+`registerComponentSchema` emits a console warning at runtime if a single `groupKey` covers variables whose name-derived slots differ. Treat that warning as a build-time error.
+
+### When the last-dash fallback surprises you
+
+For tokens without an explicit `groupKey`, the store derives one by splitting on the last dash:
+
+- `--segmentedcontrol-option-text-font-weight` → fallback groupKey `weight`.
+
+So the fallback property is always the literal last segment. If you don't want a token to participate in the fallback grouping, declare an explicit `groupKey` (or omit `canBeLinked`).
+
+## Checklist for adding a new component token
+
+1. Does the value belong at the **theme layer**? (It's a color or scale that multiple components could reuse.) → Add it to `tokens.css` under the correct category, not here.
+2. Pick a **componentId** matching the one used in `component-configs/` and the editor's `const component = '...'` literal.
+3. Build the name as `--<componentId>-<part>[-<state>]-<property>`.
+4. Use **full words**: no `bg`, no shortened component IDs.
+5. Declare the slot in both the component's Svelte `<style>` (`--tok: var(--theme-alias);`) and the config JSON (`"--tok": "--theme-alias"`).
+6. If the slot should link across variants, add `canBeLinked: true` and `groupKey: '<your-key>'` in the editor's token list. Siblings are tokens that share the same `groupKey`. Pick a `groupKey` that names the kind of property (`radius`, `border-width`, `font-weight`, `font-family`, etc.); a unique key isolates a token from any other. For typography on multi-slot components, prefix the slot name (see "Typography slot scoping").
+7. Make sure the editor calls `registerComponentSchema(component, tokens)` once at module load so the store sees the explicit groupKeys.
+
+## What's still pending
+
+- **`primary` → `brand` rename.** Disambiguates the emphasis-tier, color-family, and component-variant uses of "primary." Tracked in `temp/primary-to-brand-rename.md`.
+- **Theme-layer cleanups** tracked in `temp/theme-token-improvements.md`: font-weight scale normalization, bare-word orphan audit, full `bg` → `canvas` sweep.

package/src/system/styles/fonts.css

@@ -0,0 +1,20 @@
+/* Generated from the production theme by syncFontsToCss. Do not edit. */
+/* Both fonts.css and fonts/ are in dist/, so relative paths work at runtime. */
+
+/* Adobe Typekit — fira-code */
+@import url('https://use.typekit.net/jes8oow.css');
+
+/* Google Fonts — Arvo */
+@import url('https://fonts.googleapis.com/css2?family=Arvo:ital,wght@0,400;0,700;1,400;1,700&display=swap');
+
+/* Google Fonts — GFS Didot */
+@import url('https://fonts.googleapis.com/css2?family=GFS+Didot&display=swap');
+
+/* Local — Manrope */
+@font-face {
+  font-family: "Manrope";
+  src: url('/src/system/styles/fonts/Manrope/Manrope-latin.woff2') format('woff2');
+  font-weight: 200 800;
+  font-style: normal;
+  font-display: swap;
+}