@viraui/react 2026.3.10 → 2026.4.0

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

@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="surface">
+  <when_to_use>
+    <item>Group content with base-level background and contrast border</item>
+    <item>Frosted glass panels with `data-vibrant` — omit `color` for page-level shell or pass `color` for a tinted fill</item>
+    <item>Popup or card chrome with optional hover background</item>
+    <item>Compose with Elevator for animated elevation transitions</item>
+    <item>Set radius to a token on the outermost Surface that needs rounded corners</item>
+    <item>Set radius to a four-value tuple [top-left, top-right, bottom-right, bottom-left] when corners need different token radii</item>
+    <item>Set radius=&quot;auto&quot; on a nested Surface when its parent Surface has a radius so each corner subtracts the nearest ancestor padding and stays concentric</item>
+    <item>Stack nested auto-radius Surfaces recursively; context still resolves through wrapper layout such as Stack</item>
+    <item>Set overflow=&quot;hidden&quot; (or scroll/auto) when Surface must clip or scroll inner content with radius or padding</item>
+    <item>Style descendants with `@container surface` queries when layout or typography should respond to the Surface&apos;s own inline-size instead of the viewport (set `enableContainer` on the Surface you&apos;re querying)</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Interactive control semantics without an appropriate render root</item>
+    <item>Expecting hover background on touch-primary devices</item>
+    <item>Using radius=&quot;auto&quot; on the outermost Surface when no ancestor Surface provides a radius context</item>
+  </when_not_to_use>
+  <prop name="border" kind="react">
+    <description>Applies the shared contrast border on one or more sides (`all`, `top`, `right`, `bottom`, `left`). Pass a single side or a list (e.g. `[&quot;bottom&quot;, &quot;left&quot;]`). Omit for no border.</description>
+  </prop>
+  <prop name="enableContainer" kind="react">
+    <description>Opt-in named CSS container query context for this Surface (enables `container: surface / inline-size` on the root). Required for `@container surface (min-width: ...)` rules to react to this Surface inline-size. Warning: inline-size containment can affect nested layout (e.g. cards inside Masonry). Use only when you need container queries against this specific Surface.</description>
+  </prop>
+  <prop name="borderStyle" kind="react">
+    <description>Sets the CSS border style when `border` is set.</description>
+  </prop>
+  <prop name="color" kind="react">
+    <description>Sets the resting background using a base ramp layer (`1`–`3`), a literal CSS color value, or the named token `primary` (`data-surface-color=&quot;primary&quot;`; CSS owns light/dark opacity via `--global-primary`).</description>
+  </prop>
+  <prop name="hoverColor" kind="react">
+    <description>Sets the hover background on hover-capable pointers using a base ramp layer (`1`–`3`), a literal CSS value, or the named token `primary` (`data-surface-hover-color=&quot;primary&quot;`; CSS owns light/dark opacity via `--global-primary`).</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="overflow" kind="react">
+    <description>Sets root overflow through the `--vui-surface-overflow` custom property.</description>
+  </prop>
+  <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="ref" kind="react">
+    <description>Ref forwarded to the rendered surface root element.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `div` root using Base UI render semantics.</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>Resting surface background on the root.</description>
+  </css_var>
+  <css_var suffix="background-hover">
+    <description>Hover surface background on the root.</description>
+  </css_var>
+  <css_var suffix="border-radius">
+    <description>Uniform corner radius when radius is a single token.</description>
+  </css_var>
+  <css_var suffix="border-radius-bottom-left">
+    <description>Bottom-left corner radius; radius tuple or auto resolves per corner.</description>
+  </css_var>
+  <css_var suffix="border-radius-bottom-right">
+    <description>Bottom-right corner radius; radius tuple or auto resolves per corner.</description>
+  </css_var>
+  <css_var suffix="border-radius-top-left">
+    <description>Top-left corner radius; radius tuple or auto resolves per corner.</description>
+  </css_var>
+  <css_var suffix="border-radius-top-right">
+    <description>Top-right corner radius; radius tuple or auto resolves per corner.</description>
+  </css_var>
+  <css_var suffix="border-style">
+    <description>Border style when border is enabled.</description>
+  </css_var>
+  <css_var suffix="overflow">
+    <description>Root overflow behavior.</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>
+</props>

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

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="surface">
+  <do>Group content with base-level background and contrast border</do>
+  <do>Frosted glass panels with `data-vibrant` — omit `color` for page-level shell or pass `color` for a tinted fill</do>
+  <do>Popup or card chrome with optional hover background</do>
+  <do>Compose with Elevator for animated elevation transitions</do>
+  <do>Set radius to a token on the outermost Surface that needs rounded corners</do>
+  <do>Set radius to a four-value tuple [top-left, top-right, bottom-right, bottom-left] when corners need different token radii</do>
+  <do>Set radius=&quot;auto&quot; on a nested Surface when its parent Surface has a radius so each corner subtracts the nearest ancestor padding and stays concentric</do>
+  <do>Stack nested auto-radius Surfaces recursively; context still resolves through wrapper layout such as Stack</do>
+  <dont>Overwriting transition shorthand without composing box-shadow when data-elevation is present</dont>
+  <dont>Assuming hoverColor applies on touch devices</dont>
+  <dont>Reusing the parent token radius on nested Surfaces instead of radius=&quot;auto&quot; when concentric corners are required</dont>
+  <dont>Expecting radius=&quot;auto&quot; to inherit a token when the nearest ancestor Surface has no radius set</dont>
+  <dont>Using viewport media queries when @container surface queries against the rendered Surface inline-size would match the design intent</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="switch">
+  <rule>Provide visible label or aria-label so the switch has an accessible name</rule>
+  <rule>Checked state must map to the native switch semantics exposed by the control</rule>
+  <rule>Surface invalid state and error copy through the shared field pattern</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="switch" title="Switch" category="form" shared_contract="switch">
+  <summary>Field-wrapped toggle control with medium or small track and optional field copy.</summary>
+  <exports>
+    <export name="Switch" />
+  </exports>
+  <related>
+    <ref id="textfield" />
+    <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/switch#api-reference" />
+</meta>

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

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

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

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="switch">
+  <when_to_use>
+    <item>Boolean on/off settings with optional label and helper text</item>
+    <item>Compact small or medium track sizes</item>
+    <item>Invalid and disabled states with Textfield-parity focus treatment</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Unlabeled switch without aria-label on the root</item>
+    <item>Expecting size or variant beyond medium and small</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Helper copy rendered with `Field.Description` and `Text` while the field is valid.</description>
+  </prop>
+  <prop name="error" kind="react">
+    <description>Error copy rendered with `Field.Error` and `Text` in the same slot as `description`. Replaces description while the field is invalid and dirty.</description>
+  </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 switch 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="thumb-background">
+    <description>Switch thumb background color.</description>
+  </css_var>
+  <css_var suffix="thumb-inset">
+    <description>Inset between thumb and track edges.</description>
+  </css_var>
+  <css_var suffix="thumb-size">
+    <description>Switch thumb size derived from track block size.</description>
+  </css_var>
+  <css_var suffix="track-background">
+    <description>Switch track background color.</description>
+  </css_var>
+  <css_var suffix="track-block-size">
+    <description>Switch track block size; size presets adjust track and thumb.</description>
+  </css_var>
+  <css_var suffix="track-radius">
+    <description>Switch track corner radius.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="switch">
+  <do>Boolean on/off settings with optional label and helper text</do>
+  <do>Compact small or medium track sizes</do>
+  <do>Invalid and disabled states with Textfield-parity focus treatment</do>
+  <dont>Rendering a switch without label and without aria-label</dont>
+  <dont>Expecting description to stay visible when invalid without an error message</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="tabs">
+  <rule>Keep tab labels as visible text; addons are decorative and aria-hidden</rule>
+  <rule>Ensure each `Tabs.Panel` value matches a `Tabs.Tab` value</rule>
+  <rule>Disabled items cannot be activated through pointer or keyboard</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="tabs" title="Tabs" category="layout" shared_contract="tabs">
+  <summary>Compound segmented tab control with Surface list chrome, moving indicator, and animated panels.</summary>
+  <exports>
+    <export name="Tabs" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <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/tabs#api-reference" />
+</meta>

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

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="tabs">
+  <example title="Tabs structure">
+    <tsx><![CDATA[<Tabs>
+  <Tabs.List>
+    <Tabs.Tab value="a">…</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Viewport>
+    <Tabs.Panel value="a">…</Tabs.Panel>
+  </Tabs.Viewport>
+</Tabs>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="tabs">
+  <when_to_use>
+    <item>Switching between related views in the same surface</item>
+    <item>Compact horizontal segmented navigation</item>
+    <item>Decorative start/end addons on tab labels without changing accessible names</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Primary app navigation that should use links or routes directly</item>
+    <item>Vertical tab layouts in v1 styled targets</item>
+  </when_not_to_use>
+  <prop name="listAlignment" kind="react">
+    <description>Horizontal alignment of tab list within root Stack.</description>
+  </prop>
+  <prop name="Tab.addon" kind="react">
+    <description>Decorative addon rendered alongside the tab label.</description>
+  </prop>
+  <prop name="Tab.addonPosition" kind="react">
+    <description>Controls whether the addon appears before or after the label.</description>
+  </prop>
+  <css_var suffix="translate-amount">
+    <description>Panel entry translate distance for tab transitions.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="tabs">
+  <do>Switching between related views in the same surface</do>
+  <do>Compact horizontal segmented navigation</do>
+  <do>Decorative start/end addons on tab labels without changing accessible names</do>
+  <dont>Using addons as the only visible label for a tab</dont>
+  <dont>Trying to compose a separate public `Tabs.Indicator`; the indicator is owned by `Tabs.List`</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="text">
+  <rule>Use Text for body copy; do not substitute for heading elements in the document outline</rule>
+  <rule>Semantic tone supports meaning but does not replace explicit labels on controls</rule>
+  <rule>Choose render when the copy must live on a specific inline or block element</rule>
+</a11y>

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

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="text" title="Text" category="typography" shared_contract="text">
+  <summary>Theme-aware body-copy primitive with tone, family, and responsive body sizing.</summary>
+  <exports>
+    <export name="Text" />
+  </exports>
+  <related>
+    <ref id="title" />
+    <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/text/patterns.xml

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

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

@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="text">
+  <when_to_use>
+    <item>Body copy with semantic tone (including brand `primary`) and token-backed typography</item>
+    <item>Helper, label, or inline copy inside other components</item>
+    <item>Mono or body family text with fluid clamp sizing</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Headings or display typography — use Title</item>
+    <item>Heading semantics without an appropriate render root</item>
+  </when_not_to_use>
+  <prop name="align" kind="react">
+    <description>Aligns text using logical alignment values.</description>
+  </prop>
+  <prop name="balanced" kind="react">
+    <description>Enables balanced wrapping for block-like copy.</description>
+  </prop>
+  <prop name="color" kind="react">
+    <description>Applies a literal color escape hatch when semantic `tone` is not used.</description>
+  </prop>
+  <prop name="family" kind="react">
+    <description>Selects the semantic font family for body copy and inline code-like text.</description>
+  </prop>
+  <prop name="fontWidth" kind="react">
+    <description>Overrides font width as a percentage (100 = normal); maps to `font-stretch` and `wdth`.</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="lineHeight" kind="react">
+    <description>Controls line height through foundation leading tokens.</description>
+  </prop>
+  <prop name="maxWidth" kind="react">
+    <description>Constrains the maximum inline size of the rendered text block.</description>
+  </prop>
+  <prop name="opticalSize" kind="react">
+    <description>Overrides the optical size (`opsz`) axis on variable fonts; static fonts keep `font-optical-sizing: auto`.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered 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="selection" kind="react">
+    <description>Enables text selection on the rendered copy.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Selects a semantic body typography size from the active theme scale.</description>
+  </prop>
+  <prop name="tone" kind="react">
+    <description>Sets the semantic text color role when no literal `color` override is used. `default` inherits; `primary` → `--global-primary`; `muted` → `--global-muted`; `interactive` → `--global-interactive-text`; `positive` / `informative` / `danger` / `warning` → `--highlight-green` / `--highlight-blue` / `--highlight-red` / `--highlight-yellow`.</description>
+  </prop>
+  <prop name="tracking" kind="react">
+    <description>Sets letter spacing on the rendered copy.</description>
+  </prop>
+  <prop name="transform" kind="react">
+    <description>Applies a text-transform on the rendered copy.</description>
+  </prop>
+  <prop name="trim" kind="react">
+    <description>Trims text box whitespace at the chosen edge when the browser supports `text-box`. Pass `false` to disable text-box trim.</description>
+  </prop>
+  <prop name="trimType" kind="react">
+    <description>Selects the `text-box` trim basis when `trim` is active.</description>
+  </prop>
+  <prop name="vPadding" kind="react">
+    <description>Sets block padding using one token for both sides or a `[start, end]` tuple.</description>
+  </prop>
+  <prop name="weight" kind="react">
+    <description>Selects a semantic weight keyword or a numeric weight (`font-weight` + `wght` axis).</description>
+  </prop>
+  <prop name="whiteSpace" kind="react">
+    <description>Controls white-space preservation and wrapping behavior.</description>
+  </prop>
+  <css_var suffix="align">
+    <description>Text alignment on the root.</description>
+  </css_var>
+  <css_var suffix="font-family">
+    <description>Font family; family prop presets via data attributes.</description>
+  </css_var>
+  <css_var suffix="font-opsz">
+    <description>Optical size axis on the root (variable fonts).</description>
+  </css_var>
+  <css_var suffix="font-size">
+    <description>Body font size; size prop presets via data attributes.</description>
+  </css_var>
+  <css_var suffix="font-weight">
+    <description>Font weight on the root; keyword presets or numeric via weight prop.</description>
+  </css_var>
+  <css_var suffix="font-width">
+    <description>Font width percentage on the root (font-stretch + wdth).</description>
+  </css_var>
+  <css_var suffix="line-height">
+    <description>Line height; lineHeight prop presets via data attributes.</description>
+  </css_var>
+  <css_var suffix="letter-spacing">
+    <description>Letter spacing on the root.</description>
+  </css_var>
+  <css_var suffix="literal-color">
+    <description>Literal color override on the root.</description>
+  </css_var>
+  <css_var suffix="max-width">
+    <description>Max inline size of the text root.</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="trim">
+    <description>Text-box trim mode on the root.</description>
+  </css_var>
+  <css_var suffix="trim-type">
+    <description>Text-box trim basis on the root.</description>
+  </css_var>
+  <css_var suffix="text-transform">
+    <description>Text transform on the root.</description>
+  </css_var>
+  <css_var suffix="white-space">
+    <description>White-space behavior on the root.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="text">
+  <do>Body copy with semantic tone (including brand `primary`) and token-backed typography</do>
+  <do>Helper, label, or inline copy inside other components</do>
+  <do>Mono or body family text with fluid clamp sizing</do>
+  <dont>Using Text for headings instead of Title</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="textarea">
+  <rule>Associate label with the textarea through the field label pattern</rule>
+  <rule>Expose validation and helper copy through description and error slots</rule>
+  <rule>Prefer resize modes that do not hide required content from keyboard users</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="textarea" title="Textarea" category="form" shared_contract="textarea">
+  <summary>Multi-line field control with shared field copy, optional resize, and optional content sizing.</summary>
+  <exports>
+    <export name="Textarea" />
+  </exports>
+  <related>
+    <ref id="fieldset" />
+    <ref id="textfield" />
+    <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/field#api-reference" />
+</meta>

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

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

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

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="textarea">
+  <when_to_use>
+    <item>Multi-line text entry with label, description, and error</item>
+    <item>Optional native CSS resize (vertical, horizontal, both, and other valid resize values)</item>
+    <item>Content-sized growth via fitContent</item>
+    <item>Native textarea attributes through the field control</item>
+    <item>One or more Textareas inside Fieldset when they belong to a labeled form section with other fields</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Single-line input — use Textfield</item>
+    <item>Addon slots like Textfield startAddon or endAddon</item>
+    <item>Wrapping a lone Textarea in Fieldset when its own label is sufficient</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Helper copy rendered with `Field.Description` and `Text` while the field is valid.</description>
+  </prop>
+  <prop name="error" kind="react">
+    <description>Error copy rendered with `Field.Error` and `Text` in the same slot as `description`. Replaces description while the field is invalid and dirty. Validation messages from `validate` are shown by `Field.Error` even when this prop is omitted (also requires dirty).</description>
+  </prop>
+  <prop name="fitContent" kind="react">
+    <description>When `true`, sets `field-sizing: content` so the control grows with its value. Still respects `min-block-size` and `resize`. Omitted / `false` keeps the browser fixed default.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible label rendered with shared internal `FieldLabel`.</description>
+  </prop>
+  <prop name="resize" kind="react">
+    <description>Native CSS `resize` for the control, serialized to `data-resize`. Omitted keeps resize disabled (`none`); accepts any valid `CSSProperties[&apos;resize&apos;]` value such as `&quot;vertical&quot;`, `&quot;horizontal&quot;`, or `&quot;both&quot;`.</description>
+  </prop>
+  <css_var suffix="input-border-radius">
+    <description>Corner radius for the BasicInput textarea control (also drives field label/description inline padding).</description>
+  </css_var>
+  <css_var suffix="min-block-size">
+    <description>Minimum block size of the BasicInput textarea control.</description>
+  </css_var>
+  <css_var suffix="padding-block">
+    <description>Block padding on the BasicInput textarea control.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="textarea">
+  <do>Multi-line text entry with label, description, and error</do>
+  <do>Optional native CSS resize (vertical, horizontal, both, and other valid resize values)</do>
+  <do>Content-sized growth via fitContent</do>
+  <do>Native textarea attributes through the field control</do>
+  <do>One or more Textareas inside Fieldset when they belong to a labeled form section with other fields</do>
+  <dont>Using Textarea for single-line values</dont>
+  <dont>Expecting unsupported size or variant props</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="textfield">
+  <rule>Associate label with the input through the field label pattern</rule>
+  <rule>Surface validation errors in the shared description slot or Field.Error</rule>
+  <rule>Addon buttons must keep type=&quot;button&quot; and their own accessible names</rule>
+</a11y>

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

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="textfield" title="Textfield" category="form" shared_contract="textfield">
+  <summary>Single-line field input with control-group chrome and optional addons.</summary>
+  <exports>
+    <export name="Textfield" />
+  </exports>
+  <related>
+    <ref id="autocomplete" />
+    <ref id="fieldset" />
+    <ref id="textarea" />
+    <ref id="select" />
+    <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/input#api-reference" />
+</meta>

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

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