@motion-proto/live-tokens 0.67.1 → 0.69.0

package/src/editor/core/sketch/sketchStyles.ts

@@ -6,7 +6,7 @@ import dashed from '../../../live-tokens/data/sketch-styles/dashed.json';
 import napkin from '../../../live-tokens/data/sketch-styles/napkin.json';
 import dry from '../../../live-tokens/data/sketch-styles/dry.json';
 
-export interface SketchStyle {
+export interface SketchStyleSettings {
   label: string;
   blurb: string;
   /** How far the fill's edge travels at its furthest, in px. Every dial that
@@ -80,7 +80,7 @@ export interface SketchStyle {
   /** Whether the two move together. Unlinked they part, and the field comes out
       stretched: blobs wider than they are tall read as a wash dragged sideways,
       the way ink pulled across a page does. Stored rather than inferred from
-      the pair matching, so a look that stretches to exactly square keeps its
+      the pair matching, so a sketchstyle that stretches to exactly square keeps its
       dials apart. */
   maskBlobLinked: boolean;
   /** Output levels on the coverage field, 0 to 1: the palest the fill gets and
@@ -144,40 +144,40 @@ export interface SketchStyle {
 /**
  * The shipped sketchstyles, read from the files the package distributes. The
  * files are the source: a project shadows one by saving a sketchstyle under the
- * same id, the editor restores a shipped look by deleting that file, and
+ * same id, the editor restores a shipped sketchstyle by deleting that file, and
  * `themeFileApi` serves these as the read-only fallback behind the project's own
- * directory. Editing a look here means editing its JSON, which is what the
+ * directory. Editing a sketchstyle here means editing its JSON, which is what the
  * Sketchstyle view already writes.
  *
  * Each file carries every dial, so there is nothing to merge a default into.
  * `sketchStyles.test.ts` pins that: the seven key sets have to match, and a dial
- * added to `SketchStyle` has to reach all seven before the suite goes green.
+ * added to `SketchStyleSettings` has to reach all seven before the suite goes green.
  *
  * Order is picker order.
  */
 const SHIPPED_FILES = { pencil, marker, whiteboard, hatched, dashed, napkin, dry };
 
-export const SKETCH_STYLES: Record<string, SketchStyle> = Object.fromEntries(
-  Object.entries(SHIPPED_FILES).map(([id, file]) => [id, file.settings as unknown as SketchStyle]),
+export const SHIPPED_SKETCH_SETTINGS: Record<string, SketchStyleSettings> = Object.fromEntries(
+  Object.entries(SHIPPED_FILES).map(([id, file]) => [id, file.settings as unknown as SketchStyleSettings]),
 );
 
 export const DEFAULT_SKETCH_STYLE = 'marker';
 
-/** The id of the look a theme carries, in the same id namespace as the shipped
+/** The id for sketch settings a theme carries, in the same id namespace as the shipped
     sketchstyles so one picker row and one `setSketch` call cover both. Never a
-    key of `SKETCH_STYLES`: a shipped style claiming it would shadow the theme's
-    own look in every picker. `index.test.ts` pins that. */
+    key of `SHIPPED_SKETCH_SETTINGS`: a shipped style claiming it would shadow the theme's
+    own sketchstyle in every picker. `index.test.ts` pins that. */
 export const THEME_SKETCH_ID = 'theme';
 
 /** Reconciled against a full sketchstyle in both directions: a value stored before a
     control existed picks up the default, and a value stored for a control since
     retired is dropped. Without the drop, a stale key survives every spread and
     makes the settings compare unequal to any baseline forever. */
-export function hydrateSketchStyle(raw: unknown): SketchStyle {
-  const base = SKETCH_STYLES[DEFAULT_SKETCH_STYLE];
-  const stored = (raw ?? {}) as Partial<SketchStyle>;
+export function hydrateSketchSettings(raw: unknown): SketchStyleSettings {
+  const base = SHIPPED_SKETCH_SETTINGS[DEFAULT_SKETCH_STYLE];
+  const stored = (raw ?? {}) as Partial<SketchStyleSettings>;
   const out = { ...base };
-  for (const key of Object.keys(base) as (keyof SketchStyle)[]) {
+  for (const key of Object.keys(base) as (keyof SketchStyleSettings)[]) {
     if (stored[key] !== undefined) (out[key] as unknown) = stored[key];
   }
   // A retired option: the fill's presence belongs to the theme, not the effect.
@@ -194,9 +194,9 @@ export function hydrateSketchStyle(raw: unknown): SketchStyle {
 }
 
 /** The second pass used to sit at a distance derived from the stroke width,
-    with no dial of its own. A look stored before the dial comes back at that
+    with no dial of its own. A sketchstyle stored before the dial comes back at that
     distance rather than at whatever the fallback sketchstyle happens to carry. */
-function restoreDerivedRetrace(stored: Record<string, unknown>, out: SketchStyle): void {
+function restoreDerivedRetrace(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   if (stored.retraceOffset === undefined) {
     out.retraceOffset = Number(Math.max(1.2, out.strokeWidth * 0.55).toFixed(2));
   }
@@ -204,7 +204,7 @@ function restoreDerivedRetrace(stored: Record<string, unknown>, out: SketchStyle
 
 /** The four displacement dials used to be stated as the map's own `scale`,
     which is the full swing: the number on the dial was twice the furthest
-    anything actually moved. They are peak travel in px now, so a look stored
+    anything actually moved. They are peak travel in px now, so a sketchstyle stored
     under the old names comes back halved and renders identically. */
 const SWING_DIALS = {
   fillScale: 'fillTravel',
@@ -216,11 +216,11 @@ const SWING_DIALS = {
 /** The pen wobble used to be stated as `frequency`, in cycles per px, which is
     the number the filter wants and not one anybody can picture. It is a
     wavelength in px now, the way the mask states its blobs. */
-function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchStyle): void {
+function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const cycles = stored.frequency;
   if (typeof cycles === 'number' && cycles > 0) out.wobble = Math.round(1 / cycles);
   // The layer count was `octaves`, and its dial ran to 5. The top two moved
-  // nothing, so a look stored there comes back at the roughest that reads.
+  // nothing, so a sketchstyle stored there comes back at the roughest that reads.
   // Both were multipliers on the frequency, so they ran the other way.
   for (const [legacy, key] of [
     ['borderFrequency', 'borderWavelength'], ['iconFrequency', 'iconWavelength'],
@@ -234,9 +234,9 @@ function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchS
   if (typeof layers === 'number') out.roughness = Math.min(3, Math.max(1, layers));
 }
 
-/** The blob size was one number for both axes. A look stored before the split
-    comes back square, with the two dials linked, which is the look it had. */
-function splitBlobAxes(stored: Record<string, unknown>, out: SketchStyle): void {
+/** The blob size was one number for both axes. A sketchstyle stored before the split
+    comes back square, with the two dials linked, which is the shape it had. */
+function splitBlobAxes(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const blob = stored.maskBlob;
   if (typeof blob !== 'number') return;
   out.maskBlobX = blob;
@@ -249,13 +249,13 @@ function splitBlobAxes(stored: Record<string, unknown>, out: SketchStyle): void
     of the field, so it came out either untouched or gone. It is a share of the
     glyph now, and the old default reads as one period across the glyph, which
     is what that size was aiming at. */
-function convertIconTileToScale(stored: Record<string, unknown>, out: SketchStyle): void {
+function convertIconTileToScale(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const tile = stored.iconMaskTile;
   if (typeof tile !== 'number') return;
   out.iconMaskScale = Math.min(5, Math.max(0.5, Number((tile / 90).toFixed(2))));
 }
 
-function halveSwingDials(stored: Record<string, unknown>, out: SketchStyle): void {
+function halveSwingDials(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   for (const [legacy, key] of Object.entries(SWING_DIALS)) {
     const value = stored[legacy];
     if (typeof value === 'number') out[key as 'fillTravel'] = value / 2;
@@ -265,7 +265,7 @@ function halveSwingDials(stored: Record<string, unknown>, out: SketchStyle): voi
 /** The mask used to be a 600-unit tile painted at `maskScale` px, with the
     coverage point buried in the hardness slope. Recover page-px blobs and
     softness, and the levels the old slope and floor put the edge at. */
-function convertTiledMask(stored: Record<string, unknown>, out: SketchStyle): void {
+function convertTiledMask(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const scale = stored.maskScale;
   if (typeof scale !== 'number') return;
   const freq = stored.maskFrequency;
@@ -283,7 +283,7 @@ function convertTiledMask(stored: Record<string, unknown>, out: SketchStyle): vo
  * levels the pair put the edge between, and rescale them onto the field as it
  * is now: stretched onto its full range before the levels see it.
  */
-function convertCutToLevels(stored: Record<string, unknown>, out: SketchStyle): void {
+function convertCutToLevels(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   const contrast = stored.maskContrast;
   const coverage = stored.maskCoverage;
   if (typeof contrast !== 'number' || typeof coverage !== 'number') return;
@@ -297,9 +297,9 @@ function convertCutToLevels(stored: Record<string, unknown>, out: SketchStyle):
 
 /** The pair were input levels, a cut through the field, and are output levels
     now, the palest and densest the fill gets. The same two numbers carry over:
-    a look cut between 20% and 50% comes back as a wash between 20% and 50% ink,
+    a sketchstyle cut between 20% and 50% comes back as a wash between 20% and 50% ink,
     which keeps its spread and loses only the hole. */
-function carryLevelsToOutput(stored: Record<string, unknown>, out: SketchStyle): void {
+function carryLevelsToOutput(stored: Record<string, unknown>, out: SketchStyleSettings): void {
   if (typeof stored.maskLevelMin === 'number') out.maskOutputMin = stored.maskLevelMin;
   if (typeof stored.maskLevelMax === 'number') out.maskOutputMax = stored.maskLevelMax;
 }

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

@@ -20,6 +20,7 @@ import { store } from './editorCore';
 import { quietGet, quietSet } from '../storage/storage';
 import { isGradientSlot, makeDefaultGradients } from '../themes/slices/gradients';
 import { seedShadowsFromDom } from '../themes/slices/shadows';
+import { makeDefaultScrimTokens, makeDefaultTintTokens } from '../themes/slices/washes';
 import { sanitizeHarmonyAxes } from '../palettes/colorHarmony';
 import {
   renameBackgroundPaletteKey,
@@ -77,6 +78,48 @@ function migrateGradients(state: EditorState): EditorState {
 // calls `Object.entries(slice.config)` unconditionally, so backfill the
 // required fields and drop any non-object slice before the state reaches the
 // renderer. Spread preserves optional fields like `unlinked`.
+// The washes slice was `overlays: { tokens, hoverTokens }` before the scrim and
+// tint renames, and `hydrate` shallow-merges, so a persisted state from an
+// older build replaces `washes` wholesale and arrives without `tints`.
+// `washesToVars` iterates both lists unconditionally, so reshape here: carry the
+// stops across under their new names, and rewrite the variable each one carries.
+const WASH_VAR_RENAMES: Record<string, string> = {
+  '--overlay-low': '--scrim-low',
+  '--overlay': '--scrim',
+  '--overlay-high': '--scrim-high',
+  '--hover-low': '--tint-low',
+  '--hover': '--tint',
+  '--hover-high': '--tint-high',
+};
+
+type LegacyWashes = {
+  scrims?: unknown;
+  tints?: unknown;
+  hoverTokens?: unknown;
+  tokens?: unknown;
+};
+
+/** Carry a persisted stop list forward, or fall back to the shipped defaults. */
+function washList(raw: unknown, fallback: () => EditorState['washes']['scrims']) {
+  if (!Array.isArray(raw) || raw.length === 0) return fallback();
+  const carried = raw
+    .filter((t): t is EditorState['washes']['scrims'][number] => !!t && typeof t === 'object' && 'variable' in t)
+    .map((t) => ({ ...t, variable: WASH_VAR_RENAMES[t.variable] ?? t.variable }));
+  return carried.length > 0 ? carried : fallback();
+}
+
+export function normalizeWashes(state: EditorState): EditorState {
+  const washes = (state.washes ?? {}) as LegacyWashes;
+  const legacy = ((state as unknown as { overlays?: LegacyWashes }).overlays ?? {}) as LegacyWashes;
+  const next = { ...state } as EditorState & { overlays?: unknown };
+  next.washes = {
+    scrims: washList(washes.scrims ?? legacy.tokens, makeDefaultScrimTokens),
+    tints: washList(washes.tints ?? washes.hoverTokens ?? legacy.hoverTokens, makeDefaultTintTokens),
+  };
+  delete next.overlays;
+  return next;
+}
+
 export function normalizeComponents(state: EditorState): EditorState {
   const raw = state.components;
   if (!raw || typeof raw !== 'object') return { ...state, components: {} };
@@ -134,7 +177,7 @@ export function hydrate(): void {
     store.set(
       normalizeHarmonyAxes(
         normalizeBaseAnchors(
-          normalizePaletteBasis(normalizePaletteLabels(normalizeComponents(migrateGradients(merged)))),
+          normalizePaletteBasis(normalizePaletteLabels(normalizeComponents(normalizeWashes(migrateGradients(merged))))),
         ),
       ),
     );

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

@@ -19,7 +19,7 @@ import {
   editorState,
   columnsToVars,
   columnsEqualsDefault,
-  overlaysToVars,
+  washesToVars,
   shadowsToVars,
   gradientsToVars,
   componentsToVars,
@@ -30,7 +30,7 @@ export function deriveCssVars(state: EditorState): Record<string, string> {
   if (!columnsEqualsDefault(state.columns)) {
     Object.assign(out, columnsToVars(state.columns));
   }
-  Object.assign(out, overlaysToVars(state.overlays));
+  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

@@ -1,7 +1,7 @@
 /**
  * Central editor state store — the single mutation funnel.
  *
- * All editor state (palettes, fonts, shadows, overlays, columns, ad-hoc CSS
+ * All editor state (palettes, fonts, shadows, washes, columns, ad-hoc CSS
  * vars) lives in one `EditorState` tree. Every change must go through
  * `mutate` (or a transaction). History is captured automatically; the
  * renderer subscribes and writes derived CSS vars to :root via `cssVarSync`
@@ -62,10 +62,10 @@ import {
   loadColumnsFromVars,
 } from '../themes/slices/columns';
 import {
-  loadOverlaysFromVars,
-  makeDefaultOverlaysState,
-  overlaysToVars,
-} from '../themes/slices/overlays';
+  loadWashesFromVars,
+  makeDefaultWashesState,
+  washesToVars,
+} from '../themes/slices/washes';
 import {
   loadShadowsFromVars,
   shadowsToVars,
@@ -99,7 +99,7 @@ function emptyState(): EditorState {
       tokens: [],
       overrides: {},
     },
-    overlays: makeDefaultOverlaysState(),
+    washes: makeDefaultWashesState(),
     columns: { ...DEFAULT_COLUMNS },
     components: {},
     gradients: { tokens: makeDefaultGradients() },
@@ -150,15 +150,15 @@ export {
 } from '../themes/slices/columns';
 
 export {
-  overlaysToVars,
-  OVERLAY_VAR_NAMES,
-  applyOverlayVarsToState,
-  makeDefaultOverlaysState,
-  makeDefaultOverlayTokens,
-  makeDefaultHoverTokens,
-  overlayTokenToCss,
-  parseOverlayCss,
-} from '../themes/slices/overlays';
+  washesToVars,
+  WASH_VAR_NAMES,
+  applyWashVarsToState,
+  makeDefaultWashesState,
+  makeDefaultScrimTokens,
+  makeDefaultTintTokens,
+  washTokenToCss,
+  parseWashCss,
+} from '../themes/slices/washes';
 
 export {
   shadowsToVars,
@@ -364,7 +364,7 @@ type DomainLoader = (next: EditorState, rawVars: Record<string, string>) => void
 
 const domainLoaders: Record<string, DomainLoader> = {
   columns: loadColumnsFromVars,
-  overlays: loadOverlaysFromVars,
+  washes: loadWashesFromVars,
   shadows: loadShadowsFromVars,
   components: loadComponentsFromVars,
 };
@@ -428,7 +428,7 @@ function colorsAndTypeContent(state: EditorState): Omit<ColorsAndType, 'name' |
   if (!columnsEqualsDefault(state.columns)) {
     Object.assign(cssVariables, columnsToVars(state.columns));
   }
-  Object.assign(cssVariables, overlaysToVars(state.overlays));
+  Object.assign(cssVariables, washesToVars(state.washes));
   if (state.shadows.tokens.length > 0) {
     Object.assign(cssVariables, shadowsToVars(state.shadows));
   }
@@ -450,7 +450,7 @@ function colorsAndTypeContent(state: EditorState): Omit<ColorsAndType, 'name' |
 
 /**
  * Serialize current state for saving. Domains with their own typed state
- * (columns, overlays, shadows) fold derived vars into `cssVariables` only
+ * (columns, washes, shadows) fold derived vars into `cssVariables` only
  * when they diverge from defaults; the catch-all `cssVars` bag carries
  * everything not yet migrated to a typed domain.
  *

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

@@ -23,9 +23,10 @@ export interface ShadowOverrideFlags {
   distance: boolean; blur: boolean; size: boolean;
 }
 
-/** Overlay stop: an aliased color token + an opacity. Emits as
- *  `color-mix(in srgb, var(<alias>) <opacity%>, transparent)`. */
-export interface OverlayToken {
+/** A wash: an aliased color token + an opacity. Emits as
+ *  `color-mix(in srgb, var(<alias>) <opacity%>, transparent)`. Scrims dim what
+ *  is behind them; tints shade the surface they sit on. */
+export interface WashToken {
   variable: string;
   label: string;
   alias: string;
@@ -111,9 +112,9 @@ export interface EditorState {
     tokens: ShadowToken[];
     overrides: Record<string, ShadowOverrideFlags>;
   };
-  overlays: {
-    tokens: OverlayToken[];
-    hoverTokens: OverlayToken[];
+  washes: {
+    scrims: WashToken[];
+    tints: WashToken[];
   };
   columns: ColumnsState;
   components: Record<string, ComponentSlice>;

package/src/editor/core/themes/colorsAndTypeService.ts

@@ -65,7 +65,7 @@ export const sanitizeFileName = sanitizeFileNameImpl;
 
 /** Flush the editor state to the buffer under `displayName`, the name of the
  *  theme the buffer belongs to, and clear the dirty flag. A capture reads the
- *  buffer back, so this is what makes Save and Adopt mean the look on screen. */
+ *  buffer back, so this is what makes Save and Adopt mean the theme on screen. */
 export async function persistColorsAndType(
   state: EditorState,
   displayName: string,

package/src/editor/core/themes/loadRows.ts

@@ -1,7 +1,7 @@
 import type { ThemeMeta, ColorsAndTypeMeta } from './themeTypes';
 
 /**
- * The one Load list. A theme is the whole look; a colors and type file is a
+ * The one Load list. A theme is the whole theme; a colors and type file is a
  * preset holding that half of one. Both belong in the same window, told apart
  * by a badge rather than by living in separate managers.
  *
@@ -10,7 +10,7 @@ import type { ThemeMeta, ColorsAndTypeMeta } from './themeTypes';
  * that copy is exactly the file the list must keep reachable.
  */
 
-export type LoadRowKind = 'look' | 'layer';
+export type LoadRowKind = 'theme' | 'layer';
 
 export interface LoadRow {
   /** `<kind>:<slug>`. The two kinds are separate resources with separate name
@@ -25,12 +25,12 @@ export interface LoadRow {
 
 export const loadRowId = (kind: LoadRowKind, slug: string): string => `${kind}:${slug}`;
 
-export function buildLoadRows(looks: ThemeMeta[], layers: ColorsAndTypeMeta[]): LoadRow[] {
-  const lookRows: LoadRow[] = looks
+export function buildLoadRows(themes: ThemeMeta[], layers: ColorsAndTypeMeta[]): LoadRow[] {
+  const themeRows: LoadRow[] = themes
     .map((f): LoadRow => ({
-      fileName: loadRowId('look', f.fileName),
+      fileName: loadRowId('theme', f.fileName),
       slug: f.fileName,
-      kind: 'look',
+      kind: 'theme',
       name: f.name,
       updatedAt: f.updatedAt,
       isProtected: f.isProtected,
@@ -46,12 +46,12 @@ export function buildLoadRows(looks: ThemeMeta[], layers: ColorsAndTypeMeta[]):
       updatedAt: f.updatedAt,
       isProtected: false,
     }));
-  return [...lookRows, ...layerRows];
+  return [...themeRows, ...layerRows];
 }
 
 /**
  * Whether picking this row loads colors and type alone. A layer file holds
- * nothing else, so it ignores the toggle; a look honors it.
+ * nothing else, so it ignores the toggle; a theme honors it.
  */
 export function isColorsOnly(row: LoadRow | null, colorsOnly: boolean): boolean {
   if (row?.kind === 'layer') return true;

package/src/editor/core/themes/migrations/2026-09-01-gate-suffix-enabled.ts

@@ -0,0 +1,31 @@
+import type { Migration } from './index';
+
+/**
+ * Gate suffix, state word to `-enabled` (2026-09-01).
+ *
+ * An optional interaction is switched by a gate variable. Those gates were named
+ * with a state word at the end (`--card-hover-border-active`,
+ * `--image-zoom-hover`), which reads as state-after-property and fails
+ * `check-component`. A gate is not a state: it says whether the interaction is
+ * on at all, so it takes `-enabled`.
+ *
+ * Values are unchanged; a gate still holds either its off value or its on value.
+ */
+const RENAMED: Record<string, string> = {
+  '--card-hover-border-active': '--card-hover-border-enabled',
+  '--card-hover-shadow-active': '--card-hover-shadow-enabled',
+  '--image-zoom-hover': '--image-zoom-enabled',
+  '--image-grow-hover': '--image-grow-enabled',
+};
+
+export const componentMigration_2026_09_01_gateSuffixEnabled: Migration = {
+  id: '2026-09-01-gate-suffix-enabled',
+  fromVersion: 24,
+  toVersion: 25,
+  appliesTo: 'component-config',
+  apply(rawVars) {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) out[RENAMED[key] ?? key] = value;
+    return out;
+  },
+};

package/src/editor/core/themes/migrations/2026-09-01-scrim-rename.ts

@@ -0,0 +1,52 @@
+import type { Migration } from './index';
+
+/**
+ * Scrim rename (2026-09-01): `--overlay-*` became `--scrim-*`.
+ *
+ * An overlay is a scrim, a translucent layer that dims what is behind it. The
+ * name had spread to cover surface tints too, which are the opposite operation,
+ * and it collided with `backdrop`, an exported concept about what paints behind
+ * an element. Each name now means one thing.
+ *
+ * Values are unchanged, so this is a pure key rename in colors-and-type files.
+ * Component configs need both halves: Dialog's `--dialog-overlay-surface` is a
+ * key, and any alias *value* pointing at a scrim stop is a bare token name that
+ * has to be rebound.
+ */
+const RENAMED: Record<string, string> = {
+  '--overlay-low': '--scrim-low',
+  '--overlay': '--scrim',
+  '--overlay-high': '--scrim-high',
+};
+
+const RENAMED_COMPONENT_KEYS: Record<string, string> = {
+  '--dialog-overlay-surface': '--dialog-scrim-surface',
+};
+
+export const colorsAndTypeMigration_2026_09_01_scrimRename: Migration = {
+  id: '2026-09-01-scrim-rename-theme',
+  fromVersion: 5,
+  toVersion: 6,
+  appliesTo: 'colors-and-type',
+  apply(rawVars) {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      out[RENAMED[key] ?? key] = value;
+    }
+    return out;
+  },
+};
+
+export const componentMigration_2026_09_01_scrimRename: Migration = {
+  id: '2026-09-01-scrim-rename-component',
+  fromVersion: 21,
+  toVersion: 22,
+  appliesTo: 'component-config',
+  apply(rawVars) {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      out[RENAMED_COMPONENT_KEYS[key] ?? key] = RENAMED[value] ?? value;
+    }
+    return out;
+  },
+};

package/src/editor/core/themes/migrations/2026-09-01-tabbar-active-tint.ts

@@ -0,0 +1,27 @@
+import type { Migration } from './index';
+
+/**
+ * TabBar active surface, scrim to tint (2026-09-01, tabbar only).
+ *
+ * The active tab is a wash *on* the bar, not a layer dimming what is behind it,
+ * so it belongs to the tint family. It only ever read a scrim because no tint
+ * family existed. Rebinding is a visible change: the 38% near-black scrim
+ * becomes a 10% white tint, so the active tab reads lighter rather than darker.
+ *
+ * Scoped to the shipped default value. A theme that pointed this alias
+ * somewhere else keeps its choice.
+ */
+export const componentMigration_2026_09_01_tabbarActiveTint: Migration = {
+  id: '2026-09-01-tabbar-active-tint',
+  fromVersion: 23,
+  toVersion: 24,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    if (meta.component !== 'tabbar') return { ...rawVars };
+    const out = { ...rawVars };
+    if (out['--tabbar-active-surface'] === '--scrim-low') {
+      out['--tabbar-active-surface'] = '--tint-low';
+    }
+    return out;
+  },
+};

package/src/editor/core/themes/migrations/2026-09-01-tint-rename.ts

@@ -0,0 +1,42 @@
+import type { Migration } from './index';
+
+/**
+ * Tint rename (2026-09-01): `--hover-*` became `--tint-*`.
+ *
+ * A state is a segment of a property name (`--button-outline-hover-surface`),
+ * not a token of its own, so the three stops are named for what they are: a
+ * tint shades the surface it sits on. Values are unchanged.
+ *
+ * Nothing shipped read the old names, so this only touches saved files that
+ * captured them from the editor's own stops.
+ */
+const RENAMED: Record<string, string> = {
+  '--hover-low': '--tint-low',
+  '--hover': '--tint',
+  '--hover-high': '--tint-high',
+};
+
+export const colorsAndTypeMigration_2026_09_01_tintRename: Migration = {
+  id: '2026-09-01-tint-rename-theme',
+  fromVersion: 6,
+  toVersion: 7,
+  appliesTo: 'colors-and-type',
+  apply(rawVars) {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) out[RENAMED[key] ?? key] = value;
+    return out;
+  },
+};
+
+export const componentMigration_2026_09_01_tintRename: Migration = {
+  id: '2026-09-01-tint-rename-component',
+  fromVersion: 22,
+  toVersion: 23,
+  appliesTo: 'component-config',
+  apply(rawVars) {
+    const out: Record<string, string> = {};
+    // Alias values are bare token names; rebind any that pointed at a hover stop.
+    for (const [key, value] of Object.entries(rawVars)) out[key] = RENAMED[value] ?? value;
+    return out;
+  },
+};

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

@@ -62,6 +62,16 @@ import {
   colorsAndTypeMigration_2026_08_15_lineHeightScaleRename,
   componentMigration_2026_08_15_lineHeightScaleRename,
 } from './2026-08-15-line-height-scale-rename';
+import {
+  colorsAndTypeMigration_2026_09_01_scrimRename,
+  componentMigration_2026_09_01_scrimRename,
+} from './2026-09-01-scrim-rename';
+import {
+  colorsAndTypeMigration_2026_09_01_tintRename,
+  componentMigration_2026_09_01_tintRename,
+} from './2026-09-01-tint-rename';
+import { componentMigration_2026_09_01_tabbarActiveTint } from './2026-09-01-tabbar-active-tint';
+import { componentMigration_2026_09_01_gateSuffixEnabled } from './2026-09-01-gate-suffix-enabled';
 
 /**
  * Registered migrations. Order in this array does not matter — the runner
@@ -94,6 +104,12 @@ export const MIGRATIONS: Migration[] = [
   colorsAndTypeMigration_2026_08_13_dropLegacyShapeSpaceKeys,
   colorsAndTypeMigration_2026_08_15_lineHeightScaleRename,
   componentMigration_2026_08_15_lineHeightScaleRename,
+  colorsAndTypeMigration_2026_09_01_scrimRename,
+  componentMigration_2026_09_01_scrimRename,
+  colorsAndTypeMigration_2026_09_01_tintRename,
+  componentMigration_2026_09_01_tintRename,
+  componentMigration_2026_09_01_tabbarActiveTint,
+  componentMigration_2026_09_01_gateSuffixEnabled,
 ];
 
 function countFor(kind: 'colors-and-type' | 'component-config'): number {

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

@@ -5,11 +5,11 @@
  * so the store stays the single source of truth.
  */
 import { COLUMN_VAR_NAMES } from './columns';
-import { OVERLAY_VAR_NAMES } from './overlays';
+import { WASH_VAR_NAMES } from './washes';
 import { SHADOW_VAR_NAMES } from './shadows';
 
 export const DOMAIN_VAR_NAMES: readonly string[] = [
   ...COLUMN_VAR_NAMES,
-  ...OVERLAY_VAR_NAMES,
+  ...WASH_VAR_NAMES,
   ...SHADOW_VAR_NAMES,
 ];