@motion-proto/live-tokens 0.78.0 → 0.80.0

package/src/system/components/CornerBadge.svelte

@@ -1,10 +1,16 @@
-<!--
-  CornerBadge.svelte. A badge that sits on a corner of its parent.
-  Use for: a count or status marker that sits on the thing it describes.
-  Not for: a label in the text flow (Badge); feedback after an action
-  (Notification).
--->
 <script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+    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.',
+    },
+  } satisfies CatalogueEntry;
+
   export type CornerAnchor = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
 </script>
 
@@ -32,7 +38,7 @@
   }: Props = $props();
 </script>
 
-<span class="corner-badge corner-badge-{anchor} corner-badge-{variant}">
+<span class="cornerbadge cornerbadge-{anchor} cornerbadge-{variant}">
   <Badge {variant} {size} {icon} {iconSlot}>
     {@render children?.()}
   </Badge>
@@ -41,7 +47,7 @@
 <style lang="scss">
   @use '../styles/padding' as *;
 
-  $variants: primary, accent, neutral, alternate, canvas, special, success, warning, danger, info;
+  $variants: brand, accent, neutral, alternate, canvas, special, success, warning, danger, info;
 
   // Shape, offset, and type are uniform across variants — one flat token set
   // owns them. Colors are per-variant so authors can tune CornerBadge to read
@@ -50,110 +56,110 @@
   // re-targets the previewed variant so authors only see 3 color rows at a
   // time, scoped to whatever variant they're previewing.
   :global(:root) {
-    --corner-badge-margin: var(--space-0);
-    --corner-badge-outer-radius: var(--radius-none);
-    --corner-badge-inner-radius: var(--radius-none);
-    --corner-badge-h-axis-radius: var(--radius-none);
-    --corner-badge-v-axis-radius: var(--radius-none);
-    --corner-badge-padding: var(--space-6);
-    --corner-badge-text-font-family: var(--font-sans);
-    --corner-badge-text-font-size: var(--font-size-sm);
-    --corner-badge-text-font-weight: var(--font-weight-medium);
-    --corner-badge-text-line-height: var(--line-height-none);
+    --cornerbadge-margin: var(--space-0);
+    --cornerbadge-outer-radius: var(--radius-none);
+    --cornerbadge-inner-radius: var(--radius-none);
+    --cornerbadge-h-axis-radius: var(--radius-none);
+    --cornerbadge-v-axis-radius: var(--radius-none);
+    --cornerbadge-padding: var(--space-6);
+    --cornerbadge-text-font-family: var(--font-sans);
+    --cornerbadge-text-font-size: var(--font-size-sm);
+    --cornerbadge-text-font-weight: var(--font-weight-medium);
+    --cornerbadge-text-line-height: var(--line-height-none);
 
     /* Per-variant color overrides. Default = inherit the same family/level the
        inner Badge uses; author can swap to a different level (e.g. -low) to
        reduce contrast against the host surface. */
-    --corner-badge-primary-surface: var(--surface-brand);
-    --corner-badge-primary-border: var(--border-brand);
-    --corner-badge-primary-text: var(--text-brand);
-    --corner-badge-accent-surface: var(--surface-accent);
-    --corner-badge-accent-border: var(--border-accent);
-    --corner-badge-accent-text: var(--text-accent);
-    --corner-badge-neutral-surface: var(--surface-neutral);
-    --corner-badge-neutral-border: var(--border-neutral);
-    --corner-badge-neutral-text: var(--text-primary);
-    --corner-badge-alternate-surface: var(--surface-alternate);
-    --corner-badge-alternate-border: var(--border-alternate);
-    --corner-badge-alternate-text: var(--text-alternate);
-    --corner-badge-canvas-surface: var(--surface-canvas);
-    --corner-badge-canvas-border: var(--border-canvas);
-    --corner-badge-canvas-text: var(--text-canvas);
-    --corner-badge-special-surface: var(--surface-special);
-    --corner-badge-special-border: var(--border-special);
-    --corner-badge-special-text: var(--text-special);
-    --corner-badge-success-surface: var(--surface-success);
-    --corner-badge-success-border: var(--border-success);
-    --corner-badge-success-text: var(--text-success);
-    --corner-badge-warning-surface: var(--surface-warning);
-    --corner-badge-warning-border: var(--border-warning);
-    --corner-badge-warning-text: var(--text-warning);
-    --corner-badge-danger-surface: var(--surface-danger);
-    --corner-badge-danger-border: var(--border-danger);
-    --corner-badge-danger-text: var(--text-danger);
-    --corner-badge-info-surface: var(--surface-info);
-    --corner-badge-info-border: var(--border-info);
-    --corner-badge-info-text: var(--text-info);
+    --cornerbadge-brand-surface: var(--surface-brand);
+    --cornerbadge-brand-border: var(--border-brand);
+    --cornerbadge-brand-text: var(--text-brand);
+    --cornerbadge-accent-surface: var(--surface-accent);
+    --cornerbadge-accent-border: var(--border-accent);
+    --cornerbadge-accent-text: var(--text-accent);
+    --cornerbadge-neutral-surface: var(--surface-neutral);
+    --cornerbadge-neutral-border: var(--border-neutral);
+    --cornerbadge-neutral-text: var(--text-primary);
+    --cornerbadge-alternate-surface: var(--surface-alternate);
+    --cornerbadge-alternate-border: var(--border-alternate);
+    --cornerbadge-alternate-text: var(--text-alternate);
+    --cornerbadge-canvas-surface: var(--surface-canvas);
+    --cornerbadge-canvas-border: var(--border-canvas);
+    --cornerbadge-canvas-text: var(--text-canvas);
+    --cornerbadge-special-surface: var(--surface-special);
+    --cornerbadge-special-border: var(--border-special);
+    --cornerbadge-special-text: var(--text-special);
+    --cornerbadge-success-surface: var(--surface-success);
+    --cornerbadge-success-border: var(--border-success);
+    --cornerbadge-success-text: var(--text-success);
+    --cornerbadge-warning-surface: var(--surface-warning);
+    --cornerbadge-warning-border: var(--border-warning);
+    --cornerbadge-warning-text: var(--text-warning);
+    --cornerbadge-danger-surface: var(--surface-danger);
+    --cornerbadge-danger-border: var(--border-danger);
+    --cornerbadge-danger-text: var(--text-danger);
+    --cornerbadge-info-surface: var(--surface-info);
+    --cornerbadge-info-border: var(--border-info);
+    --cornerbadge-info-text: var(--text-info);
   }
 
