@viraui/react 2026.3.11 → 2026.4.1

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="dialog">
+  <example title="Dialog structure">
+    <tsx><![CDATA[<Dialog.Provider>
+  <Dialog.IndentBackground />
+  <Dialog.Indent>
+    …
+    <Dialog>
+      <Dialog.Trigger />
+      <Dialog.Sheet title="…">
+        …
+        <Dialog.Close />
+      </Dialog.Sheet>
+    </Dialog>
+  </Dialog.Indent>
+</Dialog.Provider>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="dialog">
+  <when_to_use>
+    <item>Focused tasks or confirmations that interrupt the current page without navigation</item>
+    <item>Short forms or read-only content that needs a modal layer above the app</item>
+    <item>Bottom sheets where swipe dismissal or snap points are useful (pass `snapPoints`, `snapPoint`/`onSnapPointChange`, or `defaultSnapPoint` directly on `Dialog`)</item>
+    <item>Drill-down sheet flows (for example settings sub-pages) by nesting a `Dialog` inside `Dialog.Sheet` children</item>
+    <item>App-shell indent effects by wrapping page content in `Dialog.Provider`, `Dialog.IndentBackground`, and `Dialog.Indent`</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>Small anchored hints or quick actions that should use Popover or Menu</item>
+    <item>Highly custom sheet anatomy that needs primitive-level composition</item>
+    <item>Centered modal layouts that should not slide from the screen edge</item>
+  </when_not_to_use>
+  <prop name="Sheet.children" kind="react">
+    <description>Optional body content rendered below the description.</description>
+  </prop>
+  <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.fitContent" kind="react">
+    <description>Centers the sheet horizontally within the viewport.</description>
+  </prop>
+  <prop name="Sheet.headerAlign" kind="react">
+    <description>Aligns the header stack and title/description text (`start` | `center` | `end`).</description>
+  </prop>
+  <prop name="Sheet.maxContentWidth" kind="react">
+    <description>Optional maximum width of the content area.</description>
+  </prop>
+  <prop name="Sheet.maxHeight" kind="react">
+    <description>Maximum block size of the sheet panel.</description>
+  </prop>
+  <prop name="Sheet.showCloseButton" kind="react">
+    <description>Whether to show the close button.</description>
+  </prop>
+  <prop name="Sheet.showHandle" kind="react">
+    <description>Whether to show the drag handle above the sheet header.</description>
+  </prop>
+  <prop name="Sheet.title" kind="react">
+    <description>Accessible dialog title rendered as the modal heading.</description>
+  </prop>
+  <css_var suffix="max-block-size">
+    <description>Max block size of Dialog.Sheet popup root.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="dialog">
+  <do>Focused tasks or confirmations that interrupt the current page without navigation</do>
+  <do>Short forms or read-only content that needs a modal layer above the app</do>
+  <do>Bottom sheets where swipe dismissal or snap points are useful (pass `snapPoints`, `snapPoint`/`onSnapPointChange`, or `defaultSnapPoint` directly on `Dialog`)</do>
+  <do>Drill-down sheet flows (for example settings sub-pages) by nesting a `Dialog` inside `Dialog.Sheet` children</do>
+  <do>App-shell indent effects by wrapping page content in `Dialog.Provider`, `Dialog.IndentBackground`, and `Dialog.Indent`</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <dont>Opening a sheet without `title` copy for assistive technologies</dont>
+  <dont>Relying only on backdrop press or swipe when a footer action is the primary close path</dont>
+  <dont>Using Dialog when a centered non-gesture modal is enough and a future Dialog primitive is available</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="elevator">
+  <rule>Elevation is visual only — do not use shadow depth as the only affordance for interactivity</rule>
+  <rule>Preserve child focus order and semantics; Elevator does not add a focusable node</rule>
+  <rule>Respect reduced-motion preferences when pairing animated elevation with motion</rule>
+</a11y>

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

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="elevator" title="Elevator" category="effect" shared_contract="elevator">
+  <summary>No-DOM elevation utility that merges shadow hooks onto valid element children.</summary>
+  <exports>
+    <export name="Elevator" />
+  </exports>
+  <related>
+    <ref id="surface" />
+  </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/elevator/patterns.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="elevator">
+  <example title="Elevator structure">
+    <tsx><![CDATA[<Elevator resting={1}>…</Elevator>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="elevator">
+  <when_to_use>
+    <item>Apply resting and optional hover elevation to existing elements</item>
+    <item>Compose animated box-shadow transitions with data-elevation hooks</item>
+    <item>Use getElevationProps when you need the mapping directly</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>When you need a wrapper DOM node for layout or styling isolation</item>
+    <item>Non-element children that cannot receive merged props</item>
+  </when_not_to_use>
+  <prop name="children" kind="react">
+    <description>Element or elements that receive elevation hooks on their rendered root.</description>
+  </prop>
+  <prop name="direction" kind="react">
+    <description>Shadow cast direction mapped to `data-elevation-direction`.</description>
+  </prop>
+  <prop name="extraShadow" kind="react">
+    <description>Additional shadow layer mapped to the `--extra-shadow` custom property.</description>
+  </prop>
+  <prop name="hover" kind="react">
+    <description>Hover elevation level mapped to `data-elevation-hover`.</description>
+  </prop>
+  <prop name="resting" kind="react">
+    <description>Resting elevation level mapped to `data-elevation`.</description>
+  </prop>
+  <prop name="shadowColor" kind="react">
+    <description>Shadow color mapped to the `--shadow-color` custom property.</description>
+  </prop>
+
+</props>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="elevator">
+  <do>Apply resting and optional hover elevation to existing elements</do>
+  <do>Compose animated box-shadow transitions with data-elevation hooks</do>
+  <do>Use getElevationProps when you need the mapping directly</do>
+  <dont>Wrapping invalid or non-element nodes</dont>
+  <dont>Overwriting child transition shorthand without composing box-shadow</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="fieldset">
+  <rule>Map visible label to Fieldset.Legend so grouped controls share an accessible section name</rule>
+  <rule>Keep group invalid state on Field.Root and surface group error copy through Fieldset error</rule>
+  <rule>Pass disabled to `&lt;Fieldset disabled&gt;` when the whole section should ignore interaction</rule>
+</a11y>

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

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="fieldset" title="Fieldset" category="form" shared_contract="fieldset">
+  <summary>Semantic field grouping with shared legend and optional group helper copy.</summary>
+  <exports>
+    <export name="Fieldset" />
+  </exports>
+  <related>
+    <ref id="radio-group" />
+    <ref id="checkbox-group" />
+    <ref id="textfield" />
+    <ref id="textarea" />
+    <ref id="select" />
+    <ref id="stack" />
+  </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/fieldset#api-reference" />
+</meta>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="fieldset">
+  <example title="Fieldset structure">
+    <tsx><![CDATA[<Fieldset label="…">…</Fieldset>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="fieldset">
+  <when_to_use>
+    <item>Section legends for multiple related fields — billing details with Textfield, Textarea, or Select children</item>
+    <item>Choice groups that need a shared legend, group description, or group error — Field.Root &gt; Fieldset render={&lt;RadioGroup&lt;Value&gt; /&gt;} or render={&lt;CheckboxGroup /&gt;}</item>
+    <item>Group validation and helper copy that require a Field.Root ancestor plus Fieldset description or error</item>
+    <item>Type-safe radio unions via RadioGroup&lt;&apos;ssd&apos; | &apos;hdd&apos;&gt; merged through Fieldset render</item>
+    <item>Shared legend plus optional group description/error for a form block — border/section chrome belongs on Surface or the consumer</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Every RadioGroup or CheckboxGroup by default — Fieldset is optional when options already have labels and no group copy is needed</item>
+    <item>Single Textfield, Textarea, Select, Radio, or Checkbox that already exposes its own label</item>
+    <item>Standalone RadioGroup or CheckboxGroup inside Field.Root with no shared legend — primitives are enough</item>
+    <item>Group legend, description, or validation on RadioGroup or CheckboxGroup props — those belong on Fieldset (with Field.Root when validating)</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Group helper copy rendered below the legend while valid. Requires a `Field.Root` ancestor for `FieldHelperCopy`.</description>
+  </prop>
+  <prop name="error" kind="react">
+    <description>Group error copy rendered below the legend when invalid. Requires a `Field.Root` ancestor.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible legend copy rendered with shared internal `FieldLabel`.</description>
+  </prop>
+
+</props>

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="fieldset">
+  <do>Section legends for multiple related fields — billing details with Textfield, Textarea, or Select children</do>
+  <do>Choice groups that need a shared legend, group description, or group error — Field.Root &gt; Fieldset render={&lt;RadioGroup&lt;Value&gt; /&gt;} or render={&lt;CheckboxGroup /&gt;}</do>
+  <do>Group validation and helper copy that require a Field.Root ancestor plus Fieldset description or error</do>
+  <do>Type-safe radio unions via RadioGroup&lt;&apos;ssd&apos; | &apos;hdd&apos;&gt; merged through Fieldset render</do>
+  <do>Shared legend plus optional group description/error for a form block — border/section chrome belongs on Surface or the consumer</do>
+  <dont>Wrapping Fieldset.Root in Stack render — breaks Base UI render merge with RadioGroup or CheckboxGroup</dont>
+  <dont>Expecting description or error on Fieldset without a Field.Root ancestor</dont>
+  <dont>Omitting RadioGroup&lt;Value&gt; generics when option values are a restricted union</dont>
+</usage>

package/dist/specs/components/fit-text/a11y.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="fit-text">
+  <rule>Children render twice; the reference copy is aria-hidden and inert so assistive tech sees one tree</rule>
+  <rule>Keep semantic roots on the visible children (Title render, heading elements, paragraphs)</rule>
+  <rule>Fitted size still respects user zoom because the ratio multiplies 1em</rule>
+</a11y>

package/dist/specs/components/fit-text/meta.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="fit-text" title="FitText" category="typography" shared_contract="fit-text">
+  <summary>CSS-only fit-to-width wrapper that scales children to fill available inline space.</summary>
+  <exports>
+    <export name="FitText" />
+  </exports>
+  <related>
+    <ref id="title" />
+    <ref id="text" />
+    <ref id="clamp-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/fit-text/patterns.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="fit-text">
+  <example title="FitText structure">
+    <tsx><![CDATA[<FitText>…</FitText>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

package/dist/specs/components/fit-text/props.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="fit-text">
+  <when_to_use>
+    <item>Headlines or short copy that should fill a constrained inline width</item>
+    <item>Multi-line display type broken with br (or equivalent) inside Title, Text, or native markup</item>
+    <item>Resize-friendly marketing/hero type without JS measurement</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Long body copy that should wrap and reflow at a fixed type size</item>
+    <item>Truncation — use ClampText instead</item>
+    <item>Cases that need a JS-measured or observer-driven fit</item>
+  </when_not_to_use>
+  <prop name="maxFontSize" kind="react">
+    <description>Caps the fitted font size using any valid CSS length string.</description>
+  </prop>
+  <css_var suffix="max-font-size">
+    <description>Upper bound for the fitted font size on the display slot.</description>
+  </css_var>
+</props>

package/dist/specs/components/fit-text/usage.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="fit-text">
+  <do>Headlines or short copy that should fill a constrained inline width</do>
+  <do>Multi-line display type broken with br (or equivalent) inside Title, Text, or native markup</do>
+  <do>Resize-friendly marketing/hero type without JS measurement</do>
+  <dont>Expecting automatic line breaks without br or block structure in children</dont>
+  <dont>Putting interactive controls inside FitText (duplicate trees and inert reference)</dont>
+  <dont>Using FitText for truncation or ellipsis</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="glow">
+  <rule>Root stays in the accessibility tree; highlight is decorative CSS only</rule>
+  <rule>Glow is not a focus or status indicator — consumer owns accessible names and state</rule>
+  <rule>Highlight hides under coarse pointer / no-hover and under prefers-reduced-motion</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="glow" title="Glow" category="effect" shared_contract="glow">
+  <summary>Decorative pointer-driven border highlight on a transparent Surface shell (radius only). Put the visual card as children; a shared rAF tracker paints CSS variables without React re-renders. Memory-heavy — use sparingly (rarely).</summary>
+  <exports>
+    <export name="Glow" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="beam" />
+    <ref id="shimmer" />
+    <ref id="progressive-blur" />
+  </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/glow/patterns.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="glow">
+  <example title="Glow structure">
+    <tsx><![CDATA[<Glow>{children}</Glow>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="glow">
+  <when_to_use>
+    <item>Wrap a Surface (or other content) that should highlight toward the pointer</item>
+    <item>Grid of glow shells that share one pointer highlight path</item>
+    <item>Nested glow inside a padded Surface using radius=&quot;auto&quot;</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Default decoration on many cards — memory cost is high; reserve for rare focal moments</item>
+    <item>Static or continuously animated borders — use Surface border or Beam instead</item>
+    <item>Accessible status or focus indication — glow is decorative only</item>
+    <item>As a replacement for Surface color/padding — compose Surface as children</item>
+  </when_not_to_use>
+  <prop name="radius" kind="react">
+    <description>Sets corner radius from the Vira radius token scale, a per-corner [top-left, top-right, bottom-right, bottom-left] tuple (0 for square corners), or auto for concentric radii from the nearest ancestor Surface.</description>
+  </prop>
+  <prop name="proximity" kind="react">
+    <description>Distance from the surface edge where the glow becomes fully active.</description>
+  </prop>
+  <prop name="spread" kind="react">
+    <description>Angular width of the highlighted arc (degrees, used as a unitless CSS number).</description>
+  </prop>
+  <prop name="opacity" kind="react">
+    <description>Resting opacity of the glow when the pointer is outside proximity.</description>
+  </prop>
+  <prop name="fitContent" kind="react">
+    <description>Shrinks the root to fit its content (`max-width: fit-content`).</description>
+  </prop>
+  <prop name="borderWidth" kind="react">
+    <description>Width of the masked glow border ring.</description>
+  </prop>
+  <prop name="borderColor" kind="react">
+    <description>Color of the masked border ring under the highlight.</description>
+  </prop>
+  <prop name="borderOffset" kind="react">
+    <description>Offset of the glow ring from the surface edge. Negative values place the ring outside.</description>
+  </prop>
+  <prop name="glowColor" kind="react">
+    <description>Overrides the glow gradient with a solid color or custom background value. Ignored when `rainbowColors` is true.</description>
+  </prop>
+  <prop name="globalHighlight" kind="react">
+    <description>Shares the highlight gradient across cards via `background-attachment: fixed`. Forced off when `rainbowColors` is true.</description>
+  </prop>
+  <prop name="rainbowColors" kind="react">
+    <description>Uses the multi-stop rainbow highlight gradient and disables global highlight attachment.</description>
+  </prop>
+  <prop name="angleLag" kind="react">
+    <description>CSS transition duration in milliseconds for the pointer-driven starting angle. Soft follow by default; set 0 for instant snap.</description>
+  </prop>
+  <css_var suffix="starting-angle">
+    <description>Conic gradient start angle in degrees (unitless number). Pointer tracker writes a continuous unwrapped value.</description>
+  </css_var>
+  <css_var suffix="angle-lag">
+    <description>Transition duration for `--vui-glow-starting-angle`.</description>
+  </css_var>
+  <css_var suffix="active-opacity">
+    <description>Current glow opacity from proximity tracking. Written by the shared tracker.</description>
+  </css_var>
+  <css_var suffix="spread">
+    <description>Angular width of the highlighted arc.</description>
+  </css_var>
+  <css_var suffix="border-width">
+    <description>Masked glow border ring width.</description>
+  </css_var>
+  <css_var suffix="border-color">
+    <description>Masked border ring color under the highlight.</description>
+  </css_var>
+  <css_var suffix="border-offset">
+    <description>Glow ring offset from the surface edge.</description>
+  </css_var>
+  <css_var suffix="color">
+    <description>Glow fill (solid color or gradient).</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="glow">
+  <do>Wrap a Surface (or other content) that should highlight toward the pointer</do>
+  <do>Grid of glow shells that share one pointer highlight path</do>
+  <do>Nested glow inside a padded Surface using radius=&quot;auto&quot;</do>
+  <dont>Relying on Glow for keyboard focus visibility</dont>
+  <dont>Treating Glow as the visual card (color/padding) instead of composing Surface children</dont>
+  <dont>Setting overflow:hidden on an ancestor Surface when outer glow must remain visible</dont>
+  <dont>Expecting soft bloom Light layer — Glow is border-ring only</dont>
+  <dont>Using many Glow instances on one page — memory- and CPU-heavy</dont>
+  <dont>Expecting continuous spin — use Beam instead</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="grid">
+  <rule>Grid is presentational — choose render roots that preserve correct semantics (section, list, article)</rule>
+  <rule>DOM order follows source order; keep reading and keyboard order aligned with visual placement</rule>
+  <rule>Prefer Grid.Item render when list or article semantics matter for children</rule>
+</a11y>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="grid" title="Grid" category="layout" shared_contract="grid">
+  <summary>CSS Grid layout primitive for auto-fill/fit or fixed track layouts with token gaps, Stack-aligned padding, and item placement (`fullWidth` / `fullHeight` / column / row).</summary>
+  <exports>
+    <export name="Grid" />
+  </exports>
+  <related>
+    <ref id="stack" />
+    <ref id="masonry" />
+    <ref id="surface" />
+  </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/grid/patterns.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="grid">
+  <example title="Grid structure">
+    <tsx><![CDATA[<Grid>
+  <Grid.Item>…</Grid.Item>
+</Grid>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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>