@viraui/react 2026.6.0 → 2026.6.1

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

@@ -44,52 +44,52 @@
   <prop name="variant" kind="react">
     <description>Selects the visual treatment matching Button. (icon-button-link)</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>
-  <css_var suffix="background">
+  </prop>
+  <prop name="background" kind="css">
     <description>Button fill; variant and state selectors preset this. (icon-button-link)</description>
-  </css_var>
-  <css_var suffix="color">
+  </prop>
+  <prop name="color" kind="css">
     <description>Button label and icon color. (icon-button-link)</description>
-  </css_var>
-  <css_var suffix="height">
+  </prop>
+  <prop name="height" kind="css">
     <description>Button block size; size prop presets via data attributes. (icon-button-link)</description>
-  </css_var>
-  <css_var suffix="icon-size">
+  </prop>
+  <prop name="icon-size" kind="css">
     <description>Addon icon size inside the button. (icon-button-link)</description>
-  </css_var>
-  <css_var suffix="padding-block">
+  </prop>
+  <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button. (icon-button-link)</description>
-  </css_var>
-  <css_var suffix="padding-inline">
+  </prop>
+  <prop name="padding-inline" kind="css">
     <description>Horizontal padding inside the button. (icon-button-link)</description>
-  </css_var>
-  <css_var suffix="radius">
+  </prop>
+  <prop name="radius" kind="css">
     <description>Corner radius; pill sets full radius via data-pill. (icon-button-link)</description>
-  </css_var>
-  <css_var suffix="spinner-color">
+  </prop>
+  <prop name="spinner-color" kind="css">
     <description>Loading spinner color on the root. (icon-button-link)</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,14 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="icon-button">
   <do>Compact toolbar or chrome actions identified only by icon</do>
-  <do>Same size, variant, and loading model as Button without visible label</do>
-  <do>Decorative glyph with explicit accessible naming on the root button</do>
-  <do>Compact toolbar or chrome navigation identified only by icon</do>
-  <do>Same size, variant, and loading model as IconButton without button semantics</do>
-  <do>Compose with framework Link via ButtonLink render prop</do>
-  <dont>Passing children, addon, or addonPosition — not part of the public API</dont>
+  <do>Same size, variant, and loading model as Button without a visible label</do>
+  <do>Decorative glyph with an explicit accessible name on the root (`aria-label` / `aria-labelledby`)</do>
+  <do>Toolbar / zoom / chrome clusters: Stack row of IconButtons inside Surface — gap via Stack, not per-control CSS</do>
+  <do>Textfield `endAddon` / `startAddon` for compact field chrome (e.g. copy) — keep addon control `size=&quot;s&quot;`</do>
+  <do>Menu / overlay triggers via `Menu.Trigger render={&lt;IconButton … /&gt;}` (and peers with the same pattern)</do>
+  <do>Icon-only navigation — use IconButtonLink (framework Link via `render`)</do>
+  <dont>Passing `children`, `addon`, or `addonPosition` — not part of the public API; use `icon`</dont>
   <dont>Using icon-only Button instead of IconButton</dont>
-  <dont>Using IconButton with render={&lt;a /&gt;} for links — use IconButtonLink</dont>
-  <dont>Passing children, addon, or addonPosition — not part of the public API</dont>
-  <dont>Using IconButton with render={&lt;a /&gt;} instead of IconButtonLink</dont>
+  <dont>Using IconButton for persistent or temporal pressed state — use ToggleButton</dont>
+  <dont>Using IconButton with `render={&lt;a /&gt;}` for links — use IconButtonLink</dont>
+  <dont>Omitting both `aria-label` and `aria-labelledby`</dont>
+  <dont>Inventing `width: 100%` / `w-full` CSS on IconButton when a parent Stack `fullWidth` / `expandChildren` can own the fill</dont>
 </usage>

package/dist/specs/components/linear-progress/patterns.xml

