@motion-proto/live-tokens 0.9.0 → 0.11.0

package/src/editor/core/themes/migrations/2026-05-24-progressbar-collapse-variants.ts

@@ -0,0 +1,41 @@
+import type { Migration } from './index';
+
+/**
+ * Component-config migration (2026-05-24, progressbar only): ProgressBar
+ * collapsed from a per-variant token namespace (primary/success/warning/
+ * danger/info) to a single token set. Fill color is now a runtime `fill`
+ * prop on the consumer side, not a variant axis.
+ *
+ * Strategy: keep the `primary` namespace's values as the canonical defaults
+ * (rename `--progressbar-primary-X` → `--progressbar-X`); drop the four
+ * remaining variant namespaces entirely. Consumers that previously selected
+ * a non-primary variant lose their variant-specific surface/border/fill
+ * customizations and fall back to the merged single set.
+ */
+const PRIMARY_PREFIX = '--progressbar-primary-';
+const NEW_PREFIX = '--progressbar-';
+const DROP_PREFIXES = [
+  '--progressbar-success-',
+  '--progressbar-warning-',
+  '--progressbar-danger-',
+  '--progressbar-info-',
+];
+
+export const componentMigration_2026_05_24_progressbarCollapseVariants: Migration = {
+  id: '2026-05-24-progressbar-collapse-variants',
+  fromVersion: 13,
+  toVersion: 14,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    if (meta.component !== 'progressbar') return { ...rawVars };
+    const out: Record<string, string> = {};
+    for (const [oldKey, value] of Object.entries(rawVars)) {
+      if (DROP_PREFIXES.some((p) => oldKey.startsWith(p))) continue;
+      const key = oldKey.startsWith(PRIMARY_PREFIX)
+        ? NEW_PREFIX + oldKey.slice(PRIMARY_PREFIX.length)
+        : oldKey;
+      if (!(key in out)) out[key] = value;
+    }
+    return out;
+  },
+};

package/src/editor/core/themes/migrations/2026-05-24-promote-state-shared-tokens.ts

@@ -0,0 +1,59 @@
+import type { Migration } from './index';
+
+/**
+ * Component-config migration (2026-05-24, button + segmentedcontrol):
+ *
+ * Promotes shape/icon-size properties that don't actually vary per state into
+ * their own "base" part. The editor's per-state shape rows were dead UI — the
+ * runtime treated them as separate tokens that were always linked anyway. The
+ * runtime CSS now reads the default-state token in hover/disabled rules, so
+ * the per-state tokens are dropped entirely.
+ *
+ * Saved per-state overrides are dropped (rare case; users re-customize once).
+ * The default-state value remains the authoritative one.
+ *
+ *   button         drops --button-{v}-{hover|disabled}-{padding|radius|border-width}
+ *                  for v in primary/secondary/outline/success/danger/warning.
+ *
+ *   segmentedcontrol drops --segmentedcontrol-{selected|option-hover|disabled}-icon-size.
+ */
+
+const BUTTON_VARIANTS = ['primary', 'secondary', 'outline', 'success', 'danger', 'warning'] as const;
+const BUTTON_STATES = ['hover', 'disabled'] as const;
+const BUTTON_PROPS = ['padding', 'radius', 'border-width'] as const;
+
+const buttonDeadKeys = new Set<string>(
+  BUTTON_VARIANTS.flatMap((v) =>
+    BUTTON_STATES.flatMap((s) =>
+      BUTTON_PROPS.map((p) => `--button-${v}-${s}-${p}`),
+    ),
+  ),
+);
+
+const segmentedcontrolDeadKeys = new Set<string>([
+  '--segmentedcontrol-selected-icon-size',
+  '--segmentedcontrol-option-hover-icon-size',
+  '--segmentedcontrol-disabled-icon-size',
+]);
+
+export const componentMigration_2026_05_24_promoteStateSharedTokens: Migration = {
+  id: '2026-05-24-promote-state-shared-tokens',
+  fromVersion: 12,
+  toVersion: 13,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    const dead =
+      meta.component === 'button'
+        ? buttonDeadKeys
+        : meta.component === 'segmentedcontrol'
+          ? segmentedcontrolDeadKeys
+          : null;
+    if (!dead) return { ...rawVars };
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      if (dead.has(key)) continue;
+      out[key] = value;
+    }
+    return out;
+  },
+};