-  .corner-badge {
+  .cornerbadge {
     position: absolute;
     z-index: 1;
     pointer-events: none;
     // Pull public tokens into private vars so anchor mappings below stay generic.
-    --_margin: var(--corner-badge-margin);
-    --_outer-radius: var(--corner-badge-outer-radius);
-    --_inner-radius: var(--corner-badge-inner-radius);
-    --_h-axis-radius: var(--corner-badge-h-axis-radius);
-    --_v-axis-radius: var(--corner-badge-v-axis-radius);
+    --_margin: var(--cornerbadge-margin);
+    --_outer-radius: var(--cornerbadge-outer-radius);
+    --_inner-radius: var(--cornerbadge-inner-radius);
+    --_h-axis-radius: var(--cornerbadge-h-axis-radius);
+    --_v-axis-radius: var(--cornerbadge-v-axis-radius);
 
     // Forward padding + font onto the inner Badge to override Badge's own
     // `.badge-#{$v}` rule. Specificity (0,2,0) beats Badge's (0,1,0).
     :global(.badge) {
-      @include themed-padding(--corner-badge-padding, $h: 2);
-      font-family: var(--corner-badge-text-font-family);
-      font-size: var(--corner-badge-text-font-size);
-      font-weight: var(--corner-badge-text-font-weight);
-      line-height: var(--corner-badge-text-line-height);
+      @include themed-padding(--cornerbadge-padding, $h: 2);
+      font-family: var(--cornerbadge-text-font-family);
+      font-size: var(--cornerbadge-text-font-size);
+      font-weight: var(--cornerbadge-text-font-weight);
+      line-height: var(--cornerbadge-text-line-height);
     }
   }
 
   // Per-variant color overrides: rebind Badge's per-variant CSS vars inside
-  // the corner-badge scope so the inner Badge picks up CornerBadge's color
+  // the cornerbadge scope so the inner Badge picks up CornerBadge's color
   // tokens without CornerBadge having to re-implement the painting rules.
   @each $v in $variants {
-    .corner-badge-#{$v} {
-      --badge-#{$v}-surface: var(--corner-badge-#{$v}-surface);
-      --badge-#{$v}-border: var(--corner-badge-#{$v}-border);
-      --badge-#{$v}-text: var(--corner-badge-#{$v}-text);
+    .cornerbadge-#{$v} {
+      --badge-#{$v}-surface: var(--cornerbadge-#{$v}-surface);
+      --badge-#{$v}-border: var(--cornerbadge-#{$v}-border);
+      --badge-#{$v}-text: var(--cornerbadge-#{$v}-text);
     }
   }
 