@@ -1,7 +1,62 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="linear-progress">
-  <example title="LinearProgress structure">
-    <tsx><![CDATA[<LinearProgress value={40} />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: preview-grid blocks — cleaned (no handlers, no kitchen chrome). -->
+
+  <example title="Goal card track + caption row">
+    <tsx><![CDATA[
+<Surface color={2} radius="m" hPadding="m" vPadding="m">
+  <Stack rowGap="m">
+    <Text family="mono" size="xs" tone="muted">
+      RETIREMENT
+    </Text>
+    <Text size="2xl">$420,000</Text>
+    <LinearProgress aria-label="RETIREMENT progress" max={100} min={0} value={65} />
+    <Stack columnGap="s" direction="row" hAlign="space-between" vAlign="center">
+      <Text tone="muted">65% achieved</Text>
+      <Text weight="semibold">$273,000</Text>
+    </Stack>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From preview-grid `savings-targets` goal card. Track-only LinearProgress + Stack captions for human-readable progress — do not invent custom track CSS.</notes>
+  </example>
+
+  <example title="Intake vs daily goal">
+    <tsx><![CDATA[
+<Surface border="all" radius="auto" hPadding="m" vPadding="m">
+  <Stack rowGap="m" hAlign="center">
+    <Stack hAlign="center" rowGap="2xs">
+      <Title align="center" size="display" lineHeight="s" whiteSpace="nowrap">
+        350
+      </Title>
+      <Text align="center" size="xs" tone="muted">
+        CALORIES/DAY
+      </Text>
+    </Stack>
+
+    <LinearProgress aria-label="Today's calorie intake" max={350} min={0} value={220} />
+
+    <Stack columnGap="s" direction="row" hAlign="space-between" vAlign="center">
+      <Text tone="muted">Today</Text>
+      <Text weight="semibold">220 cal</Text>
+    </Stack>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From preview-grid `daily-activity-goal`. `max` matches the goal; `value` is today's intake. Drop Beam/Dialog kitchen chrome from this hint.</notes>
+  </example>
+
+  <example title="Labeled progress with value">
+    <tsx><![CDATA[
+<LinearProgress
+  label="Upload"
+  description="Compressing assets before publish."
+  max={100}
+  min={0}
+  renderValue
+  value={42}
+/>
+]]></tsx>
+    <notes>API pattern from props/`linear-progress` stories. `label` + `renderValue` + optional `description`. Use `value={null}` for indeterminate when percent is unknown.</notes>
   </example>
 </patterns>

package/dist/specs/components/linear-progress/props.xml

@@ -19,13 +19,13 @@
   <prop name="renderValue" kind="react">
     <description>Shows the current value beside the label. Pass `true` for Base UI default formatting, or a function matching `Progress.Value` `children` to customize the printed label.</description>
   </prop>
-  <css_var suffix="indicator-color">
+  <prop name="indicator-color" kind="css">
     <description>Progress indicator color for determinate fill and indeterminate sweep.</description>
-  </css_var>
-  <css_var suffix="track-background">
+  </prop>
+  <prop name="track-background" kind="css">
     <description>Progress track background color.</description>
-  </css_var>
-  <css_var suffix="track-size">
+  </prop>
+  <prop name="track-size" kind="css">
     <description>Progress track thickness on the root.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/linear-progress/usage.xml

@@ -1,11 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="linear-progress">
-  <do>Use for task completion with a known percentage or bounded numeric value.</do>
-  <do>Use with `value={null}` when progress is active but the amount complete is unknown.</do>
-  <do>Use with a label when the progress bar needs a visible task name.</do>
-  <dont>Do not use LinearProgress as an interactive value control.</dont>
-  <dont>Do not add fake percentages for work where progress is unknown.</dont>
-  <dont>Do not model invalid progress; Base UI Progress does not expose an invalid state.</dont>
-  <dont>Do not model disabled progress; Base UI Progress does not expose a disabled state.</dont>
-  <dont>Do not hide the task label when multiple progress indicators are visible.</dont>
+  <do>Task completion with known percent or bounded `value` / `min` / `max` (upload, export, goal progress)</do>
+  <do>Indeterminate work: `value={null}` — do not invent fake percentages</do>
+  <do>Labeled track: `label` + optional `renderValue` + `description` — root already renders as Stack, so nest captions without custom flex CSS</do>
+  <do>Goal cards: Surface + Stack headlines / captions around a track-only LinearProgress (`aria-label` when no `label` prop)</do>
+  <do>Prefer Meter for static capacity / score within a range (storage, quota, battery) — LinearProgress for in-progress tasks</do>
+  <dont>Using LinearProgress as an interactive value control — use Slider</dont>
+  <dont>Using LinearProgress for layout placeholders — use Skeleton; for tiny busy chrome use Spinner / Button `loading`</dont>
+  <dont>Modeling invalid or disabled progress — Base UI Progress exposes neither</dont>
+  <dont>Hiding the task name when multiple progress indicators share a view</dont>
 </usage>

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

@@ -1,9 +1,72 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="masonry">
-  <example title="Masonry structure">
-    <tsx><![CDATA[<Masonry>
-  <Masonry.Item>…</Masonry.Item>
-</Masonry>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: packages/react/src/components/masonry/masonry.stories.tsx — cleaned (no ResizeObserver mocks, no play harness). -->
+
+  <example title="Responsive card wall">
+    <tsx><![CDATA[
+<Masonry gap="l">
+  <Masonry.Item>
+    <Elevator resting={1}>
+      <Surface border="all" hoverColor={3} color={2} radius="m">
+        <Stack expandChildren hPadding="l" vPadding="l" rowGap="s">
+          <Text weight="semibold">Atlas</Text>
+          <Text tone="muted">Short block for baseline column packing.</Text>
+        </Stack>
+      </Surface>
+    </Elevator>
+  </Masonry.Item>
+  <Masonry.Item>
+    <Elevator resting={1}>
+      <Surface border="all" hoverColor={3} color={2} radius="m">
+        <Stack expandChildren hPadding="l" vPadding="l" rowGap="s">
+          <Text weight="semibold">Beacon</Text>
+          <Text tone="muted">
+            Longer copy to stretch item height and make the column flow visible.
+          </Text>
+        </Stack>
+      </Surface>
+    </Elevator>
+  </Masonry.Item>
+  <Masonry.Item>
+    <Elevator resting={1}>
+      <Surface border="all" hoverColor={3} color={2} radius="m">
+        <Stack expandChildren hPadding="l" vPadding="l" rowGap="s">
+          <Text weight="semibold">Comet</Text>
+          <Text tone="muted">Compact card.</Text>
+        </Stack>
+      </Surface>
+    </Elevator>
+  </Masonry.Item>
+</Masonry>
+]]></tsx>
+    <notes>From `DefaultResponsiveLayout`. Default `breakpointCols` pack uneven Surface cards; `gap` owns column + within-column spacing. Presentational wall only — DOM order follows columns.</notes>
+  </example>
+
+  <example title="Custom column breakpoints">
+    <tsx><![CDATA[
+<Masonry gap="l" breakpointCols={{ default: 1, 640: 2, 1152: 3 }}>
+  <Masonry.Item>
+    <Elevator resting={1}>
+      <Surface border="all" color={2} radius="m">
+        <Stack expandChildren hPadding="l" vPadding="l" rowGap="s">
+          <Text weight="semibold">North</Text>
+          <Text tone="muted">Custom min-width keys are CSS px against the Masonry root.</Text>
+        </Stack>
+      </Surface>
+    </Elevator>
+  </Masonry.Item>
+  <Masonry.Item>
+    <Elevator resting={1}>
+      <Surface border="all" color={2} radius="m">
+        <Stack expandChildren hPadding="l" vPadding="l" rowGap="s">
+          <Text weight="semibold">South</Text>
+          <Text tone="muted">Neighbor item for multi-column layout.</Text>
+        </Stack>
+      </Surface>
+    </Elevator>
+  </Masonry.Item>
+</Masonry>
+]]></tsx>
+    <notes>From `CustomBreakpoints`. Keys may be unsorted; largest matching px wins. Not viewport media — root content-box inline size.</notes>
   </example>
 </patterns>

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

@@ -26,7 +26,7 @@
   <prop name="render" kind="react">
     <description>Replaces the default `div` root using Base UI render semantics.</description>
   </prop>
-  <css_var suffix="gap">
+  <prop name="gap" kind="css">
     <description>Column gap only (`--vui-masonry-gap` on the flex root). Within-column item spacing uses Stack `rowGap`, not this custom property.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,9 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="masonry">
   <do>Card walls, gallery-like collections, and editorial layouts with uneven item heights</do>
-  <do>Presentational walls where responsive column count matters more than source-order reading</do>
-  <do>Read-only collections composed from Surface, Stack, Text, and similar content primitives</do>
-  <do>Style descendants with @container masonry queries when layout should respond to the Masonry root&apos;s inline-size (peer Surface/Stack named containers)</do>
+  <do>Compose each `Masonry.Item` as Elevator → Surface → Stack → Text (title + muted body) — Masonry packs columns; Surface/Stack own chrome and spacing</do>
+  <do>Presentational walls where responsive column count (`breakpointCols`) matters more than source-order reading</do>
+  <do>Set `gap` from the density profile — open props; do not invent CSS `gap` / column margins</do>
+  <do>Style descendants with `@container masonry` when layout should respond to this root&apos;s inline-size (peer of Surface/Stack named containers)</do>
   <dont>Treating React columns as a true interactive grid with predictable source-order keyboard traversal</dont>
-  <dont>Using arbitrary child margins instead of the gap contract (column flex gap + Stack rowGap)</dont>
+  <dont>Using Grid when you only need ragged uneven-height packing — and conversely: use Grid (not Masonry) when you need row/column spans or placement</dont>
+  <dont>Using arbitrary child margins or CSS `gap` instead of the public `gap` prop</dont>
+  <dont>Using CSS `columns` / `column-count` instead of Masonry for ragged packing</dont>
+  <dont>Inventing `width: 100%` on masonry children when the column track already owns the inline size</dont>
+  <dont>Enabling Stack/Surface `enableContainer` on cards inside Masonry unless you need those queries — inline-size containment can change nested packing</dont>
 </usage>

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

@@ -1,25 +1,189 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="menu">
-  <example title="Menu structure">
-    <tsx><![CDATA[<Menu>
-  <Menu.Trigger />
-  <Menu.Popup>
-    <Menu.Item />
-    <Menu.LinkItem />
-    <Menu.CheckboxItem />
-    <Menu.Group label="…">
-      <Menu.Item />
+  <!-- Sources: viraui-app/components + design-kitchen preview-grid — cleaned (no handlers, no portal/preview chrome). -->
+
+  <example title="Account menu">
+    <tsx><![CDATA[
+<Menu>
+  <Menu.Trigger
+    render={
+      <Stack hPadding="s" render={<button type="button" />} vPadding="s" expandChildren>
+        <Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
+          <Stack columnGap="s" direction="row" vAlign="center">
+            <Avatar alt="Maya Chen" fallback="MC" size="s" />
+            <Stack rowGap="s">
+              <Text weight="semibold">Maya Chen</Text>
+              <Text size="s" tone="muted">
+                maya@ledger.io
+              </Text>
+            </Stack>
+          </Stack>
+          <ChevronExpandY aria-hidden size={16} />
+        </Stack>
+      </Stack>
+    }
+  />
+  <Menu.Popup align="start" side="bottom">
+    <Stack hPadding="s" rowGap="2xs" vPadding="s">
+      <Stack columnGap="s" direction="row" vAlign="center">
+        <Avatar alt="Maya Chen" fallback="MC" size="m" />
+        <Stack rowGap="s">
+          <Text weight="semibold">Maya Chen</Text>
+          <Text size="s" tone="muted">
+            maya@ledger.io
+          </Text>
+        </Stack>
+      </Stack>
+    </Stack>
+    <Menu.Separator />
+    <Menu.Item addon={<StarUpgrade aria-hidden size={16} />}>Upgrade to Pro</Menu.Item>
+    <Menu.Separator />
+    <Menu.Group label="Settings">
+      <Menu.Item addon={<BadgeCheck aria-hidden size={16} />}>Account</Menu.Item>
+      <Menu.Item addon={<CreditCards aria-hidden size={16} />}>Billing</Menu.Item>
+      <Menu.Item addon={<Bell aria-hidden size={16} />}>Notifications</Menu.Item>
+    </Menu.Group>
+    <Menu.Separator />
+    <Menu.Item addon={<ArrowDoorOut aria-hidden size={16} />} sentiment="destructive">
+      Log out
+    </Menu.Item>
+  </Menu.Popup>
+</Menu>
+]]></tsx>
+    <notes>From preview-grid `menu-account`. Surface-chip Trigger + static profile header inside Popup + Group/Separator/destructive Item. Do not wrap Menu in Popover.</notes>
+  </example>
+
+  <example title="Report actions (check / radio / submenu)">
+    <tsx><![CDATA[
+<Menu>
+  <Menu.Trigger
+    render={
+      <Button size="s" addon={<ChevronDown aria-hidden size={16} />} variant="secondary">
+        Actions
+      </Button>
+    }
+  />
+  <Menu.Popup align="end" side="bottom">
+    <Menu.Group label="Edit">
+      <Menu.Item addon={<Pencil aria-hidden size={16} />} note="⌘E">
+        Rename report
+      </Menu.Item>
+      <Menu.Item addon={<Duplicate aria-hidden size={16} />} note="⌘D">
+        Duplicate
+      </Menu.Item>
+      <Menu.Item addon={<Archive aria-hidden size={16} />}>Archive</Menu.Item>
+    </Menu.Group>
+    <Menu.Separator />
+    <Menu.Group label="View">
+      <Menu.CheckboxItem addon={<Eye aria-hidden size={16} />} checked>
+        Show totals row
+      </Menu.CheckboxItem>
+      <Menu.CheckboxItem>Compact table rows</Menu.CheckboxItem>
     </Menu.Group>
-    <Menu.RadioGroup>
-      <Menu.RadioItem value="…" />
+    <Menu.Separator />
+    <Menu.RadioGroup label="Sort by" value="date">
+      <Menu.RadioItem value="date">Date</Menu.RadioItem>
+      <Menu.RadioItem value="amount">Amount</Menu.RadioItem>
+      <Menu.RadioItem value="recipient">Recipient</Menu.RadioItem>
     </Menu.RadioGroup>
     <Menu.Separator />
     <Menu.Submenu>
-      <Menu.SubmenuTrigger />
-      <Menu.Popup>…</Menu.Popup>
+      <Menu.SubmenuTrigger addon={<Link aria-hidden size={16} />}>Share</Menu.SubmenuTrigger>
+      <Menu.Popup side="inline-end">
+        <Menu.LinkItem href="#">Copy link</Menu.LinkItem>
+        <Menu.Item note="⌘⇧E">Export PDF</Menu.Item>
+        <Menu.Item>Send to team</Menu.Item>
+      </Menu.Popup>
     </Menu.Submenu>
+    <Menu.Separator />
+    <Menu.Item addon={<Trash aria-hidden size={16} />} sentiment="destructive">
+      Delete report
+    </Menu.Item>
+  </Menu.Popup>
+</Menu>
+]]></tsx>
+    <notes>From preview-grid `menu-actions`. Full item surface: Group, CheckboxItem, RadioGroup, Submenu + LinkItem, destructive. Drop checked-change handlers.</notes>
+  </example>
+
+  <example title="Row more-menu">
+    <tsx><![CDATA[
+<Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
+  <Stack rowGap="s">
+    <Text weight="semibold">Q2 payout report</Text>
+    <Text size="s" tone="muted">
+      PDF · Updated 2 hours ago
+    </Text>
+  </Stack>
+  <Menu>
+    <Menu.Trigger
+      render={
+        <IconButton
+          aria-label="More actions for Q2 payout report"
+          icon={<DotsVertical size={16} />}
+          pill
+          size="s"
+          variant="flat"
+        />
+      }
+    />
+    <Menu.Popup align="end" side="bottom">
+      <Menu.Item addon={<Pencil aria-hidden size={16} />}>Rename</Menu.Item>
+      <Menu.Item addon={<Duplicate aria-hidden size={16} />}>Duplicate</Menu.Item>
+      <Menu.Item addon={<Archive aria-hidden size={16} />}>Archive</Menu.Item>
+      <Menu.Separator />
+      <Menu.Item addon={<Trash aria-hidden size={16} />} sentiment="destructive">
+        Delete
+      </Menu.Item>
+    </Menu.Popup>
+  </Menu>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `menu-more`. IconButton Trigger on a list row. Drop Glow kitchen wrapper.</notes>
+  </example>
+
+  <example title="Base theme radio menu">
+    <tsx><![CDATA[
+<Menu>
+  <Menu.Trigger
+    aria-labelledby="base-theme-label base-theme-value"
+    render={
+      <Surface
+        color={2}
+        hPadding="m"
+        radius="m"
+        hoverColor={3}
+        render={<Stack render={<button type="button" />} />}
+        vPadding="m"
+      />
+    }
+  >
+    <Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
+      <Stack rowGap="s">
+        <Text id="base-theme-label" size="s" tone="muted">
+          Base theme
+        </Text>
+        <Title id="base-theme-value" lineHeight="xs" size="6">
+          Vira
+        </Title>
+      </Stack>
+      <ChevronExpandY aria-hidden size={24} />
+    </Stack>
+  </Menu.Trigger>
+  <Menu.Popup align="start" side="right">
+    <Menu.RadioGroup value="vira">
+      <Menu.RadioItem closeOnClick value="vira">
+        Vira
+      </Menu.RadioItem>
+      <Menu.RadioItem closeOnClick value="sunburst">
+        Sunburst
+      </Menu.RadioItem>
+      <Menu.RadioItem closeOnClick value="cinder">
+        Cinder
+      </Menu.RadioItem>
+    </Menu.RadioGroup>
   </Menu.Popup>
-</Menu>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+</Menu>
+]]></tsx>
+    <notes>From `editor/controls/base-theme-selector`. Surface-as-button Trigger + RadioGroup of themes. Drop preview-dwell handlers.</notes>
   </example>
 </patterns>

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

@@ -1,15 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="menu">
-  <do>Action menus anchored to a button or icon button</do>
-  <do>Nested command lists with checkbox or radio options that stay open on toggle</do>
-  <do>Link rows mixed with actions in one menu surface</do>
+  <do>Action menus anchored to Button or IconButton — not page-blocking flows (Dialog) or rich free-layout panels (Popover)</do>
+  <do>Nested command lists with `Menu.CheckboxItem` / `Menu.RadioGroup`+`Menu.RadioItem` (stay open on toggle by default) and `Menu.Submenu` + nested `Menu.Popup`</do>
+  <do>Mix `Menu.LinkItem` with action `Menu.Item` rows; group with `Menu.Group` / `Menu.Separator`</do>
+  <do>Account / user chip: `Menu.Trigger` as Surface/Stack (Avatar + Text) opening `Menu.Popup` with static profile header plus Items</do>
   <do>Detached or multi-trigger menus via `Menu.createHandle`</do>
-  <do>Account / user widgets: `Menu.Trigger` as a Surface chip (avatar + name + email) opening a Popup with a static profile header plus action items</do>
-  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on `Menu.Popup`</do>
   <dont>Expecting `Menu.Arrow`, `Menu.Backdrop`, or public Portal/Positioner/Viewport exports</dont>
-  <dont>Closing checkbox/radio items on click by default when the menu should stay open for multi-toggle</dont>
+  <dont>Closing checkbox/radio items on click by default when the menu should stay open for multi-toggle — pass `closeOnClick` only when a single pick should dismiss</dont>
   <dont>Using physical left/right CSS that breaks RTL submenu chevrons</dont>
   <dont>Expecting RTL item rows / left-opening submenus without Base UI `DirectionProvider direction=&quot;rtl&quot;` plus app `dir=&quot;rtl&quot;` on a portal ancestor (usually `&lt;html&gt;` / document root — a local wrapper alone does not reach body-mounted popups)</dont>
   <dont>Nesting Menu inside Popover for an account menu — Menu already owns portal, positioning, and listbox keyboard behavior</dont>
-  <dont>Putting focusable controls (inputs, nested buttons) in `Menu.Popup` outside `Menu.Item` / `Menu.LinkItem` / checkbox / radio / submenu trigger parts</dont>
+  <dont>Putting focusable controls (inputs, nested buttons) in `Menu.Popup` outside `Menu.Item` / `Menu.LinkItem` / checkbox / radio / submenu trigger parts — use Popover or Dialog for forms</dont>
+  <dont>Using Menu for form-field single-select from a long list — use Select</dont>
 </usage>

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

@@ -1,7 +1,53 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="meter">
-  <example title="Meter structure">
-    <tsx><![CDATA[<Meter value={40} />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: preview-grid blocks — cleaned (no handlers, no kitchen chrome). -->
+
+  <example title="Workspace usage stack">
+    <tsx><![CDATA[
+<Stack rowGap="l">
+  <Meter label="Storage" renderValue value={74} description="74 GB of 100 GB" />
+  <Meter
+    label="API quota"
+    renderValue
+    value={18400}
+    min={0}
+    max={25000}
+    locale="en-US"
+    format={{ maximumFractionDigits: 0 }}
+    description={
+      <>
+        <code>18,400</code> of <code>25,000</code> requests this month
+      </>
+    }
+  />
+  <Meter
+    renderValue
+    value={91}
+    label={
+      <Stack direction="row" columnGap="xs" vAlign="center">
+        <Sun aria-hidden size={16} />
+        <span>Backup health</span>
+      </Stack>
+    }
+  />
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `workspace-usage`. Capacity metrics use Meter (not LinearProgress). `label` may be a Stack with decorative icon; `format`/`locale` tune printed `renderValue`.</notes>
+  </example>
+
+  <example title="Pace check in nested sheet">
+    <tsx><![CDATA[
+<Surface color={2} radius="l" hPadding="m" vPadding="m">
+  <Meter
+    description="Today's intake against the draft goal."
+    label="Pace check"
+    max={350}
+    min={0}
+    renderValue
+    value={220}
+  />
+</Surface>
+]]></tsx>
+    <notes>From preview-grid `daily-activity-goal` nested tips sheet. Meter for score-within-range; LinearProgress stays on the live activity track outside the dialog.</notes>
   </example>
 </patterns>