package/src/editor/core/themes/migrations/2026-05-24-segmentedcontrol-divider-inset.ts

@@ -0,0 +1,29 @@
+import type { Migration } from './index';
+
+/**
+ * Component-config migration (2026-05-24, segmentedcontrol only):
+ * `--segmentedcontrol-divider-height` was retired in favor of
+ * `--segmentedcontrol-divider-inset`. The old token set a percentage / pixel
+ * height on a centered flex item; with `Full` (100%) it collapsed to zero in
+ * auto-sized inline-flex parents. The new token is `margin-block` trimmed
+ * from a stretched divider, so Full = 0 inset = bar-height divider.
+ *
+ * Value semantic flipped (larger old value meant taller divider; larger new
+ * value means shorter divider), so the saved customization is dropped rather
+ * than copied across. Users fall back to the new default and re-pick once.
+ */
+export const componentMigration_2026_05_24_segmentedcontrolDividerInset: Migration = {
+  id: '2026-05-24-segmentedcontrol-divider-inset',
+  fromVersion: 11,
+  toVersion: 12,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    if (meta.component !== 'segmentedcontrol') return { ...rawVars };
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      if (key === '--segmentedcontrol-divider-height') continue;
+      out[key] = value;
+    }
+    return out;
+  },
+};

package/src/editor/core/themes/migrations/2026-05-25-cornerbadge-flatten-variants.ts

@@ -0,0 +1,46 @@
+import type { Migration } from './index';
+
+/**
+ * 2026-05-25: drop the per-variant token axis from cornerbadge.
+ *
+ * CornerBadge's "variants" carried only shape + spacing + type aliases — never
+ * colors (those come from the composed Badge). With every variant's defaults
+ * identical, the axis was 10× duplication that the editor had to tile across
+ * a variant strip for no semantic gain. Collapsing to a single flat token set
+ * removes the strip and the duplication.
+ *
+ * For each `--corner-badge-{variant}-{prop}`, fold into `--corner-badge-{prop}`.
+ * First-occurrence wins on conflict — defaults were uniform so this is a no-op
+ * in the typical case, and any tuned divergence is rare enough that picking
+ * one is better than silently averaging.
+ */
+const VARIANTS = ['primary', 'accent', 'neutral', 'alternate', 'canvas', 'special', 'success', 'warning', 'danger', 'info'] as const;
+const RE = new RegExp(`^--corner-badge-(${VARIANTS.join('|')})-(.+)$`);
+
+function flattenVariants(rawVars: Record<string, string>, meta: { component?: string }): Record<string, string> {
+  if (meta.component !== 'cornerbadge') return rawVars;
+  const out: Record<string, string> = {};
+  const collected: Map<string, string> = new Map();
+  for (const [key, value] of Object.entries(rawVars)) {
+    const m = key.match(RE);
+    if (m) {
+      const prop = m[2];
+      if (!collected.has(prop)) collected.set(prop, value);
+      continue;
+    }
+    out[key] = value;
+  }
+  for (const [prop, value] of collected) {
+    const flatKey = `--corner-badge-${prop}`;
+    if (!(flatKey in out)) out[flatKey] = value;
+  }
+  return out;
+}
+
+export const componentMigration_2026_05_25_cornerbadgeFlattenVariants: Migration = {
+  id: '2026-05-25-cornerbadge-flatten-variants',
+  fromVersion: 15,
+  toVersion: 16,
+  appliesTo: 'component-config',
+  apply: flattenVariants,
+};

package/src/editor/core/themes/migrations/2026-05-26-drop-overlay-extra-stops.ts

