@motion-proto/live-tokens 0.68.1 → 0.69.0

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

@@ -0,0 +1,186 @@
+<script module lang="ts">
+  import { buildTypeGroupColorTokens } from './scaffolding/buildTypeGroupTokens';
+  import type { Token, TypeGroupConfig } from './scaffolding/types';
+  import { sliderVariants } from '../../system/components/Slider.svelte';
+
+  export const component = 'slider';
+  const variants = sliderVariants;
+  type Variant = typeof variants[number];
+
+  // Geometry and colour are identical across the two variants by default, so
+  // every row is linkable: an edit to the single slider's track moves the range
+  // slider's track until a user unlinks them on purpose.
+  function variantDefaultTokens(v: Variant): Token[] {
+    return [
+      { label: 'surface', element: 'track', canBeLinked: true, groupKey: 'track-surface', variable: `--slider-${v}-track-surface` },
+      { label: 'border', element: 'track', canBeLinked: true, groupKey: 'track-border', variable: `--slider-${v}-track-border` },
+      { label: 'border width', element: 'track', canBeLinked: true, groupKey: 'track-border-width', variable: `--slider-${v}-track-border-width` },
+      { label: 'height', element: 'track', canBeLinked: true, groupKey: 'track-height', variable: `--slider-${v}-track-height` },
+      { label: 'corner radius', element: 'track', canBeLinked: true, groupKey: 'track-radius', variable: `--slider-${v}-track-radius` },
+      { label: 'color', element: 'fill', canBeLinked: true, groupKey: 'fill', variable: `--slider-${v}-fill` },
+      { label: 'surface', element: 'thumb', canBeLinked: true, groupKey: 'thumb-surface', variable: `--slider-${v}-thumb-surface` },
+      { label: 'border', element: 'thumb', canBeLinked: true, groupKey: 'thumb-border', variable: `--slider-${v}-thumb-border` },
+      { label: 'border width', element: 'thumb', canBeLinked: true, groupKey: 'thumb-border-width', variable: `--slider-${v}-thumb-border-width` },
+      { label: 'size', element: 'thumb', canBeLinked: true, groupKey: 'thumb-size', variable: `--slider-${v}-thumb-size` },
+      { label: 'corner radius', element: 'thumb', canBeLinked: true, groupKey: 'thumb-radius', variable: `--slider-${v}-thumb-radius` },
+      { label: 'shadow', element: 'thumb', canBeLinked: true, groupKey: 'thumb-shadow', variable: `--slider-${v}-thumb-shadow` },
+    ];
+  }
+
+  function variantHoverTokens(v: Variant): Token[] {
+    return [
+      { label: 'thumb surface', canBeLinked: true, groupKey: 'hover-thumb-surface', variable: `--slider-${v}-hover-thumb-surface` },
+      { label: 'thumb border', canBeLinked: true, groupKey: 'hover-thumb-border', variable: `--slider-${v}-hover-thumb-border` },
+    ];
+  }
+
+  function variantDisabledTokens(v: Variant): Token[] {
+    return [
+      { label: 'track surface', canBeLinked: true, groupKey: 'disabled-track-surface', variable: `--slider-${v}-disabled-track-surface` },
+      { label: 'fill color', canBeLinked: true, groupKey: 'disabled-fill', variable: `--slider-${v}-disabled-fill` },
+      { label: 'thumb surface', canBeLinked: true, groupKey: 'disabled-thumb-surface', variable: `--slider-${v}-disabled-thumb-surface` },
+      { label: 'thumb border', canBeLinked: true, groupKey: 'disabled-thumb-border', variable: `--slider-${v}-disabled-thumb-border` },
+    ];
+  }
+
+  // The label and its gap are shared by both variants, so their rows render
+  // once, under the single variant beside the type groups.
+  const labelGapToken: Token = { label: 'label gap', element: 'label', groupKey: 'label-gap', variable: '--slider-label-gap' };
+
+  function variantStates(v: Variant): Record<string, Token[]> {
+    return {
+      default: v === 'single' ? [...variantDefaultTokens(v), labelGapToken] : variantDefaultTokens(v),
+      hover: variantHoverTokens(v),
+      disabled: variantDisabledTokens(v),
+    };
+  }
+
+  // The label and value readout are shared by both variants, so they live in
+  // one type group outside the per-variant states.
+  const typeGroups: Record<string, TypeGroupConfig[]> = {
+    default: [
+      {
+        legend: '',
+        element: 'label',
+        colorVariable: '--slider-label',
+        familyVariable: '--slider-label-font-family',
+        sizeVariable: '--slider-label-font-size',
+        weightVariable: '--slider-label-font-weight',
+        lineHeightVariable: '--slider-label-line-height',
+      },
+      {
+        legend: '',
+        element: 'value',
+        colorVariable: '--slider-value',
+        familyVariable: '--slider-value-font-family',
+        sizeVariable: '--slider-value-font-size',
+        weightVariable: '--slider-value-font-weight',
+        lineHeightVariable: '--slider-value-line-height',
+      },
+    ],
+  };
+
+  const typeGroupTokens: Token[] = [
+    { label: 'font family', canBeLinked: true, groupKey: 'label-font-family', variable: '--slider-label-font-family' },
+    { label: 'font size', canBeLinked: true, groupKey: 'label-font-size', variable: '--slider-label-font-size' },
+    { label: 'font weight', canBeLinked: true, groupKey: 'label-font-weight', variable: '--slider-label-font-weight' },
+    { label: 'line height', canBeLinked: true, groupKey: 'label-line-height', variable: '--slider-label-line-height' },
+    { label: 'font family', canBeLinked: true, groupKey: 'value-font-family', variable: '--slider-value-font-family' },
+    { label: 'font size', canBeLinked: true, groupKey: 'value-font-size', variable: '--slider-value-font-size' },
+    { label: 'font weight', canBeLinked: true, groupKey: 'value-font-weight', variable: '--slider-value-font-weight' },
+    { label: 'line height', canBeLinked: true, groupKey: 'value-line-height', variable: '--slider-value-line-height' },
+  ];
+
+  export const allTokens: Token[] = [
+    ...variants.flatMap((v) => Object.values(variantStates(v)).flat()),
+    ...buildTypeGroupColorTokens(typeGroups, { component }),
+    ...typeGroupTokens,
+  ];
+
+  const linkableContexts = new Map<string, string>([
+    ...variants.flatMap((v) =>
+      Object.entries(variantStates(v)).flatMap(([state, list]) =>
+        list.filter((t) => t.canBeLinked).map((t) => [t.variable, `${v} ${state}`] as [string, string]),
+      ),
+    ),
+    ...typeGroupTokens
+      .filter((t) => t.canBeLinked)
+      .map((t) => [t.variable, t.variable.includes('-label-') ? 'label' : 'value'] as [string, string]),
+  ]);
+
+  const variantOptions = variants.map((v) => ({ value: v, label: v.charAt(0).toUpperCase() + v.slice(1) }));
+</script>
+
+<script lang="ts">
+  import Slider from '../../system/components/Slider.svelte';
+  import VariantGroup from './scaffolding/VariantGroup.svelte';
+  import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
+  import { editorState } from '../core/store/editorStore';
+  import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
+  import { buildSiblings } from './scaffolding/siblings';
+
+  let linked = $derived(computeLinkedBlock(component, linkableContexts, allTokens, $editorState));
+  let visibleVariantStates = $derived((v: Variant) => Object.fromEntries(
+    Object.entries(variantStates(v)).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+  ) as Record<string, Token[]>);
+
+  let value = $state(40);
+  let low = $state(20);
+  let high = $state(70);
+
+  function previewProps(activeState: string) {
+    return {
+      disabled: activeState === 'disabled',
+      forceClass: activeState === 'hover' ? 'force-hover' : '',
+    };
+  }
+</script>
+
+<ComponentEditorBase
+  {component}
+  title="Slider"
+  description="A number chosen by position on a track. Single moves one thumb to a value; range moves two thumbs to a low and a high bound."
+  tokens={allTokens}
+  {linked}
+  variants={variantOptions}
+>
+  {#each variants as v}
+    <VariantGroup
+      name={v}
+      title={v.charAt(0).toUpperCase() + v.slice(1)}
+      states={visibleVariantStates(v)}
+      typeGroups={v === 'single' ? typeGroups : undefined}
+      {component}
+      siblings={buildSiblings(variants, v, variantStates)}
+    >
+      {#snippet children({ activeState })}
+        {@const p = previewProps(activeState)}
+        <div class="slider-demo-stack">
+          {#if v === 'range'}
+            <Slider
+              variant="range"
+              label="Price"
+              {low}
+              {high}
+              disabled={p.disabled}
+              class={p.forceClass}
+              onrangechange={(l, h) => { low = l; high = h; }}
+            />
+          {:else}
+            <Slider label="Volume" {value} disabled={p.disabled} class={p.forceClass} onchange={(n) => (value = n)} />
+          {/if}
+        </div>
+      {/snippet}
+    </VariantGroup>
+  {/each}
+</ComponentEditorBase>
+
+<style>
+  .slider-demo-stack {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-12);
+    width: 100%;
+    max-width: 32rem;
+  }
+</style>

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

@@ -1,6 +1,6 @@
 <script module lang="ts">
   import { buildTypeGroupColorTokens } from './scaffolding/buildTypeGroupTokens';
-  import type { Token, TypeGroupConfig } from './scaffolding/types';
+  import type { Token, TypeGroupConfig, IntrinsicSpec } from './scaffolding/types';
 
   export const component = 'tabbar';
 
@@ -81,14 +81,55 @@
     [`--tabbar-${s}-text-line-height`, `${s} tab`] as const,
   ]),
   ]);
