@viraui/react 2026.7.0 → 2026.8.0

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

@@ -6,7 +6,9 @@
   <do>Separated islands with root `islands`; attached block corners when `islands={false}`</do>
   <do>Insert `Separator` between items when `Item` `useSurface={false}`</do>
   <do>Multiple open sections with root `multiple` (+ `defaultValue` / `value` as needed)</do>
+  <do>Omit `size` / width / height on Item `iconClosed` / `iconOpen` glyphs unless expressly overriding — prefer chrome/host default</do>
   <dont>Trying to compose separate public `Accordion.Header`, `Accordion.Trigger`, or `Accordion.Panel` exports — those stay inside `Accordion.Item`</dont>
+  <dont>Passing `size=&quot;1rem&quot;` on every Accordion icon by habit — omit unless expressly overriding</dont>
   <dont>Rendering an item without trigger text and without an external aria-label strategy</dont>
   <dont>Using Accordion for a single expandable section — use Disclosure</dont>
   <dont>Using Accordion for primary navigation that should be links, Tabs, or routes</dont>

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

@@ -11,7 +11,7 @@
   placeholder="Search by name…"
   items={reviewers}
   itemToStringValue={(person) => person.label}
-  startAddon={<Magnifier aria-hidden size={16} />}
+  startAddon={<Magnifier aria-hidden />}
 >
   {(person) => (
     <Autocomplete.Item
@@ -36,7 +36,7 @@
   placeholder="SaaS, travel, contractors…"
   items={expenseCategories}
   itemToStringValue={(category) => category.label}
-  startAddon={<Magnifier aria-hidden size={16} />}
+  startAddon={<Magnifier aria-hidden />}
 >
   {(category) => (
     <Autocomplete.Item key={category.id} value={category}>
@@ -57,7 +57,7 @@
   placeholder="Paris, Austin, Singapore…"
   items={transferDesks}
   itemToStringValue={(desk) => desk.label}
-  startAddon={<Magnifier aria-hidden size={16} />}
+  startAddon={<Magnifier aria-hidden />}
 >
   {(group) => (
     <Autocomplete.Group key={group.value} items={group.items} label={group.value}>
@@ -85,7 +85,7 @@
   items={results}
   itemToStringValue={(article) => article.title}
   placeholder="Wire limits, SEPA, tax forms…"
-  startAddon={<Magnifier aria-hidden size={16} />}
+  startAddon={<Magnifier aria-hidden />}
   status={
     <Stack columnGap="s" direction="row" vAlign="center">
       <Spinner aria-hidden size="s" />

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

@@ -25,7 +25,7 @@
     <description>Content rendered inside baked `Autocomplete.Empty` when the filtered list has no items.</description>
   </prop>
   <prop name="endAddon" kind="react">
-    <description>Trailing decoration (icon, button). Buttons must use `type=&quot;button&quot;`.</description>
+    <description>Trailing decoration (icon, button). Buttons must use `type=&quot;button&quot;`. Omit glyph `size` / width / height on icons unless expressly overriding; IconButton/Button hosts own SVG size via CSS.</description>
   </prop>
   <prop name="error" kind="react">
     <description>Error copy rendered with `Field.Error` and `Text` in the same slot as `description`. Replaces description while the field is invalid and dirty.</description>
@@ -52,7 +52,7 @@
     <description>Ref forwarded to the autocomplete input.</description>
   </prop>
   <prop name="startAddon" kind="react">
-    <description>Leading decoration (prefix text, icon). Not a second field control.</description>
+    <description>Leading decoration (prefix text, icon). Not a second field control. Omit glyph `size` / width / height on icons unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="status" kind="react">
     <description>Content rendered inside baked `Autocomplete.Status` (async / limit messaging). Keep the slot mounted; update children when status changes.</description>

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

@@ -4,7 +4,7 @@
   <do>Prefer Autocomplete over Select when users may type a value not in the list (tags, categories, search)</do>
   <do>Form section: Fieldset legend + Autocomplete with sibling Textfield/Select when they share one section — Stack owns gap</do>
   <do>Fill a form column via a parent Stack `fullWidth` / `expandChildren` (Autocomplete has no `fullWidth` prop) — not CSS `width: 100%`</do>
-  <do>`startAddon` / `endAddon` for leading/trailing chrome (same control-group pattern as Textfield) — IconButton/Button addons use `size=&quot;s&quot;` and `type=&quot;button&quot;`</do>
+  <do>`startAddon` / `endAddon` for leading/trailing chrome (same control-group pattern as Textfield) — IconButton/Button addons use control `size=&quot;s&quot;` and `type=&quot;button&quot;`; omit glyph `size` / width / height on icons</do>
   <do>Grouped suggestion lists via `Autocomplete.Group` + `Autocomplete.Collection`; item rows via `Autocomplete.Item` `addon` (e.g. Avatar)</do>
   <do>Async or limited result lists: pass `empty` for no-match copy; keep root `status` mounted and update its children — Spinner + Text inside `status` is fine</do>
   <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>

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

@@ -81,10 +81,10 @@
   <example title="Flat addon links (clone)">
     <tsx><![CDATA[
 <Stack hAlign="start" rowGap="2xs">
-  <Button addon={<CircleImage size={18} />} variant="flat" size="s">
+  <Button addon={<CircleImage />} variant="flat" size="s">
     Open with GitHub Desktop
   </Button>
-  <Button addon={<ArrowDown size={18} />} variant="flat" size="s">
+  <Button addon={<ArrowDown />} variant="flat" size="s">
     Download ZIP
   </Button>
 </Stack>

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

@@ -13,7 +13,7 @@
     <item>Forcing full panel width with CSS `width: 100%` / `w-full` — wrap in Stack with `fullWidth` and/or `expandChildren` (see stack units)</item>
   </when_not_to_use>
   <prop name="addon" kind="react">
-    <description>Decorative addon rendered alongside the button label. Pass any React element; use a named icon from `@viraui/icons/react` or `&lt;Chip /&gt;` for status chips.</description>
+    <description>Decorative addon rendered alongside the button label. Pass any React element; use a named icon from `@viraui/icons/react` or `&lt;Chip /&gt;` for status chips. Omit glyph `size` / width / height — Button CSS sizes SVG via `--vui-button-icon-size`.</description>
   </prop>
   <prop name="addonPosition" kind="react">
     <description>Controls whether the addon appears before or after the label.</description>
@@ -31,7 +31,7 @@
     <description>Selects the visual treatment for the button.</description>
   </prop>
   <prop name="addon" kind="react">
-    <description>Decorative addon rendered alongside the link label. (button-link)</description>
+    <description>Decorative addon rendered alongside the link label. Omit glyph `size` / width / height — host CSS sizes SVG. (button-link)</description>
   </prop>
   <prop name="addonPosition" kind="react">
     <description>Controls whether the addon appears before or after the label. (button-link)</description>
@@ -61,7 +61,7 @@
     <description>Button block size; size prop presets via data attributes.</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button.</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode.</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button.</description>
@@ -85,7 +85,7 @@
     <description>Button block size; size prop presets via data attributes. (button-link)</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button. (button-link)</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode. (button-link)</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button. (button-link)</description>

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

@@ -8,10 +8,11 @@
   <do>Dialog / sheet action strips: Stack row of Button + ButtonLink; Cancel via `Dialog.Close render={&lt;Button variant=&quot;secondary&quot; /&gt;}`</do>
   <do>Primary Chip addons inside a primary Button — set `data-mode=&quot;inverted&quot;` on the Chip so its fill contrasts</do>
   <do>Navigation that should look like Button — use ButtonLink (framework Link via `render`; sets `data-no-link-style` so preflight underline does not fight button paint)</do>
+  <do>Omit `size` / width / height on `addon` icons — host CSS sets `--vui-button-icon-size` from control `size`; set glyph size only to expressly override</do>
   <dont>Using Button without children as icon-only — prefer IconButton</dont>
   <dont>Using Button with `render={&lt;a /&gt;}` for links — Base UI enforces button semantics; use ButtonLink</dont>
   <dont>Inventing `width: 100%` / `inline-size: 100%` / `w-full` / `.fullWidth` / size-fill `className` (e.g. `.Submit`) on Button when a parent Stack can own the fill</dont>
-  <dont>Duplicating icon size on every addon slot — Button CSS sizes SVG descendants</dont>
+  <dont>Passing `size={16}` / `size=&quot;1rem&quot;` (or width/height) on every `addon` icon — Button CSS sizes SVG descendants via `--vui-button-icon-size`</dont>
   <dont>Mixing `pill` with custom border-radius overrides that fight `data-pill` styling</dont>
   <dont>Primary Chip addon inside a primary Button without `data-mode=&quot;inverted&quot;` — chip fill matches the button and disappears</dont>
   <dont>Forcing `role=&quot;button&quot;` on a link</dont>

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

@@ -10,7 +10,7 @@
     Deploying
   </Chip>
   <Chip variant="yellow">Queued</Chip>
-  <Chip variant="red" addon={<Xmark size={14} />}>
+  <Chip variant="red" addon={<Xmark />}>
     Failed
   </Chip>
   <Chip variant="salmon">Rolled back</Chip>
@@ -30,7 +30,7 @@
       $0.00
     </Title>
   </Stack>
-  <Chip variant="outline" addon={<CircleCross size={8} color="var(--highlight-yellow)" />}>
+  <Chip variant="outline" addon={<CircleCross color="var(--highlight-yellow)" />}>
     Pending Setup
   </Chip>
 </Stack>

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

@@ -11,7 +11,7 @@
     <item>Long-form text content that should wrap like body copy — use Text</item>
   </when_not_to_use>
   <prop name="addon" kind="react">
-    <description>Decorative addon rendered alongside the chip label.</description>
+    <description>Decorative addon rendered alongside the chip label. Omit glyph `size` / width / height — Chip CSS sizes SVG via `--vui-chip-icon-size`.</description>
   </prop>
   <prop name="addonPosition" kind="react">
     <description>Controls whether the addon appears before or after the label.</description>
@@ -44,6 +44,6 @@
     <description>Fixed chip block size.</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Decorative addon icon size.</description>
+    <description>Decorative addon icon size (`--vui-chip-icon-size`). Prefer this over setting `size` on the glyph ReactNode.</description>
   </prop>
 </props>

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

@@ -4,10 +4,12 @@
   <do>Metadata, category, status, or inline tag-like presentation in Stack rows with Text / Title</do>
   <do>Color-coded status via highlight `variant` values (`green`, `red`, `yellow`, …) or `primary` / `secondary` / `outline`</do>
   <do>Primary Chip as Button `addon` — set `data-mode=&quot;inverted&quot;` on the Chip when the Button is primary so fills contrast</do>
+  <do>Omit `size` / width / height on `addon` icons — Chip CSS sets `--vui-chip-icon-size`; set glyph size only to expressly override</do>
   <do>Equal-width Chip clusters: wrap in Stack with `fullWidth` and/or `expandChildren` — never per-Chip width CSS</do>
   <do>Polymorphic label root via `render` (default `div`; Chip sets `data-no-link-style` so Chip-as-`&lt;a&gt;` keeps chip chrome)</do>
   <dont>Using Chip as a button replacement for clickable actions — use Button or IconButton</dont>
   <dont>Expecting `addonPosition` to have any effect when `addon` is omitted</dont>
+  <dont>Passing `size={16}` / width / height on every Chip `addon` icon — Chip CSS sizes SVG descendants</dont>
   <dont>Introducing custom size variants instead of the fixed compact height</dont>
   <dont>Re-adding a one-off destructive variant instead of `variant=&quot;red&quot;`</dont>
   <dont>Primary Chip inside a primary Button without `data-mode=&quot;inverted&quot;` — chip fill matches the button and disappears</dont>

package/dist/specs/components/direction-provider/a11y.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="direction-provider">
+  <rule>Not an APG widget — direction context only; keep accessible names and semantics when flipping LTR/RTL</rule>
+  <rule>Pair provider `direction=&quot;rtl&quot;` with document `dir=&quot;rtl&quot;` so CSS logical properties and portaled overlays stay consistent for assistive tech and visual layout</rule>
+  <rule>Do not rely on mirrored chrome alone to communicate meaning that must stay in the accessible name</rule>
+</a11y>

package/dist/specs/components/direction-provider/meta.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="direction-provider" title="DirectionProvider" category="layout" shared_contract="direction-provider">
+  <summary>Transparent re-export of Base UI DirectionProvider and useDirection. Enables RTL behavior for Base UI–backed components; does not set HTML dir or CSS direction — pair with document dir=rtl on a portal ancestor (usually html).</summary>
+  <exports>
+    <export name="DirectionProvider" />
+    <export name="useDirection" />
+  </exports>
+  <related>
+    <ref id="menu" />
+    <ref id="slider" />
+    <ref id="select" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/utils/direction-provider#api-reference" />
+</meta>

package/dist/specs/components/direction-provider/patterns.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="direction-provider">
+  <example title="RTL subtree with Slider">
+    <tsx><![CDATA[
+<div dir="rtl">
+  <DirectionProvider direction="rtl">
+    <Slider defaultValue={25} label="Volume" />
+  </DirectionProvider>
+</div>
+]]></tsx>
+    <notes>Transparent Base UI re-export. Provider feeds Base UI context; `dir` on an ancestor owns HTML/CSS direction. For app-wide RTL set `dir` on `html`. Upstream: https://base-ui.com/react/utils/direction-provider</notes>
+  </example>
+
+  <example title="Read direction in a portal-safe hook">
+    <tsx><![CDATA[
+function DirectionLabel() {
+  const direction = useDirection();
+  return <Text size="s">Direction: {direction}</Text>;
+}
+
+<DirectionProvider direction="rtl">
+  <DirectionLabel />
+</DirectionProvider>
+]]></tsx>
+    <notes>`useDirection` reads the provider context — useful when portaled trees are outside a local `dir` wrapper.</notes>
+  </example>
+</patterns>

package/dist/specs/components/direction-provider/props.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="direction-provider">
+  <when_to_use>
+    <item>RTL apps that need Base UI–backed Vira menus, sliders, selects, and other direction-aware primitives to flip behavior</item>
+    <item>Reading the active text direction in portaled trees via `useDirection` when `dir` on html is not enough</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Expecting this provider alone to flip HTML/CSS layout — also set `dir=&quot;rtl&quot;` (or `direction: rtl`) on a portal ancestor, usually `&lt;html&gt;`</item>
+    <item>Mandatory root chrome — opt-in like BreakpointsProvider; not part of Dialog/Tooltip/Toast overlay shell</item>
+    <item>Inventing a Vira wrapper API — this surface is a transparent Base UI re-export</item>
+  </when_not_to_use>
+  <prop name="children" kind="react">
+    <description>Tree that should receive Base UI direction context. Pass-through from Base UI.</description>
+  </prop>
+  <prop name="direction" kind="react">
+    <description>Reading direction: `ltr` (default) or `rtl`. Pass-through from Base UI — see upstream API.</description>
+  </prop>
+</props>

package/dist/specs/components/direction-provider/usage.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="direction-provider">
+  <do>Import `DirectionProvider` / `useDirection` from `@viraui/react` — transparent Base UI re-export; full API → https://base-ui.com/react/utils/direction-provider</do>
+  <do>Wrap the app (or RTL subtree) in `DirectionProvider direction=&quot;rtl&quot;` and set `dir=&quot;rtl&quot;` on a portal ancestor (usually `&lt;html&gt;`) so body-mounted popups inherit CSS direction</do>
+  <do>Use `useDirection` when a portaled component needs the context direction without reading the DOM `dir` attribute</do>
+  <dont>Assuming `DirectionProvider` sets HTML `dir` or CSS `direction` — it only feeds Base UI context</dont>
+  <dont>Setting `dir=&quot;rtl&quot;` only on a local wrapper when popups portal to `document.body` — use `html` / document root</dont>
+  <dont>Importing `@base-ui/react/direction-provider` directly in Vira apps when `@viraui/react` already re-exports it</dont>
+  <dont>Treating this as required overlay bootstrap — Dialog/Tooltip/Toast providers stay separate; DirectionProvider is opt-in for RTL</dont>
+</usage>

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

@@ -22,9 +22,9 @@
   <Disclosure.Trigger
     hPadding="m"
     interpolateIcons
-    openIcon={<Xmark size="1rem" />}
+    openIcon={<Xmark />}
     radius="m"
-    restingIcon={<Plus size="1rem" />}
+    restingIcon={<Plus />}
     vPadding="m"
   >
     Advanced

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

@@ -10,10 +10,10 @@
     <item>Primary navigation that should use links, Tabs, or routes</item>
   </when_not_to_use>
   <prop name="Trigger.restingIcon" kind="react">
-    <description>Decorative icon while the panel is closed. Defaults to ChromeChevronEnd when both icon slots are omitted.</description>
+    <description>Decorative icon while the panel is closed. Defaults to ChromeChevronEnd when both icon slots are omitted. Omit glyph `size` / width / height — Disclosure CSS sizes SVG in the icon box.</description>
   </prop>
   <prop name="Trigger.openIcon" kind="react">
-    <description>Decorative icon while the panel is open. Defaults to ChromeChevronDown when both icon slots are omitted. When only restingIcon is set, that icon shows in both states.</description>
+    <description>Decorative icon while the panel is open. Defaults to ChromeChevronDown when both icon slots are omitted. When only restingIcon is set, that icon shows in both states. Omit glyph `size` / width / height — host CSS sizes SVG.</description>
   </prop>
   <prop name="Trigger.interpolateIcons" kind="react">
     <description>When dual icons are present, crossfade and light-rotate between them (`data-interpolate=&quot;true&quot;`). When false, swap instantly with no transition.</description>

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

@@ -4,8 +4,10 @@
   <do>Spread Surface chrome on Trigger (`color`, `hoverColor`, `border`, `radius`, padding) when using the default host</do>
   <do>Supply Panel children layout (Stack/padding) yourself — Panel has no default content padding</do>
   <do>Use `restingIcon` / `openIcon` / `interpolateIcons` for ToggleButton-style icon pairs; omit both for chrome chevron End/Down</do>
+  <do>Omit `size` / width / height on Trigger icon glyphs — Disclosure CSS sizes SVG in the icon box; set glyph size only to expressly override</do>
   <do>Pass Trigger `render` when replacing the Surface compose entirely</do>
   <dont>Using Accordion for a single section — Accordion is multi-item</dont>
   <dont>Expecting Accordion-like default Panel padding from Disclosure.Panel</dont>
+  <dont>Passing `size=&quot;1rem&quot;` / width / height on every Trigger icon glyph — host CSS sizes SVG descendants</dont>
   <dont>Relying on icon animation alone for open/closed meaning under reduced motion</dont>
 </usage>

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

@@ -19,7 +19,7 @@
           render={
             <IconButton
               aria-label="More actions for Q2 payout report"
-              icon={<DotsVertical size={16} />}
+              icon={<DotsVertical />}
               pill
               size="s"
               variant="flat"

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

@@ -38,13 +38,13 @@
 <Surface border="all" color={1} radius="l" hPadding="m" vPadding="m">
   <Grid columns={7} rows={6} columnGap="m" rowGap="m">
     <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
-      <IconButton aria-label="Home" icon={<House size={22} aria-hidden />} variant="flat" />
+      <IconButton aria-label="Home" icon={<House aria-hidden />} variant="flat" />
     </Grid.Item>
     <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
-      <IconButton aria-label="Search" icon={<Magnifier size={22} aria-hidden />} variant="flat" />
+      <IconButton aria-label="Search" icon={<Magnifier aria-hidden />} variant="flat" />
     </Grid.Item>
     <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
-      <IconButton aria-label="Settings" icon={<Gear size={22} aria-hidden />} variant="flat" />
+      <IconButton aria-label="Settings" icon={<Gear aria-hidden />} variant="flat" />
     </Grid.Item>
     {/* more IconButtons… */}
   </Grid>

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

@@ -12,7 +12,7 @@
     <item>Temporally swap icons after user interactions with temporal pressed state, like copy feedback. Use ToggleButton instead</item>
   </when_not_to_use>
   <prop name="icon" kind="react">
-    <description>Icon rendered as the sole visible control content.</description>
+    <description>Icon rendered as the sole visible control content. Omit glyph `size` / width / height — host CSS sizes SVG via `--vui-button-icon-size`.</description>
   </prop>
   <prop name="loading" kind="react">
     <description>Shows a centered spinner overlay while preserving the original content width.</description>
@@ -27,7 +27,7 @@
     <description>Selects the visual treatment for the button.</description>
   </prop>
   <prop name="icon" kind="react">
-    <description>Icon rendered as the sole visible control content. (icon-button-link)</description>
+    <description>Icon rendered as the sole visible control content. Omit glyph `size` / width / height — host CSS sizes SVG. (icon-button-link)</description>
   </prop>
   <prop name="loading" kind="react">
     <description>Shows a centered spinner overlay while preserving the original content width. Sets `aria-disabled` / `aria-busy` for loading chrome; link stays activatable. (icon-button-link)</description>
@@ -54,7 +54,7 @@
     <description>Button block size; size prop presets via data attributes.</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button.</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode.</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button.</description>
@@ -78,7 +78,7 @@
     <description>Button block size; size prop presets via data attributes. (icon-button-link)</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button. (icon-button-link)</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode. (icon-button-link)</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button. (icon-button-link)</description>

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

@@ -3,8 +3,9 @@
   <do>Compact toolbar or chrome actions identified only by icon</do>
   <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>Omit `size` / width / height on the `icon` glyph — host CSS sizes SVG via `--vui-button-icon-size`; set glyph size only to expressly override</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>Textfield `endAddon` / `startAddon` for compact field chrome (e.g. copy) — keep addon control `size=&quot;s&quot;` (control size, not glyph size)</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>
@@ -12,5 +13,6 @@
   <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>Passing `size={16}` / `size=&quot;1rem&quot;` (or width/height) on the `icon` glyph — IconButton CSS sizes SVG descendants</dont>
   <dont>Inventing `width: 100%` / `inline-size: 100%` / `w-full` / size-fill `className` (e.g. `.Social`) on IconButton — it is intentionally square; Stack owns gap/align only</dont>
 </usage>

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

@@ -18,7 +18,7 @@
               </Text>
             </Stack>
           </Stack>
-          <ChevronExpandY aria-hidden size={16} />
+          <ChevronExpandY aria-hidden />
         </Stack>
       </Stack>
     }
@@ -36,15 +36,15 @@
       </Stack>
     </Stack>
     <Menu.Separator />
-    <Menu.Item addon={<StarUpgrade aria-hidden size={16} />}>Upgrade to Pro</Menu.Item>
+    <Menu.Item addon={<StarUpgrade aria-hidden />}>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.Item addon={<BadgeCheck aria-hidden />}>Account</Menu.Item>
+      <Menu.Item addon={<CreditCards aria-hidden />}>Billing</Menu.Item>
+      <Menu.Item addon={<Bell aria-hidden />}>Notifications</Menu.Item>
     </Menu.Group>
     <Menu.Separator />
-    <Menu.Item addon={<ArrowDoorOut aria-hidden size={16} />} sentiment="destructive">
+    <Menu.Item addon={<ArrowDoorOut aria-hidden />} sentiment="destructive">
       Log out
     </Menu.Item>
   </Menu.Popup>
@@ -58,24 +58,24 @@
 <Menu>
   <Menu.Trigger
     render={
-      <Button size="s" addon={<ChevronDown aria-hidden size={16} />} variant="secondary">
+      <Button size="s" addon={<ChevronDown aria-hidden />} variant="secondary">
         Actions
       </Button>
     }
   />
   <Menu.Popup align="end" side="bottom">
     <Menu.Group label="Edit">
-      <Menu.Item addon={<Pencil aria-hidden size={16} />} note="⌘E">
+      <Menu.Item addon={<Pencil aria-hidden />} note="⌘E">
         Rename report
       </Menu.Item>
-      <Menu.Item addon={<Duplicate aria-hidden size={16} />} note="⌘D">
+      <Menu.Item addon={<Duplicate aria-hidden />} note="⌘D">
         Duplicate
       </Menu.Item>
-      <Menu.Item addon={<Archive aria-hidden size={16} />}>Archive</Menu.Item>
+      <Menu.Item addon={<Archive aria-hidden />}>Archive</Menu.Item>
     </Menu.Group>
     <Menu.Separator />
     <Menu.Group label="View">
-      <Menu.CheckboxItem addon={<Eye aria-hidden size={16} />} checked>
+      <Menu.CheckboxItem addon={<Eye aria-hidden />} checked>
         Show totals row
       </Menu.CheckboxItem>
       <Menu.CheckboxItem>Compact table rows</Menu.CheckboxItem>
@@ -88,7 +88,7 @@
     </Menu.RadioGroup>
     <Menu.Separator />
     <Menu.Submenu>
-      <Menu.SubmenuTrigger addon={<Link aria-hidden size={16} />}>Share</Menu.SubmenuTrigger>
+      <Menu.SubmenuTrigger addon={<Link aria-hidden />}>Share</Menu.SubmenuTrigger>
       <Menu.Popup side="inline-end">
         <Menu.LinkItem href="#">Copy link</Menu.LinkItem>
         <Menu.Item note="⌘⇧E">Export PDF</Menu.Item>
@@ -96,7 +96,7 @@
       </Menu.Popup>
     </Menu.Submenu>
     <Menu.Separator />
-    <Menu.Item addon={<Trash aria-hidden size={16} />} sentiment="destructive">
+    <Menu.Item addon={<Trash aria-hidden />} sentiment="destructive">
       Delete report
     </Menu.Item>
   </Menu.Popup>
@@ -119,7 +119,7 @@
       render={
         <IconButton
           aria-label="More actions for Q2 payout report"
-          icon={<DotsVertical size={16} />}
+          icon={<DotsVertical />}
           pill
           size="s"
           variant="flat"
@@ -127,11 +127,11 @@
       }
     />
     <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.Item addon={<Pencil aria-hidden />}>Rename</Menu.Item>
+      <Menu.Item addon={<Duplicate aria-hidden />}>Duplicate</Menu.Item>
+      <Menu.Item addon={<Archive aria-hidden />}>Archive</Menu.Item>
       <Menu.Separator />
-      <Menu.Item addon={<Trash aria-hidden size={16} />} sentiment="destructive">
+      <Menu.Item addon={<Trash aria-hidden />} sentiment="destructive">
         Delete
       </Menu.Item>
     </Menu.Popup>

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

@@ -16,7 +16,7 @@
     <item>Rich non-menu panels with forms or free layout (use Popover / Dialog — do not wrap Menu in Popover)</item>
   </when_not_to_use>
   <prop name="CheckboxItem.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="CheckboxItem.note" kind="react">
     <description>End-aligned secondary text (e.g. keyboard shortcut) before the check indicator. Rendered muted `xs`.</description>
@@ -28,7 +28,7 @@
     <description>Accessible group label rendered with `Menu.GroupLabel`.</description>
   </prop>
   <prop name="Item.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="Item.note" kind="react">
     <description>End-aligned secondary text (e.g. keyboard shortcut). Rendered muted `xs`.</description>
@@ -37,7 +37,7 @@
     <description>Visual sentiment. `destructive` uses highlight-red wash + text.</description>
   </prop>
   <prop name="LinkItem.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="LinkItem.note" kind="react">
     <description>End-aligned secondary text (e.g. keyboard shortcut). Rendered muted `xs`.</description>
@@ -55,7 +55,7 @@
     <description>Optional accessible group label rendered with `Menu.GroupLabel`.</description>
   </prop>
   <prop name="RadioItem.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="RadioItem.note" kind="react">
     <description>End-aligned secondary text (e.g. keyboard shortcut) before the check indicator. Rendered muted `xs`.</description>
@@ -64,7 +64,7 @@
     <description>Visual sentiment. `destructive` uses highlight-red wash + text.</description>
   </prop>
   <prop name="SubmenuTrigger.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="SubmenuTrigger.sentiment" kind="react">
     <description>Visual sentiment. `destructive` uses highlight-red wash + text.</description>

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

@@ -6,10 +6,12 @@
   <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>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on `Menu.Popup`</do>
+  <do>Omit `size` / width / height on Item / LinkItem / checkbox / radio / submenu `addon` icons — prefer icon-library default; set only to expressly override</do>
   <dont>Expecting `Menu.Arrow`, `Menu.Backdrop`, or public Portal/Positioner/Viewport exports</dont>
+  <dont>Passing `size={16}` on every menu `addon` icon by habit — omit unless expressly overriding the library default</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>Expecting RTL item rows / left-opening submenus without `@viraui/react` `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 — use Popover or Dialog for forms</dont>
   <dont>Using Menu for form-field single-select from a long list — use Select</dont>

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

@@ -25,7 +25,7 @@
     value={91}
     label={
       <Stack direction="row" columnGap="xs" vAlign="center">
-        <Sun aria-hidden size={16} />
+        <Sun aria-hidden />
         <span>Backup health</span>
       </Stack>
     }

package/dist/specs/components/progressive-blur/usage.xml

@@ -4,8 +4,10 @@
   <do>Edge scrim on glass / `data-vibrant` Surface heroes, sheets, or scroll regions where content should fade into blur</do>
   <do>Keep semantics and layout on Surface/Stack/Title/Text children underneath — ProgressiveBlur is decorative atmosphere only</do>
   <do>Use sparingly — stacked `backdrop-filter` is GPU/memory-heavy; prefer one focal overlay per view</do>
+  <do>Rounded scroll shells: clip with Surface `overflow` + `radius`, mount ProgressiveBlur as a sibling overlay, set matching `border-radius` on the blur root (layers inherit)</do>
   <dont>Leaving the ProgressiveBlur root `position: static` so absolute layers escape the intended overlay box</dont>
   <dont>Driving layout size or scroll behavior from inside the overlay</dont>
   <dont>Scattering ProgressiveBlur across many cards or stacking full-viewport instances</dont>
   <dont>Using ProgressiveBlur as standalone loading or status feedback without a labeled parent region</dont>
+  <dont>Nesting under an ancestor that pairs overflow clipping with border-radius (e.g. Surface `overflow="hidden"` + `radius`) — Chromium drops masked backdrop-filter</dont>
 </usage>

package/dist/specs/components/prose/meta.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="prose" title="Prose" category="typography" shared_contract="prose">
-  <summary>Grouping region that applies heading-aware em rhythm to direct document blocks.</summary>
+  <summary>Text-wall grouping region (articles, docs, privacy) with heading-aware em rhythm; reading column via parent Stack `maxWidth` sized for body Text `size`.</summary>
   <exports>
     <export name="Prose" />
   </exports>