@viraui/react 2026.3.10 → 2026.4.0

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

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="textfield">
+  <when_to_use>
+    <item>Single-line text, email, password, or similar native input types</item>
+    <item>Start or end addon slots inside the shared control group</item>
+    <item>Label, description, and error copy with validation states</item>
+    <item>Several related Textfields grouped under one section legend as Fieldset children (e.g. billing details)</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Multi-line entry — use Textarea</item>
+    <item>Custom size or variant props — fixed medium treatment</item>
+    <item>Wrapping a lone Textfield in Fieldset when its own label is sufficient — Fieldset is for multi-field sections or shared legends</item>
+    <item>Using Fieldset instead of the Textfield label for a single control</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="endAddon" kind="react">
+    <description>Trailing decoration (icon, button). Buttons must use `type=&quot;button&quot;`.</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 inline with its value. Block chrome stays `var(--vui-textfield-input-height)`. Omitted / `false` keeps the browser fixed default.</description>
+  </prop>
+  <prop name="fullWidth" kind="react">
+    <description>When `true`, root and control group take `inline-size: 100%`.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible label rendered with shared internal `FieldLabel`.</description>
+  </prop>
+  <prop name="startAddon" kind="react">
+    <description>Leading decoration (prefix text, icon). Not a second field control.</description>
+  </prop>
+  <css_var suffix="control-group-background">
+    <description>Textfield control group background.</description>
+  </css_var>
+  <css_var suffix="control-group-border-color">
+    <description>Textfield control group border color.</description>
+  </css_var>
+  <css_var suffix="control-group-border-radius">
+    <description>Textfield control group corner radius.</description>
+  </css_var>
+  <css_var suffix="control-group-color">
+    <description>Textfield control group foreground color.</description>
+  </css_var>
+  <css_var suffix="input-height">
+    <description>Textfield control group block size.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="textfield">
+  <do>Single-line text, email, password, or similar native input types</do>
+  <do>Start or end addon slots inside the shared control group</do>
+  <do>Label, description, and error copy with validation states</do>
+  <do>Several related Textfields grouped under one section legend as Fieldset children (e.g. billing details)</do>
+  <dont>Passing unsupported size or variant props</dont>
+  <dont>Expecting a focus ring when focus is only on addon controls</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="title">
+  <rule>Title renders a span by default, so choose render to match the correct heading level for the page outline</rule>
+  <rule>Visual size presets do not replace picking the right h1–h6 element</rule>
+  <rule>Use size for appearance and render for semantics; pair them unless you intentionally need a visual mismatch</rule>
+  <rule>Keep heading hierarchy sequential; do not skip outline levels for styling alone</rule>
+</a11y>

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

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="title" title="Title" category="typography" shared_contract="title">
+  <summary>Theme-aware heading and display typography primitive.</summary>
+  <exports>
+    <export name="Title" />
+  </exports>
+  <related>
+    <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/title/patterns.xml

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

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

