@motion-proto/live-tokens 0.82.0 → 0.84.0

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

@@ -2995,7 +2995,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",
@@ -3139,7 +3140,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",
@@ -3993,5 +3995,5 @@
       }
     }
   },
-  "componentSchemaVersion": 35
-}
+  "componentSchemaVersion": 37
+}

package/src/live-tokens/data/themes/royal-velvet.json

@@ -3026,7 +3026,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-3",
@@ -3170,7 +3171,8 @@
         "--imagelightbox-tile-border": "--color-transparent",
         "--imagelightbox-tile-border-width": "--border-width-1",
         "--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-2",
@@ -4024,5 +4026,5 @@
       }
     }
   },
-  "componentSchemaVersion": 35
-}
+  "componentSchemaVersion": 37
+}

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

@@ -3009,7 +3009,8 @@
       "createdAt": "2026-05-10T20:05:24.719Z",
       "updatedAt": "2026-08-25T01:13:11.520Z",
       "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",
@@ -3153,7 +3154,8 @@
         "--imagelightbox-tile-border": "--color-transparent",
         "--imagelightbox-tile-border-width": "--border-width-1",
         "--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",
@@ -4007,5 +4009,5 @@
       }
     }
   },
-  "componentSchemaVersion": 35
-}
+  "componentSchemaVersion": 37
+}

package/src/live-tokens/data/themes/spring-meadow.json

@@ -2982,7 +2982,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",
@@ -3126,7 +3127,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",
@@ -3980,5 +3982,5 @@
       }
     }
   },
-  "componentSchemaVersion": 35
-}
+  "componentSchemaVersion": 37
+}

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

@@ -3034,7 +3034,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",
@@ -3178,7 +3179,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",
@@ -4032,5 +4034,5 @@
       }
     }
   },
-  "componentSchemaVersion": 35
-}
+  "componentSchemaVersion": 37
+}

package/src/system/components/Badge.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'A short standing label on an element.',
-    useFor: 'status the reader takes at a glance, such as "Beta", "New", or a version.',
-    notFor: "a marker that sits on a parent's corner (CornerBadge); feedback after an action (Notification).",
+    whenToUse: 'status the reader takes at a glance, such as "Beta", "New", or a version.',
+    whenNotToUse: [
+      { when: "the marker sits on the thing it describes, in the parent's corner.", use: 'cornerbadge' },
+      { when: 'the message is feedback about something that just happened.', use: 'notification' },
+    ],
     props: {
       variant: '`brand`, `accent`, `special`, `alternate`, `canvas`, and `neutral` paint a color family; `success`, `warning`, `danger`, and `info` carry a status.',
     },

package/src/system/components/Button.svelte

