@motion-proto/live-tokens 0.68.1 → 0.70.0

package/src/editor/core/components/aliasKinds.ts

@@ -21,36 +21,59 @@ export type TokenKind =
   | 'easing'
   | 'text-color';
 
-/** Suffix/prefix patterns mapped to kinds — the one source of truth for the
-    editor's selector layout and the `adjust` CLI, so the two cannot drift.
-    Order matters: `-text` must run before `-border`/`-surface` because `--text-*`
-    would otherwise match `surface`/`border` if any pattern overlapped. Variables
-    that don't match any pattern fall through to `text-color` (renders as a palette
-    picker). Tokens with unconventional suffixes should be renamed. */
-export const KIND_PATTERNS: ReadonlyArray<{ kind: TokenKind; matches: (v: string) => boolean }> = [
-  { kind: 'font-family',    matches: (v) => v.endsWith('-font-family') },
-  { kind: 'font-weight',    matches: (v) => v.endsWith('-font-weight') },
-  { kind: 'font-size',      matches: (v) => v.endsWith('-font-size') || v.endsWith('-icon-size') || v.endsWith('-thumb-size') },
-  { kind: 'line-height',    matches: (v) => v.endsWith('-line-height') },
-  { kind: 'letter-spacing', matches: (v) => v.endsWith('-letter-spacing') },
-  { kind: 'text-color',     matches: (v) => v.endsWith('-text') || v.startsWith('--text-') },
-  { kind: 'radius',         matches: (v) => v.endsWith('-radius') || v.startsWith('--radius-') },
-  { kind: 'divider-width',  matches: (v) => v.endsWith('-divider-width') || v.endsWith('-divider-thickness') },
-  { kind: 'divider-height', matches: (v) => v.endsWith('-divider-height') || v.endsWith('-track-height') },
-  { kind: 'divider-inset',  matches: (v) => v.endsWith('-divider-inset') },
-  { kind: 'dot-size',       matches: (v) => v.endsWith('-dot-size') },
-  { kind: 'blur',           matches: (v) => v.endsWith('-blur') || v.startsWith('--blur-') },
-  { kind: 'scale',          matches: (v) => v.endsWith('-scale') || v.startsWith('--scale-') },
-  { kind: 'shadow',         matches: (v) => v.endsWith('-shadow') || v.startsWith('--shadow-') },
-  { kind: 'padding',        matches: (v) => v.endsWith('-padding') || v.endsWith('-margin') },
-  { kind: 'gap',            matches: (v) => v.endsWith('-gap') },
-  { kind: 'duration',       matches: (v) => v.endsWith('-duration') || v.startsWith('--duration-') },
-  { kind: 'easing',         matches: (v) => v.endsWith('-easing') || v.startsWith('--ease-') },
-  { kind: 'border-width',   matches: (v) => v.endsWith('-border-width') || v.endsWith('-accent-width') || v.endsWith('-hairline-thickness') || v.startsWith('--border-width-') },
-  { kind: 'border',         matches: (v) => v.endsWith('-border') || v.startsWith('--border-') },
-  { kind: 'surface',        matches: (v) => v.endsWith('-surface') || v.startsWith('--surface-') },
+/** Suffix and prefix data mapped to kinds — the one source of truth for the
+    editor's selector layout, the `adjust` CLI, and `check-component`'s naming
+    rule, so the three cannot drift. `bin/check-component.mjs` reads the
+    `suffix:` arrays out of this file, which is why they are plain literals.
+
+    Order matters: `-text` must run before `-border`/`-surface`, and
+    `-accent-width` before `-accent`, because the first match wins. A variable
+    matching nothing falls through to `text-color` (a palette picker), but that
+    fall-through is a smell — `check-component` rejects an unrecognised suffix,
+    so add the name here rather than letting it drift. */
+export const KIND_RULES: ReadonlyArray<{
+  kind: TokenKind;
+  suffix?: readonly string[];
+  prefix?: readonly string[];
+}> = [
+  { kind: 'font-family',    suffix: ['-font-family'] },
+  { kind: 'font-weight',    suffix: ['-font-weight'] },
+  { kind: 'font-size',      suffix: ['-font-size', '-icon-size', '-thumb-size'] },
+  { kind: 'line-height',    suffix: ['-line-height'] },
+  { kind: 'letter-spacing', suffix: ['-letter-spacing'] },
+  // Element-named colour roles: the property *is* the element it paints.
+  { kind: 'text-color',     suffix: ['-text', '-label', '-icon', '-title', '-body', '-eyebrow',
+                                     '-description', '-hint', '-error', '-placeholder', '-value'],
+                            prefix: ['--text-'] },
+  { kind: 'radius',         suffix: ['-radius'], prefix: ['--radius-'] },
+  { kind: 'divider-width',  suffix: ['-divider-width', '-divider-thickness'] },
+  { kind: 'divider-height', suffix: ['-divider-height', '-track-height'] },
+  { kind: 'divider-inset',  suffix: ['-divider-inset', '-inset'] },
+  { kind: 'dot-size',       suffix: ['-dot-size'] },
+  { kind: 'blur',           suffix: ['-blur'], prefix: ['--blur-'] },
+  { kind: 'scale',          suffix: ['-scale'], prefix: ['--scale-'] },
+  { kind: 'shadow',         suffix: ['-shadow'], prefix: ['--shadow-'] },
+  { kind: 'padding',        suffix: ['-padding', '-margin'] },
+  { kind: 'gap',            suffix: ['-gap'] },
+  { kind: 'duration',       suffix: ['-duration'], prefix: ['--duration-'] },
+  { kind: 'easing',         suffix: ['-easing'], prefix: ['--ease-'] },
+  { kind: 'border-width',   suffix: ['-border-width', '-accent-width', '-hairline-thickness', '-thickness'],
+                            prefix: ['--border-width-'] },
+  { kind: 'border',         suffix: ['-border'], prefix: ['--border-'] },
+  // Fills. A tint is a wash over a surface, so it takes the surface picker: the
+  // full palette with an alpha, not just the tint stops it defaults to.
+  { kind: 'surface',        suffix: ['-surface', '-fill', '-divider', '-background', '-indicator',
+                                     '-thumb', '-accent', '-color', '-tint', '-opacity',
+                                     '-width', '-height', '-size'],
+                            prefix: ['--surface-', '--tint', '--color-'] },
 ];
 
+export const KIND_PATTERNS: ReadonlyArray<{ kind: TokenKind; matches: (v: string) => boolean }> =
+  KIND_RULES.map(({ kind, suffix = [], prefix = [] }) => ({
+    kind,
+    matches: (v: string) => suffix.some((s) => v.endsWith(s)) || prefix.some((p) => v.startsWith(p)),
+  }));
+
 export function rawKind(variable: string): TokenKind {
   for (const { kind, matches } of KIND_PATTERNS) {
     if (matches(variable)) return kind;

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

@@ -227,6 +227,22 @@ const PART_SPECS: readonly PartSpec[] = [
     // Holds the picture inside the frame; without it a zoom spills out square.
     clips: true,
   },
+  ...['single', 'range'].map((v) => ({
+    sel: `.slider.${v} .slider-track`,
+    fill: `var(--slider-${v}-track-surface)`,
+    stroke: `var(--slider-${v}-track-border)`,
+    radius: `var(--slider-${v}-track-radius, 0px)`,
+  })),
+  // The fill rides inside the track, so it is stroked by nothing and hatched
+  // in the track's ink.
+  ...['single', 'range'].map((v) => ({
+    sel: `.slider.${v} .slider-fill`,
+    fill: `var(--slider-${v}-fill)`,
+    stroke: 'transparent',
+    hatch: `var(--slider-${v}-track-border)`,
+    radius: `var(--slider-${v}-track-radius, 0px)`,
+    positioned: true,
+  })),
   { sel: '.toggle .track', stem: 'toggle-track' },
   { sel: '.toggle.on .track', stem: 'toggle-on-track', radius: 'var(--toggle-track-radius, 0px)' },
 

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/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,
 ];

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

@@ -0,0 +1,107 @@
+/**
+ * Washes slice — a wash is a translucent layer of color, stored as
+ * `{alias, opacity}` and emitted as
+ * `color-mix(in srgb, var(<alias>) <pct>%, transparent)`, so it follows its
+ * aliased source token (a brand-color shift propagates without re-editing
+ * every stop).
+ *
+ * Two families, opposite jobs. A **scrim** dims what sits behind it, which is
+ * what a modal needs. A **tint** shades the surface it sits on, which is what
+ * a hover needs. They are not interchangeable: scrims alias a near-black
+ * surface, tints alias the text color, so a tint lightens a dark theme and
+ * darkens a light one without picking a direction.
+ *
+ * Defaults diverge from tokens.css by design: the editor starts from a
+ * neutral alias and tokens.css continues to win until first edit.
+ */
+import type { EditorState, WashToken } from '../../store/editorTypes';
+
+export function makeDefaultScrimTokens(): WashToken[] {
+  return [
+    { variable: '--scrim-low',  label: 'Low',  alias: '--surface-neutral-lowest', opacity: 0.38 },
+    { variable: '--scrim',      label: 'Base', alias: '--surface-neutral-lowest', opacity: 0.51 },
+    { variable: '--scrim-high', label: 'High', alias: '--surface-neutral-lowest', opacity: 0.64 },
+  ];
+}
+
+export function makeDefaultTintTokens(): WashToken[] {
+  return [
+    { variable: '--tint-low',  label: 'Low',  alias: '--text-primary', opacity: 0.05 },
+    { variable: '--tint',      label: 'Base', alias: '--text-primary', opacity: 0.1  },
+    { variable: '--tint-high', label: 'High', alias: '--text-primary', opacity: 0.15 },
+  ];
+}
+
+export function makeDefaultWashesState(): EditorState['washes'] {
+  return {
+    scrims: makeDefaultScrimTokens(),
+    tints: makeDefaultTintTokens(),
+  };
+}
+
+export const WASH_VAR_NAMES = [
+  '--scrim-low', '--scrim', '--scrim-high',
+  '--tint-low', '--tint', '--tint-high',
+] as const;
+
+export function washTokenToCss(t: WashToken): string {
+  const pct = Math.round(t.opacity * 100);
+  if (pct >= 100) return `var(${t.alias})`;
+  return `color-mix(in srgb, var(${t.alias}) ${pct}%, transparent)`;
+}
+
+const COLOR_MIX_RE = /^color-mix\(in srgb,\s*var\((--[a-z0-9-]+)\)\s+(\d+)%,\s*transparent\)$/i;
+const PLAIN_VAR_RE = /^var\((--[a-z0-9-]+)\)$/i;
+
+export function parseWashCss(raw: string): { alias: string; opacity: number } | null {
+  const s = raw.trim();
+  const mix = s.match(COLOR_MIX_RE);
+  if (mix) {
+    const pct = parseInt(mix[2], 10);
+    if (!Number.isFinite(pct)) return null;
+    return { alias: mix[1], opacity: Math.max(0, Math.min(100, pct)) / 100 };
+  }
+  const plain = s.match(PLAIN_VAR_RE);
+  if (plain) return { alias: plain[1], opacity: 1 };
+  return null;
+}
+
+export function washesToVars(w: EditorState['washes']): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const t of w.scrims) out[t.variable] = washTokenToCss(t);
+  for (const t of w.tints) out[t.variable] = washTokenToCss(t);
+  return out;
+}
+
+export function applyWashVarsToState(washes: EditorState['washes'], vars: Record<string, string>): void {
+  const applyTo = (list: WashToken[]) => {
+    for (const t of list) {
+      const raw = vars[t.variable];
+      if (!raw) continue;
+      const parsed = parseWashCss(raw);
+      if (!parsed) continue;
+      t.alias = parsed.alias;
+      t.opacity = parsed.opacity;
+    }
+  };
+  applyTo(washes.scrims);
+  applyTo(washes.tints);
+}
+
+/**
+ * Loader: route wash entries from a freshly-loaded theme's vars bag into
+ * `next.washes` and remove them from the bag — but only when the value parses
+ * as the new format (color-mix / plain var). Legacy rgba values pass through to
+ * the cssVars bag so the DOM still paints them; the user's next edit in the
+ * picker promotes them to the typed slice.
+ */
+export function loadWashesFromVars(
+  next: EditorState,
+  rawVars: Record<string, string>,
+): void {
+  applyWashVarsToState(next.washes, rawVars);
+  for (const name of WASH_VAR_NAMES) {
+    const raw = rawVars[name];
+    if (raw && parseWashCss(raw) !== null) delete rawVars[name];
+  }
+}

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

@@ -57,10 +57,12 @@ Numeric scales with a slider per step.
 
 Change a step and every element using it repaints.
 
-## Overlays and gradients
+## Washes and gradients
 
-- **Overlays** are translucent tints layered over surfaces, like the subtle
-  tint a card gets on hover. Set a colour and opacity per state.
+- **Scrims** are translucent layers that dim what sits behind them, like the
+  one a dialog draws over the page. Set a colour and opacity per stop.
+- **Tints** are the opposite operation: they shade the surface they sit on
+  rather than dimming what is behind it, which is what a hover needs.
 - **Gradients** are reusable gradient tokens with a stop list and direction, for
   hero panels and accent backgrounds.