+
+  // The hover tint is off unless a project turns it on: the gate holds a
+  // transparent layer, a no-op, until it holds the tint itself.
+  export const intrinsics: IntrinsicSpec[] = [
+    {
+      key: 'hover-tint',
+      variants: ['default'],
+      variable: () => '--tabbar-hover-tint-enabled',
+      values: ['var(--color-transparent)', 'var(--tabbar-hover-tint)'],
+      default: { default: 'var(--color-transparent)' },
+    },
+  ];
 </script>
 
 <script lang="ts">
   import TabBar from '../../system/components/TabBar.svelte';
   import VariantGroup from './scaffolding/VariantGroup.svelte';
   import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
-  import { editorState } from '../core/store/editorStore';
+  import { editorState, setComponentAlias, clearComponentAlias } from '../core/store/editorStore';
   import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
+  import Toggle from '../ui/Toggle.svelte';
+  import UIPaletteSelector from '../ui/UIPaletteSelector.svelte';
+
+  // One switch. Turning the tint on also stands each hover surface down to its
+  // own base, so hover is the tint alone rather than a swap wearing a wash.
+  // Written as aliases rather than gated in CSS: a component token's value is
+  // substituted at :root, so it can never name a per-variant private var.
+  // Off clears the overrides, returning each surface to its shipped default.
+  const HOVER_SWAPS: readonly (readonly [hover: string, base: string])[] = [
+    ['--tabbar-hover-surface', '--tabbar-default-surface'],
+  ];
+  const TINT_ON = 'var(--tabbar-hover-tint)';
+  const TINT_OFF = 'var(--color-transparent)';
+
+  let tintOn = $derived.by(() => {
+    const ref = $editorState.components.tabbar?.aliases['--tabbar-hover-tint-enabled'];
+    return (ref?.kind === 'literal' ? ref.value : TINT_OFF) === TINT_ON;
+  });
+
+  function setTintOn(checked: boolean) {
+    setComponentAlias('tabbar', '--tabbar-hover-tint-enabled', {
+      kind: 'literal',
+      value: checked ? TINT_ON : TINT_OFF,
+    });
+    for (const [hover, base] of HOVER_SWAPS) {
+      if (checked) setComponentAlias('tabbar', hover, { kind: 'token', name: base });
+      else clearComponentAlias('tabbar', hover);
+    }
+  }
 
   let selectedDemoTab = $state('overview');
   const demoTabs = [
@@ -101,7 +142,12 @@
   let linked = $derived(computeLinkedBlock(component, linkableContexts, allTokens, $editorState));
 
   let visibleStates = $derived(Object.fromEntries(
-    Object.entries(states).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+    Object.entries(states).map(([name, list]) => [
+      name,
+      withLinkedDisabled(list, linked.varSet).map((t) =>
+        tintOn && t.variable.endsWith('-hover-surface') ? { ...t, disabled: true } : t,
+      ),
+    ]),
   ) as Record<string, Token[]>);
 </script>
 
@@ -114,6 +160,20 @@
     {component}
     
   >
+    {#snippet extraPropertyRows(stateName)}
+      {#if stateName === 'hover tab'}
+        <div class="property-row" data-token-variables="--tabbar-hover-tint-enabled">
+          <span class="property-label">tint layer</span>
+          <Toggle checked={tintOn} onchange={setTintOn} />
+        </div>
+        {#if tintOn}
+          <div class="property-row">
+            <span class="property-label">tint color</span>
+            <UIPaletteSelector variable="--tabbar-hover-tint" {component} showNone={false} />
+          </div>
+        {/if}
+      {/if}
+    {/snippet}
     {#snippet children({ activeState })}
         {@const forceClass = activeState === 'hover tab' ? 'force-hover' : ''}
       <TabBar tabs={demoTabs} selectedTab={selectedDemoTab} class={forceClass} on:tabChange={(e) => (selectedDemoTab = e.detail)} />

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

@@ -19,6 +19,7 @@ import MenuSelectEditor, { allTokens as menuSelectTokens } from './MenuSelectEdi
 import NotificationEditor, { allTokens as notificationTokens } from './NotificationEditor.svelte';
 import PanelEditor, { allTokens as panelTokens } from './PanelEditor.svelte';
 import ProgressBarEditor, { allTokens as progressBarTokens } from './ProgressBarEditor.svelte';
+import SliderEditor, { allTokens as sliderTokens } from './SliderEditor.svelte';
 import RadioButtonEditor, { allTokens as radioButtonTokens } from './RadioButtonEditor.svelte';
 import SectionDividerEditor, { allTokens as sectionDividerTokens, intrinsics as sectionDividerIntrinsics } from './SectionDividerEditor.svelte';
 import SegmentedControlEditor, { allTokens as segmentedControlTokens } from './SegmentedControlEditor.svelte';
@@ -320,6 +321,15 @@ const builtInRegistry: Readonly<Record<BuiltInComponentId, RegistryEntry>> = Obj
     schema: progressBarTokens,
     origin: 'system',
   },
+  slider: {
+    id: 'slider',
+    label: 'Slider',
+    icon: 'fas fa-sliders',
+    sourceFile: 'src/system/components/Slider.svelte',
+    editorComponent: SliderEditor,
+    schema: sliderTokens,
+    origin: 'system',
+  },
 });
 
 /** Mutable map of consumer-registered components, populated by `registerComponent()`. */

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;
+  },
+};