@viraui/react 2026.3.10 → 2026.4.0

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

@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="grid">
+  <when_to_use>
+    <item>Responsive card or tile walls that need true CSS Grid tracks (auto-fill/fit or fixed columns)</item>
+    <item>Fixed-count columns that keep a given track breadth — pair `columns` with an explicit `colMinWidth` so a parent with `overflow: auto` can scroll</item>
+    <item>Layouts where items must span full row or full column tracks</item>
+    <item>Token-spaced grids with optional axis padding without custom grid CSS</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Uneven-height presentational walls where reading order can follow columns — prefer Masonry</item>
+    <item>Simple one-axis flex spacing — prefer Stack</item>
+    <item>Expecting Masonry-style React column packing instead of CSS Grid tracks</item>
+  </when_not_to_use>
+  <prop name="colMinWidth" kind="react">
+    <description>Minimum column track width for `filling` auto-fill/auto-fit tracks. When `columns` is also set, an explicit value opts into fixed-breadth tracks (`repeat(N, var(--vui-grid-column-min-w))`) and sets `data-grid-fixed-breadth`; omit this prop to keep fluid `1fr` tracks.</description>
+  </prop>
+  <prop name="columnGap" kind="react">
+    <description>Sets the gap between grid columns using the Vira space token scale.</description>
+  </prop>
+  <prop name="columns" kind="react">
+    <description>Fixes the number of column tracks. When set, `filling` is ignored and `data-grid-filling-type` is omitted. Bare `columns={N}` uses fluid `repeat(N, minmax(0, 1fr))` tracks. Pass an explicit `colMinWidth` as well for fixed-breadth tracks and `data-grid-fixed-breadth=&quot;true&quot;` (`inline-size: max-content`).</description>
+  </prop>
+  <prop name="filling" kind="react">
+    <description>Controls `repeat(auto-fill|auto-fit, …)` when `columns` is unset. Pass `false` to skip the filling data attribute.</description>
+  </prop>
+  <prop name="hPadding" kind="react">
+    <description>Sets inline padding using one token for both sides or a `[start, end]` tuple.</description>
+  </prop>
+  <prop name="Item.column" kind="react">
+    <description>Sets explicit `grid-column` placement via `--vui-grid-item-column`.</description>
+  </prop>
+  <prop name="Item.fullHeight" kind="react">
+    <description>Spans the item across every row track (`grid-row: 1 / -1`). Wins over `row` when both are set.</description>
+  </prop>
+  <prop name="Item.fullWidth" kind="react">
+    <description>Spans the item across every column track (`grid-column: 1 / -1`). Wins over `column` when both are set.</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="Item.row" kind="react">
+    <description>Sets explicit `grid-row` placement via `--vui-grid-item-row`.</description>
+  </prop>
+  <prop name="Item.subgrid" kind="react">
+    <description>Opts the item into a nested CSS grid that inherits parent tracks via `subgrid`. Sets `display: grid` and `grid-template-columns` and/or `grid-template-rows` to `subgrid`. Pass `true` for both axes, or `&apos;column&apos;` / `&apos;row&apos;` for one axis. Pair with `fullWidth` / `fullHeight` or a `column` / `row` span so the item covers the tracks to inherit.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered grid root element.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `div` root using Base UI render semantics.</description>
+  </prop>
+  <prop name="rowGap" kind="react">
+    <description>Sets the gap between grid rows using the Vira space token scale.</description>
+  </prop>
+  <prop name="rowMinHeight" kind="react">
+    <description>Minimum row track size used when `rows` is set.</description>
+  </prop>
+  <prop name="rows" kind="react">
+    <description>Fixes the number of row tracks via `--vui-grid-rows`.</description>
+  </prop>
+  <prop name="vPadding" kind="react">
+    <description>Sets block padding using one token for both sides or a `[start, end]` tuple.</description>
+  </prop>
+  <css_var suffix="column-gap">
+    <description>Grid column gap on the root.</description>
+  </css_var>
+  <css_var suffix="column-min-w">
+    <description>Minimum column track width for auto-fill/auto-fit track sizing, and the fixed track breadth when `columns` is set with an explicit `colMinWidth`.</description>
+  </css_var>
+  <css_var suffix="column-size">
+    <description>Resolved column track size (`minmax` formula) used by auto-fill/fit.</description>
+  </css_var>
+  <css_var suffix="columns">
+    <description>Fixed column track count when `columns` is set and filling is inactive; bare `columns` sizes tracks as `minmax(0, 1fr)`; with explicit `colMinWidth`, tracks use `var(--vui-grid-column-min-w)` under `data-grid-fixed-breadth`.</description>
+  </css_var>
+  <css_var suffix="padding-block-end">
+    <description>Block-end padding when padding is enabled.</description>
+  </css_var>
+  <css_var suffix="padding-block-start">
+    <description>Block-start padding when padding is enabled.</description>
+  </css_var>
+  <css_var suffix="padding-inline-end">
+    <description>Inline-end padding when padding is enabled.</description>
+  </css_var>
+  <css_var suffix="padding-inline-start">
+    <description>Inline-start padding when padding is enabled.</description>
+  </css_var>
+  <css_var suffix="row-gap">
+    <description>Grid row gap on the root.</description>
+  </css_var>
+  <css_var suffix="row-min-h">
+    <description>Minimum row track size when fixed rows are enabled.</description>
+  </css_var>
+  <css_var suffix="rows">
+    <description>Fixed row track count when `rows` is set.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="grid">
+  <do>Responsive card or tile walls that need true CSS Grid tracks (auto-fill/fit or fixed columns)</do>
+  <do>Fixed-count columns that keep a given track breadth — pair `columns` with an explicit `colMinWidth` so a parent with `overflow: auto` can scroll</do>
+  <do>Layouts where items must span full row or full column tracks</do>
+  <do>Token-spaced grids with optional axis padding without custom grid CSS</do>
+  <dont>Using Masonry when you need explicit row/column placement or full-width/full-height spans</dont>
+  <dont>Re-declaring grid-template and gap in app CSS when Grid can own the layout</dont>
+  <dont>Setting both fullWidth and column (or fullHeight and row) and expecting the explicit placement to win — full-* data attrs override</dont>
+</usage>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="icon-button">
+  <rule>Provide aria-label or aria-labelledby on every IconButton — icon alone is not a name</rule>
+  <rule>Loading sets aria-busy on the control; Spinner is decorative</rule>
+  <rule>Keep the accessible name stable when loading state changes</rule>
+  <rule>Provide aria-label or aria-labelledby on every IconButtonLink — icon alone is not a name</rule>
+  <rule>Renders a real link root so assistive tech get link role</rule>
+  <rule>loading sets aria-disabled / aria-busy for loading chrome; no disabled prop — native links stay activatable</rule>
+</a11y>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="icon-button" title="IconButton" category="action" shared_contract="button">
+  <summary>Icon-only button that shares Button visual chrome (--vui-button-* CSS) and requires an accessible name through aria-label or aria-labelledby.</summary>
+  <exports>
+    <export name="IconButton" />
+    <export name="IconButtonLink" />
+  </exports>
+  <related>
+    <ref id="button" />
+    <ref id="spinner" />
+  </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/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>