@@ -0,0 +1,46 @@
+import type { Migration } from './index';
+
+/**
+ * Overlay scale trim (2026-05-26): `--overlay-lowest`, `--overlay-lower`,
+ * `--overlay-higher`, and `--overlay-highest` were retired. The kept stops
+ * are `--overlay-low`, `--overlay`, and `--overlay-high`. Theme files
+ * stripped of the dropped keys; component configs whose aliases referenced
+ * a dropped stop rebind to the nearest survivor.
+ */
+const DROPPED_TO_KEPT: Record<string, string> = {
+  '--overlay-lowest': '--overlay-low',
+  '--overlay-lower': '--overlay-low',
+  '--overlay-higher': '--overlay-high',
+  '--overlay-highest': '--overlay-high',
+};
+
+export const themeMigration_2026_05_26_dropOverlayExtraStops: Migration = {
+  id: '2026-05-26-drop-overlay-extra-stops-theme',
+  fromVersion: 2,
+  toVersion: 3,
+  appliesTo: 'theme',
+  apply(rawVars) {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      if (key in DROPPED_TO_KEPT) continue;
+      out[key] = value;
+    }
+    return out;
+  },
+};
+
+export const componentMigration_2026_05_26_dropOverlayExtraStops: Migration = {
+  id: '2026-05-26-drop-overlay-extra-stops-component',
+  fromVersion: 16,
+  toVersion: 17,
+  appliesTo: 'component-config',
+  apply(rawVars) {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      // Alias values are bare token names like "--overlay-higher" — rebind
+      // those to the nearest kept stop. Literal CSS values are left alone.
+      out[key] = DROPPED_TO_KEPT[value] ?? value;
+    }
+    return out;
+  },
+};

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

@@ -45,6 +45,15 @@ import { componentMigration_2026_05_19_sectiondividerRichGradient } from './2026
 import { componentMigration_2026_05_20_sectiondividerSlimVariants } from './2026-05-20-sectiondivider-slim-variants';
 import { componentMigration_2026_05_21_sectiondividerSpacingToPadding } from './2026-05-21-sectiondivider-spacing-to-padding';
 import { componentMigration_2026_05_22_sectiondividerIntrinsicsToCss } from './2026-05-22-sectiondivider-intrinsics-to-css';