-  .corner-badge-bottom-right { bottom: var(--_margin); right: var(--_margin); }
-  .corner-badge-bottom-left  { bottom: var(--_margin); left:  var(--_margin); }
-  .corner-badge-top-right    { top:    var(--_margin); right: var(--_margin); }
-  .corner-badge-top-left     { top:    var(--_margin); left:  var(--_margin); }
+  .cornerbadge-bottom-right { bottom: var(--_margin); right: var(--_margin); }
+  .cornerbadge-bottom-left  { bottom: var(--_margin); left:  var(--_margin); }
+  .cornerbadge-top-right    { top:    var(--_margin); right: var(--_margin); }
+  .cornerbadge-top-left     { top:    var(--_margin); left:  var(--_margin); }
 
   /* Logical roles to physical corners, per anchor. */
-  .corner-badge-bottom-right :global(.badge) {
+  .cornerbadge-bottom-right :global(.badge) {
     border-top-left-radius:     var(--_inner-radius);
     border-top-right-radius:    var(--_v-axis-radius);
     border-bottom-right-radius: var(--_outer-radius);
     border-bottom-left-radius:  var(--_h-axis-radius);
   }
-  .corner-badge-bottom-left :global(.badge) {
+  .cornerbadge-bottom-left :global(.badge) {
     border-top-left-radius:     var(--_v-axis-radius);
     border-top-right-radius:    var(--_inner-radius);
     border-bottom-right-radius: var(--_h-axis-radius);
     border-bottom-left-radius:  var(--_outer-radius);
   }
-  .corner-badge-top-right :global(.badge) {
+  .cornerbadge-top-right :global(.badge) {
     border-top-left-radius:     var(--_h-axis-radius);
     border-top-right-radius:    var(--_outer-radius);
     border-bottom-right-radius: var(--_v-axis-radius);
     border-bottom-left-radius:  var(--_inner-radius);
   }
-  .corner-badge-top-left :global(.badge) {
+  .cornerbadge-top-left :global(.badge) {
     border-top-left-radius:     var(--_outer-radius);
     border-top-right-radius:    var(--_h-axis-radius);
     border-bottom-right-radius: var(--_inner-radius);

package/src/system/components/Dialog.svelte

@@ -1,10 +1,13 @@
-<!--
-  Dialog.svelte. A modal window that blocks the page.
-  Use for: a decision the page cannot continue without, such as a destructive
-  confirmation or a sign-in.
-  Not for: a routine form (Panel); a message that asks nothing of the reader
-  (Notification).
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
   import { createEventDispatcher, tick } from 'svelte';
   import type { Snippet } from 'svelte';
@@ -30,7 +33,7 @@
   let cancelVarValue = $state(readCssVar('--dialog-cancel-variant'));
 
   interface Props {
-    show?: boolean;
+    open?: boolean;
     title?: string;
     width?: string;
     /** When true, the dialog renders inline within its parent rather than as a fixed-position overlay. Used by the editor preview. */
@@ -47,7 +50,7 @@
   }
 
   let {
-    show = $bindable(false),
+    open = $bindable(false),
     title = '',
     width = '500px',
     inline = false,
@@ -82,7 +85,7 @@
 
   // Focus the primary button when dialog opens (skip in inline mode so the editor doesn't steal focus).
   $effect(() => {
-    if (show && !inline) {
+    if (open && !inline) {
       tick().then(() => {
         if (confirm && confirmButtonRef && !confirm.disabled) {
           confirmButtonRef.focus();
@@ -107,12 +110,12 @@
     } else {
       onclose?.();
       dispatch('close');
-      show = false;
+      open = false;
     }
   }
 </script>
 
-{#if show}
+{#if open}
   <!-- The fixed backdrop portals to <body> to escape transformed/isolated
        ancestors; the inline preview variant stays in flow. -->
   <div class="dialog-backdrop" class:inline use:portal={!inline}>
@@ -186,8 +189,8 @@
 
     /* Header */
     --dialog-header-surface: var(--surface-neutral-lower);
-    --dialog-header-divider: var(--border-neutral-subtle);
-    --dialog-header-divider-width: var(--border-width-1);
+    --dialog-header-hairline-color: var(--border-neutral-subtle);
+    --dialog-header-hairline-width: var(--border-width-1);
     --dialog-header-padding: var(--space-8);
 
     /* Title */
@@ -210,8 +213,8 @@
     --dialog-body-line-height: var(--line-height-normal);
 
     /* Footer */
-    --dialog-footer-divider: var(--border-neutral-subtle);
-    --dialog-footer-divider-width: var(--border-width-1);
+    --dialog-footer-hairline-color: var(--border-neutral-subtle);
+    --dialog-footer-hairline-width: var(--border-width-1);
     --dialog-footer-padding: var(--space-16);
   }
 
@@ -271,7 +274,7 @@
       var(--dialog-header-padding-right, calc(var(--dialog-header-padding) * 3))
       var(--dialog-header-padding-bottom, var(--dialog-header-padding))
       var(--dialog-header-padding-left, calc(var(--dialog-header-padding) * 3));
-    border-bottom: var(--dialog-header-divider-width) solid var(--dialog-header-divider);
+    border-bottom: var(--dialog-header-hairline-width) solid var(--dialog-header-hairline-color);
     background: var(--dialog-header-surface);
     display: flex;
     justify-content: space-between;
@@ -327,7 +330,7 @@
       var(--dialog-footer-padding-right, var(--dialog-footer-padding))
       var(--dialog-footer-padding-bottom, var(--dialog-footer-padding))
       var(--dialog-footer-padding-left, var(--dialog-footer-padding));
-    border-top: var(--dialog-footer-divider-width) solid var(--dialog-footer-divider);
+    border-top: var(--dialog-footer-hairline-width) solid var(--dialog-footer-hairline-color);
     display: flex;
     justify-content: space-between;
     align-items: center;

package/src/system/components/IconButton.svelte

@@ -1,12 +1,16 @@
-<!--
-  IconButton.svelte. An action that an icon alone carries.
-  Use for: an action whose meaning is plain from the glyph, such as close,
-  edit, or delete.
-  Not for: an action that needs a word (Button); the confirm-and-cancel pair
-  after an inline edit (InlineEditActions).
-  Emphasis: one primary per page; secondary for the rest; outline for a
-  tertiary action; danger for a destructive one.
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+    props: {
+      variant: 'one primary per page; secondary for the rest; outline for a tertiary action; danger for a destructive one.',
+    },
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
    interface Props {
     /** Wash the hovered surface with the theme's tint. `undefined` inherits the

package/src/system/components/Image.svelte

@@ -1,11 +1,17 @@
-<!--
-  Image.svelte. A framed picture in the page flow.
-  Use for: any picture the page shows.
-  Not for: a picture whose detail the reader must open (ImageLightbox);
-  decoration that page CSS paints.
-  Variant: `default` keeps the picture's own proportions, `banner` gives it a
-  tall frame, `medium` and `compact` shorter ones.
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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.',
+    props: {
+      variant:
+        "`default` keeps the picture's own proportions, `banner` gives it a tall frame, `medium` and `compact` shorter ones.",
+    },
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
   interface Props {
     src: string;

package/src/system/components/ImageLightbox.svelte

@@ -1,9 +1,13 @@
-<!--
-  ImageLightbox.svelte. A picture that opens to a full view on click.
-  Use for: a screenshot, artwork, or chart whose detail is the point, and for
-  a gallery of them.
-  Not for: decoration or a picture the reader takes in at a glance (Image).
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
   import { onMount, tick } from 'svelte';
   import { portal } from '../internal/portal';

package/src/system/components/InlineEditActions.svelte

@@ -1,20 +1,23 @@
-<!--
-  InlineEditActions.svelte. The confirm-and-cancel pair that ends an inline
-  edit.
-  Use for: the two actions that close an in-place rename or value edit.
-  Not for: the actions of a form or a dialog (Button); a lone action on a row
-  (IconButton).
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
-   
+
 
    interface Props {
       /**
     * Reusable inline edit action buttons (confirm/cancel)
     * Used for inline editing throughout the app
     */
-      onSave: () => void | Promise<void>;
-      onCancel: () => void;
+      onsave: () => void | Promise<void>;
+      oncancel: () => void;
       disabled?: boolean;
       saveTitle?: string;
       cancelTitle?: string;
@@ -22,8 +25,8 @@
    }
 
    let {
-      onSave,
-      onCancel,
+      onsave,
+      oncancel,
       disabled = false,
       saveTitle = "Save",
       cancelTitle = "Cancel",
@@ -36,7 +39,7 @@
    <button
       class="save-btn"
       type="button"
-      onclick={onSave}
+      onclick={onsave}
       {disabled}
       title={saveTitle}
    >
@@ -45,7 +48,7 @@
    <button
       class="cancel-btn"
       type="button"
-      onclick={onCancel}
+      onclick={oncancel}
       disabled={disabled}
       title={cancelTitle}
    >

package/src/system/components/Input.svelte

@@ -1,10 +1,16 @@
-<!--
-  Input.svelte. A text field with its label, hint, and error line.
-  Use for: an answer the page cannot list, such as a name, an amount, or a
-  search string.
-  Not for: a choice from a set the page can write down (MenuSelect); an on/off
-  setting (Toggle).
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+    props: {
+      type: '`number` for an amount, `search` for a query, `password` for a secret; `text` otherwise.',
+    },
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
   import { createEventDispatcher } from 'svelte';
 

package/src/system/components/MenuSelect.svelte

@@ -1,10 +1,16 @@
-<!--
-  MenuSelect.svelte. A list of options with one checked.
-  Use for: single selection from a set too long to sit in a row, dropped from
-  a Button.
-  Not for: two to four inline alternatives (SegmentedControl); a form-style
-  list read in full (RadioButton).
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+    props: {
+      role: '`listbox` for a select; `menu` for a command menu.',
+    },
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
   import { createEventDispatcher } from 'svelte';
 

package/src/system/components/Notification.svelte

@@ -1,10 +1,16 @@
-<!--
-  Notification.svelte. Feedback about something that just happened.
-  Use for: the outcome of an action or a system event, which the reader can
-  dismiss.
-  Not for: standing content in a section (Callout); a decision that blocks the
-  page (Dialog).
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+    props: {
+      variant: '`info` notes, `success` confirms, `warning` cautions, `danger` flags harm.',
+    },
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
    import { createEventDispatcher } from 'svelte';
    import Button from './Button.svelte';
@@ -14,7 +20,7 @@
       title: string;
       description: string;
       variant?: 'info' | 'warning' | 'danger' | 'success';
-      size?: 'normal' | 'compact';
+      size?: 'default' | 'small';
       icon?: string;
       dismissible?: boolean;
       emphasis?: boolean;
@@ -28,7 +34,7 @@
       title,
       description,
       variant = 'info',
-      size = 'normal',
+      size = 'default',
       icon = '',
       dismissible = false,
       emphasis = false,
@@ -56,7 +62,7 @@
    }
 </script>
 
-<div class="notification" class:info={variant === 'info'} class:warning={variant === 'warning'} class:danger={variant === 'danger'} class:success={variant === 'success'} class:emphasis={emphasis} class:compact={size === 'compact'}>
+<div class="notification" class:info={variant === 'info'} class:warning={variant === 'warning'} class:danger={variant === 'danger'} class:success={variant === 'success'} class:emphasis={emphasis} class:small={size === 'small'}>
    <div class="notification-header" class:has-action={actions.header}>
       <i class={displayIcon}></i>
       <span class="notification-title">{title}</span>
@@ -214,7 +220,7 @@
          border-left-width: 0.375rem;
       }
 
-      &.compact {
+      &.small {
          font-size: var(--font-size-sm);
 
          .notification-description,

package/src/system/components/Panel.svelte

@@ -1,9 +1,16 @@
-<!--
-  Panel.svelte. A frame around one section of the page's content.
-  Use for: a stage, a list, a form, or a block of copy that reads as one
-  region. `minHeight` holds the height while the content changes.
-  Not for: one item in a set (Card); a modal surface (Dialog).
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+    props: {
+      minHeight: 'holds the height while the content changes.',
+    },
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
   import type { Snippet } from 'svelte';
 

package/src/system/components/ProgressBar.svelte

@@ -1,8 +1,13 @@
-<!--
-  ProgressBar.svelte. A read-out of progress against a labelled track.
-  Use for: reporting how far a task has run.
-  Not for: a number the reader sets (Slider); a standing status label (Badge).
--->
+<script module lang="ts">
+  import type { CatalogueEntry } from '../../editor/component-editor/scaffolding/types';
+
+  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).',
+  } satisfies CatalogueEntry;
+</script>
+
 <script lang="ts">
   interface Props {
     value?: number;