@viraui/react 2026.5.0 → 2026.6.1

package/dist/specs/components/title/patterns.xml

@@ -1,7 +1,78 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="title">
-  <example title="Title structure">
-    <tsx><![CDATA[<Title>…</Title>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app + design-kitchen preview-grid — cleaned (no handlers, no i18n). -->
+
+  <example title="Auth hero heading">
+    <tsx><![CDATA[
+<Title size="1" render={<h1 />} maxWidth="32rem" lineHeight="s">
+  Ship real UI at the speed of thought.
+</Title>
+]]></tsx>
+    <notes>From `auth/login-view`. Pair `size` with `render={<h1 />}` — visual preset and heading semantics stay intentional. (Live app nests Typewriter inside; see typewriter patterns.)</notes>
+  </example>
+
+  <example title="Card section heading">
+    <tsx><![CDATA[
+<Stack rowGap="xs">
+  <Title size="6" render={<h2 />}>
+    Preferences
+  </Title>
+  <Text size="s" maxWidth="18rem" tone="muted">
+    Manage your account settings and notifications.
+  </Text>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `preferences` (+ payout-threshold, notifications, …). Dense card titles use `size="6"` + `h2`.</notes>
+  </example>
+
+  <example title="Empty-state heading">
+    <tsx><![CDATA[
+<Title align="center" size="5" render={<h3 />}>
+  No Team Members
+</Title>
+]]></tsx>
+    <notes>From preview-grid `empty-team`. Centered mid-size heading; pair with muted Text below.</notes>
+  </example>
+
+  <example title="Display metric">
+    <tsx><![CDATA[
+<Stack hAlign="center" rowGap="2xs">
+  <Title align="center" size="display" lineHeight="s" whiteSpace="nowrap">
+    2400
+  </Title>
+  <Text align="center" size="xs" tone="muted">
+    CALORIES/DAY
+  </Text>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `daily-activity-goal`. `size="display"` for hero numerals; `whiteSpace="nowrap"` keeps metric on one line.</notes>
+  </example>
+
+  <example title="Balance display">
+    <tsx><![CDATA[
+<Stack rowGap="s">
+  <Text size="s" tone="muted">
+    Claimable Balance
+  </Text>
+  <Title size="1" lineHeight="s">
+    $0.00
+  </Title>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `claimable-balance`. Large `size="1"` Title as primary figure — muted label Text above, no heading tag required for non-outline figures.</notes>
+  </example>
+
+  <example title="Theme panel title">
+    <tsx><![CDATA[
+<Stack rowGap="s">
+  <Title size="4" render={<h3 />}>
+    Colors
+  </Title>
+  <Text size="s" tone="muted">
+    Preview of theme voice, contrast, and color rhythm across accents.
+  </Text>
+</Stack>
+]]></tsx>
+    <notes>From design-kitchen `theme-preview` (+ `base-theme-selector` label scale). Mid panel titles use `size="4"` + `h3`.</notes>
   </example>
 </patterns>

package/dist/specs/components/title/props.xml

@@ -4,11 +4,13 @@
     <item>Headings and display text with title presets</item>
     <item>Semantic heading tags chosen explicitly through render</item>
     <item>Size and render paired together for most heading use cases</item>
-    <item>Fluid clamp sizing across title appearance presets (gated by --effect-fluid-typography; off → fixed at --font-scale-display / h-* for that size)</item>
+    <item>Letter-spacing via `tracking` or text-transform via `transform` — prefer props over CSS on the Title root</item>
+    <item>Fluid clamp sizing across title appearance presets (theme `--effect-fluid-typography` or per-instance `fluid`; off → fixed at --font-scale-display / h-* for that size)</item>
   </when_to_use>
   <when_not_to_use>
     <item>Body copy — use Text</item>
     <item>Body or mono family typography</item>
+    <item>Inventing CSS `letter-spacing` / `text-transform` / `width: 100%` when `tracking` / `transform` / parent Stack `fullWidth` cover the need</item>
   </when_not_to_use>
   <prop name="align" kind="react">
     <description>Aligns text using logical alignment values.</description>
@@ -19,6 +21,9 @@
   <prop name="color" kind="react">
     <description>Applies a literal color escape hatch.</description>
   </prop>
+  <prop name="fluid" kind="react">
+    <description>Enables viewport fluid clamp sizing for this instance. Pass false to lock at this size’s --font-scale-display / --font-scale-h* token. Theme --effect-fluid-typography: initial still locks all Title globally.</description>
+  </prop>
   <prop name="fontWidth" kind="react">
     <description>Overrides font width as a percentage (100 = normal); maps to `font-stretch` and `wdth`.</description>
   </prop>
@@ -44,13 +49,13 @@
     <description>Enables text selection on the rendered copy.</description>
   </prop>
   <prop name="size" kind="react">
-    <description>Selects a heading or display typography preset from the active theme scale. This controls only the visual preset. Semantic heading choice remains owned by `render`, because `Title` keeps a `span` root unless `render` replaces it. Fluid clamp between prev step and this size’s --font-scale-display / --font-scale-h* token is on when --effect-fluid-typography is empty; set the theme effect to initial to lock at that scale token.</description>
+    <description>Selects a heading or display typography preset from the active theme scale. This controls only the visual preset. Semantic heading choice remains owned by `render`, because `Title` keeps a `span` root unless `render` replaces it. Fluid clamp between prev step and this size’s --font-scale-display / --font-scale-h* token is on when --effect-fluid-typography is empty and `fluid` is true; set the theme effect to initial or pass `fluid={false}` to lock at that scale token.</description>
   </prop>
   <prop name="tracking" kind="react">
-    <description>Sets letter spacing on the rendered copy. Overrides size preset letter-spacing when set.</description>
+    <description>Sets letter-spacing on the rendered copy (overrides size preset when set). Prefer this prop over CSS `letter-spacing` / Tailwind tracking utilities on the same Title root.</description>
   </prop>
   <prop name="transform" kind="react">
-    <description>Applies a text-transform on the rendered copy.</description>
+    <description>Applies CSS `text-transform` on the rendered copy via `--vui-title-text-transform` (`uppercase` \| `lowercase` \| `capitalize` \| …). Prefer this prop over CSS `text-transform` on the same Title root.</description>
   </prop>
   <prop name="trim" kind="react">
     <description>Trims text box whitespace at the chosen edge when the browser supports `text-box`. Pass `false` to disable text-box trim.</description>
@@ -67,58 +72,58 @@
   <prop name="whiteSpace" kind="react">
     <description>Controls white-space preservation and wrapping behavior.</description>
   </prop>
-  <css_var suffix="align">
+  <prop name="align" kind="css">
     <description>Title alignment on the root.</description>
-  </css_var>
-  <css_var suffix="font-family">
+  </prop>
+  <prop name="font-family" kind="css">
     <description>Heading font family on the root.</description>
-  </css_var>
-  <css_var suffix="font-opsz">
+  </prop>
+  <prop name="font-opsz" kind="css">
     <description>Optical size axis on the root (variable fonts).</description>
-  </css_var>
-  <css_var suffix="font-size">
-    <description>Heading font size; size prop presets via data attributes. Defaults to the theme scale token for that size; clamp (prev step→token) applies only when --effect-fluid-typography is on.</description>
-  </css_var>
-  <css_var suffix="font-weight">
+  </prop>
+  <prop name="font-size" kind="css">
+    <description>Heading font size; size prop presets via data attributes. Defaults to the theme scale token for that size; clamp (prev step→token) applies only when --effect-fluid-typography is on and `fluid` is true.</description>
+  </prop>
+  <prop name="font-weight" kind="css">
     <description>Font weight on the root.</description>
-  </css_var>
-  <css_var suffix="font-width">
+  </prop>
+  <prop name="font-width" kind="css">
     <description>Font width percentage on the root (font-stretch + wdth).</description>
-  </css_var>
-  <css_var suffix="letter-spacing">
-    <description>Public letter spacing from the `tracking` prop when set.</description>
-  </css_var>
-  <css_var suffix="line-height">
+  </prop>
+  <prop name="letter-spacing" kind="css">
+    <description>Public letter spacing from the `tracking` prop when set. Prefer that React prop over inventing CSS `letter-spacing` on the Title root.</description>
+  </prop>
+  <prop name="line-height" kind="css">
     <description>Line height; lineHeight prop presets via data attributes.</description>
-  </css_var>
-  <css_var suffix="literal-color">
+  </prop>
+  <prop name="literal-color" kind="css">
     <description>Literal color override on the root.</description>
-  </css_var>
-  <css_var suffix="max-width">
+  </prop>
+  <prop name="max-width" kind="css">
     <description>Max inline size of the title root.</description>
-  </css_var>
-  <css_var suffix="padding-block-end">
+  </prop>
+  <prop name="padding-block-end" kind="css">
     <description>Block-end padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-block-start">
+  </prop>
+  <prop name="padding-block-start" kind="css">
     <description>Block-start padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-inline-end">
+  </prop>
+  <prop name="padding-inline-end" kind="css">
     <description>Inline-end padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-inline-start">
+  </prop>
+  <prop name="padding-inline-start" kind="css">
     <description>Inline-start padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="trim">
+  </prop>
+  <prop name="trim" kind="css">
     <description>Text-box trim mode on the root.</description>
-  </css_var>
-  <css_var suffix="trim-type">
+  </prop>
+  <prop name="trim-type" kind="css">
     <description>Text-box trim basis on the root.</description>
-  </css_var>
-  <css_var suffix="text-transform">
-    <description>Text transform on the root.</description>
-  </css_var>
-  <css_var suffix="white-space">
+  </prop>
+  <prop name="text-transform" kind="css">
+    <description>Text transform on the root. Prefer the `transform` React prop; set this hook only when theming beyond the prop.</description>
+  </prop>
+  <prop name="white-space" kind="css">
     <description>White-space behavior on the root.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/title/usage.xml

@@ -1,10 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="title">
-  <do>Headings and display text with title presets</do>
-  <do>Semantic heading tags chosen explicitly through render</do>
-  <do>Size and render paired together for most heading use cases</do>
-  <do>Fluid clamp sizing across title appearance presets (gated by --effect-fluid-typography; off → fixed at --font-scale-display / h-* for that size)</do>
-  <dont>Assuming size changes the HTML tag automatically</dont>
-  <dont>Letting size force the HTML tag instead of choosing render explicitly</dont>
-  <dont>Using Title for long body paragraphs</dont>
+  <do>Headings and display type — pair `size` (visual preset) with `render={&lt;h1 /&gt;}`…`h6` for outline semantics (default root is `span`)</do>
+  <do>Card / panel header: Stack `rowGap=&quot;xs&quot;` + Title + muted Text blurb — Surface for card chrome</do>
+  <do>Auth / hero cycle: nest Typewriter inside Title (`preserveSpace`, caret props) so display preset + heading tag stay on the parent</do>
+  <do>Loading title copy: nest Shimmer inside Title — parent region owns busy semantics</do>
+  <do>Truncation: ClampText `render={&lt;Title size=… render={&lt;h* /&gt;} /&gt;}` — FitText wraps Title when short headlines must fill a constrained width</do>
+  <do>Fluid clamp across presets (`fluid` / theme `--effect-fluid-typography`); pass `fluid={false}` inside chrome or dense UI</do>
+  <do>Letter-spacing via `tracking`; text-transform via `transform`; width via `maxWidth` or parent Stack `fullWidth`</do>
+  <dont>Assuming `size` changes the HTML tag — choose `render` explicitly</dont>
+  <dont>Using Title for long body paragraphs — use Text</dont>
+  <dont>Inventing CSS `letter-spacing` / `text-transform` / `width: 100%` when props / Stack cover it</dont>
 </usage>

package/dist/specs/components/toast/patterns.xml

@@ -1,15 +1,92 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="toast">
-  <example title="Toast structure">
-    <tsx><![CDATA[<Toast.Provider>
+  <!-- Sources: viraui-app/components + design-kitchen preview-support — cleaned (no handlers, no portal/preview chrome). -->
+
+  <example title="App toast region">
+    <tsx><![CDATA[
+const toastManager = Toast.createToastManager();
+
+<Toast.Provider toastManager={toastManager}>
+  {/* app tree */}
   <Toast.Portal>
-    <Toast.Viewport>
-      <Toast.Banner toast={…}>
-        <Toast.Action>…</Toast.Action>
-      </Toast.Banner>
+    <Toast.Viewport position="bottom-left">
+      {toasts.map((toast) => (
+        <Toast.Banner key={toast.id} description={toast.description} toast={toast} />
+      ))}
     </Toast.Viewport>
   </Toast.Portal>
-</Toast.Provider>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+</Toast.Provider>
+]]></tsx>
+    <notes>From `providers/providers`. Non-callable `Toast` namespace: Provider + Portal + Viewport + Banner list. `toasts` from `Toast.useToastManager()` inside the Provider.</notes>
+  </example>
+
+  <example title="Stacked alerts">
+    <tsx><![CDATA[
+const stackedManager = Toast.createToastManager();
+
+{/* somewhere under Toast.Provider toastManager={stackedManager} */}
+<button type="button" onClick={() => stackedManager.add({ title: 'Order submitted', description: '1.95 shares at market price.' })}>
+  Simulate alert
+</button>
+
+<Toast.Portal>
+  <Toast.Viewport>
+    {toasts.map((toast) => (
+      <Toast.Banner key={toast.id} description={toast.description} toast={toast} />
+    ))}
+  </Toast.Viewport>
+</Toast.Portal>
+]]></tsx>
+    <notes>From preview-grid `activity-feedback` + `preview-toast`. Manager `.add({ title, description })` feeds Banner. Drop portal-container props.</notes>
+  </example>
+
+  <example title="Anchored confirmation">
+    <tsx><![CDATA[
+const anchoredManager = Toast.createToastManager();
+const copyLinkRef = React.useRef<HTMLButtonElement>(null);
+
+<button
+  ref={copyLinkRef}
+  type="button"
+  onClick={() =>
+    anchoredManager.add({
+      description: 'Link copied to clipboard.',
+      timeout: 1500,
+      positionerProps: { anchor: copyLinkRef.current, sideOffset: 8 },
+    })
+  }
+>
+  Copy
+</button>
+
+<Toast.Portal>
+  <Toast.Viewport position="anchored">
+    {toasts.map((toast) => {
+      if (!toast.positionerProps?.anchor) return null;
+      return (
+        <Toast.Positioner key={toast.id} toast={toast}>
+          <Toast.Banner description={toast.description} dismissable={false} toast={toast} />
+        </Toast.Positioner>
+      );
+    })}
+  </Toast.Viewport>
+</Toast.Portal>
+]]></tsx>
+    <notes>From preview `preview-providers` anchored list + `activity-feedback` Copy. Viewport `position="anchored"` + `Toast.Positioner` wraps Banner.</notes>
+  </example>
+
+  <example title="Banner with undo action">
+    <tsx><![CDATA[
+<Toast.Portal>
+  <Toast.Viewport>
+    {toasts.map((toast) => (
+      <Toast.Banner key={toast.id} description={toast.description} toast={toast}>
+        <Toast.Action render={<Button variant="destructive" />}>Undo</Toast.Action>
+      </Toast.Banner>
+    ))}
+  </Toast.Viewport>
+</Toast.Portal>
+]]></tsx>
+    <notes>From Toast stories undo list. Banner children are `Toast.Action` only. Close via manager inside a real handler — omitted here.</notes>
   </example>
 </patterns>

package/dist/specs/components/toast/usage.xml

@@ -1,10 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="toast">
-  <do>Confirming a completed action such as save or delete</do>
-  <do>Offering a short undo window after a reversible change</do>
-  <do>Showing contextual feedback anchored to the control that triggered it</do>
-  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <do>Mount once: `Toast.createToastManager()` → `Toast.Provider toastManager={…}` around the app tree</do>
+  <do>Render region: `Toast.Portal` → `Toast.Viewport` → map `Toast.useToastManager().toasts` to `Toast.Banner`</do>
+  <do>Confirm save/delete or short undo: manager `.add({ title, description })` feeds Banner</do>
+  <do>Undo / secondary actions: Banner children are `Toast.Action` only — default Button chrome, or `render={&lt;Button …/&gt;}`</do>
+  <do>Anchored feedback: Viewport `position=&quot;anchored&quot;` + `Toast.Positioner` wrapping Banner; pass `positionerProps.anchor` from `.add`</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on `Toast.Portal`</do>
   <dont>Nesting arbitrary components inside Toast.Banner — children must be Toast.Action only</dont>
+  <dont>Calling Toast as a component — it is a non-callable namespace (Provider / Portal / Viewport / Banner / Action)</dont>
+  <dont>Using toasts for critical validation that blocks the task — use field errors or Dialog</dont>
   <dont>Stacking many simultaneous toasts without a clear limit</dont>
-  <dont>Using toasts for critical validation errors that block task completion</dont>
 </usage>

package/dist/specs/components/toggle-button/patterns.xml

@@ -1,7 +1,105 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="toggle-button">
-  <example title="ToggleButton structure">
-    <tsx><![CDATA[<ToggleButton restingIcon={<Plus />} aria-label="Pin" />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app — cleaned (no handlers, no i18n, no studio store). Icon-only; never children. -->
+
+  <example title="Copy feedback (interpolate)">
+    <tsx><![CDATA[
+<ToggleButton
+  aria-label="Copy to clipboard"
+  restingIcon={<Duplicate aria-hidden />}
+  pressedIcon={<CircleCheck aria-hidden color="var(--highlight-green)" />}
+  interpolateIcons
+  variant="secondary"
+/>
+]]></tsx>
+    <notes>From `common/code-block` (+ `editor/export-dialog` preset copy). Temporal pressed state swaps glyph; `interpolateIcons` crossfades. App resets pressed after a timer — omit that from the hint.</notes>
+  </example>
+
+  <example title="Shuffle lock">
+    <tsx><![CDATA[
+<Tooltip>
+  <Tooltip.Trigger
+    render={
+      <ToggleButton
+        aria-label="Lock in shuffle"
+        restingIcon={<LockOpen2 aria-hidden size="1rem" />}
+        pressedIcon={<Lock aria-hidden size="1rem" color="var(--global-primary)" />}
+        variant="flat"
+        pressedVariant="secondary"
+      />
+    }
+  />
+  <Tooltip.Content>Unlocked in shuffle</Tooltip.Content>
+</Tooltip>
+]]></tsx>
+    <notes>From `editor/controls/shuffle-lock-toggle`. Flat resting + `pressedVariant` for locked chrome. Name via `aria-label`; tooltip is optional extra copy.</notes>
+  </example>
+
+  <example title="Mode sync (pressedVariant)">
+    <tsx><![CDATA[
+<Tooltip>
+  <Tooltip.Trigger
+    render={
+      <ToggleButton
+        aria-label="Sync light and dark"
+        size="s"
+        restingIcon={<DarkLight aria-hidden size="1rem" />}
+        variant="flat"
+        pressedVariant="primary"
+      />
+    }
+  />
+  <Tooltip.Content>Keep light and dark in sync</Tooltip.Content>
+</Tooltip>
+]]></tsx>
+    <notes>From `editor/controls/primary-color-select` / `foreground-color` custom fields. Single ToggleButton (not a group) with `pressedVariant="primary"` for sync-on.</notes>
+  </example>
+
+  <example title="Notify mute with Badge">
+    <tsx><![CDATA[
+<Badge show color="yellow">
+  <ToggleButton
+    aria-label="Mute notifications"
+    restingIcon={<BellSlash aria-hidden size={16} />}
+    pressedIcon={<BellOn aria-hidden size={16} />}
+    size="s"
+    interpolateIcons
+    variant="secondary"
+  />
+</Badge>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/team-directory`. Badge attention dot wraps ToggleButton; icon pair + `interpolateIcons`. Accessible name on the control (app may use `aria-labelledby` + Tooltip text).</notes>
+  </example>
+
+  <example title="Segmented group child">
+    <tsx><![CDATA[
+<ToggleGroup aria-label="Color mode" value={['system']}>
+  <ToggleButton
+    value="light"
+    aria-label="Light"
+    restingIcon={<Sun aria-hidden size="1rem" />}
+    variant="flat"
+    size="s"
+    pressedVariant="secondary"
+  />
+  <ToggleButton
+    value="dark"
+    aria-label="Dark"
+    restingIcon={<MoonStars aria-hidden size="1rem" />}
+    variant="flat"
+    size="s"
+    pressedVariant="secondary"
+  />
+  <ToggleButton
+    value="system"
+    aria-label="System"
+    restingIcon={<DarkLight aria-hidden size="1rem" />}
+    variant="flat"
+    size="s"
+    pressedVariant="secondary"
+  />
+</ToggleGroup>
+]]></tsx>
+    <notes>From `common/mode-switcher`. Inside ToggleGroup each child needs `value` + accessible name. Prefer ToggleGroup patterns for full chrome; this shows the per-button shape.</notes>
   </example>
 </patterns>

package/dist/specs/components/toggle-button/props.xml

@@ -34,28 +34,28 @@
   <prop name="variant" kind="react">
     <description>Visual variant while the toggle is not pressed.</description>
   </prop>
-  <css_var suffix="background">
+  <prop name="background" kind="css">
     <description>Button fill; variant and state selectors preset this.</description>
-  </css_var>
-  <css_var suffix="color">
+  </prop>
+  <prop name="color" kind="css">
     <description>Button label and icon color.</description>
-  </css_var>
-  <css_var suffix="height">
+  </prop>
+  <prop name="height" kind="css">
     <description>Button block size; size prop presets via data attributes.</description>
-  </css_var>
-  <css_var suffix="icon-size">
+  </prop>
+  <prop name="icon-size" kind="css">
     <description>Addon icon size inside the button.</description>
-  </css_var>
-  <css_var suffix="padding-block">
+  </prop>
+  <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button.</description>
-  </css_var>
-  <css_var suffix="padding-inline">
+  </prop>
+  <prop name="padding-inline" kind="css">
     <description>Horizontal padding inside the button.</description>
-  </css_var>
-  <css_var suffix="radius">
+  </prop>
+  <prop name="radius" kind="css">
     <description>Corner radius; pill sets full radius via data-pill.</description>
-  </css_var>
-  <css_var suffix="spinner-color">
+  </prop>
+  <prop name="spinner-color" kind="css">
     <description>Loading spinner color on the root.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/toggle-button/usage.xml

@@ -1,10 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="toggle-button">
-  <do>Toolbar pin, favorite, or mute toggles identified only by icon</do>
+  <do>Toolbar pin, favorite, mute, or lock toggles identified only by icon</do>
   <do>Compact on/off controls that share IconButton size, variant, and loading model</do>
-  <do>Two-state actions where pressed state should swap the visible glyph</do>
-  <do>Temporally swap icons after user interactions with temporal pressed state, like copy feedback.</do>
-  <dont>Using IconButton for persistent pressed toolbar state</dont>
+  <do>Two-state actions where pressed state should swap the visible glyph via `restingIcon` / `pressedIcon`</do>
+  <do>Temporal pressed feedback (e.g. copy) with optional `interpolateIcons` crossfade</do>
+  <do>Segmented toolbars: nest ToggleButtons with `value` inside ToggleGroup; label each control and the group</do>
+  <do>Optional chrome: wrap with Tooltip.Trigger / Badge — keep the accessible name on the ToggleButton</do>
+  <dont>Using IconButton for persistent or temporal pressed toolbar state</dont>
   <dont>Using Switch for compact icon-only toolbar toggles</dont>
-  <dont>Passing icon or render — ToggleButton owns icon swap and Toggle render wiring</dont>
+  <dont>Passing `icon` or `render` — ToggleButton owns icon swap and Toggle render wiring; use `restingIcon` / `pressedIcon`</dont>
+  <dont>Omitting `value` on ToggleButton children inside a ToggleGroup</dont>
+  <dont>Omitting both `aria-label` and `aria-labelledby`</dont>
 </usage>

package/dist/specs/components/toggle-group/patterns.xml

@@ -1,9 +1,38 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="toggle-group">
-  <example title="ToggleGroup structure">
-    <tsx><![CDATA[<ToggleGroup>
-  <ToggleButton restingIcon={<Plus />} aria-label="List" value="list" />
-</ToggleGroup>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app — cleaned (no handlers, no i18n, no theme store). Compound: ToggleGroup + ToggleButton children with value. -->
+
+  <example title="Mode switcher chrome">
+    <tsx><![CDATA[
+<Surface border="all" radius="m" vPadding="2xs" hPadding="2xs">
+  <ToggleGroup aria-label="Color mode" value={['system']}>
+    <ToggleButton
+      value="light"
+      aria-label="Light"
+      restingIcon={<Sun aria-hidden size="1rem" />}
+      variant="flat"
+      size="s"
+      pressedVariant="secondary"
+    />
+    <ToggleButton
+      value="dark"
+      aria-label="Dark"
+      restingIcon={<MoonStars aria-hidden size="1rem" />}
+      variant="flat"
+      size="s"
+      pressedVariant="secondary"
+    />
+    <ToggleButton
+      value="system"
+      aria-label="System"
+      restingIcon={<DarkLight aria-hidden size="1rem" />}
+      variant="flat"
+      size="s"
+      pressedVariant="secondary"
+    />
+  </ToggleGroup>
+</Surface>
+]]></tsx>
+    <notes>From `common/mode-switcher`. ToggleGroup selection is `string[]` (`value` / `defaultValue` / `onValueChange`). Label the group with `aria-label`. Surface tight padding is chrome — group Stack owns item gap (`2xs`). Exclusive mode: one selected value in the array.</notes>
   </example>
 </patterns>

package/dist/specs/components/toggle-group/usage.xml

@@ -1,9 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="toggle-group">
-  <do>Segmented icon toolbars such as text alignment or formatting controls</do>
-  <do>Single- or multi-select pressed states across related ToggleButton items</do>
-  <do>Compact action clusters that need coordinated value and disabled state</do>
-  <dont>Omitting value on ToggleButton children inside a group</dont>
+  <do>Segmented icon toolbars such as text alignment, formatting, or mode switchers</do>
+  <do>Single- or multi-select pressed states across related ToggleButton items (`value` / `defaultValue` as `string[]`)</do>
+  <do>Compose only ToggleButton children — each child needs a `value` plus `aria-label` / `aria-labelledby`</do>
+  <do>Label the group root with `aria-label` or `aria-labelledby`</do>
+  <do>Optional Surface chrome around the group for bordered toolbar shells — Stack gap is owned by ToggleGroup</do>
+  <dont>Omitting `value` on ToggleButton children inside a group</dont>
   <dont>Using Switch for icon-only toolbar toggle sets</dont>
-  <dont>Embedding Surface chrome in the component — wrap demos or app chrome at the consumer</dont>
+  <dont>Using ToggleGroup for tabbed panel navigation — use Tabs</dont>
+  <dont>Using ToggleGroup for a lone one-off toggle — use ToggleButton alone</dont>
+  <dont>Embedding Surface chrome inside the component — wrap demos or app chrome at the consumer</dont>
 </usage>