+import { componentMigration_2026_05_24_segmentedcontrolDividerInset } from './2026-05-24-segmentedcontrol-divider-inset';
+import { componentMigration_2026_05_24_promoteStateSharedTokens } from './2026-05-24-promote-state-shared-tokens';
+import { componentMigration_2026_05_24_progressbarCollapseVariants } from './2026-05-24-progressbar-collapse-variants';
+import { componentMigration_2026_05_24_collapsiblesectionDropActiveState } from './2026-05-24-collapsiblesection-drop-active-state';
+import { componentMigration_2026_05_25_cornerbadgeFlattenVariants } from './2026-05-25-cornerbadge-flatten-variants';
+import {
+  themeMigration_2026_05_26_dropOverlayExtraStops,
+  componentMigration_2026_05_26_dropOverlayExtraStops,
+} from './2026-05-26-drop-overlay-extra-stops';
 
 /**
  * Registered migrations. Order in this array does not matter — the runner
@@ -64,6 +73,13 @@ export const MIGRATIONS: Migration[] = [
   componentMigration_2026_05_20_sectiondividerSlimVariants,
   componentMigration_2026_05_21_sectiondividerSpacingToPadding,
   componentMigration_2026_05_22_sectiondividerIntrinsicsToCss,
+  componentMigration_2026_05_24_segmentedcontrolDividerInset,
+  componentMigration_2026_05_24_promoteStateSharedTokens,
+  componentMigration_2026_05_24_progressbarCollapseVariants,
+  componentMigration_2026_05_24_collapsiblesectionDropActiveState,
+  componentMigration_2026_05_25_cornerbadgeFlattenVariants,
+  themeMigration_2026_05_26_dropOverlayExtraStops,
+  componentMigration_2026_05_26_dropOverlayExtraStops,
 ];
 
 function countFor(kind: 'theme' | 'component-config'): number {

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

@@ -1,28 +1,28 @@
 /**
- * Overlays slice — overlay + hover RGBA tokens. Defaults are editor-defined
- * (mirror what `VariablesTab` historically initialised into local let state)
- * and diverge from tokens.css by design: the editor starts with a neutral
- * palette and tokens.css continues to win until first edit.
+ * Overlays slice — overlay + hover stops, each stored as `{alias, opacity}`.
+ * Emits as `color-mix(in srgb, var(<alias>) <pct>%, transparent)` so the
+ * overlay tints automatically follow the aliased source token (a brand-color
+ * shift propagates without re-editing every overlay).
+ *
+ * Defaults diverge from tokens.css by design: the editor starts from a
+ * neutral alias and tokens.css continues to win until first edit (see
+ * `overlaysEqualsDefault`).
  */
 import type { EditorState, OverlayToken } from '../../store/editorTypes';
 
 export function makeDefaultOverlayTokens(): OverlayToken[] {
   return [
-    { variable: '--overlay-lowest', label: 'Lowest', r: 0, g: 0, b: 0, opacity: 0.05 },
-    { variable: '--overlay-lower',  label: 'Lower',  r: 0, g: 0, b: 0, opacity: 0.1  },
-    { variable: '--overlay-low',    label: 'Low',    r: 0, g: 0, b: 0, opacity: 0.2  },
-    { variable: '--overlay',        label: 'Base',   r: 0, g: 0, b: 0, opacity: 0.3  },
-    { variable: '--overlay-high',   label: 'High',   r: 0, g: 0, b: 0, opacity: 0.5  },
-    { variable: '--overlay-higher', label: 'Higher', r: 0, g: 0, b: 0, opacity: 0.7  },
-    { variable: '--overlay-highest',label: 'Highest',r: 0, g: 0, b: 0, opacity: 0.95 },
+    { variable: '--overlay-low',  label: 'Low',  alias: '--surface-neutral-lowest', opacity: 0.38 },
+    { variable: '--overlay',      label: 'Base', alias: '--surface-neutral-lowest', opacity: 0.51 },
+    { variable: '--overlay-high', label: 'High', alias: '--surface-neutral-lowest', opacity: 0.64 },
   ];
 }
 
 export function makeDefaultHoverTokens(): OverlayToken[] {
   return [
-    { variable: '--hover-low',  label: 'Low',  r: 255, g: 255, b: 255, opacity: 0.05 },
-    { variable: '--hover',      label: 'Base', r: 255, g: 255, b: 255, opacity: 0.1  },
-    { variable: '--hover-high', label: 'High', r: 255, g: 255, b: 255, opacity: 0.15 },
+    { variable: '--hover-low',  label: 'Low',  alias: '--text-primary', opacity: 0.05 },
+    { variable: '--hover',      label: 'Base', alias: '--text-primary', opacity: 0.1  },
+    { variable: '--hover-high', label: 'High', alias: '--text-primary', opacity: 0.15 },
   ];
 }
 
@@ -30,88 +30,52 @@ export function makeDefaultOverlaysState(): EditorState['overlays'] {
   return {
     tokens: makeDefaultOverlayTokens(),
     hoverTokens: makeDefaultHoverTokens(),
-    globals: {
-      overlay: { hue: 0, saturation: 0, lightness: 0, opacityMin: 0.05, opacityMax: 0.95 },
-      hover:   { hue: 0, saturation: 0, lightness: 100, opacityMin: 0.05, opacityMax: 0.15 },
-    },
   };
 }
 
 export const OVERLAY_VAR_NAMES = [
-  '--overlay-lowest', '--overlay-lower', '--overlay-low', '--overlay',
-  '--overlay-high', '--overlay-higher', '--overlay-highest',
+  '--overlay-low', '--overlay', '--overlay-high',
   '--hover-low', '--hover', '--hover-high',
 ] as const;
 
