@viraui/react 2026.3.11 → 2026.4.0

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="icon-button">
+  <example title="IconButton structure">
+    <tsx><![CDATA[<IconButton icon={<Plus />} aria-label="Add" />]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+  <example title="IconButtonLink structure">
+    <tsx><![CDATA[<IconButtonLink href="#" icon={<Plus />} aria-label="Add" />]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="icon-button">
+  <when_to_use>
+    <item>Compact toolbar or chrome actions identified only by icon</item>
+    <item>Same size, variant, and loading model as Button without visible label</item>
+    <item>Decorative glyph with explicit accessible naming on the root button</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Actions that need visible text — use Button</item>
+    <item>Missing both aria-label and aria-labelledby</item>
+    <item>Navigation or non-button semantics — use IconButtonLink</item>
+    <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>
+  </prop>
+  <prop name="loading" kind="react">
+    <description>Shows a centered spinner overlay while preserving the original content width.</description>
+  </prop>
+  <prop name="pill" kind="react">
+    <description>Applies a fully rounded pill shape to the button.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Controls the visual button size.</description>
+  </prop>
+  <prop name="variant" kind="react">
+    <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>
+  </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>
+  </prop>
+  <prop name="pill" kind="react">
+    <description>Applies a fully rounded pill shape. (icon-button-link)</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `a` root using Base UI render semantics (e.g. Next.js `Link`). (icon-button-link)</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Controls the visual button size. (icon-button-link)</description>
+  </prop>
+  <prop name="variant" kind="react">
+    <description>Selects the visual treatment matching Button. (icon-button-link)</description>
+  </prop>
+  <css_var suffix="background">
+    <description>Button fill; variant and state selectors preset this.</description>
+  </css_var>
+  <css_var suffix="color">
+    <description>Button label and icon color.</description>
+  </css_var>
+  <css_var suffix="height">
+    <description>Button block size; size prop presets via data attributes.</description>
+  </css_var>
+  <css_var suffix="icon-size">
+    <description>Addon icon size inside the button.</description>
+  </css_var>
+  <css_var suffix="padding-block">
+    <description>Vertical padding inside the button.</description>
+  </css_var>
+  <css_var suffix="padding-inline">
+    <description>Horizontal padding inside the button.</description>
+  </css_var>
+  <css_var suffix="radius">
+    <description>Corner radius; pill sets infinite radius via data-pill.</description>
+  </css_var>
+  <css_var suffix="spinner-color">
+    <description>Loading spinner color on the root.</description>
+  </css_var>
+  <css_var suffix="background">
+    <description>Button fill; variant and state selectors preset this. (icon-button-link)</description>
+  </css_var>
+  <css_var suffix="color">
+    <description>Button label and icon color. (icon-button-link)</description>
+  </css_var>
+  <css_var suffix="height">
+    <description>Button block size; size prop presets via data attributes. (icon-button-link)</description>
+  </css_var>
+  <css_var suffix="icon-size">
+    <description>Addon icon size inside the button. (icon-button-link)</description>
+  </css_var>
+  <css_var suffix="padding-block">
+    <description>Vertical padding inside the button. (icon-button-link)</description>
+  </css_var>
+  <css_var suffix="padding-inline">
+    <description>Horizontal padding inside the button. (icon-button-link)</description>
+  </css_var>
+  <css_var suffix="radius">
+    <description>Corner radius; pill sets infinite radius via data-pill. (icon-button-link)</description>
+  </css_var>
+  <css_var suffix="spinner-color">
+    <description>Loading spinner color on the root. (icon-button-link)</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,14 @@
+<?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>
+  <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>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="linear-progress">
+  <rule>Provide a visible `label` or an accessible name through Base UI progress props when the task is not otherwise clear.</rule>
+  <rule>Use determinate numeric `value` when actual progress is known.</rule>
+  <rule>Use `value={null}` only for truly indeterminate work.</rule>
+</a11y>

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

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="linear-progress" title="LinearProgress" category="feedback" shared_contract="linear-progress">
+  <summary>Shows determinate or indeterminate progress for a task in a compact horizontal track.</summary>
+  <exports>
+    <export name="LinearProgress" />
+  </exports>
+  <related>
+    <ref id="slider" />
+    <ref id="spinner" />
+    <ref id="skeleton" />
+    <ref id="text" />
+    <ref id="meter" />
+  </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/components/progress#api-reference" />
+</meta>

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

@@ -0,0 +1,7 @@
+<?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>
+  </example>
+</patterns>

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

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="linear-progress">
+  <when_to_use>
+    <item>Use for task completion with a known percentage or bounded numeric value.</item>
+    <item>Use with `value={null}` when progress is active but the amount complete is unknown.</item>
+    <item>Use with a label when the progress bar needs a visible task name.</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Use Spinner for a small standalone loading affordance without task context.</item>
+    <item>Use Skeleton when representing loading content layout.</item>
+    <item>Use Slider when the user needs to choose or adjust a value.</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Static helper copy rendered with `Text` below the progress track.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible label rendered through `Progress.Label` with shared internal `FieldLabel`.</description>
+  </prop>
+  <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">
+    <description>Progress indicator color for determinate fill and indeterminate sweep.</description>
+  </css_var>
+  <css_var suffix="track-background">
+    <description>Progress track background color.</description>
+  </css_var>
+  <css_var suffix="track-size">
+    <description>Progress track thickness on the root.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,11 @@
+<?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>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="masonry">
+  <rule>Masonry distributes items round-robin into React column wrappers, so DOM, screen-reader, and keyboard order follow columns rather than original child order</rule>
+  <rule>Avoid interactive descendants when the visual arrangement could mislead keyboard users</rule>
+  <rule>Choose semantic item roots with Masonry.Item render when list or article semantics matter</rule>
+</a11y>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="masonry" title="Masonry" category="layout" shared_contract="masonry">
+  <summary>Responsive React-column layout primitive for read-only mixed-height content walls; root is a named CSS container query context (`masonry` / inline-size).</summary>
+  <exports>
+    <export name="Masonry" />
+  </exports>
+  <related>
+    <ref id="stack" />
+    <ref id="surface" />
+    <ref id="text" />
+  </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>
+</meta>

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

@@ -0,0 +1,9 @@
+<?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>
+  </example>
+</patterns>

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

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="masonry">
+  <when_to_use>
+    <item>Card walls, gallery-like collections, and editorial layouts with uneven item heights</item>
+    <item>Presentational walls where responsive column count matters more than source-order reading</item>
+    <item>Read-only collections composed from Surface, Stack, Text, and similar content primitives</item>
+    <item>Style descendants with @container masonry queries when layout should respond to the Masonry root&apos;s inline-size (peer Surface/Stack named containers)</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Interactive collections where keyboard tab order must match source order</item>
+    <item>Layouts that need strict row alignment or item-to-item placement control</item>
+    <item>Cases where Stack or another linear layout already preserves the intended reading sequence</item>
+  </when_not_to_use>
+  <prop name="breakpointCols" kind="react">
+    <description>Sets the mobile-first column count at each CSS px container breakpoint. Each non-`default` key is a unitless `min-width` in px against the Masonry root&apos;s content-box inline size. Keys may be in any order; the largest matching breakpoint wins. Non-finite keys are ignored.</description>
+  </prop>
+  <prop name="gap" kind="react">
+    <description>Sets the gap between columns (`--vui-masonry-gap`) and the `rowGap` on each column `Stack`.</description>
+  </prop>
+  <prop name="Item.ref" kind="react">
+    <description>Ref forwarded to the rendered item root element.</description>
+  </prop>
+  <prop name="Item.render" kind="react">
+    <description>Replaces the default `div` item root using Base UI render semantics.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `div` root using Base UI render semantics.</description>
+  </prop>
+  <css_var suffix="gap">
+    <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>
+</props>

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

@@ -0,0 +1,9 @@
+<?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>
+  <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>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="menu">
+  <rule>Give the trigger an accessible name (`Button` label, visible text in a Surface trigger rendered as `&lt;button&gt;`, or `aria-label` on IconButton)</rule>
+  <rule>Use `Menu.Group` `label` for grouped sections so assistive tech gets a group name</rule>
+  <rule>Prefer Base UI keyboard navigation; do not trap focus outside the menu pattern</rule>
+  <rule>`Menu.Popup` may include static non-item children (e.g. profile header); keep them non-interactive so focus roving stays on menu items</rule>
+</a11y>

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

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="menu" title="Menu" category="overlay" shared_contract="menu">
+  <summary>Compound menu built on Base UI Menu with `Menu.Trigger`, `Menu.Popup`, unified item rows, groups, checkbox/radio items, nested submenus, destructive sentiment, and `Menu.createHandle` for detached triggers; `Popup` owns Portal + Positioner + Elevator/Surface Select-like list chrome.</summary>
+  <exports>
+    <export name="Menu" />
+  </exports>
+  <related>
+    <ref id="avatar" />
+    <ref id="button" />
+    <ref id="icon-button" />
+    <ref id="popover" />
+    <ref id="select" />
+    <ref id="stack" />
+    <ref id="surface" />
+    <ref id="text" />
+    <ref id="tooltip" />
+  </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/components/menu#api-reference" />
+</meta>

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

@@ -0,0 +1,25 @@
+<?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 />
+    </Menu.Group>
+    <Menu.RadioGroup>
+      <Menu.RadioItem value="…" />
+    </Menu.RadioGroup>
+    <Menu.Separator />
+    <Menu.Submenu>
+      <Menu.SubmenuTrigger />
+      <Menu.Popup>…</Menu.Popup>
+    </Menu.Submenu>
+  </Menu.Popup>
+</Menu>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="menu">
+  <when_to_use>
+    <item>Action menus anchored to a button or icon button</item>
+    <item>Nested command lists with checkbox or radio options that stay open on toggle</item>
+    <item>Link rows mixed with actions in one menu surface</item>
+    <item>Detached or multi-trigger menus via `Menu.createHandle`</item>
+    <item>Account / user widgets: `Menu.Trigger` as a Surface chip (avatar + name + email) opening a Popup with a static profile header plus action items</item>
+    <item>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Page-blocking modal flows (use Dialog)</item>
+    <item>Form field single-select from a long list (use Select)</item>
+    <item>Context menu or menubar chrome (not in this surface)</item>
+    <item>System-wide transient alerts (use Toast)</item>
+    <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>
+  </prop>
+  <prop name="CheckboxItem.note" kind="react">
+    <description>End-aligned secondary text (e.g. keyboard shortcut) before the check indicator. Rendered muted `x-small`.</description>
+  </prop>
+  <prop name="CheckboxItem.sentiment" kind="react">
+    <description>Visual sentiment. `destructive` uses highlight-red wash + text.</description>
+  </prop>
+  <prop name="Group.label" kind="react">
+    <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>
+  </prop>
+  <prop name="Item.note" kind="react">
+    <description>End-aligned secondary text (e.g. keyboard shortcut). Rendered muted `x-small`.</description>
+  </prop>
+  <prop name="Item.sentiment" kind="react">
+    <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>
+  </prop>
+  <prop name="LinkItem.note" kind="react">
+    <description>End-aligned secondary text (e.g. keyboard shortcut). Rendered muted `x-small`.</description>
+  </prop>
+  <prop name="LinkItem.sentiment" kind="react">
+    <description>Visual sentiment. `destructive` uses highlight-red wash + text.</description>
+  </prop>
+  <prop name="Popup.children" kind="react">
+    <description>Menu items and optional static, non-interactive content rendered inside the popup.</description>
+  </prop>
+  <prop name="Popup.container" kind="react">
+    <description>Portal mount node (iframe body, shadow root, or app overlay root). Omit for Base UI default (`document.body` from the module window — iframe hosts must pass the iframe document body explicitly).</description>
+  </prop>
+  <prop name="RadioGroup.label" kind="react">
+    <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>
+  </prop>
+  <prop name="RadioItem.note" kind="react">
+    <description>End-aligned secondary text (e.g. keyboard shortcut) before the check indicator. Rendered muted `x-small`.</description>
+  </prop>
+  <prop name="RadioItem.sentiment" kind="react">
+    <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>
+  </prop>
+  <prop name="SubmenuTrigger.sentiment" kind="react">
+    <description>Visual sentiment. `destructive` uses highlight-red wash + text.</description>
+  </prop>
+
+</props>

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

@@ -0,0 +1,15 @@
+<?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>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>
+  <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>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>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="meter">
+  <rule>Provide a visible `label` or an accessible name through `aria-label` / `aria-labelledby` when the metric is not otherwise clear.</rule>
+  <rule>Keep `value` numeric and within `min` / `max` for accurate `aria-valuenow` semantics.</rule>
+  <rule>Use `description` for supplementary context that should not replace the accessible name.</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="meter" title="Meter" category="feedback" shared_contract="meter">
+  <summary>Shows a determinate metric in a compact horizontal track for static capacity, level, or score values.</summary>
+  <exports>
+    <export name="Meter" />
+  </exports>
+  <related>
+    <ref id="linear-progress" />
+    <ref id="slider" />
+    <ref id="text" />
+  </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/components/meter#api-reference" />
+</meta>

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

@@ -0,0 +1,7 @@
+<?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>
+  </example>
+</patterns>

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

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="meter">
+  <when_to_use>
+    <item>Use for storage usage, battery level, capacity, or score within a known range.</item>
+    <item>Use with a label when the metric needs a visible name.</item>
+    <item>Use with `renderValue` when the formatted value should appear beside the label.</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Use LinearProgress for in-progress tasks or indeterminate work.</item>
+    <item>Use Slider when the user needs to choose or adjust a value.</item>
+    <item>Use Spinner for a small standalone loading affordance without metric context.</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Static helper copy rendered with `Text` below the meter track.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible label rendered through `Meter.Label` with shared internal `FieldLabel`.</description>
+  </prop>
+  <prop name="renderValue" kind="react">
+    <description>Shows the current value beside the label. Pass `true` for Base UI default formatting, or a function matching `Meter.Value` `children` to customize the printed label.</description>
+  </prop>
+  <css_var suffix="indicator-color">
+    <description>Determinate meter indicator color.</description>
+  </css_var>
+  <css_var suffix="track-background">
+    <description>Meter track background color.</description>
+  </css_var>
+  <css_var suffix="track-size">
+    <description>Meter track thickness on the root.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="meter">
+  <do>Use for storage usage, battery level, capacity, or score within a known range.</do>
+  <do>Use with a label when the metric needs a visible name.</do>
+  <do>Use with `renderValue` when the formatted value should appear beside the label.</do>
+  <dont>Do not use Meter as an interactive value control.</dont>
+  <dont>Do not use Meter for indeterminate or in-progress work.</dont>
+  <dont>Do not hide the metric label when multiple meters are visible.</dont>
+  <dont>Do not model invalid or disabled meter state; Base UI Meter does not expose those states.</dont>
+</usage>

package/dist/specs/components/popover/a11y.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="popover">
+  <rule>Always pass `title`; add `description` when the heading alone is not enough context</rule>
+  <rule>With `unstyled`, render `Popover.Title` inside `children` (and `Popover.Description` when needed) so the popup keeps an accessible name</rule>
+  <rule>Compose `Popover.Close` with an accessible name when a visible close control is needed, or set `showCloseButton` for the built-in one</rule>
+  <rule>Use `modal` to control focus trap and outside interaction; render a `Popover.Close` inside the popup when `modal` is `true` or `&apos;trap-focus&apos;` so touch screen readers can escape</rule>
+</a11y>

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

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="popover" title="Popover" category="overlay" shared_contract="popover">
+  <summary>Compound popover built on Base UI Popover with `Popover.Trigger`, `Popover.Sheet`, `Popover.Close`, `Popover.Title`, `Popover.Description`, and `Popover.createHandle` for detached and multiple triggers; `Sheet` encapsulates Portal + Positioner + Popup + Viewport + Title + Description and animates position, size, and content between triggers; `Sheet` with `unstyled` skips the built-in Surface and header so the consumer composes the popup chrome, including `Popover.Title` and `Popover.Description`.</summary>
+  <exports>
+    <export name="Popover" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="button" />
+    <ref id="icon-button" />
+    <ref id="stack" />
+    <ref id="dialog" />
+    <ref id="tabs" />
+  </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/components/popover#api-reference" />
+</meta>

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

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="popover">
+  <example title="Popover structure">
+    <tsx><![CDATA[<Popover>
+  <Popover.Trigger />
+  <Popover.Sheet unstyled>
+    <Popover.Title>…</Popover.Title>
+    <Popover.Description>…</Popover.Description>
+    …
+    <Popover.Close />
+  </Popover.Sheet>
+</Popover>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="popover">
+  <when_to_use>
+    <item>Anchored quick actions or contextual hints next to a triggering control</item>
+    <item>Lightweight forms or confirmations that float beside the trigger without blocking the page</item>
+    <item>Multi-trigger panels that swap content with direction-aware animations using `Popover.createHandle` and trigger `payload`</item>
+    <item>Hover-revealed hints via `openOnHover` with `delay` and `closeDelay`</item>
+    <item>Fully custom popup chrome via `Sheet` `unstyled` composed with `Popover.Title` and `Popover.Description`</item>
+    <item>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Modal tasks that must block the page and demand focused attention (use Dialog)</item>
+    <item>Nested drill-down sheet flows (use Dialog)</item>
+    <item>System-wide transient alerts and confirmations (use Toast)</item>
+  </when_not_to_use>
+  <prop name="Sheet.container" kind="react">
+    <description>Portal mount node (iframe body, shadow root, or app overlay root). Omit for Base UI default (`document.body` from the module window — iframe hosts must pass the iframe document body explicitly).</description>
+  </prop>
+  <prop name="Sheet.description" kind="react">
+    <description>Supporting copy announced with the title.</description>
+  </prop>
+  <prop name="Sheet.headerAlign" kind="react">
+    <description>Aligns the header content.</description>
+  </prop>
+  <prop name="Sheet.showCloseButton" kind="react">
+    <description>Whether to show the built-in flat IconButton close control.</description>
+  </prop>
+  <prop name="Sheet.title" kind="react">
+    <description>Accessible popover title rendered as the popup heading.</description>
+  </prop>
+  <prop name="Sheet.unstyled" kind="react">
+    <description>Whether to skip the built-in Surface, header, and close chrome and render only the positioning/animation shell (Portal + Positioner + Popup + Viewport).</description>
+  </prop>
+  <css_var suffix="content-fade-duration">
+    <description>content fade duration custom property on the component root.</description>
+  </css_var>
+</props>