@motion-proto/live-tokens 0.82.0 → 0.84.0

package/src/editor/skill-atlas/trees/create-page.ts

@@ -2,7 +2,7 @@ import type { SkillTree } from '../types';
 
 export const createPage: SkillTree = {
   "id": "live-tokens-create-page",
-  "digest": "sha256:0d78d225ef7199e2",
+  "digest": "sha256:e9eafa612a3b863b",
   "title": "create-page",
   "tagline": "Create a Page Using Live Tokens",
   "nodes": [
@@ -88,38 +88,34 @@ export const createPage: SkillTree = {
       "row": 4,
       "kind": "chipset",
       "title": "Choose containers by purpose",
-      "desc": "Each purpose has its container. Panel is a stage, Card is titled content.",
+      "desc": "Panel is a stage, Card is titled content; a component's own constraints come from the components command.",
       "lines": [15, 15],
-      "anchor": "Give each section its container from the Containers by purpo",
+      "anchor": "Give each section its container. `npx live-tokens components",
       "chips": [
         {
           "label": "Stage",
-          "lines": [75, 76],
-          "anchor": "`Panel` is a stage: a canvas, a player, a preview. `minHeigh",
-          "anchorEnd": "An empty stage shows a heading that names the condition and "
+          "lines": [81, 81],
+          "anchor": "An empty stage shows a heading that names the condition and "
         },
         {
           "label": "Card",
-          "lines": [77, 78],
-          "anchor": "`Card` is a titled block of content. Its `title` prop is the",
-          "anchorEnd": "A container in a tool UI labels itself: `Card variant=\"bare\""
+          "lines": [82, 82],
+          "anchor": "A container in a tool UI labels itself: `Card variant=\"bare\""
         },
         {
           "label": "Form",
-          "lines": [79, 80],
-          "anchor": "A form puts the essential fields first and the secondary fie",
-          "anchorEnd": "A row of fields is a flex row with `gap: var(--space-20)`. E"
+          "lines": [83, 83],
+          "anchor": "A row of fields is a flex row with `gap: var(--space-20)`; e"
         },
         {
           "label": "Buttons",
-          "lines": [81, 82],
-          "anchor": "A toolbar is a flex row of Buttons on the section's bottom e",
-          "anchorEnd": "A vertical stack of Buttons sets `fullWidth` on each Button."
+          "lines": [84, 84],
+          "anchor": "A toolbar is a flex row of Buttons on the section's bottom e"
         },
         {
           "label": "Picker",
-          "lines": [83, 83],
-          "anchor": "`MenuSelect` renders its list open. For a picker, toggle it "
+          "lines": [85, 85],
+          "anchor": "For a `MenuSelect` picker, toggle it from a Button with a tr"
         }
       ]
     },
@@ -134,7 +130,7 @@ export const createPage: SkillTree = {
       "chips": [
         {
           "label": "Components",
-          "lines": [85, 92],
+          "lines": [73, 80],
           "anchor": "## Components",
           "anchorEnd": "Text inside a `Card` or a `CollapsibleSection` takes the con"
         },
@@ -162,25 +158,25 @@ export const createPage: SkillTree = {
       "chips": [
         {
           "label": "Tokens",
-          "lines": [94, 99],
+          "lines": [96, 101],
           "anchor": "## Tokens",
           "anchorEnd": "A value that comes from data, such as a sheet's padding in p"
         },
         {
           "label": "Type",
-          "lines": [103, 118],
+          "lines": [105, 120],
           "anchor": "### Type",
           "anchorEnd": "Use the semantic element for each place: one `h1`, an `h2` f"
         },
         {
           "label": "Size and emphasis",
-          "lines": [120, 128],
+          "lines": [122, 130],
           "anchor": "### Size",
           "anchorEnd": "In a row of actions the primary sits last, on the right. Up "
         },
         {
           "label": "Spacing",
-          "lines": [130, 144],
+          "lines": [132, 146],
           "anchor": "### Spacing",
           "anchorEnd": "Every section after the first opens with a hairline: `paddin"
         }
@@ -197,12 +193,12 @@ export const createPage: SkillTree = {
       "chips": [
         {
           "label": "LiveTokensRouter",
-          "lines": [150, 150],
+          "lines": [152, 152],
           "anchor": "`<LiveTokensRouter pages={...}>`: add a `pages` entry with `"
         },
         {
           "label": "LiveEditorOverlay",
-          "lines": [151, 151],
+          "lines": [153, 153],
           "anchor": "Manual `<LiveEditorOverlay>`: dispatch with `$derived.by(() "
         }
       ]
@@ -213,7 +209,7 @@ export const createPage: SkillTree = {
       "kind": "cli",
       "title": "Run check-page",
       "desc": "check-page --tests --strict --json applies every auto repair, proves the rendered page at its own route, and returns the fixes beside the remaining findings.",
-      "lines": [168, 168],
+      "lines": [170, 170],
       "anchor": "Run `npx live-tokens check-page <file> --tests --strict --js"
     },
     {
@@ -222,7 +218,7 @@ export const createPage: SkillTree = {
       "kind": "gate",
       "title": "Repair from guidance",
       "desc": "Each remaining finding carries its guidance. Make each repair, then run check-page again.",
-      "lines": [170, 170],
+      "lines": [172, 172],
       "anchor": "Each remaining finding carries a rule id, a line, and its `g"
     },
     {
@@ -231,31 +227,31 @@ export const createPage: SkillTree = {
       "kind": "chipset",
       "title": "Check the page in the browser",
       "desc": "The checkers cannot see a layout. Open the page at its width and check each line.",
-      "lines": [172, 188],
+      "lines": [174, 190],
       "anchor": "The checkers cannot see a layout. Open the page at the width",
       "anchorEnd": "`references/interaction-sources.md` names the sources for th",
       "chips": [
         {
           "label": "Structure",
-          "lines": [174, 178],
+          "lines": [176, 180],
           "anchor": "The first section holds what the user came for.",
           "anchorEnd": "The containers in a section align at the bottom."
         },
         {
           "label": "Actions",
-          "lines": [179, 182],
+          "lines": [181, 184],
           "anchor": "The actions sit where the eye goes last, with the one primar",
           "anchorEnd": "An action that runs longer than a moment shows progress in a"
         },
         {
           "label": "Fields",
-          "lines": [183, 184],
+          "lines": [185, 186],
           "anchor": "Every field has a default, and Reset restores it.",
           "anchorEnd": "Secondary settings sit in a `CollapsibleSection`. Every cont"
         },
         {
           "label": "Words and access",
-          "lines": [185, 186],
+          "lines": [187, 188],
           "anchor": "Labels use the user's words, such as \"Export slices\".",
           "anchorEnd": "Every `img` has `alt` text. Focus order follows the reading "
         }
@@ -267,7 +263,7 @@ export const createPage: SkillTree = {
       "kind": "step",
       "title": "Read the page twice",
       "desc": "From a distance only the sections show. Up close, every border and bar earns its place or goes.",
-      "lines": [190, 190],
+      "lines": [192, 192],
       "anchor": "Then read the page from a distance: the sections and their e"
     },
     {

package/src/editor/skill-atlas/trees/pick-component.ts

@@ -2,7 +2,7 @@ import type { SkillTree } from '../types';
 
 export const pickComponent: SkillTree = {
   "id": "live-tokens-pick-component",
-  "digest": "sha256:fa031772b2802175",
+  "digest": "sha256:2c4a39712f046d14",
   "title": "pick-component",
   "tagline": "Select a component from the catalogue",
   "nodes": [
@@ -10,245 +10,143 @@ export const pickComponent: SkillTree = {
       "id": "pk-trig",
       "row": 0,
       "kind": "trigger",
-      "title": "Check the catalogue",
-      "desc": "Recommends the shipped component that fits a UX need. The catalogue lists every registered component, shipped and custom, with its usage.",
+      "title": "Pick a component",
+      "desc": "Recommends the component that fits a UX need, from the shipped components and the project's own.",
       "lines": [3, 3],
       "anchor": "description: Recommend which shipped @motion-proto/live-toke"
     },
     {
-      "id": "pk-fam",
+      "id": "pk-cli",
       "row": 1,
+      "kind": "cli",
+      "title": "List the catalogue",
+      "desc": "The components command, with its JSON flag, returns every component's catalogue entry.",
+      "lines": [12, 12],
+      "anchor": "Run `npx live-tokens components --json`. The list carries th"
+    },
+    {
+      "id": "pk-read",
+      "row": 2,
+      "kind": "step",
+      "title": "Read the candidates' entries",
+      "desc": "whenToUse is the condition that makes a component right. whenNotToUse lists the conditions that rule it out. constraints are its rules of use.",
+      "lines": [13, 13],
+      "anchor": "Read each plausible candidate's `whenToUse`, `whenNotToUse`,"
+    },
+    {
+      "id": "pk-drop",
+      "row": 3,
       "kind": "decide",
-      "title": "Component purpose",
-      "desc": "Each family names its candidates and helps select one.",
-      "lines": [8, 8],
-      "anchor": "When more than one shipped component could fit, find the fam",
+      "title": "Drop what the requirement rules out",
+      "desc": "A candidate goes when one of its whenNotToUse conditions matches the requirement. A row that names a use points at the component to weigh next.",
+      "lines": [14, 15],
+      "anchor": "Drop a candidate whose `whenNotToUse` names a condition the ",
+      "anchorEnd": "When a dropped row names a `use`, weigh that component the s",
       "chips": [
         {
-          "label": "Action family",
-          "lines": [14, 14],
-          "anchor": "## Action family"
+          "label": "a dropped row names a use",
+          "lines": [15, 15],
+          "anchor": "When a dropped row names a `use`, weigh that component the s"
         },
         {
-          "label": "Single-selection family",
-          "lines": [20, 20],
-          "anchor": "## Single-selection family"
-        },
-        {
-          "label": "Text entry",
-          "lines": [34, 34],
-          "anchor": "## Text entry"
-        },
-        {
-          "label": "On and off",
-          "lines": [43, 43],
-          "anchor": "## On and off"
-        },
-        {
-          "label": "Container family",
-          "lines": [55, 55],
-          "anchor": "## Container family"
-        },
-        {
-          "label": "Messaging family",
-          "lines": [68, 68],
-          "anchor": "## Messaging family"
-        },
-        {
-          "label": "Display family",
-          "lines": [82, 82],
-          "anchor": "## Display family"
+          "label": "surviving candidate",
+          "lines": [16, 16],
+          "anchor": "Choose the surviving candidate whose `whenToUse` condition t"
         }
       ]
     },
-    {
-      "id": "pk-act",
-      "row": 2,
-      "kind": "chipset",
-      "title": "Action family",
-      "desc": "Does the action need a word, a glyph, or a confirm and cancel pair.",
-      "lines": [14, 18],
-      "anchor": "## Action family",
-      "anchorEnd": "The pair that confirms or cancels an inline edit: `InlineEdi"
-    },
-    {
-      "id": "pk-sel",
-      "row": 2,
-      "kind": "chipset",
-      "title": "Single-selection family",
-      "desc": "How many options there are and what does the selection change.",
-      "lines": [20, 32],
-      "anchor": "## Single-selection family",
-      "anchorEnd": "The URL changes: `SideNavigation`. Sections inside one page:"
-    },
-    {
-      "id": "pk-text",
-      "row": 2,
-      "kind": "chipset",
-      "title": "Text entry",
-      "desc": "If the options are known, use a list or select. Anything else is an input field.",
-      "lines": [34, 41],
-      "anchor": "## Text entry",
-      "anchorEnd": "A number where the position on a track carries the meaning ("
-    },
-    {
-      "id": "pk-bin",
-      "row": 2,
-      "kind": "chipset",
-      "title": "On and off",
-      "desc": "If two states have names of their own use segmented control or radio buttons.",
-      "lines": [43, 53],
-      "anchor": "## On and off",
-      "anchorEnd": "When the two states share the feature's one name, use `Toggl"
-    },
-    {
-      "id": "pk-con",
-      "row": 2,
-      "kind": "chipset",
-      "title": "Container family",
-      "desc": "Is the block: an item, a section, collapsed content, or a decision.",
-      "lines": [55, 66],
-      "anchor": "## Container family",
-      "anchorEnd": "A set of items is one `Card` per item. A routine form goes i"
-    },
-    {
-      "id": "pk-msg",
-      "row": 2,
-      "kind": "chipset",
-      "title": "Messaging family",
-      "desc": "What is the message about? What triggers it? Is it dismissable?",
-      "lines": [68, 80],
-      "anchor": "## Messaging family",
-      "anchorEnd": "`Badge` and `CornerBadge` differ in position only."
-    },
-    {
-      "id": "pk-disp",
-      "row": 2,
-      "kind": "chipset",
-      "title": "Display family",
-      "desc": "Does the user view it, or interact with it?",
-      "lines": [82, 90],
-      "anchor": "## Display family",
-      "anchorEnd": "A titled break between the sections of one page: `SectionDiv"
-    },
     {
       "id": "pk-fits",
-      "row": 3,
+      "row": 4,
       "kind": "decide",
-      "title": "Is there a match in the catalogue",
-      "desc": "Use a component from the catalogue if one fits, otherwise build a new one.",
-      "lines": [92, 96],
-      "anchor": "## Nothing fits",
-      "anchorEnd": "`npx live-tokens components <id>` prints one component's cat",
+      "title": "Choose the candidate that fits",
+      "desc": "The survivor whose whenToUse matches the requirement is the answer. With no survivor, the piece is a native element or a new component.",
+      "lines": [16, 17],
+      "anchor": "Choose the surviving candidate whose `whenToUse` condition t",
+      "anchorEnd": "When no candidate fits, follow \"Nothing fits\".",
       "chips": [
         {
-          "label": "shipped component",
-          "lines": [12, 12],
-          "anchor": "Before choosing, run `npx live-tokens components`. The list "
-        },
-        {
-          "label": "custom component",
-          "lines": [12, 12],
-          "anchor": "Before choosing, run `npx live-tokens components`. The list "
+          "label": "whenToUse condition the requirement meets",
+          "lines": [16, 16],
+          "anchor": "Choose the surviving candidate whose `whenToUse` condition t"
         },
         {
           "label": "native element",
-          "lines": [94, 94],
+          "lines": [21, 21],
           "anchor": "A native element with no chrome of its own needs no componen"
         },
         {
           "label": "nothing in the catalogue fits",
-          "lines": [94, 94],
+          "lines": [21, 21],
           "anchor": "A native element with no chrome of its own needs no componen"
         }
       ]
     },
     {
       "id": "pk-inspect",
-      "row": 4,
+      "row": 5,
       "kind": "cli",
       "title": "Check the component",
-      "desc": "See the component's props and usage before placing it.",
-      "lines": [96, 96],
+      "desc": "The components command, given the id, prints the chosen component's props and the values each accepts.",
+      "lines": [23, 23],
       "anchor": "`npx live-tokens components <id>` prints one component's cat"
     },
     {
       "id": "pk-native",
-      "row": 4,
+      "row": 5,
       "kind": "step",
       "title": "Use a native element",
       "desc": "An element with no chrome of its own needs no component.",
-      "lines": [94, 94],
+      "lines": [21, 21],
       "anchor": "A native element with no chrome of its own needs no componen"
     },
     {
       "id": "pk-make",
-      "row": 4,
+      "row": 5,
       "kind": "hand",
       "title": "Create a component",
       "desc": "A piece with chrome that nothing in the catalogue fits goes to live-tokens-create-component.",
-      "lines": [94, 94],
+      "lines": [21, 21],
       "anchor": "A native element with no chrome of its own needs no componen"
     },
     {
       "id": "pk-page",
-      "row": 5,
+      "row": 6,
       "kind": "hand",
       "title": "Return the selected component",
       "desc": "The named component returns to live-tokens-create-page, which owns size, emphasis, and placement.",
-      "lines": [94, 94],
+      "lines": [21, 21],
       "anchor": "A native element with no chrome of its own needs no componen"
     }
   ],
   "edges": [
     {
-      "to": "pk-fam",
+      "to": "pk-cli",
       "from": "pk-trig"
     },
     {
-      "to": "pk-act",
-      "from": "pk-fam",
-      "label": "Action family"
-    },
-    {
-      "to": "pk-sel",
-      "from": "pk-fam",
-      "label": "Single-selection family"
+      "to": "pk-read",
+      "from": "pk-cli"
     },
     {
-      "to": "pk-text",
-      "from": "pk-fam",
-      "label": "Text entry"
+      "to": "pk-drop",
+      "from": "pk-read"
     },
     {
-      "to": "pk-bin",
-      "from": "pk-fam",
-      "label": "On and off"
+      "to": "pk-read",
+      "from": "pk-drop",
+      "label": "a dropped row names a use",
+      "back": true
     },
     {
-      "to": "pk-con",
-      "from": "pk-fam",
-      "label": "Container family"
-    },
-    {
-      "to": "pk-msg",
-      "from": "pk-fam",
-      "label": "Messaging family"
-    },
-    {
-      "to": "pk-disp",
-      "from": "pk-fam",
-      "label": "Display family"
-    },
-    {
-      "to": "pk-inspect",
-      "from": "pk-fits",
-      "label": "shipped component"
+      "to": "pk-fits",
+      "from": "pk-drop",
+      "label": "surviving candidate"
     },
     {
       "to": "pk-inspect",
       "from": "pk-fits",
-      "label": "custom component"
+      "label": "whenToUse condition the requirement meets"
     },
     {
       "to": "pk-native",
@@ -267,34 +165,6 @@ export const pickComponent: SkillTree = {
     {
       "to": "pk-page",
       "from": "pk-native"
-    },
-    {
-      "to": "pk-fits",
-      "from": "pk-act"
-    },
-    {
-      "to": "pk-fits",
-      "from": "pk-sel"
-    },
-    {
-      "to": "pk-fits",
-      "from": "pk-text"
-    },
-    {
-      "to": "pk-fits",
-      "from": "pk-bin"
-    },
-    {
-      "to": "pk-fits",
-      "from": "pk-con"
-    },
-    {
-      "to": "pk-fits",
-      "from": "pk-msg"
-    },
-    {
-      "to": "pk-fits",
-      "from": "pk-disp"
     }
   ]
 };

package/src/editor/ui/UIVariantSelector.svelte

@@ -55,7 +55,7 @@
   let validKeys = $derived(new Set(options.map((o) => o.key)));
   let refMatcher = $derived.by(() => {
     const escaped = varPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    return new RegExp(`var\\((${escaped}[^)\\s]+)\\)`);
+    return new RegExp(`var\\((${escaped}[^)\\s]*)\\)`);
   });
 
   function parseRef(value: string): string | null {

package/src/editor/ui/variantScales.ts

@@ -45,6 +45,17 @@ export const SCALE: VariantScaleEntry = {
   ],
 };
 
+/** The scrim's three strengths. The middle stop has no suffix, as `--scrim`
+ *  and `--tint` have none, so its key is empty. */
+export const SCRIM_OPACITY: VariantScaleEntry = {
+  varPrefix: '--scrim-opacity',
+  options: [
+    { key: '-low', label: 'Low', value: '0.38' },
+    { key: '', label: 'Medium', value: '0.51' },
+    { key: '-high', label: 'High', value: '0.64' },
+  ],
+};
+
 export const BORDER_WIDTH: VariantScaleEntry = {
   varPrefix: '--border-width-',
   options: [

package/src/live-tokens/data/themes/autumn.json

@@ -2996,7 +2996,8 @@
       "createdAt": "2026-05-10T20:05:24.719Z",
       "updatedAt": "2026-08-19T22:39:32.785Z",
       "aliases": {
-        "--dialog-scrim-surface": "--scrim-high",
+        "--dialog-scrim-color": "--scrim-color",
+        "--dialog-scrim-opacity": "--scrim-opacity-high",
         "--dialog-surface": "--surface-neutral-lowest",
         "--dialog-border": "--border-neutral-strong",
         "--dialog-border-width": "--border-width-2",
@@ -3140,7 +3141,8 @@
         "--imagelightbox-tile-border": "--color-transparent",
         "--imagelightbox-tile-border-width": "--border-width-0",
         "--imagelightbox-tile-shadow": "--shadow-md",
-        "--imagelightbox-overlay-surface": "color-mix(in srgb, var(--color-neutral-950) 76%, transparent)",
+        "--imagelightbox-scrim-color": "color-mix(in srgb, var(--color-neutral-950) 76%, transparent)",
+        "--imagelightbox-scrim-opacity": "1",
         "--imagelightbox-chrome-surface": "--surface-neutral-low",
         "--imagelightbox-chrome-border": "--border-brand",
         "--imagelightbox-chrome-border-width": "--border-width-1",
@@ -3994,5 +3996,5 @@
       }
     }
   },
-  "componentSchemaVersion": 35
-}
+  "componentSchemaVersion": 37
+}

package/src/live-tokens/data/themes/halloween.json

@@ -3035,7 +3035,8 @@
       "createdAt": "2026-05-10T20:05:24.719Z",
       "updatedAt": "2026-08-19T22:39:32.785Z",
       "aliases": {
-        "--dialog-scrim-surface": "--scrim-high",
+        "--dialog-scrim-color": "--scrim-color",
+        "--dialog-scrim-opacity": "--scrim-opacity-high",
         "--dialog-surface": "--surface-neutral-lowest",
         "--dialog-border": "--border-neutral-strong",
         "--dialog-border-width": "--border-width-4",
@@ -3179,7 +3180,8 @@
         "--imagelightbox-tile-border": "--color-transparent",
         "--imagelightbox-tile-border-width": "--border-width-2",
         "--imagelightbox-tile-shadow": "--shadow-md",
-        "--imagelightbox-overlay-surface": "color-mix(in srgb, var(--color-neutral-950) 76%, transparent)",
+        "--imagelightbox-scrim-color": "color-mix(in srgb, var(--color-neutral-950) 76%, transparent)",
+        "--imagelightbox-scrim-opacity": "1",
         "--imagelightbox-chrome-surface": "--surface-neutral-low",
         "--imagelightbox-chrome-border": "--border-brand",
         "--imagelightbox-chrome-border-width": "--border-width-3",
@@ -4033,5 +4035,5 @@
       }
     }
   },
-  "componentSchemaVersion": 35
-}
+  "componentSchemaVersion": 37
+}

package/src/live-tokens/data/themes/midnight-study.json

@@ -3053,7 +3053,8 @@
       "createdAt": "2026-05-10T20:05:24.719Z",
       "updatedAt": "2026-08-19T22:39:32.785Z",
       "aliases": {
-        "--dialog-scrim-surface": "--scrim-high",
+        "--dialog-scrim-color": "--scrim-color",
+        "--dialog-scrim-opacity": "--scrim-opacity-high",
         "--dialog-surface": "--surface-neutral-lowest",
         "--dialog-border": "--border-neutral-strong",
         "--dialog-border-width": "--border-width-2",
@@ -3197,7 +3198,8 @@
         "--imagelightbox-tile-border": "--color-transparent",
         "--imagelightbox-tile-border-width": "--border-width-0",
         "--imagelightbox-tile-shadow": "--shadow-md",
-        "--imagelightbox-overlay-surface": "color-mix(in srgb, var(--color-neutral-950) 76%, transparent)",
+        "--imagelightbox-scrim-color": "color-mix(in srgb, var(--color-neutral-950) 76%, transparent)",
+        "--imagelightbox-scrim-opacity": "1",
         "--imagelightbox-chrome-surface": "--surface-neutral-low",
         "--imagelightbox-chrome-border": "--border-brand",
         "--imagelightbox-chrome-border-width": "--border-width-1",
@@ -4052,5 +4054,5 @@
       }
     }
   },
-  "componentSchemaVersion": 35
-}
+  "componentSchemaVersion": 37
+}