-// Accepts rgb(), rgba(), and #rrggbb[aa] — themes saved by the editor
-// always use rgba(), but loading hand-written files shouldn't break.
-export const RGBA_RE = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)/i;
-export const HEX_RE = /^#([0-9a-f]{6})([0-9a-f]{2})?$/i;
+export function overlayTokenToCss(t: OverlayToken): 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 parseRgba(raw: string): { r: number; g: number; b: number; opacity: number } | null {
+export function parseOverlayCss(raw: string): { alias: string; opacity: number } | null {
   const s = raw.trim();
-  const m = s.match(RGBA_RE);
-  if (m) {
-    const r = parseInt(m[1], 10);
-    const g = parseInt(m[2], 10);
-    const b = parseInt(m[3], 10);
-    const a = m[4] !== undefined ? parseFloat(m[4]) : 1;
-    if (![r, g, b].every((n) => Number.isFinite(n) && n >= 0 && n <= 255)) return null;
-    return { r, g, b, opacity: Number.isFinite(a) ? a : 1 };
-  }
-  const h = s.match(HEX_RE);
-  if (h) {
-    const hex = h[1];
-    const alpha = h[2] !== undefined ? parseInt(h[2], 16) / 255 : 1;
-    return {
-      r: parseInt(hex.slice(0, 2), 16),
-      g: parseInt(hex.slice(2, 4), 16),
-      b: parseInt(hex.slice(4, 6), 16),
-      opacity: Math.round(alpha * 100) / 100,
-    };
+  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 overlayTokenToRgba(t: OverlayToken): string {
-  return `rgba(${t.r}, ${t.g}, ${t.b}, ${t.opacity})`;
-}
-
 export function overlaysToVars(o: EditorState['overlays']): Record<string, string> {
   const out: Record<string, string> = {};
-  for (const t of o.tokens) out[t.variable] = overlayTokenToRgba(t);
-  for (const t of o.hoverTokens) out[t.variable] = overlayTokenToRgba(t);
+  for (const t of o.tokens) out[t.variable] = overlayTokenToCss(t);
+  for (const t of o.hoverTokens) out[t.variable] = overlayTokenToCss(t);
   return out;
 }
 
-function tokensEqualDefault(tokens: OverlayToken[], defaults: OverlayToken[]): boolean {
-  if (tokens.length !== defaults.length) return false;
-  for (let i = 0; i < tokens.length; i++) {
-    const a = tokens[i]; const b = defaults[i];
-    if (a.variable !== b.variable || a.r !== b.r || a.g !== b.g || a.b !== b.b || a.opacity !== b.opacity) return false;
-  }
-  return true;
-}
-
-/**
- * Same pattern as columns: only emit overlay CSS vars once state diverges
- * from the editor defaults. tokens.css owns the rgba values until the
- * user touches any overlay control (or loads a theme that already
- * contains overrides).
- */
-export function overlaysEqualsDefault(o: EditorState['overlays']): boolean {
-  return tokensEqualDefault(o.tokens, makeDefaultOverlayTokens())
-    && tokensEqualDefault(o.hoverTokens, makeDefaultHoverTokens());
-}
-
 export function applyOverlayVarsToState(overlays: EditorState['overlays'], vars: Record<string, string>): void {
   const applyTo = (list: OverlayToken[]) => {
     for (const t of list) {
       const raw = vars[t.variable];
       if (!raw) continue;
-      const parsed = parseRgba(raw);
+      const parsed = parseOverlayCss(raw);
       if (!parsed) continue;
-      t.r = parsed.r; t.g = parsed.g; t.b = parsed.b; t.opacity = parsed.opacity;
+      t.alias = parsed.alias;
+      t.opacity = parsed.opacity;
     }
   };
   applyTo(overlays.tokens);
@@ -120,13 +84,18 @@ export function applyOverlayVarsToState(overlays: EditorState['overlays'], vars:
 
 /**
  * Loader: route overlay/hover entries from a freshly-loaded theme's vars
- * bag into `next.overlays` and remove them from the bag. Mutates `next`
- * and `rawVars` in place.
+ * bag into `next.overlays` 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 loadOverlaysFromVars(
   next: EditorState,
   rawVars: Record<string, string>,
 ): void {
   applyOverlayVarsToState(next.overlays, rawVars);
-  for (const name of OVERLAY_VAR_NAMES) delete rawVars[name];
+  for (const name of OVERLAY_VAR_NAMES) {
+    const raw = rawVars[name];
+    if (raw && parseOverlayCss(raw) !== null) delete rawVars[name];
+  }
 }

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

@@ -5,6 +5,7 @@ import { applyFontSources, applyFontStacks } from '../fonts/fontLoader';
 import { loadFromFile, seedComponentsFromApi } from '../store/editorStore';
 import { getActiveComponentConfig } from '../components/componentConfigService';
 import { safeFetch } from '../storage/storage';
+import { API_BASE } from '../storage/apiBase';
 
 interface ComponentSummaryDto {
   name: string;
@@ -34,7 +35,7 @@ interface ListComponentsDto {
  * `safeFetch` (instead of empty try/catch) to make the silence intentional.
  */
 export async function initializeTheme(): Promise<void> {
-  const theme = await safeFetch<Theme>('/api/themes/active');
+  const theme = await safeFetch<Theme>(`${API_BASE}/themes/active`);
   if (theme) {
     migrateThemeFonts(theme);
     loadFromFile(theme);
@@ -48,7 +49,7 @@ export async function initializeTheme(): Promise<void> {
     activeFileName.set(fileName);
   }
 
-  const list = await safeFetch<ListComponentsDto>('/api/component-configs');
+  const list = await safeFetch<ListComponentsDto>(`${API_BASE}/component-configs`);
   if (list && Array.isArray(list.components)) {
     const configs: Record<
       string,

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

@@ -5,6 +5,7 @@ import {
   versionedFileResource,
   sanitizeFileName as sanitizeFileNameImpl,
 } from '../storage/files/versionedFileResourceClient';
+import { API_BASE } from '../storage/apiBase';
 import { loadFromFile as loadEditorState, toTheme, markSaved } from '../store/editorStore';
 import { activeFileName } from '../store/editorConfigStore';
 import { applyFontSources, applyFontStacks } from '../fonts/fontLoader';
@@ -12,7 +13,7 @@ import { migrateThemeFonts } from '../fonts/fontMigration';
 
 // ── API helpers ──────────────────────────────────────────────
 //
-// All theme CRUD goes through `versionedFileResource('/api/themes')` —
+// All theme CRUD goes through `versionedFileResource(`${API_BASE}/themes`)` —
 // shared with `componentConfigService`'s per-component clients. Theme-specific
 // response shapes (ThemeMeta list payload, ProductionInfo) are layered on top
 // via the generic type parameters.
@@ -25,7 +26,7 @@ export interface ProductionInfo {
 }
 
 const themeResource = versionedFileResource<Theme, ThemeMeta, ProductionInfo>({
-  baseUrl: '/api/themes',
+  baseUrl: `${API_BASE}/themes`,
 });
 
 export async function listThemes(): Promise<ThemeMeta[]> {

package/src/editor/ui/SurfacesTab.svelte

@@ -31,13 +31,9 @@
     {
       title: 'Overlays',
       swatches: [
-        { name: 'Lowest', variable: '--overlay-lowest', description: 'Barely visible tint' },
-        { name: 'Lower', variable: '--overlay-lower', description: 'Very subtle overlay' },
-        { name: 'Low', variable: '--overlay-low', description: 'Light overlay' },
-        { name: 'Overlay', variable: '--overlay', description: 'Standard overlay' },
-        { name: 'High', variable: '--overlay-high', description: 'Heavy overlay' },
-        { name: 'Higher', variable: '--overlay-higher', description: 'Modal backdrop' },
-        { name: 'Highest', variable: '--overlay-highest', description: 'Nearly opaque' }
+        { name: 'Low', variable: '--overlay-low', description: 'Light backdrop / pressed wash' },
+        { name: 'Overlay', variable: '--overlay', description: 'Standard backdrop' },
+        { name: 'High', variable: '--overlay-high', description: 'Strong backdrop' }
       ]
     },
     {