@motion-proto/live-tokens 0.82.0 → 0.84.0

package/dist-plugin/setColors/index.cjs

@@ -2370,8 +2370,56 @@ var componentMigration_2026_09_13_sectiondividerSurface = {
   }
 };
 
-// src/editor/core/themes/migrations/2026-09-13-cornerbadge-prefix.ts
+// src/editor/core/themes/migrations/2026-09-20-imagelightbox-scrim.ts
 var RENAMES7 = {
+  "--imagelightbox-overlay-surface": "--imagelightbox-scrim-surface"
+};
+var componentMigration_2026_09_20_imagelightboxScrim = {
+  id: "2026-09-20-imagelightbox-scrim",
+  fromVersion: 35,
+  toVersion: 36,
+  appliesTo: "component-config",
+  apply(rawVars, meta) {
+    if (meta.component !== "imagelightbox") return { ...rawVars };
+    const out = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      out[RENAMES7[key] ?? key] = value;
+    }
+    return out;
+  }
+};
+
+// src/editor/core/themes/migrations/2026-09-20-scrim-color-and-opacity.ts
+var STOPS = {
+  "--scrim-low": "--scrim-opacity-low",
+  "--scrim": "--scrim-opacity",
+  "--scrim-high": "--scrim-opacity-high"
+};
+var SURFACE = /^--(imagelightbox|dialog)-scrim-surface$/;
+var componentMigration_2026_09_20_scrimColorAndOpacity = {
+  id: "2026-09-20-scrim-color-and-opacity",
+  fromVersion: 36,
+  toVersion: 37,
+  appliesTo: "component-config",
+  apply(rawVars) {
+    const out = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      const match = SURFACE.exec(key);
+      if (!match) {
+        out[key] = value;
+        continue;
+      }
+      const stem = `--${match[1]}-scrim`;
+      const stop = STOPS[value];
+      out[`${stem}-color`] = stop ? "--scrim-color" : value;
+      out[`${stem}-opacity`] = stop ?? "1";
+    }
+    return out;
+  }
+};
+
+// src/editor/core/themes/migrations/2026-09-13-cornerbadge-prefix.ts
+var RENAMES8 = {
   cornerbadge: {
     "--corner-badge-margin": "--cornerbadge-margin",
     "--corner-badge-outer-radius": "--cornerbadge-outer-radius",
@@ -2421,7 +2469,7 @@ var componentMigration_2026_09_13_cornerbadgePrefix = {
   toVersion: 32,
   appliesTo: "component-config",
   apply(rawVars, meta) {
-    const renames = meta.component ? RENAMES7[meta.component] : void 0;
+    const renames = meta.component ? RENAMES8[meta.component] : void 0;
     if (!renames) return { ...rawVars };
     const out = {};
     for (const [key, value] of Object.entries(rawVars)) {
@@ -2432,7 +2480,7 @@ var componentMigration_2026_09_13_cornerbadgePrefix = {
 };
 
 // src/editor/core/themes/migrations/2026-09-13-toggle-label.ts
-var RENAMES8 = {
+var RENAMES9 = {
   toggle: {
     "--toggle-label-text": "--toggle-label",
     "--toggle-disabled-label-text": "--toggle-disabled-label"
@@ -2444,7 +2492,7 @@ var componentMigration_2026_09_13_toggleLabel = {
   toVersion: 33,
   appliesTo: "component-config",
   apply(rawVars, meta) {
-    const renames = meta.component ? RENAMES8[meta.component] : void 0;
+    const renames = meta.component ? RENAMES9[meta.component] : void 0;
     if (!renames) return { ...rawVars };
     const out = {};
     for (const [key, value] of Object.entries(rawVars)) {
@@ -2455,7 +2503,7 @@ var componentMigration_2026_09_13_toggleLabel = {
 };
 
 // src/editor/core/themes/migrations/2026-09-13-collapsiblesection-open.ts
-var RENAMES9 = {
+var RENAMES10 = {
   collapsiblesection: {
     "--collapsiblesection-chromeless-expanded-padding": "--collapsiblesection-chromeless-open-padding",
     "--collapsiblesection-hairline-expanded-padding": "--collapsiblesection-hairline-open-padding",
@@ -2469,7 +2517,7 @@ var componentMigration_2026_09_13_collapsiblesectionOpen = {
   toVersion: 34,
   appliesTo: "component-config",
   apply(rawVars, meta) {
-    const renames = meta.component ? RENAMES9[meta.component] : void 0;
+    const renames = meta.component ? RENAMES10[meta.component] : void 0;
     if (!renames) return { ...rawVars };
     const out = {};
     for (const [key, value] of Object.entries(rawVars)) {
@@ -2496,7 +2544,7 @@ var BADGE_SUFFIXES = [
   "icon-size"
 ];
 var CORNERBADGE_SUFFIXES = ["surface", "border", "text"];
-var RENAMES10 = {
+var RENAMES11 = {
   badge: Object.fromEntries(
     BADGE_SUFFIXES.map((s) => [`--badge-primary-${s}`, `--badge-brand-${s}`])
   ),
@@ -2510,7 +2558,7 @@ var componentMigration_2026_09_13_badgeBrand = {
   toVersion: 35,
   appliesTo: "component-config",
   apply(rawVars, meta) {
-    const renames = meta.component ? RENAMES10[meta.component] : void 0;
+    const renames = meta.component ? RENAMES11[meta.component] : void 0;
     if (!renames) return { ...rawVars };
     const out = {};
     for (const [key, value] of Object.entries(rawVars)) {
@@ -2564,7 +2612,9 @@ var MIGRATIONS = [
   componentMigration_2026_09_13_cornerbadgePrefix,
   componentMigration_2026_09_13_toggleLabel,
   componentMigration_2026_09_13_collapsiblesectionOpen,
-  componentMigration_2026_09_13_badgeBrand
+  componentMigration_2026_09_13_badgeBrand,
+  componentMigration_2026_09_20_imagelightboxScrim,
+  componentMigration_2026_09_20_scrimColorAndOpacity
 ];
 function countFor(kind) {
   return MIGRATIONS.filter((m) => m.appliesTo === kind).length;

package/dist-plugin/setColors/index.js

@@ -18,7 +18,7 @@ import {
 } from "../chunk-O6GQ6GBH.js";
 import {
   CURRENT_COMPONENT_SCHEMA_VERSION
-} from "../chunk-REBHE3ZM.js";
+} from "../chunk-FD4FVDOC.js";
 import {
   cssColorToOklch,
   gamutClamp,

package/dist-plugin/setGeometry/index.cjs

@@ -74,6 +74,9 @@ var KIND_RULES = [
   { kind: "dot-size", suffix: ["-dot-size"] },
   { kind: "blur", suffix: ["-blur"], prefix: ["--blur-"] },
   { kind: "scale", suffix: ["-scale"], prefix: ["--scale-"] },
+  // A strength from 0 to 1 that the component mixes into a colour where it
+  // paints. A palette picker here writes a colour into a number.
+  { kind: "opacity", suffix: ["-opacity"], prefix: ["--scrim-opacity"] },
   { kind: "shadow", suffix: ["-shadow"], prefix: ["--shadow-"] },
   { kind: "padding", suffix: ["-padding", "-margin"] },
   { kind: "gap", suffix: ["-gap"] },
@@ -95,8 +98,7 @@ var KIND_RULES = [
       "-indicator",
       "-thumb",
       "-color",
-      "-tint",
-      "-opacity"
+      "-tint"
     ],
     prefix: ["--surface-", "--tint", "--color-"]
   }
@@ -1519,8 +1521,56 @@ var componentMigration_2026_09_13_sectiondividerSurface = {
   }
 };
 
-// src/editor/core/themes/migrations/2026-09-13-cornerbadge-prefix.ts
+// src/editor/core/themes/migrations/2026-09-20-imagelightbox-scrim.ts
 var RENAMES7 = {
+  "--imagelightbox-overlay-surface": "--imagelightbox-scrim-surface"
+};
+var componentMigration_2026_09_20_imagelightboxScrim = {
+  id: "2026-09-20-imagelightbox-scrim",
+  fromVersion: 35,
+  toVersion: 36,
+  appliesTo: "component-config",
+  apply(rawVars, meta) {
+    if (meta.component !== "imagelightbox") return { ...rawVars };
+    const out = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      out[RENAMES7[key] ?? key] = value;
+    }
+    return out;
+  }
+};
+
+// src/editor/core/themes/migrations/2026-09-20-scrim-color-and-opacity.ts
+var STOPS = {
+  "--scrim-low": "--scrim-opacity-low",
+  "--scrim": "--scrim-opacity",
+  "--scrim-high": "--scrim-opacity-high"
+};
+var SURFACE = /^--(imagelightbox|dialog)-scrim-surface$/;
+var componentMigration_2026_09_20_scrimColorAndOpacity = {
+  id: "2026-09-20-scrim-color-and-opacity",
+  fromVersion: 36,
+  toVersion: 37,
+  appliesTo: "component-config",
+  apply(rawVars) {
+    const out = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      const match = SURFACE.exec(key);
+      if (!match) {
+        out[key] = value;
+        continue;
+      }
+      const stem = `--${match[1]}-scrim`;
+      const stop = STOPS[value];
+      out[`${stem}-color`] = stop ? "--scrim-color" : value;
+      out[`${stem}-opacity`] = stop ?? "1";
+    }
+    return out;
+  }
+};
+
+// src/editor/core/themes/migrations/2026-09-13-cornerbadge-prefix.ts
+var RENAMES8 = {
   cornerbadge: {
     "--corner-badge-margin": "--cornerbadge-margin",
     "--corner-badge-outer-radius": "--cornerbadge-outer-radius",
@@ -1570,7 +1620,7 @@ var componentMigration_2026_09_13_cornerbadgePrefix = {
   toVersion: 32,
   appliesTo: "component-config",
   apply(rawVars, meta) {
-    const renames = meta.component ? RENAMES7[meta.component] : void 0;
+    const renames = meta.component ? RENAMES8[meta.component] : void 0;
     if (!renames) return { ...rawVars };
     const out = {};
     for (const [key, value] of Object.entries(rawVars)) {
@@ -1581,7 +1631,7 @@ var componentMigration_2026_09_13_cornerbadgePrefix = {
 };
 
 // src/editor/core/themes/migrations/2026-09-13-toggle-label.ts
-var RENAMES8 = {
+var RENAMES9 = {
   toggle: {
     "--toggle-label-text": "--toggle-label",
     "--toggle-disabled-label-text": "--toggle-disabled-label"
@@ -1593,7 +1643,7 @@ var componentMigration_2026_09_13_toggleLabel = {
   toVersion: 33,
   appliesTo: "component-config",
   apply(rawVars, meta) {
-    const renames = meta.component ? RENAMES8[meta.component] : void 0;
+    const renames = meta.component ? RENAMES9[meta.component] : void 0;
     if (!renames) return { ...rawVars };
     const out = {};
     for (const [key, value] of Object.entries(rawVars)) {
@@ -1604,7 +1654,7 @@ var componentMigration_2026_09_13_toggleLabel = {
 };
 
 // src/editor/core/themes/migrations/2026-09-13-collapsiblesection-open.ts
-var RENAMES9 = {
+var RENAMES10 = {
   collapsiblesection: {
     "--collapsiblesection-chromeless-expanded-padding": "--collapsiblesection-chromeless-open-padding",
     "--collapsiblesection-hairline-expanded-padding": "--collapsiblesection-hairline-open-padding",
@@ -1618,7 +1668,7 @@ var componentMigration_2026_09_13_collapsiblesectionOpen = {
   toVersion: 34,
   appliesTo: "component-config",
   apply(rawVars, meta) {
-    const renames = meta.component ? RENAMES9[meta.component] : void 0;
+    const renames = meta.component ? RENAMES10[meta.component] : void 0;
     if (!renames) return { ...rawVars };
     const out = {};
     for (const [key, value] of Object.entries(rawVars)) {
@@ -1645,7 +1695,7 @@ var BADGE_SUFFIXES = [
   "icon-size"
 ];
 var CORNERBADGE_SUFFIXES = ["surface", "border", "text"];
-var RENAMES10 = {
+var RENAMES11 = {
   badge: Object.fromEntries(
     BADGE_SUFFIXES.map((s) => [`--badge-primary-${s}`, `--badge-brand-${s}`])
   ),
@@ -1659,7 +1709,7 @@ var componentMigration_2026_09_13_badgeBrand = {
   toVersion: 35,
   appliesTo: "component-config",
   apply(rawVars, meta) {
-    const renames = meta.component ? RENAMES10[meta.component] : void 0;
+    const renames = meta.component ? RENAMES11[meta.component] : void 0;
     if (!renames) return { ...rawVars };
     const out = {};
     for (const [key, value] of Object.entries(rawVars)) {
@@ -1713,7 +1763,9 @@ var MIGRATIONS = [
   componentMigration_2026_09_13_cornerbadgePrefix,
   componentMigration_2026_09_13_toggleLabel,
   componentMigration_2026_09_13_collapsiblesectionOpen,
-  componentMigration_2026_09_13_badgeBrand
+  componentMigration_2026_09_13_badgeBrand,
+  componentMigration_2026_09_20_imagelightboxScrim,
+  componentMigration_2026_09_20_scrimColorAndOpacity
 ];
 function countFor(kind) {
   return MIGRATIONS.filter((m) => m.appliesTo === kind).length;

package/dist-plugin/setGeometry/index.d.cts

@@ -37,7 +37,7 @@ interface AdjustResult {
 }
 declare function adjustAliases(configs: Record<string, ComponentConfig>, ops: readonly AdjustOp[], now: string): AdjustResult;
 
-type TokenKind = 'surface' | 'border' | 'border-width' | 'hairline-width' | 'indicator-width' | 'radius' | 'track-height' | 'hairline-inset' | 'dot-size' | 'length' | 'blur' | 'scale' | 'shadow' | 'font-family' | 'font-weight' | 'font-size' | 'line-height' | 'letter-spacing' | 'padding' | 'gap' | 'duration' | 'easing' | 'text-color';
+type TokenKind = 'surface' | 'border' | 'border-width' | 'hairline-width' | 'indicator-width' | 'radius' | 'track-height' | 'hairline-inset' | 'dot-size' | 'length' | 'blur' | 'scale' | 'opacity' | 'shadow' | 'font-family' | 'font-weight' | 'font-size' | 'line-height' | 'letter-spacing' | 'padding' | 'gap' | 'duration' | 'easing' | 'text-color';
 /** Side-aware kind test. Per-side paddings (`--card-default-body-padding-top`)
     are written by UIPaddingSelector and never declared as editor tokens, so
     `rawKind` never meets one; the CLI does, and they belong with their parent. */

package/dist-plugin/setGeometry/index.d.ts

@@ -37,7 +37,7 @@ interface AdjustResult {
 }
 declare function adjustAliases(configs: Record<string, ComponentConfig>, ops: readonly AdjustOp[], now: string): AdjustResult;
 
-type TokenKind = 'surface' | 'border' | 'border-width' | 'hairline-width' | 'indicator-width' | 'radius' | 'track-height' | 'hairline-inset' | 'dot-size' | 'length' | 'blur' | 'scale' | 'shadow' | 'font-family' | 'font-weight' | 'font-size' | 'line-height' | 'letter-spacing' | 'padding' | 'gap' | 'duration' | 'easing' | 'text-color';
+type TokenKind = 'surface' | 'border' | 'border-width' | 'hairline-width' | 'indicator-width' | 'radius' | 'track-height' | 'hairline-inset' | 'dot-size' | 'length' | 'blur' | 'scale' | 'opacity' | 'shadow' | 'font-family' | 'font-weight' | 'font-size' | 'line-height' | 'letter-spacing' | 'padding' | 'gap' | 'duration' | 'easing' | 'text-color';
 /** Side-aware kind test. Per-side paddings (`--card-default-body-padding-top`)
     are written by UIPaddingSelector and never declared as editor tokens, so
     `rawKind` never meets one; the CLI does, and they belong with their parent. */

package/dist-plugin/setGeometry/index.js

@@ -1,6 +1,6 @@
 import {
   CURRENT_COMPONENT_SCHEMA_VERSION
-} from "../chunk-REBHE3ZM.js";
+} from "../chunk-FD4FVDOC.js";
 import {
   readLiveTokensConfig,
   resolveDataDirs
@@ -42,6 +42,9 @@ var KIND_RULES = [
   { kind: "dot-size", suffix: ["-dot-size"] },
   { kind: "blur", suffix: ["-blur"], prefix: ["--blur-"] },
   { kind: "scale", suffix: ["-scale"], prefix: ["--scale-"] },
+  // A strength from 0 to 1 that the component mixes into a colour where it
+  // paints. A palette picker here writes a colour into a number.
+  { kind: "opacity", suffix: ["-opacity"], prefix: ["--scrim-opacity"] },
   { kind: "shadow", suffix: ["-shadow"], prefix: ["--shadow-"] },
   { kind: "padding", suffix: ["-padding", "-margin"] },
   { kind: "gap", suffix: ["-gap"] },
@@ -63,8 +66,7 @@ var KIND_RULES = [
       "-indicator",
       "-thumb",
       "-color",
-      "-tint",
-      "-opacity"
+      "-tint"
     ],
     prefix: ["--surface-", "--tint", "--color-"]
   }

package/dist-plugin/tokensCssMigrations/index.cjs

@@ -639,6 +639,26 @@ var tokensCssMigration_2026_09_01_tintScale = {
   }
 };
 
+// vite-plugin/tokensCssMigrations/migrations/2026-09-20-scrim-color-and-opacity.ts
+var ENTRIES2 = [
+  { name: "--scrim-color", value: "rgb(20, 3, 0)" },
+  { name: "--scrim-opacity-low", value: "0.38" },
+  { name: "--scrim-opacity", value: "0.51" },
+  { name: "--scrim-opacity-high", value: "0.64" }
+];
+var tokensCssMigration_2026_09_20_scrimColorAndOpacity = {
+  id: "2026-09-20-scrim-color-and-opacity",
+  kind: "additive",
+  description: "Add --scrim-color and --scrim-opacity-*; a scrim's colour and strength are separate tokens",
+  apply(css) {
+    return ensureScale(css, {
+      entries: ENTRIES2,
+      sectionComment: "Scrim colour and strength, which each screen mixes where it paints",
+      anchorPrefixes: ["--scrim"]
+    });
+  }
+};
+
 // vite-plugin/files/dataPaths.ts
 var import_fs = __toESM(require("fs"), 1);
 var import_path = __toESM(require("path"), 1);
@@ -691,7 +711,8 @@ var TOKENS_CSS_MIGRATIONS = [
   tokensCssMigration_2026_08_27_editorialSizeSteps,
   tokensCssMigration_2026_08_27_editorialLargeSteps,
   tokensCssMigration_2026_09_01_scrimRename,
-  tokensCssMigration_2026_09_01_tintScale
+  tokensCssMigration_2026_09_01_tintScale,
+  tokensCssMigration_2026_09_20_scrimColorAndOpacity
 ];
 function runTokensCssMigrations(css) {
   return foldMigrations(css, () => true);

package/dist-plugin/tokensCssMigrations/index.js

@@ -13,7 +13,7 @@ import {
   runTokensCssMigrations,
   semverBumpType,
   validateTokensCss
-} from "../chunk-RFVYPNRO.js";
+} from "../chunk-V2OVSC5Z.js";
 import "../chunk-7TQQTHI6.js";
 import {
   readLiveTokensConfig

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.82.0",
+  "version": "0.84.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -199,6 +199,8 @@
     "collapse:theme": "node scripts/collapse-theme-to-default.mjs",
     "check:smoke-install": "bash scripts/smoke-install.sh",
     "check:smoke-create": "bash scripts/smoke-create.sh",
+    "eval": "bash scripts/eval.sh",
+    "build:eval-project": "bash scripts/build-eval-project.sh",
     "check:smoke-component-tests": "bash scripts/smoke-component-tests.sh",
     "check:smoke-page-tests": "bash scripts/smoke-page-tests.sh",
     "prepublishOnly": "npm run check:no-style-imports && npm run check:no-tooling-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:pages && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:token-contract && npm run check:preset-themes && npm run check:skills && npm run check:cli-strings && npm run check:skill-sources && npm run check:skill-atlas && npm run check:smoke-install && npm run check:smoke-create && npm run check:smoke-component-tests && npm run check:smoke-page-tests"

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

@@ -16,7 +16,8 @@
   // Button styling lives in Button.svelte — the dialog only owns its own chrome.
   const frameStates: Record<string, Token[]> = {
     scrim: [
-      { label: 'scrim color', groupKey: 'surface', variable: '--dialog-scrim-surface' },
+      { label: 'scrim color', groupKey: 'surface', variable: '--dialog-scrim-color' },
+      { label: 'scrim opacity', variable: '--dialog-scrim-opacity' },
     ],
     dialog: [
       { label: 'surface color', variable: '--dialog-surface' },

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

@@ -15,7 +15,8 @@
       { label: 'tile shadow',                       variable: '--imagelightbox-tile-shadow' },
     ],
     overlay: [
-      { label: 'backdrop color', groupKey: 'surface', variable: '--imagelightbox-overlay-surface' },
+      { label: 'scrim color', groupKey: 'surface', variable: '--imagelightbox-scrim-color' },
+      { label: 'scrim opacity', variable: '--imagelightbox-scrim-opacity' },
     ],
     chrome: [
       { label: 'surface color',       groupKey: 'surface', variable: '--imagelightbox-chrome-surface' },

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

@@ -9,7 +9,7 @@
   import UIPaddingSelector from '../../ui/UIPaddingSelector.svelte';
   import UILetterSpacingSelector from '../../ui/UILetterSpacingSelector.svelte';
   import UIEasingSelector from '../../ui/UIEasingSelector.svelte';
-  import { BLUR, BORDER_WIDTH, DOT_SIZE, DURATION, RADIUS, SCALE, SHADOW, TRACK_HEIGHT, HAIRLINE_INSET } from '../../ui/variantScales';
+  import { BLUR, BORDER_WIDTH, DOT_SIZE, DURATION, RADIUS, SCALE, SCRIM_OPACITY, SHADOW, TRACK_HEIGHT, HAIRLINE_INSET } from '../../ui/variantScales';
   import {
     editorState,
     getComponentPropertySiblings,
@@ -80,6 +80,7 @@
     'easing',
     'blur',
     'scale',
+    'opacity',
     'shadow',
     'text-color',
     'surface',
@@ -160,6 +161,7 @@
     'easing': { component: UIEasingSelector },
     'blur': { component: UIVariantSelector, extra: () => ({ ...BLUR }) },
     'scale': { component: UIVariantSelector, extra: () => ({ ...SCALE }) },
+    'opacity': { component: UIVariantSelector, extra: () => ({ ...SCRIM_OPACITY }) },
     'shadow': { component: UIVariantSelector, extra: () => ({ ...SHADOW }) },
     'surface': { component: UIPaletteSelector, extra: paletteExtra },
     'border': { component: UIPaletteSelector, extra: paletteExtra },
@@ -190,6 +192,7 @@
       'easing',
       'blur',
       'scale',
+      'opacity',
       'shadow',
       'surface',
       'border-width',

package/src/editor/component-editor/scaffolding/types.ts

@@ -1,14 +1,19 @@
-/** A component's catalogue entry: what it is, what to use it for, what not
-    to use it for, and what any guidance-bearing prop's values mean. Exported
-    as `catalogue` from the runtime file's `<script module>` block — the
-    Svelte compiler drops a leading HTML comment before it reaches the
-    running editor, so this is the one form every reader (CLI, registry,
-    consumer) can read. */
+/** A component's catalogue entry: what it is, what to use it for, what to use
+    instead, the rules of use, and what any guidance-bearing prop's values
+    mean. Exported as `catalogue` from the runtime file's `<script module>`
+    block — the Svelte compiler drops a leading HTML comment before it
+    reaches the running editor, so this is the one form every reader (CLI,
+    registry, consumer) can read. */
 export type CatalogueEntry = {
   /** One sentence: what the component is. */
   description: string;
-  useFor: string;
-  notFor: string;
+  /** The condition that makes this component the right one. */
+  whenToUse: string;
+  /** Each row rules the component out. `use` is the component id
+      (`table`, never `Table`) that fits instead. */
+  whenNotToUse: Array<{ when: string; use?: string }>;
+  /** Rules of use, one sentence each. */
+  constraints?: string[];
   /** Keyed by prop name; the value explains that prop's values. */
   props?: Record<string, string>;
 };

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

@@ -11,6 +11,7 @@ export type TokenKind =
   | 'length'
   | 'blur'
   | 'scale'
+  | 'opacity'
   | 'shadow'
   | 'font-family'
   | 'font-weight'
@@ -59,6 +60,9 @@ export const KIND_RULES: ReadonlyArray<{
   { kind: 'dot-size',       suffix: ['-dot-size'] },
   { kind: 'blur',           suffix: ['-blur'], prefix: ['--blur-'] },
   { kind: 'scale',          suffix: ['-scale'], prefix: ['--scale-'] },
+  // A strength from 0 to 1 that the component mixes into a colour where it
+  // paints. A palette picker here writes a colour into a number.
+  { kind: 'opacity',        suffix: ['-opacity'], prefix: ['--scrim-opacity'] },
   { kind: 'shadow',         suffix: ['-shadow'], prefix: ['--shadow-'] },
   { kind: 'padding',        suffix: ['-padding', '-margin'] },
   { kind: 'gap',            suffix: ['-gap'] },
@@ -73,7 +77,7 @@ export const KIND_RULES: ReadonlyArray<{
   // 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', '-indicator',
-                                     '-thumb', '-color', '-tint', '-opacity'],
+                                     '-thumb', '-color', '-tint'],
                             prefix: ['--surface-', '--tint', '--color-'] },
 ];
 

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

@@ -186,7 +186,7 @@ const PART_SPECS: readonly PartSpec[] = [
   { sel: '.image-lightbox-thumb', stem: 'imagelightbox-tile', positioned: true, clips: true },
   // A fixed full-viewport scrim behind the open modal; no border of its own.
   {
-    sel: '.image-lightbox-overlay', fill: 'var(--imagelightbox-overlay-surface)',
+    sel: '.image-lightbox-overlay', fill: 'color-mix(in srgb, var(--imagelightbox-scrim-color) calc(var(--imagelightbox-scrim-opacity) * 100%), transparent)',
     stroke: 'transparent', positioned: true, unmasked: true,
   },
   // Close and the two nav chevrons all carry this class; each is fixed and

package/src/editor/core/themes/migrations/2026-09-20-imagelightbox-scrim.ts

@@ -0,0 +1,28 @@
+import type { Migration } from './index';
+
+/**
+ * One word for the layer that dims the page (2026-09-20).
+ *
+ * Dialog called it a scrim and read the `--scrim-*` scale; ImageLightbox called
+ * the same layer an overlay and mixed its own colour. The token scale settles
+ * the word, so the key reads `-scrim-surface`. The chrome tokens keep their own
+ * names: they paint the toolbar, not the layer behind it.
+ */
+const RENAMES: Record<string, string> = {
+  '--imagelightbox-overlay-surface': '--imagelightbox-scrim-surface',
+};
+
+export const componentMigration_2026_09_20_imagelightboxScrim: Migration = {
+  id: '2026-09-20-imagelightbox-scrim',
+  fromVersion: 35,
+  toVersion: 36,
+  appliesTo: 'component-config',
+  apply(rawVars, meta) {
+    if (meta.component !== 'imagelightbox') return { ...rawVars };
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      out[RENAMES[key] ?? key] = value;
+    }
+    return out;
+  },
+};

package/src/editor/core/themes/migrations/2026-09-20-scrim-color-and-opacity.ts

@@ -0,0 +1,45 @@
+import type { Migration } from './index';
+
+/**
+ * A scrim's colour and its strength, apart (2026-09-20).
+ *
+ * `-scrim-surface` held one composed fill, so a theme that wanted a paler
+ * screen had to restate the colour to change the strength, and a light scrim
+ * meant hand-writing a `color-mix()`. The pair splits them: `-scrim-color`
+ * takes any colour, `-scrim-opacity` how much of it covers the page.
+ *
+ * The three `--scrim-*` stops still exist, composed from the two, so a value
+ * that named one maps to that stop's opacity and the scale's colour. Anything
+ * else was a hand-written fill: it becomes the colour, at full strength, which
+ * preserves what a reader saw when the old value was already opaque and
+ * otherwise leaves a value a person chose rather than guessing at its alpha.
+ */
+const STOPS: Record<string, string> = {
+  '--scrim-low': '--scrim-opacity-low',
+  '--scrim': '--scrim-opacity',
+  '--scrim-high': '--scrim-opacity-high',
+};
+
+const SURFACE = /^--(imagelightbox|dialog)-scrim-surface$/;
+
+export const componentMigration_2026_09_20_scrimColorAndOpacity: Migration = {
+  id: '2026-09-20-scrim-color-and-opacity',
+  fromVersion: 36,
+  toVersion: 37,
+  appliesTo: 'component-config',
+  apply(rawVars) {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawVars)) {
+      const match = SURFACE.exec(key);
+      if (!match) {
+        out[key] = value;
+        continue;
+      }
+      const stem = `--${match[1]}-scrim`;
+      const stop = STOPS[value];
+      out[`${stem}-color`] = stop ? '--scrim-color' : value;
+      out[`${stem}-opacity`] = stop ?? '1';
+    }
+    return out;
+  },
+};

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

@@ -79,6 +79,8 @@ import { componentMigration_2026_09_13_selectedState } from './2026-09-13-select
 import { componentMigration_2026_09_13_hairline } from './2026-09-13-hairline';
 import { componentMigration_2026_09_13_indicator } from './2026-09-13-indicator';
 import { componentMigration_2026_09_13_sectiondividerSurface } from './2026-09-13-sectiondivider-surface';
+import { componentMigration_2026_09_20_imagelightboxScrim } from './2026-09-20-imagelightbox-scrim';
+import { componentMigration_2026_09_20_scrimColorAndOpacity } from './2026-09-20-scrim-color-and-opacity';
 import { componentMigration_2026_09_13_cornerbadgePrefix } from './2026-09-13-cornerbadge-prefix';
 import { componentMigration_2026_09_13_toggleLabel } from './2026-09-13-toggle-label';
 import { componentMigration_2026_09_13_collapsiblesectionOpen } from './2026-09-13-collapsiblesection-open';
@@ -132,6 +134,8 @@ export const MIGRATIONS: Migration[] = [
   componentMigration_2026_09_13_toggleLabel,
   componentMigration_2026_09_13_collapsiblesectionOpen,
   componentMigration_2026_09_13_badgeBrand,
+  componentMigration_2026_09_20_imagelightboxScrim,
+  componentMigration_2026_09_20_scrimColorAndOpacity,
 ];
 
 function countFor(kind: 'colors-and-type' | 'component-config'): number {

package/src/editor/docs/content/creating-components.md

@@ -46,6 +46,9 @@ component in the editor and confirm everything works.
 
 - A runtime component whose editable properties default to your theme tokens.
 - An editor entry that appears under **Custom** in the `/live-tokens/components` view.
+- A catalogue entry in the runtime file that says what the component is for and
+  what to use instead. `npx live-tokens components` prints it, and the skills
+  read it when they choose a component for a page.
 - The naming and wiring handled for you, so the component fits the system.
 
 Advanced authors who want to write a component by hand can read the naming and