@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="title">
+  <when_to_use>
+    <item>Headings and display text with title presets</item>
+    <item>Semantic heading tags chosen explicitly through render</item>
+    <item>Size and render paired together for most heading use cases</item>
+    <item>Fluid clamp sizing across title appearance presets</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Body copy — use Text</item>
+    <item>Body or mono family typography</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 titles.</description>
+  </prop>
+  <prop name="color" kind="react">
+    <description>Applies a literal color escape hatch.</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 title root element.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `span` root using Base UI render semantics. Pair this with `size` for most headings so DOM semantics and visual preset stay intentionally aligned.</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 heading or display typography preset from the active theme scale. This controls only the visual preset. Semantic heading choice remains owned by `render`, because `Title` keeps a `span` root unless `render` replaces it.</description>
+  </prop>
+  <prop name="tracking" kind="react">
+    <description>Sets letter spacing on the rendered copy. Overrides size preset letter-spacing when set.</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>Overrides the size preset 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>Title alignment on the root.</description>
+  </css_var>
+  <css_var suffix="font-family">
+    <description>Heading font family on the root.</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>Heading font size; size prop presets via data attributes.</description>
+  </css_var>
+  <css_var suffix="font-weight">
+    <description>Font weight on the root.</description>
+  </css_var>
+  <css_var suffix="font-width">
+    <description>Font width percentage on the root (font-stretch + wdth).</description>
+  </css_var>
+  <css_var suffix="letter-spacing">
+    <description>Public letter spacing from the `tracking` prop when set.</description>
+  </css_var>
+  <css_var suffix="line-height">
+    <description>Line height; lineHeight prop presets via data attributes.</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 title 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/title/usage.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="title">
+  <do>Headings and display text with title presets</do>
+  <do>Semantic heading tags chosen explicitly through render</do>
+  <do>Size and render paired together for most heading use cases</do>
+  <do>Fluid clamp sizing across title appearance presets</do>
+  <dont>Assuming size changes the HTML tag automatically</dont>
+  <dont>Letting size force the HTML tag instead of choosing render explicitly</dont>
+  <dont>Using Title for long body paragraphs</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="toast">
+  <rule>Pass title and description strings to toastManager.add for screen reader announcements on high-priority toasts</rule>
+  <rule>Keep toast copy concise; users can navigate the toast viewport landmark with F6</rule>
+  <rule>Ensure action and dismiss controls have visible labels</rule>
+  <rule>Use anchored toasts for contextual feedback tied to a specific trigger</rule>
+</a11y>

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

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="toast" title="Toast" category="feedback" shared_contract="toast">
+  <summary>Non-callable compound Toast namespace for transient notifications, with stacked or anchored placement, Banner high-level API, and optional action buttons.</summary>
+  <exports>
+    <export name="Toast" />
+  </exports>
+  <related>
+    <ref id="button" />
+    <ref id="surface" />
+    <ref id="stack" />
+    <ref id="dialog" />
+  </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/toast#api-reference" />
+</meta>

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

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="toast">
+  <example title="Toast structure">
+    <tsx><![CDATA[<Toast.Provider>
+  <Toast.Portal>
+    <Toast.Viewport>
+      <Toast.Banner toast={…}>
+        <Toast.Action>…</Toast.Action>
+      </Toast.Banner>
+    </Toast.Viewport>
+  </Toast.Portal>
+</Toast.Provider>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="toast">
+  <when_to_use>
+    <item>Confirming a completed action such as save or delete</item>
+    <item>Offering a short undo window after a reversible change</item>
+    <item>Showing contextual feedback anchored to the control that triggered it</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>Blocking errors that need immediate correction — use inline field errors or a dialog</item>
+    <item>Persistent status that should stay visible — use inline status text or a banner pattern</item>
+    <item>Long-form content that needs reading time — use a dialog or dedicated panel</item>
+  </when_not_to_use>
+  <prop name="Banner.children" kind="react">
+    <description>Optional action buttons. Accepts a single `Toast.Action` or an array of them.</description>
+  </prop>
+  <prop name="Banner.className" kind="react">
+    <description>Class name forwarded to the toast root.</description>
+  </prop>
+  <prop name="Banner.description" kind="react">
+    <description>Supporting copy below the title.</description>
+  </prop>
+  <prop name="Banner.dismissable" kind="react">
+    <description>Whether to render the dismiss control.</description>
+  </prop>
+  <prop name="Banner.dismissLabel" kind="react">
+    <description>Label for the dismiss control.</description>
+  </prop>
+  <prop name="Banner.onDismiss" kind="react">
+    <description>Called when the dismiss control is activated, before Base UI closes the toast.</description>
+  </prop>
+  <prop name="Banner.title" kind="react">
+    <description>Heading above the description. Falls back to `toast.title` from `toastManager.add`.</description>
+  </prop>
+  <prop name="Banner.toast" kind="react">
+    <description>Toast instance from `Toast.useToastManager().toasts` or `Toast.createToastManager()`.</description>
+  </prop>
+  <prop name="Viewport.position" kind="react">
+    <description>Controls viewport placement and stacking layout hooks.</description>
+  </prop>
+
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="toast">
+  <do>Confirming a completed action such as save or delete</do>
+  <do>Offering a short undo window after a reversible change</do>
+  <do>Showing contextual feedback anchored to the control that triggered it</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <dont>Nesting arbitrary components inside Toast.Banner — children must be Toast.Action only</dont>
+  <dont>Stacking many simultaneous toasts without a clear limit</dont>
+  <dont>Using toasts for critical validation errors that block task completion</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="toggle-button">
+  <rule>Provide aria-label or aria-labelledby on every ToggleButton — icon alone is not a name</rule>
+  <rule>Base UI Toggle exposes aria-pressed on the rendered button</rule>
+  <rule>Keep the accessible name stable when loading state changes</rule>
+</a11y>

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

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="toggle-button" title="ToggleButton" category="action" shared_contract="toggle-button">
+  <summary>Icon-only two-state toggle that swaps resting and optional pressed icons on Base UI Toggle state; `interpolateIcons` (default false) opt-in crossfade + light rotate between dual icons.</summary>
+  <exports>
+    <export name="ToggleButton" />
+  </exports>
+  <related>
+    <ref id="icon-button" />
+    <ref id="button" />
+    <ref id="switch" />
+    <ref id="toggle-group" />
+  </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/toggle#api-reference" />
+</meta>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="toggle-button">
+  <example title="ToggleButton structure">
+    <tsx><![CDATA[<ToggleButton restingIcon={<Plus />} aria-label="Pin" />]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="toggle-button">
+  <when_to_use>
+    <item>Toolbar pin, favorite, or mute toggles identified only by icon</item>
+    <item>Compact on/off controls that share IconButton size, variant, and loading model</item>
+    <item>Two-state actions where pressed state should swap the visible glyph</item>
+    <item>Temporally swap icons after user interactions with temporal pressed state, like copy feedback.</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Settings-style on/off fields — use Switch</item>
+    <item>One-shot actions with no pressed state — use IconButton</item>
+  </when_not_to_use>
+  <prop name="interpolateIcons" kind="react">
+    <description>When `pressedIcon` is set, crossfade and rotate between resting and pressed icons (`data-interpolate=&quot;true&quot;`). When `false`, swap instantly with no transition.</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="pressedIcon" kind="react">
+    <description>Icon shown while the toggle is pressed.</description>
+  </prop>
+  <prop name="pressedVariant" kind="react">
+    <description>Visual variant while the toggle is pressed.</description>
+  </prop>
+  <prop name="restingIcon" kind="react">
+    <description>Icon shown while the toggle is not pressed.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Controls the visual button size.</description>
+  </prop>
+  <prop name="variant" kind="react">
+    <description>Visual variant while the toggle is not pressed.</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>
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="toggle-button">
+  <do>Toolbar pin, favorite, or mute toggles identified only by icon</do>
+  <do>Compact on/off controls that share IconButton size, variant, and loading model</do>
+  <do>Two-state actions where pressed state should swap the visible glyph</do>
+  <do>Temporally swap icons after user interactions with temporal pressed state, like copy feedback.</do>
+  <dont>Using IconButton for persistent pressed toolbar state</dont>
+  <dont>Using Switch for compact icon-only toolbar toggles</dont>
+  <dont>Passing icon or render — ToggleButton owns icon swap and Toggle render wiring</dont>
+</usage>

package/dist/specs/components/toggle-group/a11y.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="toggle-group">
+  <rule>Provide aria-label or aria-labelledby on the ToggleGroup root</rule>
+  <rule>Provide aria-label or aria-labelledby on every ToggleButton child</rule>
+  <rule>Each ToggleButton exposes aria-pressed; group selection follows Base UI ToggleGroup semantics</rule>
+</a11y>

package/dist/specs/components/toggle-group/meta.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="toggle-group" title="ToggleGroup" category="action" shared_contract="toggle-group">
+  <summary>Toolbar toggle set with shared selection state; Stack direction follows orientation with zero default gap.</summary>
+  <exports>
+    <export name="ToggleGroup" />
+  </exports>
+  <related>
+    <ref id="toggle-button" />
+    <ref id="icon-button" />
+    <ref id="tabs" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/toggle-group#api-reference" />
+</meta>

package/dist/specs/components/toggle-group/patterns.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="toggle-group">
+  <example title="ToggleGroup structure">
+    <tsx><![CDATA[<ToggleGroup>
+  <ToggleButton restingIcon={<Plus />} aria-label="List" value="list" />
+</ToggleGroup>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

package/dist/specs/components/toggle-group/props.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="toggle-group">
+  <when_to_use>
+    <item>Segmented icon toolbars such as text alignment or formatting controls</item>
+    <item>Single- or multi-select pressed states across related ToggleButton items</item>
+    <item>Compact action clusters that need coordinated value and disabled state</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Standalone one-off toggles — use ToggleButton</item>
+    <item>Settings-style on/off fields — use Switch</item>
+    <item>Tabbed panel navigation — use Tabs</item>
+  </when_not_to_use>
+
+
+</props>

package/dist/specs/components/toggle-group/usage.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="toggle-group">
+  <do>Segmented icon toolbars such as text alignment or formatting controls</do>
+  <do>Single- or multi-select pressed states across related ToggleButton items</do>
+  <do>Compact action clusters that need coordinated value and disabled state</do>
+  <dont>Omitting value on ToggleButton children inside a group</dont>
+  <dont>Using Switch for icon-only toolbar toggle sets</dont>
+  <dont>Embedding Surface chrome in the component — wrap demos or app chrome at the consumer</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="tooltip">
+  <rule>Match trigger `aria-label` to tooltip copy so sighted and assistive users get the same hint</rule>
+  <rule>Keep tooltip copy concise; use Popover when the hint needs paragraphs, links, or controls</rule>
+  <rule>Wrap regions with multiple tooltips in `Tooltip.Provider` for predictable delay grouping</rule>
+</a11y>

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

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="tooltip" title="Tooltip" category="overlay" shared_contract="tooltip">
+  <summary>Compound tooltip built on Base UI Tooltip with `Tooltip.Provider`, `Tooltip.Trigger`, `Tooltip.Content`, and `Tooltip.createHandle` for detached and multiple triggers; `Content` encapsulates Portal + Positioner + Popup + Viewport and animates position, size, and content between triggers.</summary>
+  <exports>
+    <export name="Tooltip" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="button" />
+    <ref id="icon-button" />
+    <ref id="stack" />
+    <ref id="popover" />
+  </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/tooltip#api-reference" />
+</meta>

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

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

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

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="tooltip">
+  <when_to_use>
+    <item>Short hints on hover or focus for toolbar controls and icon buttons</item>
+    <item>Per-trigger labels on shared tooltip roots using `payload` and Root render-function children</item>
+    <item>Adjacent controls that benefit from shared open/close delay via `Tooltip.Provider`</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>Rich interactive panels or forms (use Popover or Dialog)</item>
+    <item>System-wide transient alerts (use Toast)</item>
+    <item>Content that must stay open while the pointer moves into the popup (enable `disableHoverablePopup` only when needed)</item>
+  </when_not_to_use>
+  <prop name="Content.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>
+  <css_var suffix="content-fade-duration">
+    <description>content fade duration custom property on the component root.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="tooltip">
+  <do>Short hints on hover or focus for toolbar controls and icon buttons</do>
+  <do>Per-trigger labels on shared tooltip roots using `payload` and Root render-function children</do>
+  <do>Adjacent controls that benefit from shared open/close delay via `Tooltip.Provider`</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <dont>Putting essential-only information in a tooltip with no accessible name on the trigger</dont>
+  <dont>Expecting `Tooltip.Arrow` (it is intentionally not exported or rendered)</dont>
+  <dont>Using tooltip for modal or focus-trapped tasks</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="typewriter">
+  <rule>One phrase layer (Ghost when preserveSpace, clipped A11y otherwise) holds the full current phrase and announces via aria-live</rule>
+  <rule>The absolute/in-flow typed layer is aria-hidden and only paints the progressive effect plus caret</rule>
+  <rule>Reduced motion shows the final phrase immediately without cycling delays</rule>
+  <rule>Parent region owns loading or busy semantics when Typewriter is decorative</rule>
+</a11y>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="typewriter" title="Typewriter" category="typography" shared_contract="typewriter">
+  <summary>Decorative inline typewriter animation that inherits typography and color from a parent text primitive.</summary>
+  <exports>
+    <export name="Typewriter" />
+  </exports>
+  <related>
+    <ref id="text" />
+    <ref id="title" />
+    <ref id="shimmer" />
+  </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>