@viraui/react 2026.3.11 → 2026.4.1

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>

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

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

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

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="typewriter">
+  <when_to_use>
+    <item>Hero or marketing copy that cycles through short phrases</item>
+    <item>Loading or status labels that reveal text progressively</item>
+    <item>Muted intro copy inside Text or Title where motion adds emphasis</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Standalone accessible status updates without a surrounding labeled region</item>
+    <item>Long-form content better served by static Text</item>
+    <item>Cases where reduced-motion users must see every phrase in a multi-text cycle</item>
+  </when_not_to_use>
+  <prop name="caret" kind="react">
+    <description>Selects the caret style rendered after the typed text.</description>
+  </prop>
+  <prop name="caretColor" kind="react">
+    <description>Overrides the caret color.</description>
+  </prop>
+  <prop name="delay" kind="react">
+    <description>Sets the initial delay before typing starts, in milliseconds.</description>
+  </prop>
+  <prop name="deleteSpeed" kind="react">
+    <description>Sets the delay between deleted characters in milliseconds.</description>
+  </prop>
+  <prop name="loop" kind="react">
+    <description>Repeats the phrase cycle after the final phrase is deleted.</description>
+  </prop>
+  <prop name="pause" kind="react">
+    <description>Sets the pause after a phrase completes before deletion starts, in milliseconds.</description>
+  </prop>
+  <prop name="preserveSpace" kind="react">
+    <description>Reserves the full phrase width and height (including wrap under parent constraints) from first paint through delay, typing, and deletion.</description>
+  </prop>
+  <prop name="speed" kind="react">
+    <description>Sets the delay between typed characters in milliseconds.</description>
+  </prop>
+  <prop name="texts" kind="react">
+    <description>Cycles through multiple phrases instead of a single `children` string.</description>
+  </prop>
+  <css_var suffix="caret-color">
+    <description>Typewriter caret color.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="typewriter">
+  <do>Hero or marketing copy that cycles through short phrases</do>
+  <do>Loading or status labels that reveal text progressively</do>
+  <do>Muted intro copy inside Text or Title where motion adds emphasis</do>
+  <dont>Using Typewriter as the only source of critical status information</dont>
+  <dont>Embedding layout positioning rules inside the component stylesheet</dont>
+  <dont>Restarting animation on every parent render by passing unstable inline text arrays without stable content</dont>
+  <dont>Setting parent Text or Title trim={false} solely so preserveSpace can reserve wrapped height</dont>
+  <dont>Driving per-character typing through React state (use DOM writes on the typed layer instead)</dont>
+</usage>