@@ -3,8 +3,16 @@
 
   export const catalogue = {
     description: 'A labelled action.',
-    useFor: 'an action that needs a word to be unambiguous.',
-    notFor: 'an icon-only action (IconButton); a link to another page.',
+    whenToUse: 'an action that needs a word to be unambiguous.',
+    whenNotToUse: [
+      { when: 'the glyph alone is plain, and space is short.', use: 'iconbutton' },
+      { when: 'the actions confirm or cancel an inline edit.', use: 'inlineeditactions' },
+    ],
+    constraints: [
+      'One primary Button per page.',
+      'A danger Button opens a Dialog to confirm before it runs.',
+      'A link to another page is an anchor.',
+    ],
     props: {
       variant: 'one primary per page; secondary for the rest; outline for a tertiary action; danger for a destructive one.',
     },

package/src/system/components/Callout.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'A standing message that sits inside a section.',
-    useFor: 'something the reader must know about the content around it.',
-    notFor: 'feedback after an action (Notification); a note that hangs off one element (Tooltip).',
+    whenToUse: 'something the reader must know about the content around it.',
+    whenNotToUse: [
+      { when: 'the message is feedback about something that just happened, and the reader can dismiss it.', use: 'notification' },
+      { when: 'the note hangs off one element, shown on hover or focus.', use: 'tooltip' },
+    ],
     props: {
       variant: '`info` notes, `success` confirms, `warning` cautions, `danger` flags harm.',
     },

package/src/system/components/Card.svelte

@@ -3,9 +3,14 @@
 
   export const catalogue = {
     description: 'One item with a title.',
-    useFor: 'an item on its own, or each item in a set: a product, a record, a plan the reader may act on.',
-    notFor:
-      "a section of the page's content (Panel); content the reader opens on demand (CollapsibleSection); a decision that blocks the page (Dialog).",
+    whenToUse: 'an item on its own, or each item in a set: a product, a record, a plan the reader may act on.',
+    whenNotToUse: [
+      { when: "the block is a stage, a list, a form, or copy that forms one section of the page's content.", use: 'panel' },
+      { when: 'the content is secondary, and most readers skip it until they open it.', use: 'collapsiblesection' },
+      { when: 'the page cannot continue until the reader decides.', use: 'dialog' },
+      { when: 'the reader scans and compares the records.', use: 'table' },
+    ],
+    constraints: ["The title prop is the Card's title, and the card's own tokens type it."],
     props: {
       variant: '`bare` drops the header for content that carries its own title.',
     },

package/src/system/components/CodeSnippet.svelte

@@ -3,8 +3,12 @@
 
   export const catalogue = {
     description: 'A command or value with a copy button.',
-    useFor: 'text the reader is meant to run or paste somewhere else.',
-    notFor: 'prose the reader only reads (a paragraph in its Card or Panel); a value the reader edits (Input).',
+    whenToUse: 'text the reader is meant to run or paste somewhere else.',
+    whenNotToUse: [
+      { when: 'the text is prose the reader only reads, inside its own titled block.', use: 'card' },
+      { when: 'the text is prose the reader only reads, inside a section of the page.', use: 'panel' },
+      { when: 'the reader edits the value.', use: 'input' },
+    ],
   } satisfies CatalogueEntry;
 </script>
 

package/src/system/components/CollapsibleSection.svelte

@@ -3,8 +3,12 @@
 
   export const catalogue = {
     description: 'A section the reader opens and closes.',
-    useFor: 'secondary content that most readers skip.',
-    notFor: 'content every reader needs (Card); moving between pages (SideNavigation).',
+    whenToUse: 'secondary content that most readers skip.',
+    whenNotToUse: [
+      { when: 'every reader needs the content, so it stays open.', use: 'card' },
+      { when: 'the choice moves the reader to another page.', use: 'sidenavigation' },
+    ],
+    constraints: ["In a form, CollapsibleSection holds the secondary fields, and the form's actions stay outside it on the form's bottom edge."],
     props: {
       variant: '`chromeless` sits inside other content, `hairline` draws a line under the header, `container` frames the whole section.',
     },

package/src/system/components/CornerBadge.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'A badge that sits on a corner of its parent.',
-    useFor: 'a count or status marker that sits on the thing it describes.',
-    notFor: 'a label in the text flow (Badge); feedback after an action (Notification).',
+    whenToUse: 'a count or status marker that sits on the thing it describes.',
+    whenNotToUse: [
+      { when: 'the label sits in the text flow.', use: 'badge' },
+      { when: 'the message is feedback about something that just happened.', use: 'notification' },
+    ],
     props: {
       variant: '`brand`, `accent`, `special`, `alternate`, `canvas`, and `neutral` paint a color family; `success`, `warning`, `danger`, and `info` carry a status.',
       anchor: 'the corner the badge sits on; `bottom-right` unless named.',

package/src/system/components/Dialog.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'A modal window that blocks the page.',
-    useFor: 'a decision the page cannot continue without, such as a destructive confirmation or a sign-in.',
-    notFor: 'a routine form (Panel); a message that asks nothing of the reader (Notification).',
+    whenToUse: 'a decision the page cannot continue without, such as a destructive confirmation or a sign-in.',
+    whenNotToUse: [
+      { when: 'the form is routine, and the page can continue around it.', use: 'panel' },
+      { when: 'the message asks nothing of the reader.', use: 'notification' },
+    ],
   } satisfies CatalogueEntry;
 </script>
 
@@ -177,7 +180,8 @@
 <style>
   :global(:root) {
     /* Scrim */
-    --dialog-scrim-surface: var(--scrim-high);
+    --dialog-scrim-color: var(--scrim-color);
+    --dialog-scrim-opacity: var(--scrim-opacity-high);
 
     /* Dialog frame */
     --dialog-surface: var(--surface-neutral-lowest);
@@ -224,7 +228,11 @@
     left: 0;
     width: 100%;
     height: 100%;
-    background: var(--dialog-scrim-surface);
+    background: color-mix(
+      in srgb,
+      var(--dialog-scrim-color) calc(var(--dialog-scrim-opacity) * 100%),
+      transparent
+    );
     display: flex;
     justify-content: center;
     align-items: center;

package/src/system/components/IconButton.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'An action that an icon alone carries.',
-    useFor: 'an action whose meaning is plain from the glyph, such as close, edit, or delete.',
-    notFor: 'an action that needs a word (Button); the confirm-and-cancel pair after an inline edit (InlineEditActions).',
+    whenToUse: 'an action whose meaning is plain from the glyph, such as close, edit, or delete.',
+    whenNotToUse: [
+      { when: 'the action needs a word to be unambiguous.', use: 'button' },
+      { when: 'the pair confirms or cancels an inline edit.', use: 'inlineeditactions' },
+    ],
     props: {
       variant: 'one primary per page; secondary for the rest; outline for a tertiary action; danger for a destructive one.',
     },

package/src/system/components/Image.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'A framed picture in the page flow.',
-    useFor: 'any picture the page shows.',
-    notFor: 'a picture whose detail the reader must open (ImageLightbox); decoration that page CSS paints.',
+    whenToUse: 'any picture the page shows.',
+    whenNotToUse: [
+      { when: 'the detail is the point, and the reader opens it to see more.', use: 'imagelightbox' },
+    ],
+    constraints: ['Page CSS paints decoration.'],
     props: {
       variant:
         "`default` keeps the picture's own proportions, `banner` gives it a tall frame, `medium` and `compact` shorter ones.",

package/src/system/components/ImageLightbox.svelte

@@ -3,8 +3,10 @@
 
   export const catalogue = {
     description: 'A picture that opens to a full view on click.',
-    useFor: 'a screenshot, artwork, or chart whose detail is the point, and for a gallery of them.',
-    notFor: 'decoration or a picture the reader takes in at a glance (Image).',
+    whenToUse: 'a screenshot, artwork, or chart whose detail is the point, and for a gallery of them.',
+    whenNotToUse: [
+      { when: 'the reader takes the picture in at a glance, with no detail to open.', use: 'image' },
+    ],
   } satisfies CatalogueEntry;
 </script>
 
@@ -41,6 +43,29 @@
         a non-zero spread has no shadow under `content` — `drop-shadow()` has no
         spread slot. */
     shadow?: 'box' | 'content' | 'none';
+    /** A ground behind the image, for this instance, as any CSS fill. Overrides
+        `--imagelightbox-tile-surface`, which a theme sets for every tile at once
+        and which defaults to transparent. Art with transparency wants one:
+        without a ground the page shows through the art's own gaps while a `box`
+        shadow still casts from the rectangle around them. */
+    surface?: string | undefined;
+    /** A line around the tile, for this instance, as any CSS colour. Overrides
+        `--imagelightbox-tile-border`. It paints nothing on its own: the width
+        is a second token, so pass `borderWidth` with it wherever the theme
+        leaves that at zero. */
+    border?: string | undefined;
+    /** The width of that line, as any CSS length. Overrides
+        `--imagelightbox-tile-border-width`. */
+    borderWidth?: string | undefined;
+    /** The scrim's colour behind the open image, for this instance. Overrides
+        `--imagelightbox-scrim-color`. The modal portals to <body>, out of reach
+        of a wrapper around the tile, so a page that wants its own scrim has to
+        say so here. */
+    scrim?: string | undefined;
+    /** How much of that colour covers the page, 0 to 1. Overrides
+        `--imagelightbox-scrim-opacity`, and stands on its own: the colour it
+        mixes with is whatever the theme holds. */
+    scrimOpacity?: number | undefined;
     /** When true, shows a bottom toolbar (zoom in/out + percent) and a top-right close button, and enables wheel/drag zoom inside the open modal. When false, click anywhere closes. */
     extended?: boolean;
     /** Maximum zoom, as a multiple of the image's natural resolution: `1` = 100%
@@ -73,6 +98,11 @@
     maxWidth = undefined,
     fit = 'contain',
     shadow = 'box',
+    surface = undefined,
+    border = undefined,
+    borderWidth = undefined,
+    scrim = undefined,
+    scrimOpacity = undefined,
     extended = false,
     maxZoom = undefined,
     capNatural = false,
@@ -603,6 +633,9 @@
     class:shadow-box={shadow === 'box'}
     class:shadow-content={shadow === 'content'}
     style:--imagelightbox-tile-object-fit={fit}
+    style:--imagelightbox-tile-surface={surface}
+    style:--imagelightbox-tile-border={border}
+    style:--imagelightbox-tile-border-width={borderWidth}
     type="button"
     aria-label={cover?.alt ? `Expand image: ${cover.alt}` : 'Expand image'}
     aria-haspopup="dialog"
@@ -625,6 +658,8 @@
     <div
       bind:this={overlayEl}
       class="image-lightbox-overlay"
+      style:--imagelightbox-scrim-color={scrim}
+      style:--imagelightbox-scrim-opacity={scrimOpacity}
       class:active={open}
       aria-hidden="true"
       onclick={closeLightbox}
@@ -748,7 +783,8 @@
     --imagelightbox-tile-object-fit:       contain;
 
     /* overlay */
-    --imagelightbox-overlay-surface:       color-mix(in srgb, var(--color-neutral-950) 76%, transparent);
+    --imagelightbox-scrim-color:           var(--scrim-color);
+    --imagelightbox-scrim-opacity:         var(--scrim-opacity-high);
 
     /* chrome (toolbar + close button) */
     --imagelightbox-chrome-surface:        var(--surface-neutral-low);
@@ -874,7 +910,11 @@
   .image-lightbox-overlay {
     position: fixed;
     inset: 0;
-    background: var(--imagelightbox-overlay-surface);
+    background: color-mix(
+      in srgb,
+      var(--imagelightbox-scrim-color) calc(var(--imagelightbox-scrim-opacity) * 100%),
+      transparent
+    );
     backdrop-filter: blur(var(--blur-md));
     z-index: var(--z-overlay);
     opacity: 0;

package/src/system/components/InlineEditActions.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'The confirm-and-cancel pair that ends an inline edit.',
-    useFor: 'the two actions that close an in-place rename or value edit.',
-    notFor: 'the actions of a form or a dialog (Button); a lone action on a row (IconButton).',
+    whenToUse: 'the two actions that close an in-place rename or value edit.',
+    whenNotToUse: [
+      { when: 'the actions belong to a form or a Dialog.', use: 'button' },
+      { when: 'the row needs one lone action.', use: 'iconbutton' },
+    ],
   } satisfies CatalogueEntry;
 </script>
 

package/src/system/components/Input.svelte

@@ -3,8 +3,12 @@
 
   export const catalogue = {
     description: 'A text field with its label, hint, and error line.',
-    useFor: 'an answer the page cannot list, such as a name, an amount, or a search string.',
-    notFor: 'a choice from a set the page can write down (MenuSelect); an on/off setting (Toggle).',
+    whenToUse: 'an answer the page cannot list, such as a name, an amount, or a search string.',
+    whenNotToUse: [
+      { when: 'the answer comes from a predefined list of options.', use: 'menuselect' },
+      { when: 'the setting is on or off, and takes effect at once.', use: 'toggle' },
+      { when: 'the position on a track carries the meaning of the number.', use: 'slider' },
+    ],
     props: {
       type: '`number` for an amount, `search` for a query, `password` for a secret; `text` otherwise.',
     },

package/src/system/components/MenuSelect.svelte

@@ -3,8 +3,15 @@
 
   export const catalogue = {
     description: 'A list of options with one checked.',
-    useFor: 'single selection from a set too long to sit in a row, dropped from a Button.',
-    notFor: 'two to four inline alternatives (SegmentedControl); a form-style list read in full (RadioButton).',
+    whenToUse: 'single selection from a set too long to sit in a row, dropped from a Button.',
+    whenNotToUse: [
+      { when: 'the choice allows more than one value.' },
+      { when: 'the set is two to four options that fit inline.', use: 'segmentedcontrol' },
+      { when: 'the reader reads every option as text inside a larger form.', use: 'radiobutton' },
+    ],
+    constraints: [
+      'The Button that opens it is the control on the page; MenuSelect renders its list open.',
+    ],
     props: {
       role: '`listbox` for a select; `menu` for a command menu.',
     },

package/src/system/components/Notification.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'Feedback about something that just happened.',
-    useFor: 'the outcome of an action or a system event, which the reader can dismiss.',
-    notFor: 'standing content in a section (Callout); a decision that blocks the page (Dialog).',
+    whenToUse: 'the outcome of an action or a system event, which the reader can dismiss.',
+    whenNotToUse: [
+      { when: 'the reader must know it about the content around it, and it stays present.', use: 'callout' },
+      { when: 'the page cannot continue until the reader decides.', use: 'dialog' },
+    ],
     props: {
       variant: '`info` notes, `success` confirms, `warning` cautions, `danger` flags harm.',
     },

package/src/system/components/Panel.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: "A frame around one section of the page's content.",
-    useFor: 'a stage, a list, a form, or a block of copy that forms one section.',
-    notFor: 'one item in a set (Card); a modal window (Dialog).',
+    whenToUse: 'a stage, a list, a form, or a block of copy that forms one section.',
+    whenNotToUse: [
+      { when: 'the block is one item, or each item in a set.', use: 'card' },
+      { when: 'the page cannot continue until the reader decides.', use: 'dialog' },
+    ],
     props: {
       minHeight: 'holds the height while the content changes.',
     },

package/src/system/components/ProgressBar.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'A read-out of progress against a labelled track.',
-    useFor: 'reporting how far a task has run.',
-    notFor: 'a number the reader sets (Slider); a standing status label (Badge).',
+    whenToUse: 'reporting how far a task has run.',
+    whenNotToUse: [
+      { when: 'the reader sets the number.', use: 'slider' },
+      { when: 'the label stands on its own, with no progress to report.', use: 'badge' },
+    ],
   } satisfies CatalogueEntry;
 </script>
 

package/src/system/components/RadioButton.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'A form row that selects one option.',
-    useFor: 'a choice the reader reviews as text before committing to a larger form.',
-    notFor: 'an inline switch between views (SegmentedControl); a setting that takes effect at once (Toggle).',
+    whenToUse: 'a choice the reader reviews as text before committing to a larger form.',
+    whenNotToUse: [
+      { when: 'the choice switches between views of the same data, inline.', use: 'segmentedcontrol' },
+      { when: 'the setting takes effect the moment it flips.', use: 'toggle' },
+    ],
   } satisfies CatalogueEntry;
 </script>
 

package/src/system/components/SectionDivider.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'A titled break between the sections of a page.',
-    useFor: 'naming the section that follows it.',
-    notFor: 'moving between pages (SideNavigation); a title inside a container (Card).',
+    whenToUse: 'naming the section that follows it.',
+    whenNotToUse: [
+      { when: 'the titles are links that move the reader between pages.', use: 'sidenavigation' },
+      { when: 'the title belongs to one item inside a container.', use: 'card' },
+    ],
     props: {
       variant: '`sm` titles a section, `md` titles a page, and `lg` is the largest size.',
       eyebrow: 'an opt-in label above the title.',

package/src/system/components/SegmentedControl.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'An inline switch between named alternatives.',
-    useFor: 'two to four short labels that pick one view of the same data.',
-    notFor: "swapping the page's content area (TabBar); labels long enough to wrap (RadioButton).",
+    whenToUse: 'two to four short labels that pick one view of the same data.',
+    whenNotToUse: [
+      { when: "the choice swaps the page's content area below it.", use: 'tabbar' },
+      { when: 'a label would wrap.', use: 'radiobutton' },
+    ],
   } satisfies CatalogueEntry;
 </script>
 

package/src/system/components/SideNavigation.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'The rail that moves between the pages of a site.',
-    useFor: 'navigation that follows the current path.',
-    notFor: 'switching views inside one page (TabBar); a menu of actions (MenuSelect).',
+    whenToUse: 'navigation that follows the current path.',
+    whenNotToUse: [
+      { when: 'the switch stays inside one page, with no URL change.', use: 'tabbar' },
+      { when: 'the list holds actions.', use: 'menuselect' },
+    ],
   } satisfies CatalogueEntry;
 </script>
 

package/src/system/components/Slider.svelte

@@ -3,8 +3,12 @@
 
   export const catalogue = {
     description: 'A number the reader picks by position on a track.',
-    useFor: 'a volume, a price range, or a percentage, where the position carries the meaning.',
-    notFor: 'an exact number the reader would rather type (Input); an on/off setting (Toggle).',
+    whenToUse: 'a volume, a price range, or a percentage, where the position carries the meaning.',
+    whenNotToUse: [
+      { when: 'the reader knows the exact number and would rather type it.', use: 'input' },
+      { when: 'the setting is on or off, and takes effect at once.', use: 'toggle' },
+      { when: 'the number is a read-out of progress.', use: 'progressbar' },
+    ],
     props: {
       variant: '`single` picks one number; `range` picks a low and a high.',
     },

package/src/system/components/TabBar.svelte

@@ -3,8 +3,11 @@
 
   export const catalogue = {
     description: 'Tabs that swap the content below them.',
-    useFor: 'two to seven views the reader moves between inside one page.',
-    notFor: 'one switch among others in a row (SegmentedControl); navigation that changes the URL (SideNavigation).',
+    whenToUse: 'two to seven views the reader moves between inside one page.',
+    whenNotToUse: [
+      { when: 'the switch sits among other controls in a row.', use: 'segmentedcontrol' },
+      { when: 'the choice changes the URL.', use: 'sidenavigation' },
+    ],
   } satisfies CatalogueEntry;
 </script>
 

package/src/system/components/Table.svelte

@@ -3,8 +3,10 @@
 
   export const catalogue = {
     description: 'A themed frame around the rows and cells the page writes.',
-    useFor: 'records the reader scans and compares.',
-    notFor: 'a set of things the reader acts on (Card).',
+    whenToUse: 'records the reader scans and compares.',
+    whenNotToUse: [
+      { when: 'the reader acts on each item.', use: 'card' },
+    ],
   } satisfies CatalogueEntry;
 </script>