@viraui/react 2026.3.11 → 2026.4.1

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="beam">
+  <do>Highlight a focal Surface with a traveling border beam</do>
+  <do>Bottom-edge line travel under a card or panel</do>
+  <do>Breathing pulse glow inside or outside a Surface</do>
+  <do>Token-colored or colorful multi-stop decorative emphasis</do>
+  <dont>Relying on Beam for keyboard focus visibility</dont>
+  <dont>Treating Beam as the visual card instead of composing Surface children</dont>
+  <dont>Expecting theme light/dark auto-tuning — colors are token-driven and theme-agnostic</dont>
+  <dont>Using many pulse Beam instances on one page — shared rAF still paints per instance</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="bleed">
+  <rule>Bleed is a layout wrapper only — child content keeps native semantics</rule>
+  <rule>Parent containers should preserve readable line length for text content</rule>
+  <rule>Full bleed can introduce horizontal scroll when ancestors use overflow hidden incorrectly</rule>
+  <rule>Full bleed uses physical `margin-left: calc(50% - 50vw)` — known RTL limitation; verify mirroring in right-to-left layouts</rule>
+</a11y>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="bleed" title="Bleed" category="layout" shared_contract="bleed">
+  <summary>Layout utility that pulls content past inline padding using negative margins or full viewport bleed.</summary>
+  <exports>
+    <export name="Bleed" />
+  </exports>
+  <related>
+    <ref id="stack" />
+    <ref id="surface" />
+    <ref id="separator" />
+  </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/bleed/patterns.xml

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

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

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="bleed">
+  <when_to_use>
+    <item>Edge-to-edge media or dividers inside padded Surface or Stack containers</item>
+    <item>Hero bands or callouts that should break out of card padding</item>
+    <item>Full-bleed sections that span the viewport width from a centered layout</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Replacing Stack or Surface padding instead of composing with them</item>
+    <item>Interactive controls that need their own hit target sizing</item>
+    <item>Cases where overflow clipping on the parent should remain strict</item>
+  </when_not_to_use>
+  <prop name="amount" kind="react">
+    <description>Sets the inline bleed amount using a Vira space token.</description>
+  </prop>
+  <prop name="full" kind="react">
+    <description>Bleeds content to the viewport edges and ignores `amount`.</description>
+  </prop>
+  <css_var suffix="amount">
+    <description>Bleed distance on the root via `margin: 0 calc(var(--vui-bleed-amount, 0) * -1)` (negative inline, zero block).</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="bleed">
+  <do>Edge-to-edge media or dividers inside padded Surface or Stack containers</do>
+  <do>Hero bands or callouts that should break out of card padding</do>
+  <do>Full-bleed sections that span the viewport width from a centered layout</do>
+  <dont>Nesting multiple full bleeds without checking ancestor overflow</dont>
+  <dont>Using Bleed to compensate for missing Stack padding instead of fixing layout composition</dont>
+  <dont>Applying full bleed inside narrow overflow-hidden cards without testing clipping</dont>
+  <dont>Expecting full bleed `margin-left` to flip automatically in RTL</dont>
+</usage>

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

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="breakpoints">
+  <rule>Match state is not an APG widget. Keep the same accessible name and semantics when swapping chrome</rule>
+  <rule>Do not rely on breakpoint-only visibility as the only way to reach essential actions on small viewports</rule>
+</a11y>

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

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="breakpoints" title="BreakpointsProvider" category="layout" shared_contract="breakpoints">
+  <summary>Client provider plus `useBreakpoints` for mobile-first viewport min-width matches. Defaults are hardcoded em thresholds, not theme tokens.</summary>
+  <exports>
+    <export name="BreakpointsProvider" />
+  </exports>
+  <related>
+    <ref id="stack" />
+    <ref id="grid" />
+  </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/breakpoints/patterns.xml

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

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

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="breakpoints">
+  <when_to_use>
+    <item>Swap or hide React markup when the viewport crosses named breakpoints</item>
+    <item>Read one flag with `useBreakpoints(&apos;small&apos;)` so unrelated breakpoint flips skip work</item>
+    <item>Override the full map with the `breakpoints` prop for product-specific thresholds</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Layout that CSS `@media` or container queries can own without branching markup</item>
+    <item>Calling `useBreakpoints` outside this provider</item>
+    <item>Reading design-token CSS variables for breakpoint widths</item>
+  </when_not_to_use>
+  <prop name="breakpoints" kind="react">
+    <description>Replaces the entire default map (extra-small 30em, small 48em, medium 60em, large 80em, extra-large 100em). Values are CSS lengths used as mobile-first min-width queries.</description>
+  </prop>
+  <prop name="children" kind="react">
+    <description>Tree that may call `useBreakpoints`. The hook returns all match flags, or `useBreakpoints(name)` for one boolean.</description>
+  </prop>
+
+</props>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="breakpoints">
+  <do>Swap or hide React markup when the viewport crosses named breakpoints</do>
+  <do>Read one flag with `useBreakpoints(&apos;small&apos;)` so unrelated breakpoint flips skip work</do>
+  <do>Override the full map with the `breakpoints` prop for product-specific thresholds</do>
+  <dont>Using `useBreakpoints` without wrapping the tree in `BreakpointsProvider`</dont>
+  <dont>Merging a sparse custom map onto defaults — the `breakpoints` prop replaces the whole map</dont>
+  <dont>Putting the provider in a Server Component module — wrap it in a Client Component (`&apos;use client&apos;`)</dont>
+</usage>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="button">
+  <rule>Visible button text should name the action; avoid relying on addon alone</rule>
+  <rule>Loading sets aria-busy on the control while Spinner stays decorative</rule>
+  <rule>Disabled and loading states should not remove the action from the tab order without clear context</rule>
+  <rule>Renders a real link root so assistive tech get link role and keyboard behavior</rule>
+  <rule>loading sets aria-disabled / aria-busy for loading chrome; no disabled prop — native links stay activatable</rule>
+  <rule>Loading sets aria-busy; Spinner stays decorative</rule>
+</a11y>

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

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="button" title="Button" category="action" shared_contract="button">
+  <summary>Primary action control with size, variant, optional addon, optional pill shape, and loading state.</summary>
+  <exports>
+    <export name="Button" />
+    <export name="ButtonLink" />
+  </exports>
+  <related>
+    <ref id="icon-button" />
+    <ref id="spinner" />
+    <ref id="chip" />
+  </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/button#api-reference" />
+</meta>

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="button">
+  <example title="Button structure">
+    <tsx><![CDATA[<Button>Save</Button>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+  <example title="ButtonLink structure">
+    <tsx><![CDATA[<ButtonLink href="#">Save</ButtonLink>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="button">
+  <when_to_use>
+    <item>Labeled actions with text and optional leading or trailing addon</item>
+    <item>Primary, secondary, flat, or destructive visual treatments</item>
+    <item>Capsule-shaped actions via pill when a fully rounded button fits the layout</item>
+    <item>Async actions that need a stable width while loading</item>
+    <item>Primary Chip addons inside a primary Button — set data-mode=&quot;inverted&quot; on the Chip so its background contrasts the button fill</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Icon-only actions without a visible label — use IconButton</item>
+    <item>Navigation or non-button semantics — use ButtonLink</item>
+  </when_not_to_use>
+  <prop name="addon" kind="react">
+    <description>Decorative addon rendered alongside the button label. Pass any React element; use a named icon from `@viraui/icons/react` or `&lt;Chip /&gt;` for status chips.</description>
+  </prop>
+  <prop name="addonPosition" kind="react">
+    <description>Controls whether the addon appears before or after the label.</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="addon" kind="react">
+    <description>Decorative addon rendered alongside the link label. (button-link)</description>
+  </prop>
+  <prop name="addonPosition" kind="react">
+    <description>Controls whether the addon appears before or after the label. (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. (button-link)</description>
+  </prop>
+  <prop name="pill" kind="react">
+    <description>Applies a fully rounded pill shape. (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`). (button-link)</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Controls the visual button size. (button-link)</description>
+  </prop>
+  <prop name="variant" kind="react">
+    <description>Selects the visual treatment matching Button. (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. (button-link)</description>
+  </css_var>
+  <css_var suffix="color">
+    <description>Button label and icon color. (button-link)</description>
+  </css_var>
+  <css_var suffix="height">
+    <description>Button block size; size prop presets via data attributes. (button-link)</description>
+  </css_var>
+  <css_var suffix="icon-size">
+    <description>Addon icon size inside the button. (button-link)</description>
+  </css_var>
+  <css_var suffix="padding-block">
+    <description>Vertical padding inside the button. (button-link)</description>
+  </css_var>
+  <css_var suffix="padding-inline">
+    <description>Horizontal padding inside the button. (button-link)</description>
+  </css_var>
+  <css_var suffix="radius">
+    <description>Corner radius; pill sets infinite radius via data-pill. (button-link)</description>
+  </css_var>
+  <css_var suffix="spinner-color">
+    <description>Loading spinner color on the root. (button-link)</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="button">
+  <do>Labeled actions with text and optional leading or trailing addon</do>
+  <do>Primary, secondary, flat, or destructive visual treatments</do>
+  <do>Capsule-shaped actions via pill when a fully rounded button fits the layout</do>
+  <do>Async actions that need a stable width while loading</do>
+  <do>Primary Chip addons inside a primary Button — set data-mode=&quot;inverted&quot; on the Chip so its background contrasts the button fill</do>
+  <do>Actions that navigate (href or router Link) but should look like Button</do>
+  <do>Same size, variant, addon, pill, and loading chrome as Button without button semantics</do>
+  <do>Compose with Next.js Link or React Router Link via the render prop</do>
+  <dont>Using Button without children as icon-only — prefer IconButton</dont>
+  <dont>Using Button with render={&lt;a /&gt;} for links — Base UI enforces button semantics; use ButtonLink</dont>
+  <dont>Duplicating icon size on every addon slot — Button CSS sizes SVG descendants</dont>
+  <dont>Mixing pill with custom border-radius overrides that fight data-pill styling</dont>
+  <dont>Primary Chip addon inside a primary Button without data-mode=&quot;inverted&quot; — chip background matches the button fill and disappears</dont>
+  <dont>Using Button with render={&lt;a /&gt;} instead of ButtonLink</dont>
+  <dont>Forcing role=button on a link</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="checkbox">
+  <rule>Provide visible label or aria-label so the checkbox has an accessible name</rule>
+  <rule>Checked and indeterminate states must map to native checkbox semantics exposed by the control</rule>
+  <rule>Surface standalone invalid state and error copy through Field.Root and FieldHelperCopy on Checkbox</rule>
+</a11y>

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

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="checkbox" title="Checkbox" category="form" shared_contract="checkbox">
+  <summary>Field.Item checkbox option for standalone fields or CheckboxGroup children.</summary>
+  <exports>
+    <export name="Checkbox" />
+  </exports>
+  <related>
+    <ref id="fieldset" />
+    <ref id="checkbox-group" />
+    <ref id="switch" />
+    <ref id="stack" />
+    <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/checkbox#api-reference" />
+</meta>

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

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

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

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="checkbox">
+  <when_to_use>
+    <item>Single boolean fields wrapped in Field.Root with optional label and helper text — no Fieldset required</item>
+    <item>CheckboxGroup alone inside Field.Root when each Checkbox has its own label and no shared group legend is needed</item>
+    <item>Multi-select sets with shared legend or group copy — Field.Root &gt; Fieldset render={&lt;CheckboxGroup /&gt;} with Checkbox children</item>
+    <item>Invalid and disabled states with Switch-parity focus treatment</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Unlabeled checkbox without aria-label on the root</item>
+    <item>Mutually exclusive options in a set (use Radio and RadioGroup instead)</item>
+    <item>Assuming Fieldset is mandatory for every CheckboxGroup — add Fieldset only for shared legend or group copy</item>
+    <item>Group legend, description, or validation on CheckboxGroup props — use Field.Root and Fieldset instead</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Helper copy rendered with `Field.Description` and `Text` for this option.</description>
+  </prop>
+  <prop name="error" kind="react">
+    <description>Error copy rendered in the same slot as `description` while invalid.</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="label" kind="react">
+    <description>Visible label rendered with shared internal `FieldLabel`.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Controls the visual checkbox size.</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="background">
+    <description>Checkbox control background color.</description>
+  </css_var>
+  <css_var suffix="border-color">
+    <description>Checkbox control border color; invalid and checked states override.</description>
+  </css_var>
+  <css_var suffix="indicator-color">
+    <description>Checkbox check/minus indicator color.</description>
+  </css_var>
+  <css_var suffix="radius">
+    <description>Checkbox control corner radius.</description>
+  </css_var>
+  <css_var suffix="size">
+    <description>Checkbox control box size; size presets adjust footprint and radius.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="checkbox">
+  <do>Single boolean fields wrapped in Field.Root with optional label and helper text — no Fieldset required</do>
+  <do>CheckboxGroup alone inside Field.Root when each Checkbox has its own label and no shared group legend is needed</do>
+  <do>Multi-select sets with shared legend or group copy — Field.Root &gt; Fieldset render={&lt;CheckboxGroup /&gt;} with Checkbox children</do>
+  <do>Invalid and disabled states with Switch-parity focus treatment</do>
+  <dont>Rendering a checkbox without label and without aria-label</dont>
+  <dont>Using Checkbox without Field.Root for standalone validated fields</dont>
+  <dont>Expecting description to stay visible when invalid without an error message</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="chip">
+  <rule>Chip renders a div by default, so choose render explicitly when a different semantic element is needed</rule>
+  <rule>Decorative addons are aria-hidden and should not carry the accessible name</rule>
+  <rule>Chip does not add button semantics, disabled state, or loading behavior in v1</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="chip" title="Chip" category="action" shared_contract="chip">
+  <summary>Compact visual label primitive for short status, category, or metadata treatments.</summary>
+  <exports>
+    <export name="Chip" />
+  </exports>
+  <related>
+    <ref id="button" />
+    <ref id="icon-button" />
+    <ref id="stack" />
+    <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/chip/patterns.xml

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

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

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="chip">
+  <when_to_use>
+    <item>Short, non-interactive labels that need a compact pill treatment</item>
+    <item>Metadata, category, status, or inline tag-like presentation</item>
+    <item>Color-coded badges using the semantic highlight palette</item>
+    <item>Polymorphic label content that should render as div by default or as another semantic tag through render</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Interactive actions or dismiss controls — use Button or IconButton</item>
+    <item>Long-form text content that should wrap like body copy — use Text</item>
+  </when_not_to_use>
+  <prop name="addon" kind="react">
+    <description>Decorative addon rendered alongside the chip label.</description>
+  </prop>
+  <prop name="addonPosition" kind="react">
+    <description>Controls whether the addon appears before or after the label.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered chip root element.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `div` root using Base UI render semantics.</description>
+  </prop>
+  <prop name="variant" kind="react">
+    <description>Selects the visual treatment for the chip.</description>
+  </prop>
+  <css_var suffix="background">
+    <description>Chip fill; variant presets via data attributes.</description>
+  </css_var>
+  <css_var suffix="border-color">
+    <description>Chip border color.</description>
+  </css_var>
+  <css_var suffix="color">
+    <description>Chip label and icon color.</description>
+  </css_var>
+  <css_var suffix="color-bg-opacity">
+    <description>Highlight variant background opacity mix.</description>
+  </css_var>
+  <css_var suffix="color-border-opacity">
+    <description>Highlight variant border opacity mix.</description>
+  </css_var>
+  <css_var suffix="height">
+    <description>Fixed chip block size.</description>
+  </css_var>
+  <css_var suffix="icon-size">
+    <description>Decorative addon icon size.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="chip">
+  <do>Short, non-interactive labels that need a compact pill treatment</do>
+  <do>Metadata, category, status, or inline tag-like presentation</do>
+  <do>Color-coded badges using the semantic highlight palette</do>
+  <do>Polymorphic label content that should render as div by default or as another semantic tag through render</do>
+  <dont>Using Chip as a button replacement for clickable actions</dont>
+  <dont>Expecting addonPosition to have any effect when addon is omitted</dont>
+  <dont>Introducing custom size variants instead of the fixed compact height</dont>
+  <dont>Re-adding a one-off destructive variant instead of using the red highlight color</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="clamp-text">
+  <rule>Truncation hides content — provide full text nearby, in a tooltip, or on a detail view when it matters</rule>
+  <rule>Do not use clamped text alone for critical instructions or legal copy</rule>
+  <rule>Choose Title render for headings so document outline stays correct</rule>
+</a11y>

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

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="clamp-text" title="ClampText" category="typography" shared_contract="clamp-text">
+  <summary>Presentational utility that truncates overflowing copy to a fixed line count.</summary>
+  <exports>
+    <export name="ClampText" />
+  </exports>
+  <related>
+    <ref id="text" />
+    <ref id="title" />
+  </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/clamp-text/patterns.xml

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

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

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="clamp-text">
+  <when_to_use>
+    <item>Single- or multi-line ellipsis in constrained layouts</item>
+    <item>Clamp Text or Title roots through render</item>
+    <item>Inline or block clamped typography</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Full text must remain visible without truncation</item>
+    <item>Heading semantics without composing Title through render</item>
+  </when_not_to_use>
+  <prop name="inline" kind="react">
+    <description>Uses inline `-webkit-inline-box` display instead of block `-webkit-box`.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered clamp text root element.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `span` root using Base UI render semantics.</description>
+  </prop>
+  <prop name="rows" kind="react">
+    <description>Sets how many lines of text remain visible before truncation.</description>
+  </prop>
+  <css_var suffix="rows">
+    <description>WebKit line-clamp row count on the root.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="clamp-text">
+  <do>Single- or multi-line ellipsis in constrained layouts</do>
+  <do>Clamp Text or Title roots through render</do>
+  <do>Inline or block clamped typography</do>
+  <dont>Using ClampText as a heading primitive without Title render</dont>
+  <dont>Expecting children-driven sizing instead of rows</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="dialog">
+  <rule>Always pass `title`; add `description` when the heading alone is not enough context</rule>
+  <rule>Compose `Dialog.Close` with an accessible name when a visible close control is needed</rule>
+  <rule>Use `Dialog.Close` for footer actions that should dismiss the sheet</rule>
+  <rule>For non-modal Dialogs (`modal={false}` with `disablePointerDismissal`), the Sheet backdrop is omitted automatically — do not expect a scrim</rule>
+</a11y>

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

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="dialog" title="Dialog" category="overlay" shared_contract="dialog">
+  <summary>Compound drawer sheet with `Dialog.Trigger`, `Dialog.Sheet`, `Dialog.Close`, and Base UI pass-through `Dialog.Provider`, `Dialog.Indent`, and `Dialog.IndentBackground` for app-shell indent effects.</summary>
+  <exports>
+    <export name="Dialog" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="button" />
+    <ref id="icon-button" />
+    <ref id="stack" />
+    <ref id="elevator" />
+  </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/drawer#api-reference" />
+</meta>