@motion-proto/live-tokens 0.74.0 → 0.76.0

package/src/system/components/Callout.svelte

@@ -1,3 +1,9 @@
+<!--
+  Callout.svelte. A standing message that sits inside a section.
+  Use for: something the reader must know about the content around it.
+  Not for: feedback after an action (Notification); a hint that hangs off one
+  element (Tooltip).
+-->
 <script module lang="ts">
   export const calloutVariants = ['info', 'success', 'warning', 'danger'] as const;
   export type CalloutVariant = typeof calloutVariants[number];
@@ -29,7 +35,7 @@
     --callout-info-surface: var(--surface-info-lowest);
     --callout-info-border: var(--border-info-medium);
     --callout-info-border-width: var(--border-width-1);
-    --callout-info-accent-width: var(--border-width-4);
+    --callout-info-accent-width: var(--border-width-1);
     --callout-info-radius: var(--radius-lg);
     --callout-info-padding: var(--space-12);
     --callout-info-label: var(--text-primary);
@@ -47,7 +53,7 @@
     --callout-success-surface: var(--surface-success-lowest);
     --callout-success-border: var(--border-success-subtle);
     --callout-success-border-width: var(--border-width-1);
-    --callout-success-accent-width: var(--border-width-4);
+    --callout-success-accent-width: var(--border-width-1);
     --callout-success-radius: var(--radius-lg);
     --callout-success-padding: var(--space-12);
     --callout-success-label: var(--text-primary);
@@ -65,7 +71,7 @@
     --callout-warning-surface: var(--surface-warning-lowest);
     --callout-warning-border: var(--border-warning-subtle);
     --callout-warning-border-width: var(--border-width-1);
-    --callout-warning-accent-width: var(--border-width-4);
+    --callout-warning-accent-width: var(--border-width-1);
     --callout-warning-radius: var(--radius-lg);
     --callout-warning-padding: var(--space-12);
     --callout-warning-label: var(--text-primary);
@@ -83,7 +89,7 @@
     --callout-danger-surface: var(--surface-danger-lowest);
     --callout-danger-border: var(--border-danger-subtle);
     --callout-danger-border-width: var(--border-width-1);
-    --callout-danger-accent-width: var(--border-width-4);
+    --callout-danger-accent-width: var(--border-width-1);
     --callout-danger-radius: var(--radius-lg);
     --callout-danger-padding: var(--space-12);
     --callout-danger-label: var(--text-primary);
@@ -99,8 +105,6 @@
   }
 
   .callout {
-    margin: var(--space-24) 0;
-
     :global(p) {
       margin: 0;
       display: inline;

package/src/system/components/Card.svelte

@@ -1,3 +1,10 @@
+<!--
+  Card.svelte. One item with a title.
+  Use for: an item on its own, or each item in a set: a product, a record, a
+  plan the reader may act on.
+  Not for: a section of the page's content (Panel); content the reader opens
+  on demand (CollapsibleSection); a decision that blocks the page (Dialog).
+-->
 <script lang="ts">
   interface Props {
     icon?: string;
@@ -16,6 +23,8 @@
         default; `true`/`false` force this instance on/off. */
     hover?: boolean | undefined;
     class?: string;
+    /** Content at the header's trailing edge: a badge, a count, an action. */
+    aside?: import('svelte').Snippet;
     children?: import('svelte').Snippet;
   }
 
@@ -29,6 +38,7 @@
     flush = false,
     hover = undefined,
     class: className = '',
+    aside,
     children
   }: Props = $props();
 
@@ -40,7 +50,7 @@
     hover === undefined ? undefined : hover ? 'var(--card-hover-shadow)' : 'var(--card-default-shadow)',
   );
 
