@motion-proto/live-tokens 0.94.2 → 0.95.0

package/src/editor/component-editor/scaffolding/ShadowBackdrop.svelte

@@ -83,12 +83,21 @@
     grid-area: controls;
   }
 
+  /* Narrow: the preview leads, since it is what the pinned stage is for, and a
+     component wider than the stage scrolls inside it. */
   @container variant-group (max-width: 32rem) {
+    /* Holds its height so the pinned stage scrolls to the controls rather than
+       squeezing the preview under them. */
     .shadow-backdrop.with-controls {
+      flex-shrink: 0;
       grid-template-columns: minmax(0, 1fr);
       grid-template-areas:
-        "controls"
-        "preview";
+        "preview"
+        "controls";
+    }
+
+    .shadow-backdrop-content {
+      overflow-x: auto;
     }
   }
 </style>

package/src/editor/component-editor/scaffolding/StateBlock.svelte

@@ -268,6 +268,13 @@
     align-items: stretch;
   }
 
+  /* Sections stack one per line here, so each heading rule spans the card. */
+  @container variant-group (max-width: 32rem) {
+    .element-section {
+      flex: 1 1 100%;
+    }
+  }
+
   .element-section .state-type-groups {
     display: flex;
     flex-direction: row;

package/src/editor/component-editor/scaffolding/TokenLayout.svelte

@@ -436,10 +436,9 @@
 
   @container variant-group (max-width: 380px) {
     .token-grid {
-      grid-template-columns: max-content 1fr;
+      grid-template-columns: max-content var(--token-selector-w) minmax(0, 1fr);
       column-gap: var(--ui-space-6);
     }
-    .token-grid :global(.ui-token-selector) { grid-column: 2; }
   }
 
   .zone-divider {

package/src/editor/component-editor/scaffolding/VariantGroup.svelte

@@ -567,7 +567,7 @@
      pinned and always leaves the controls a viewport to live in. */
   .tabs-preview {
     position: sticky;
-    top: 0;
+    top: var(--editor-sticky-top, 0px);
     z-index: 2;
     display: flex;
     flex-direction: column;
@@ -598,6 +598,20 @@
     flex: none;
   }
 
+  /* A capped stage nests a scroller inside the page scroll, which a phone
+     handles badly, and an uncapped pinned band covers the controls. The band
+     scrolls with the page at full height instead. */
+  @media (max-width: 600px) {
+    .tabs-preview {
+      position: relative;
+      max-height: none;
+    }
+
+    .tabs-preview::after {
+      display: none;
+    }
+  }
+
   /* Soft fade at the bottom of the sticky band so property rows scrolling
      up don't sharply cut against the pinned preview. Greyscale (no accent).
      Sits below the preview body, above scrolling content. */
@@ -910,8 +924,9 @@
   /* Direct child of .variant-group; needs its own margin since flex gap doesn't apply across siblings. */
   .properties-header {
     display: flex;
+    flex-wrap: wrap;
     align-items: center;
-    gap: var(--ui-space-16);
+    gap: var(--ui-space-8) var(--ui-space-16);
     margin-top: var(--ui-space-8);
     margin-bottom: var(--ui-space-8);
   }

package/src/editor/core/store/editorPersistence.ts

@@ -21,6 +21,7 @@ import { quietGet, quietSet } from '../storage/storage';
 import { isGradientSlot, makeDefaultGradients } from '../themes/slices/gradients';
 import { seedShadowsFromDom } from '../themes/slices/shadows';
 import { makeDefaultWashScale, type WashFamily } from '../themes/slices/washes';
+import { normalizeColumnsState } from '../themes/slices/columns';
 import { sanitizeHarmonyAxes } from '../palettes/colorHarmony';
 import {
   renameBackgroundPaletteKey,
@@ -189,6 +190,10 @@ export function normalizePaletteBasis(state: EditorState): EditorState {
   return { ...state, palettes: migratePaletteColorsToOklch(raw) };
 }
 
+export function normalizeColumns(state: EditorState): EditorState {
+  return { ...state, columns: normalizeColumnsState(state.columns) };
+}
+
 export function hydrate(): void {
   // Corrupt state, missing key, or unavailable storage all return null;
   // the editor falls through to the empty default in that case.
@@ -200,7 +205,7 @@ export function hydrate(): void {
     store.set(
       normalizeHarmonyAxes(
         normalizeBaseAnchors(
-          normalizePaletteBasis(normalizePaletteLabels(normalizeComponents(normalizeWashes(migrateGradients(merged))))),
+          normalizePaletteBasis(normalizePaletteLabels(normalizeComponents(normalizeColumns(normalizeWashes(migrateGradients(merged)))))),
         ),
       ),
     );

package/src/editor/core/store/editorRenderer.ts

@@ -18,7 +18,6 @@ import { palettesToVars } from '../palettes/paletteDerivation';
 import {
   editorState,
   columnsToVars,
-  columnsEqualsDefault,
   washesToVars,
   shadowsToVars,
   gradientsToVars,
@@ -27,9 +26,7 @@ import {
 
 export function deriveCssVars(state: EditorState): Record<string, string> {
   const out: Record<string, string> = { ...state.cssVars };
-  if (!columnsEqualsDefault(state.columns)) {
-    Object.assign(out, columnsToVars(state.columns));
-  }
+  Object.assign(out, columnsToVars(state.columns));
   Object.assign(out, washesToVars(state.washes));
   if (state.shadows.tokens.length > 0) {
     Object.assign(out, shadowsToVars(state.shadows));

package/src/editor/core/store/editorStore.ts

@@ -56,8 +56,7 @@ import {
   initializeEditorStore,
 } from './editorPersistence';
 import {
-  DEFAULT_COLUMNS,
-  columnsEqualsDefault,
+  defaultColumns,
   columnsToVars,
   loadColumnsFromVars,
 } from '../themes/slices/columns';
@@ -100,7 +99,7 @@ function emptyState(): EditorState {
       overrides: {},
     },
     washes: makeDefaultWashesState(),
-    columns: { ...DEFAULT_COLUMNS },
+    columns: defaultColumns(),
     components: {},
     gradients: { tokens: makeDefaultGradients() },
     harmonyAxes: defaultHarmonyAxes(),
@@ -143,10 +142,9 @@ export {
 
 export {
   columnsToVars,
-  columnsEqualsDefault,
+  columnsFromVars,
   COLUMN_VAR_NAMES,
-  DEFAULT_COLUMNS,
-  parseColumnVars,
+  defaultColumns,
 } from '../themes/slices/columns';
 
 export {
@@ -430,9 +428,7 @@ export function loadFromFile(colorsAndType: ColorsAndType): void {
  */
 function colorsAndTypeContent(state: EditorState): Omit<ColorsAndType, 'name' | 'createdAt' | 'updatedAt'> {
   const cssVariables: Record<string, string> = { ...state.cssVars };
-  if (!columnsEqualsDefault(state.columns)) {
-    Object.assign(cssVariables, columnsToVars(state.columns));
-  }
+  Object.assign(cssVariables, columnsToVars(state.columns));
   Object.assign(cssVariables, washesToVars(state.washes));
   if (state.shadows.tokens.length > 0) {
     Object.assign(cssVariables, shadowsToVars(state.shadows));

package/src/editor/core/store/editorTypes.ts

@@ -1,6 +1,7 @@
 import type { PaletteConfig, FontSource, FontStack } from '../themes/themeTypes';
 import type { GradientStop, GradientValue, LinearDirection } from '../themes/parsers/gradient';
 import type { HarmonyAxis } from '../palettes/colorHarmony';
+import type { ColumnViewport, ColumnViewportValues } from '../themes/slices/columns';
 
 export interface ShadowGlobals {
   angle: number;
@@ -40,8 +41,7 @@ export interface WashScale {
 export interface ColumnsState {
   count: number;
   maxWidth: number;
-  gutter: number;
-  margin: number;
+  viewports: Record<ColumnViewport, ColumnViewportValues>;
 }
 
 /** Gradient render mode.

package/src/editor/core/themes/migrations/2026-10-15-responsive-columns.ts

@@ -0,0 +1,40 @@
+import type { Migration } from './index';
+
+/**
+ * The column grid's stored gutter and margin move to their desktop names
+ * (2026-10-15).
+ *
+ * tokens.css points `--columns-gutter` and `--columns-margin` at a
+ * per-viewport value for the window's width. A theme that stores either
+ * overrides every breakpoint, so each moves to its desktop name with its
+ * value. `--columns-count` stays one value at every width and keeps its name.
+ *
+ * A stored value equal to the one every shipped theme held (`12`, `32px`,
+ * `0px` or `0`) counts as unset and is dropped, so the theme inherits the
+ * tokens.css default. The theme stores no tablet or phone value. The names
+ * and values freeze those of 2026-10-15.
+ */
+const RENAMES: Record<string, string> = {
+  '--columns-gutter': '--columns-desktop-gutter',
+  '--columns-margin': '--columns-desktop-margin',
+};
+
+const SHIPPED: Record<string, readonly string[]> = {
+  '--columns-count': ['12'],
+  '--columns-gutter': ['32px'],
+  '--columns-margin': ['0px', '0'],
+};
+
+export const colorsAndTypeMigration_2026_10_15_responsiveColumns: Migration = {
+  id: '2026-10-15-responsive-columns',
+  fromVersion: 9,
+  toVersion: 10,
+  appliesTo: 'colors-and-type',
+  apply(rawVars) {
+    return Object.fromEntries(
+      Object.entries(rawVars)
+        .filter(([name, value]) => !SHIPPED[name]?.includes(value.trim()))
+        .map(([name, value]) => [RENAMES[name] ?? name, value]),
+    );
+  },
+};

package/src/editor/core/themes/migrations/index.ts

@@ -82,6 +82,7 @@ import { componentMigration_2026_09_13_sectiondividerSurface } from './2026-09-1
 import { componentMigration_2026_09_20_imagelightboxScrim } from './2026-09-20-imagelightbox-scrim';
 import { componentMigration_2026_09_20_scrimColorAndOpacity } from './2026-09-20-scrim-color-and-opacity';
 import { colorsAndTypeMigration_2026_09_21_washColorAndOpacity } from './2026-09-21-wash-color-and-opacity';
+import { colorsAndTypeMigration_2026_10_15_responsiveColumns } from './2026-10-15-responsive-columns';
 import { componentMigration_2026_09_21_scrimSurface } from './2026-09-21-scrim-surface';
 import { componentMigration_2026_09_13_cornerbadgePrefix } from './2026-09-13-cornerbadge-prefix';
 import { componentMigration_2026_09_13_toggleLabel } from './2026-09-13-toggle-label';
@@ -140,6 +141,7 @@ export const MIGRATIONS: Migration[] = [
   componentMigration_2026_09_20_scrimColorAndOpacity,
   colorsAndTypeMigration_2026_09_21_washColorAndOpacity,
   componentMigration_2026_09_21_scrimSurface,
+  colorsAndTypeMigration_2026_10_15_responsiveColumns,
 ];
 
 function countFor(kind: 'colors-and-type' | 'component-config'): number {

package/src/editor/core/themes/slices/columns.ts

@@ -1,59 +1,129 @@
 /**
- * Columns slice — fixed-shape (count/maxWidth/gutter/margin) state, derived to
- * four CSS vars. Values default to a 12-column 1440px grid; while state matches
- * the default we leave tokens.css in charge so the `clamp()` in
- * `--columns-gutter` survives until the editor overrides it.
+ * Columns slice. The column grid holds one count and one max width, and a
+ * gutter and a margin per viewport. `--columns-gutter` and `--columns-margin`
+ * are structural: tokens.css points them at the viewport values for the
+ * window's width, and the editor never writes them.
  */
-import type { ColumnsState } from '../../store/editorTypes';
+import type { ColumnsState, EditorState } from '../../store/editorTypes';
 
-export const DEFAULT_COLUMNS: ColumnsState = { count: 12, maxWidth: 1440, gutter: 16, margin: 0 };
+export const COLUMN_VIEWPORTS = ['desktop', 'tablet', 'phone'] as const;
+export type ColumnViewport = (typeof COLUMN_VIEWPORTS)[number];
 
-export const COLUMN_VAR_NAMES = ['--columns-count', '--columns-max-width', '--columns-gutter', '--columns-margin'] as const;
+export interface ColumnViewportValues {
+  gutter: number;
+  margin: number;
+}
+export type ColumnProperty = keyof ColumnViewportValues;
+export const COLUMN_PROPERTIES: readonly ColumnProperty[] = ['gutter', 'margin'];
 
-export function columnsToVars(c: ColumnsState): Record<string, string> {
-  return {
-    '--columns-count': String(c.count),
-    '--columns-max-width': `${c.maxWidth}px`,
-    '--columns-gutter': `${c.gutter}px`,
-    '--columns-margin': `${c.margin}px`,
-  };
+/** The widest window each narrower viewport covers, as tokens.css's `@media (max-width)` blocks declare it. */
+export const COLUMN_BREAKPOINTS: Record<Exclude<ColumnViewport, 'desktop'>, number> = {
+  tablet: 767,
+  phone: 480,
+};
+
+export const COLUMN_COUNT_NAME = '--columns-count';
+export const COLUMN_MAX_WIDTH_NAME = '--columns-max-width';
+
+export function columnVarName(viewport: ColumnViewport, property: ColumnProperty): string {
+  return `--columns-${viewport}-${property}`;
 }
 
-/**
- * Only emit column CSS vars once the user has actually modified columns.
- * While columns match the default, we leave tokens.css in charge — which
- * preserves the `clamp()` in `--columns-gutter` until the editor overrides it.
- */
-export function columnsEqualsDefault(c: ColumnsState): boolean {
-  return c.count === DEFAULT_COLUMNS.count
-    && c.maxWidth === DEFAULT_COLUMNS.maxWidth
-    && c.gutter === DEFAULT_COLUMNS.gutter
-    && c.margin === DEFAULT_COLUMNS.margin;
-}
-
-export function parseColumnVars(vars: Record<string, string>): Partial<ColumnsState> {
-  const out: Partial<ColumnsState> = {};
-  const count = parseInt(vars['--columns-count'] ?? '', 10);
-  if (Number.isFinite(count) && count > 0) out.count = count;
-  const maxWidth = parseFloat(vars['--columns-max-width'] ?? '');
-  if (Number.isFinite(maxWidth)) out.maxWidth = Math.round(maxWidth);
-  const gutter = parseFloat(vars['--columns-gutter'] ?? '');
-  if (Number.isFinite(gutter)) out.gutter = Math.round(gutter);
-  const margin = parseFloat(vars['--columns-margin'] ?? '');
-  if (Number.isFinite(margin)) out.margin = Math.round(margin);
+export const VIEWPORT_COLUMN_NAMES: readonly string[] = COLUMN_VIEWPORTS.flatMap((viewport) =>
+  COLUMN_PROPERTIES.map((property) => columnVarName(viewport, property)),
+);
+
+export const STRUCTURAL_COLUMN_NAMES = ['--columns-gutter', '--columns-margin'] as const;
+
+export const COLUMN_VAR_NAMES: readonly string[] = [COLUMN_COUNT_NAME, COLUMN_MAX_WIDTH_NAME, ...VIEWPORT_COLUMN_NAMES];
+
+export const COLUMN_DEFAULTS: Readonly<ColumnsState> = {
+  count: 12,
+  maxWidth: 1440,
+  viewports: {
+    desktop: { gutter: 32, margin: 32 },
+    tablet: { gutter: 24, margin: 24 },
+    phone: { gutter: 16, margin: 16 },
+  },
+};
+
+export function defaultColumns(): ColumnsState {
+  return structuredClone(COLUMN_DEFAULTS);
+}
+
+/** Each name appears only when its value differs from the tokens.css default. */
+export function columnsToVars(c: ColumnsState): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (c.count !== COLUMN_DEFAULTS.count) out[COLUMN_COUNT_NAME] = String(c.count);
+  if (c.maxWidth !== COLUMN_DEFAULTS.maxWidth) out[COLUMN_MAX_WIDTH_NAME] = `${c.maxWidth}px`;
+  for (const viewport of COLUMN_VIEWPORTS) {
+    for (const property of COLUMN_PROPERTIES) {
+      const value = c.viewports[viewport][property];
+      if (value !== COLUMN_DEFAULTS.viewports[viewport][property]) {
+        out[columnVarName(viewport, property)] = `${value}px`;
+      }
+    }
+  }
   return out;
 }
 
+function parseLength(raw: string | undefined): number | undefined {
+  const length = parseFloat(raw ?? '');
+  return Number.isFinite(length) ? Math.round(length) : undefined;
+}
+
+/** A name the bag lacks, or holds in a form the editor cannot edit, keeps its default. */
+export function columnsFromVars(vars: Record<string, string>): ColumnsState {
+  const columns = defaultColumns();
+  const count = parseInt(vars[COLUMN_COUNT_NAME] ?? '', 10);
+  if (Number.isFinite(count) && count > 0) columns.count = count;
+  const maxWidth = parseLength(vars[COLUMN_MAX_WIDTH_NAME]);
+  if (maxWidth !== undefined) columns.maxWidth = maxWidth;
+  for (const viewport of COLUMN_VIEWPORTS) {
+    for (const property of COLUMN_PROPERTIES) {
+      const value = parseLength(vars[columnVarName(viewport, property)]);
+      if (value !== undefined) columns.viewports[viewport][property] = value;
+    }
+  }
+  return columns;
+}
+
 /**
  * Loader: route the relevant entries from a freshly-loaded theme's vars bag
  * into `next.columns` and remove them from the bag so derivation stays
  * single-source. Mutates `next` and `rawVars` in place.
  */
-export function loadColumnsFromVars(
-  next: import('../../store/editorTypes').EditorState,
-  rawVars: Record<string, string>,
-): void {
-  const overrides = parseColumnVars(rawVars);
-  next.columns = { ...DEFAULT_COLUMNS, ...overrides };
+export function loadColumnsFromVars(next: EditorState, rawVars: Record<string, string>): void {
+  next.columns = columnsFromVars(rawVars);
   for (const name of COLUMN_VAR_NAMES) delete rawVars[name];
 }
+
+interface FlatColumnsState {
+  count: number;
+  maxWidth: number;
+  gutter: number;
+  margin: number;
+}
+
+// The flat state's old defaults rendered nothing, so a session sitting on them
+// takes today's defaults instead of pinning a 16px desktop gutter.
+const FLAT_DEFAULTS: FlatColumnsState = { count: 12, maxWidth: 1440, gutter: 16, margin: 0 };
+
+/**
+ * A session persisted before the per-viewport state holds one flat set, which
+ * the renderer wrote to the names that are now the count, the max width and
+ * the desktop gutter and margin. Its `0` margin is the one every shipped theme
+ * held, so it takes today's default as a stored theme's does.
+ */
+export function normalizeColumnsState(raw: ColumnsState | FlatColumnsState): ColumnsState {
+  if ('viewports' in raw) return raw;
+  const columns = defaultColumns();
+  const isFlatDefault = (Object.keys(FLAT_DEFAULTS) as (keyof FlatColumnsState)[])
+    .every((key) => raw[key] === FLAT_DEFAULTS[key]);
+  if (isFlatDefault) return columns;
+  columns.count = raw.count;
+  columns.maxWidth = raw.maxWidth;
+  columns.viewports.desktop.gutter = raw.gutter;
+  if (raw.margin !== FLAT_DEFAULTS.margin) columns.viewports.desktop.margin = raw.margin;
+  return columns;
+}

package/src/editor/docs/Docs.svelte

@@ -94,16 +94,7 @@
     {
       path: 'guide',
       title: 'Guide',
-      items: [
-        { path: '01-overview',         title: 'Overview' },
-        { path: 'getting-started',     title: 'Getting started' },
-        { path: 'editing-tokens',      title: 'Editing tokens' },
-        { path: 'sketch-mode',         title: 'Sketch mode' },
-        { path: 'themes-workflow',     title: 'Themes' },
-        { path: 'where-themes-live',   title: 'Where themes live' },
-        { path: 'light-and-dark',      title: 'Light and dark' },
-        { path: 'creating-components', title: 'Creating components' },
-      ],
+      items: chapters.map((c) => ({ path: c.id, title: c.title })),
     },
   ];
 
@@ -368,18 +359,27 @@
     color: var(--text-primary);
     min-height: 100vh;
   }
+  /* The open rail spans three columns of the page grid and the closed rail one.
+     A percentage resolves against the shell's content box, and the rail's own
+     width tokens resolve 100cqw against the same box, so track and rail tween
+     together. The rail's width excludes its border-right. */
   .docs-shell {
+    --docs-column: calc((100% - (var(--columns-count) - 1) * var(--columns-gutter)) / var(--columns-count));
+    --docs-rail-column: calc((100cqw - (var(--columns-count) - 1) * var(--columns-gutter)) / var(--columns-count));
+    --sidenavigation-panel-open-width: calc(3 * var(--docs-rail-column) + 2 * var(--columns-gutter) - var(--sidenavigation-panel-border-width));
+    --sidenavigation-panel-closed-width: calc(var(--docs-rail-column) - var(--sidenavigation-panel-border-width));
+    container-type: inline-size;
     display: grid;
-    grid-template-columns: var(--sidenavigation-panel-open-width, 16rem) minmax(0, 1fr);
+    grid-template-columns: calc(3 * var(--docs-column) + 2 * var(--columns-gutter)) minmax(0, 1fr);
+    column-gap: var(--columns-gutter);
+    box-sizing: content-box;
     max-width: var(--columns-max-width, 1440px);
     margin: 0 auto;
-    padding: 0 var(--space-32, 2rem);
+    padding-inline: var(--columns-margin);
     transition: grid-template-columns var(--duration-200, 200ms) var(--ease-in-out-sine, ease);
   }
-  /* The rail's own width tween (its width tokens) drives the column; keep the
-     grid track locked to the closed width so content reflows in step. */
   .docs-shell.collapsed {
-    grid-template-columns: var(--sidenavigation-panel-closed-width, 3rem) minmax(0, 1fr);
+    grid-template-columns: var(--docs-column) minmax(0, 1fr);
   }
 
   .docs-main {
@@ -390,7 +390,7 @@
   /* -------------------------------------------------------------- Top header */
   .docs-page-header {
     border-bottom: var(--border-width-1, 1px) solid var(--border-neutral-faint, #1c2327);
-    padding: var(--space-48, 3rem) 0 var(--space-32, 2rem) var(--space-32, 2rem);
+    padding: var(--space-48, 3rem) 0 var(--space-32, 2rem);
     background: linear-gradient(
       180deg,
       color-mix(in srgb, var(--surface-neutral-lower, #162027) 50%, transparent),
@@ -471,7 +471,7 @@
     min-width: 0;
     max-width: 760px;
     outline: none;
-    padding: var(--space-32, 2rem) 0 0 var(--space-32, 2rem);
+    padding: var(--space-32, 2rem) 0 0;
   }
 
   .loading-row {
@@ -664,12 +664,15 @@
     .docs-shell :global(.docs-sidebar) { height: 100%; }
   }
 
-  /* Below 960px the rail stacks above the content; the page scrolls naturally. */
+  /* Below 960px the open rail stacks full width above the content; the page
+     scrolls naturally. */
   @media (max-width: 960px) {
+    .docs-shell { --sidenavigation-panel-open-width: calc(100cqw - var(--sidenavigation-panel-border-width)); }
     .docs-shell,
-    .docs-shell.collapsed { grid-template-columns: 1fr; }
-  }
-  @media (max-width: 600px) {
-    .docs-shell { padding: 0 var(--space-16, 1rem); }
+    .docs-shell.collapsed {
+      grid-template-columns: repeat(var(--columns-count), minmax(0, 1fr));
+    }
+    .docs-shell > :global(.docs-sidebar),
+    .docs-main { grid-column: 1 / -1; }
   }
 </style>

package/src/editor/docs/chapters.ts

@@ -18,6 +18,7 @@ export const chapters: Chapter[] = [
   { id: 'where-themes-live',   title: 'Where themes live' },
   { id: 'light-and-dark',      title: 'Light and dark' },
   { id: 'creating-components', title: 'Creating components' },
+  { id: 'production-css',      title: 'Production CSS' },
 ];
 
 export const chapterIds = chapters.map((c) => c.id);

package/src/editor/docs/content/editing-tokens.md

@@ -68,9 +68,11 @@ Change a step and every element using it repaints.
 
 ## Columns
 
-The page-grid overlay. Set column count, gutter, and outer margin, and toggle
-the visual guide with `Cmd/Ctrl+G`. Pages built on the column system reflow
-live.
+Pages lay out on the column grid. The column count and the max width hold at
+every width. Desktop, Tablet, and Phone each set a gutter and an outer margin,
+and the grid takes the tablet values at 767px and narrower and the phone values
+at 480px and narrower. The columns button in the editor bar draws the grid over
+the page, and a page on the grid reflows as you edit.
 
 ## Saving
 

package/src/editor/docs/content/production-css.md

@@ -0,0 +1,116 @@
+# Production CSS
+
+In dev, every design token sits on `:root` as a CSS variable, because the
+editor can rewrite any of them while the page runs. A production build runs no
+editor, so most of those values never change. `vite build` rewrites the CSS it
+emits to match: a token stays a variable only where its value can change at
+runtime, and every other `var()` gives way to the value it reads.
+
+The dev server keeps every variable. Your source files keep every token too:
+the build rewrites only the files it emits, so `tokens.css`,
+`tokens.generated.css` and your components still name each token, and the
+token names stay the API you write against.
+
+## The build step
+
+`themeFileApi` runs the step at the end of every `vite build`, after Vite has
+bundled and minified the CSS. It reads every stylesheet and script in the
+bundle, including lazy chunks, and then:
+
+- **removes** each custom property that no rule reads, directly or through
+  another property;
+- **substitutes** each `var()` that reads a static property with the text of
+  that property's value, so `calc()` and `color-mix()` still resolve on the
+  element that uses them;
+- **declares** each remaining property once on `:root`, with the value that
+  wins the cascade, so DevTools lists it once.
+
+The build prints one line with the result:
+
+```
+live-tokens: the production CSS declares 76 of 848 custom properties and is 61.3 kB smaller.
+```
+
+A file's hashed name follows its content. Each stylesheet the build rewrites
+takes a new hash, and so does each script that loads it, so a cache that keeps
+hashed files forever serves each release its own files. A file name pattern
+without `[hash]` keeps every name.
+
+## The dynamic rule
+
+A property stays a variable when its value can change while the page runs, or
+when the build cannot prove it never does. A property that changes and loses
+its variable breaks a page, and an extra variable costs a few bytes, so a case
+that could fall either way stays a variable. A property is **dynamic** when any
+of these hold:
+
+- A rule declares it under a selector besides a root selector such as `:root`
+  or `:root:root`, or inside `@media`, `@supports` or `@container`. The size
+  tokens and the column gutter and margin in the three responsive `@media`
+  blocks of `tokens.css` stay variables this way.
+- Its name appears in a script or HTML page the build emits. That covers
+  `style:--name` directives, `setProperty`, `getPropertyValue` and inline
+  `style` attributes. Card sets `--card-hover-border-enabled` through a
+  `style:` directive, so the token stays a variable.
+- Its name appears in an at-rule's prelude, such as a `style()` container
+  query.
+- An `@property` rule registers it.
+- The `keep` option lists it.
+- Its value reads a dynamic property.
+- Its winning value is a CSS-wide keyword such as `initial`, or it reads
+  itself through a loop of `var()` references.
+- Two stylesheets give it different `:root` values.
+- Its value reads a name that no stylesheet declares and no script or `keep`
+  entry names.
+- Only a lazily loaded stylesheet declares it, and another stylesheet reads
+  it.
+
+Every other property is **static**: one value on `:root` for the life of the
+page.
+
+## Computed names
+
+The build finds a name in a script only when the script spells it out. A
+script that assembles a name while the page runs, such as
+`` `--color-${family}-500` ``, hides it. The build then substitutes or removes
+that token, so a read returns an empty string and a write changes nothing. List
+each such name under `keep`:
+
+```ts
+themeFileApi({
+  tokensCssPath: 'src/system/styles/tokens.css',
+  productionCss: { keep: ['--color-brand-500', '--color-accent-500'] },
+}),
+```
+
+`keep` takes exact names. The same goes for a stylesheet outside the bundle,
+such as one in `public/`: the build never reads it, so list each token it
+reads under `keep`.
+
+## Options
+
+`productionCss` on `themeFileApi` sets the step:
+
+- **Default.** The build removes, substitutes and declares, as above.
+- **`productionCss: { keep: [...] }`.** Each listed name stays a variable.
+- **`productionCss: { substitute: false }`.** The build removes properties no
+  rule reads and keeps every other `var()`, so DevTools shows token names while
+  you debug. It still declares each property once on `:root`.
+- **`productionCss: false`.** The build keeps every variable, as dev does.
+
+`keep` and `substitute` combine in one object. When a page renders differently
+in production, build it with `productionCss: false`. A difference that goes
+away points at a token the rule missed, and `keep` fixes it.
+
+## Limits
+
+- **Values a property rejects.** In dev, `width: var(--color-brand-500)` passes
+  the parser, and when the color reaches `width` the browser treats the
+  declaration as `unset`. After substitution, `width` holds a color, the parser
+  drops the declaration, and an earlier `width` rule applies. Keep each token's
+  value valid for every property that reads it.
+- **Fixed stylesheet names.** The build renames each stylesheet it rewrites
+  through the hash in the build's `assetFileNames` pattern. A plugin that emits
+  a stylesheet under a fixed `fileName` breaks that pattern, and the build
+  stops with `live-tokens: <file> does not follow the output pattern
+  "<pattern>"`. Set `productionCss: false` for that build.