-  let showHeader = $derived(variant !== 'bare' && Boolean(icon || title));
+  let showHeader = $derived(variant !== 'bare' && Boolean(icon || title || aside));
 
   $effect(() => {
     if (import.meta.env.DEV && variant === 'default' && !icon && !title) {
@@ -65,6 +75,9 @@
       {#if title}
         <span class="card-title">{title}</span>
       {/if}
+      {#if aside}
+        <div class="card-aside">{@render aside()}</div>
+      {/if}
     </div>
   {/if}
   <div class="card-body" class:prose class:flush>
@@ -142,10 +155,11 @@
     box-shadow: var(--card-hover-shadow-enabled);
   }
 
-  /* Editor preview hook: paint hover tokens directly, ignoring the on/off gate. */
+  /* Editor preview hook. Reads the same gated tokens as the real :hover rule,
+     so turning "Use hover" off shows the resting card the page will draw. */
   .card.force-hover {
-    border-color: var(--card-hover-border);
-    box-shadow: var(--card-hover-shadow);
+    border-color: var(--card-hover-border-enabled);
+    box-shadow: var(--card-hover-shadow-enabled);
   }
 
   .card-header {
@@ -156,6 +170,11 @@
     background: var(--card-default-header-surface);
   }
 
+  .card-aside {
+    flex-shrink: 0;
+    margin-left: auto;
+  }
+
   .card.compact .card-header,
   .card.compact .card-body {
     padding: var(--space-8) var(--space-12);

package/src/system/components/CodeSnippet.svelte

@@ -1,7 +1,8 @@
 <!--
-  CodeSnippet.svelte — code display with a copy button pinned top-right. Click
-  the button to copy `code` to the clipboard; a Tooltip-rendered confirmation
-  ("Copied") flashes briefly above the button.
+  CodeSnippet.svelte. A command or value with a copy button.
+  Use for: text the reader is meant to run or paste somewhere else.
+  Not for: prose the reader only reads (a paragraph in its Card or Panel); a
+  value the reader edits (Input).
 -->
 <script lang="ts">
   import Tooltip from './Tooltip.svelte';

package/src/system/components/CollapsibleSection.svelte

@@ -1,3 +1,11 @@
+<!--
+  CollapsibleSection.svelte. A section the reader opens and closes.
+  Use for: secondary content that most readers skip.
+  Not for: content every reader needs (Card); moving between pages
+  (SideNavigation).
+  Variant: `chromeless` sits inside other content, `divider` rules a line
+  under the header, `container` frames the whole section.
+-->
 <script lang="ts">
    import { createEventDispatcher } from 'svelte';
 
@@ -60,10 +68,17 @@
          {@render summary?.()}
       </div>
    {:else}
-      <!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_noninteractive_element_interactions, a11y_no_static_element_interactions -->
-      <div class="section-header" class:expanded onclick={fireToggle}>
+      <div class="section-header" class:expanded>
          <div class="section-toggle">
-            <i class="fas fa-chevron-right toggle-icon"></i>
+            <button
+               type="button"
+               class="section-toggle-button"
+               onclick={fireToggle}
+               aria-label={expanded ? 'Collapse section' : 'Expand section'}
+               aria-expanded={expanded}
+            >
+               <i class="fas fa-chevron-right toggle-icon"></i>
+            </button>
             <span class="section-label">{label}</span>
          </div>
          {@render summary?.()}
@@ -106,8 +121,8 @@
 
       /* Divider — default */
       --collapsiblesection-divider-default-surface: var(--color-transparent);
-      --collapsiblesection-divider-default-border: var(--border-brand);
-      --collapsiblesection-divider-default-border-width: var(--border-width-1);
+      --collapsiblesection-divider-default-hairline-color: var(--border-brand);
+      --collapsiblesection-divider-default-hairline-thickness: var(--border-width-1);
       --collapsiblesection-divider-default-padding: var(--space-4);
       --collapsiblesection-divider-default-label: var(--text-primary);
       --collapsiblesection-divider-default-label-font-family: var(--font-sans);
@@ -118,8 +133,8 @@
       --collapsiblesection-divider-default-icon-size: var(--icon-size-xs);
       /* Divider — hover */
       --collapsiblesection-divider-hover-surface: var(--color-transparent);
-      --collapsiblesection-divider-hover-border: var(--border-neutral);
-      --collapsiblesection-divider-hover-border-width: var(--border-width-1);
+      --collapsiblesection-divider-hover-hairline-color: var(--border-neutral);
+      --collapsiblesection-divider-hover-hairline-thickness: var(--border-width-1);
       --collapsiblesection-divider-hover-padding: var(--space-4);
       --collapsiblesection-divider-hover-label: var(--text-primary);
       --collapsiblesection-divider-hover-label-font-family: var(--font-sans);
@@ -237,7 +252,7 @@
    }
 
    @mixin divider-bottom($state) {
-      border-bottom: var(--collapsiblesection-divider-#{$state}-border-width) solid var(--collapsiblesection-divider-#{$state}-border);
+      border-bottom: var(--collapsiblesection-divider-#{$state}-hairline-thickness) solid var(--collapsiblesection-divider-#{$state}-hairline-color);
    }
 
    .es-root.variant-chromeless {

package/src/system/components/CornerBadge.svelte

@@ -1,3 +1,9 @@
+<!--
+  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">
   export type CornerAnchor = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
 </script>

package/src/system/components/Dialog.svelte

@@ -1,3 +1,10 @@
+<!--
+  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 lang="ts">
   import { createEventDispatcher, tick } from 'svelte';
   import type { Snippet } from 'svelte';
@@ -179,8 +186,8 @@
 
     /* Header */
     --dialog-header-surface: var(--surface-neutral-lower);
-    --dialog-header-border: var(--border-neutral-subtle);
-    --dialog-header-border-width: var(--border-width-1);
+    --dialog-header-divider: var(--border-neutral-subtle);
+    --dialog-header-divider-width: var(--border-width-1);
     --dialog-header-padding: var(--space-8);
 
     /* Title */
@@ -203,8 +210,8 @@
     --dialog-body-line-height: var(--line-height-normal);
 
     /* Footer */
-    --dialog-footer-border: var(--border-neutral-subtle);
-    --dialog-footer-border-width: var(--border-width-1);
+    --dialog-footer-divider: var(--border-neutral-subtle);
+    --dialog-footer-divider-width: var(--border-width-1);
     --dialog-footer-padding: var(--space-16);
   }
 
@@ -264,7 +271,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-border-width) solid var(--dialog-header-border);
+    border-bottom: var(--dialog-header-divider-width) solid var(--dialog-header-divider);
     background: var(--dialog-header-surface);
     display: flex;
     justify-content: space-between;
@@ -320,7 +327,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-border-width) solid var(--dialog-footer-border);
+    border-top: var(--dialog-footer-divider-width) solid var(--dialog-footer-divider);
     display: flex;
     justify-content: space-between;
     align-items: center;

package/src/system/components/IconButton.svelte

@@ -1,3 +1,12 @@
+<!--
+  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 lang="ts">
    interface Props {
     /** Wash the hovered surface with the theme's tint. `undefined` inherits the

package/src/system/components/Image.svelte

@@ -1,3 +1,11 @@
+<!--
+  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 lang="ts">
   interface Props {
     src: string;

package/src/system/components/ImageLightbox.svelte

@@ -1,3 +1,9 @@
+<!--
+  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 lang="ts">
   import { onMount, tick } from 'svelte';
   import { portal } from '../internal/portal';

package/src/system/components/InlineEditActions.svelte

@@ -1,3 +1,10 @@
+<!--
+  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 lang="ts">
    
 

package/src/system/components/Input.svelte

@@ -1,3 +1,10 @@
+<!--
+  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 lang="ts">
   import { createEventDispatcher } from 'svelte';
 

package/src/system/components/MenuSelect.svelte

@@ -1,3 +1,10 @@
+<!--
+  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 lang="ts">
   import { createEventDispatcher } from 'svelte';
 

package/src/system/components/Notification.svelte

@@ -1,3 +1,10 @@
+<!--
+  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 lang="ts">
    import { createEventDispatcher } from 'svelte';
    import Button from './Button.svelte';

package/src/system/components/Panel.svelte

@@ -1,3 +1,9 @@
+<!--
+  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 lang="ts">
   import type { Snippet } from 'svelte';
 

package/src/system/components/ProgressBar.svelte

@@ -1,3 +1,8 @@
+<!--
+  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 lang="ts">
   interface Props {
     value?: number;

package/src/system/components/RadioButton.svelte

@@ -1,3 +1,10 @@
+<!--
+  RadioButton.svelte. A form row that selects one option.
+  Use for: a choice the reader reviews as text before committing to a larger
+  form.
+  Not for: an inline switch between views (SegmentedControl); a setting that
+  takes effect at once (Toggle).
+-->
 <script lang="ts">
   import { createEventDispatcher } from 'svelte';
 
@@ -33,7 +40,7 @@
   style={color ? `--radiobutton-color: ${color};` : ''}
   onclick={fireClick}
 >
-  <span class="radio-dot"></span>
+  <span class="radio-dot"><span class="radio-dot-fill"></span></span>
   <span class="radio-label">{label}</span>
 </button>
 
@@ -103,7 +110,7 @@
       .radio-dot {
         border: var(--radiobutton-hover-dot-border-width) solid var(--radiobutton-color, var(--radiobutton-hover-dot-border-color));
 
-        &::after {
+        .radio-dot-fill {
           width: var(--radiobutton-hover-dot-size);
           height: var(--radiobutton-hover-dot-size);
           background: var(--radiobutton-color, var(--radiobutton-hover-dot-fill));
@@ -130,7 +137,7 @@
       .radio-dot {
         border: var(--radiobutton-active-dot-border-width) solid var(--radiobutton-color, var(--radiobutton-active-dot-border-color));
 
-        &::after {
+        .radio-dot-fill {
           width: var(--radiobutton-active-dot-size);
           height: var(--radiobutton-active-dot-size);
           background: var(--radiobutton-color, var(--radiobutton-active-dot-fill));
@@ -149,8 +156,7 @@
     flex-shrink: 0;
     transition: all var(--duration-200);
 
-    &::after {
-      content: '';
+    .radio-dot-fill {
       position: absolute;
       top: 50%;
       left: 50%;

package/src/system/components/SectionDivider.svelte

@@ -1,3 +1,11 @@
+<!--
+  SectionDivider.svelte. A titled break between the sections of a page.
+  Use for: naming the band that follows it.
+  Not for: moving between pages (SideNavigation); a title inside a container
+  (Card).
+  Level: `md` titles a page and `sm` titles a section; `eyebrow` is an opt-in
+  label above the title.
+-->
 <script lang="ts">
   /** Size variant. Each variant owns everything that defines its style:
    *  typography, geometry, colors AND the intrinsic display properties

package/src/system/components/SegmentedControl.svelte

@@ -1,3 +1,9 @@
+<!--
+  SegmentedControl.svelte. An inline switch between named alternatives.
+  Use for: two to four short labels that pick one view of the same data.
+  Not for: swapping the page's content area (TabBar); labels long enough to
+  wrap (RadioButton).
+-->
 <script lang="ts">
   import { createEventDispatcher } from 'svelte';
 

package/src/system/components/SideNavigation.svelte

@@ -1,3 +1,9 @@
+<!--
+  SideNavigation.svelte. The rail that moves between the pages of a site.
+  Use for: navigation that follows the current path.
+  Not for: switching panels inside one page (TabBar); a menu of actions
+  (MenuSelect).
+-->
 <script lang="ts">
   import { createEventDispatcher } from 'svelte';
   import CollapsibleSection from './CollapsibleSection.svelte';

package/src/system/components/Slider.svelte

@@ -1,8 +1,9 @@
 <!--
-  Slider.svelte — a number chosen by position on a track. `single` moves one
-  thumb to a value; `range` moves two thumbs to a low and a high bound. Both
-  variants share the track, fill, and thumb tokens, linked in the editor so an
-  edit to one moves the other unless deliberately unlinked.
+  Slider.svelte. A number the reader picks by position on a track.
+  Use for: a volume, a price band, or a percentage, where the position carries
+  the meaning.
+  Not for: an exact number the reader would rather type (Input); an on/off
+  setting (Toggle).
 -->
 <script module lang="ts">
   export const sliderVariants = ['single', 'range'] as const;
@@ -118,6 +119,8 @@
 
 <style>
   :global(:root) {
+    /* SliderEditor declares the two variant sets linkable, so an editor change
+       to one moves the other until the designer unlinks it. */
     /* Single: one thumb. */
     --slider-single-track-surface: var(--surface-neutral-lowest);
     --slider-single-track-border: var(--border-neutral-subtle);

package/src/system/components/TabBar.svelte

@@ -1,3 +1,9 @@
+<!--
+  TabBar.svelte. Tabs that swap the content below them.
+  Use for: two to seven panels the reader moves between inside one page.
+  Not for: one switch among others in a row (SegmentedControl); navigation
+  that changes the URL (SideNavigation).
+-->
 <script lang="ts">
   import { createEventDispatcher } from 'svelte';
 
@@ -100,7 +106,7 @@
     --tabbar-default-tab-border-width: var(--border-width-0);
     --tabbar-default-tab-top-radius: var(--radius-none);
     --tabbar-default-tab-bottom-radius: var(--radius-none);
-    --tabbar-default-indicator-border-width: var(--border-width-2);
+    --tabbar-default-indicator-width: var(--border-width-2);
 
     /* Hover tab */
     --tabbar-hover-text: var(--text-secondary);
@@ -116,7 +122,7 @@
     --tabbar-hover-tab-border-width: var(--border-width-0);
     --tabbar-hover-tab-top-radius: var(--radius-none);
     --tabbar-hover-tab-bottom-radius: var(--radius-none);
-    --tabbar-hover-indicator-border-width: var(--border-width-2);
+    --tabbar-hover-indicator-width: var(--border-width-2);
 
     /* Active tab */
     --tabbar-active-text: var(--text-primary);
@@ -132,7 +138,7 @@
     --tabbar-active-tab-border-width: var(--border-width-0);
     --tabbar-active-tab-top-radius: var(--radius-none);
     --tabbar-active-tab-bottom-radius: var(--radius-none);
-    --tabbar-active-indicator-border-width: var(--border-width-2);
+    --tabbar-active-indicator-width: var(--border-width-2);
 
     /* Disabled tab */
     --tabbar-disabled-text: var(--text-disabled);
@@ -148,7 +154,7 @@
     --tabbar-disabled-tab-border-width: var(--border-width-0);
     --tabbar-disabled-tab-top-radius: var(--radius-none);
     --tabbar-disabled-tab-bottom-radius: var(--radius-none);
-    --tabbar-disabled-indicator-border-width: var(--border-width-2);
+    --tabbar-disabled-indicator-width: var(--border-width-2);
   }
 
   .tab-bar {
@@ -177,7 +183,7 @@
     --_icon-size: var(--tabbar-default-icon-size);
     --_surface: var(--tabbar-default-surface);
     --_indicator-color: var(--tabbar-default-border);
-    --_indicator-width: var(--tabbar-default-indicator-border-width);
+    --_indicator-width: var(--tabbar-default-indicator-width);
     --_padding: var(--tabbar-default-padding);
     --_border-color: var(--tabbar-default-tab-border-color);
     --_border-width: var(--tabbar-default-tab-border-width);
@@ -191,7 +197,7 @@
     background: var(--_surface);
     border: var(--_border-width) solid var(--_border-color);
     /* Indicator accent owns the bottom edge. Both width and color rebind
-       per state — `--tabbar-{state}-indicator-border-width` and
+       per state — `--tabbar-{state}-indicator-width` and
        `--tabbar-{state}-border` (the indicator color slot). */
     border-bottom: var(--_indicator-width) solid var(--_indicator-color);
     border-radius: var(--_top-radius) var(--_top-radius) var(--_bottom-radius) var(--_bottom-radius);
@@ -223,7 +229,7 @@
     --_icon-size: var(--tabbar-hover-icon-size);
     --_surface: var(--tabbar-hover-surface);
     --_indicator-color: var(--tabbar-hover-border);
-    --_indicator-width: var(--tabbar-hover-indicator-border-width);
+    --_indicator-width: var(--tabbar-hover-indicator-width);
     --_padding: var(--tabbar-hover-padding);
     --_border-color: var(--tabbar-hover-tab-border-color);
     --_border-width: var(--tabbar-hover-tab-border-width);
@@ -240,7 +246,7 @@
     --_icon-size: var(--tabbar-active-icon-size);
     --_surface: var(--tabbar-active-surface);
     --_indicator-color: var(--tabbar-active-border);
-    --_indicator-width: var(--tabbar-active-indicator-border-width);
+    --_indicator-width: var(--tabbar-active-indicator-width);
     --_padding: var(--tabbar-active-padding);
     --_border-color: var(--tabbar-active-tab-border-color);
     --_border-width: var(--tabbar-active-tab-border-width);
@@ -257,7 +263,7 @@
     --_icon-size: var(--tabbar-disabled-icon-size);
     --_surface: var(--tabbar-disabled-surface);
     --_indicator-color: var(--tabbar-disabled-border);
-    --_indicator-width: var(--tabbar-disabled-indicator-border-width);
+    --_indicator-width: var(--tabbar-disabled-indicator-width);
     --_padding: var(--tabbar-disabled-padding);
     --_border-color: var(--tabbar-disabled-tab-border-color);
     --_border-width: var(--tabbar-disabled-tab-border-width);

package/src/system/components/Table.svelte

@@ -1,3 +1,8 @@
+<!--
+  Table.svelte. A themed frame around the rows and cells the page writes.
+  Use for: records the reader scans and compares.
+  Not for: a set of things the reader acts on (Card).
+-->
 <script lang="ts">
   interface Props {
     children?: import('svelte').Snippet;
@@ -29,8 +34,8 @@
     --table-default-header-font-weight: var(--font-weight-semibold);
     --table-default-header-line-height: var(--line-height-none);
     --table-default-header-padding: var(--space-12);
-    --table-default-header-border: var(--border-neutral);
-    --table-default-header-border-width: var(--border-width-1);
+    --table-default-header-divider: var(--border-neutral);
+    --table-default-header-divider-width: var(--border-width-1);
 
     /* Cell */
     --table-default-cell-text: var(--text-secondary);
@@ -77,7 +82,7 @@
     line-height: var(--table-default-header-line-height);
     @include themed-padding(--table-default-header-padding);
     text-align: left;
-    border-bottom: var(--table-default-header-border-width) solid var(--table-default-header-border);
+    border-bottom: var(--table-default-header-divider-width) solid var(--table-default-header-divider);
     border-right: var(--table-default-column-divider-width) solid var(--table-default-column-divider);
     white-space: nowrap;
   }

package/src/system/components/Toggle.svelte

@@ -1,8 +1,8 @@
 <!--
-  Toggle.svelte — Cloudscape-style on/off switch. The default state is "off",
-  whose tokens carry the baseline appearance plus all geometry and label
-  typography. "On" is a state that recolors track + thumb when the toggle is
-  checked; hover and disabled layer over the active component state.
+  Toggle.svelte. An on/off switch that names the setting it controls.
+  Use for: a setting that takes effect the moment it flips.
+  Not for: a choice between two named alternatives (SegmentedControl); a
+  yes/no answer inside a form (RadioButton).
 -->
 <script lang="ts">
   interface Props {

package/src/system/components/Tooltip.svelte

@@ -1,3 +1,9 @@
+<!--
+  Tooltip.svelte. A hint that appears on an element on hover or focus.
+  Use for: a definition or a shortcut the reader can do without.
+  Not for: content the reader must not miss (Callout); feedback after an
+  action (Notification).
+-->
 <script lang="ts">
   interface Props {
     text?: string;