@viraui/react 2026.3.10 → 2026.4.0

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="accordion">
+  <do>Progressive disclosure for related content sections in one surface</do>
+  <do>FAQ or settings groups where only one section may be open by default</do>
+  <do>Multiple open sections when `multiple` is enabled</do>
+  <dont>Trying to compose separate public `Accordion.Header`, `Accordion.Trigger`, or `Accordion.Panel` exports</dont>
+  <dont>Rendering an item without trigger text and without an external aria-label strategy</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="annotate">
+  <rule>Arrow and note are presentational spans with aria-hidden — decorative only and not exposed to assistive tech</rule>
+  <rule>Do not put critical information in note; keep real meaning in children or aria-describedby content</rule>
+  <rule>Children retain native semantics; Annotate itself is a presentational span wrap</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="annotate" title="Annotate" category="effect" shared_contract="annotate">
+  <summary>Decorative arrow and handwritten label that wraps inline content with optional highlighter mark, positioned via CSS anchor positioning.</summary>
+  <exports>
+    <export name="Annotate" />
+  </exports>
+  <related>
+    <ref id="text" />
+    <ref id="title" />
+    <ref id="tooltip" />
+    <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>
+</meta>

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

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

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

@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="annotate">
+  <when_to_use>
+    <item>Call out a word or phrase in marketing, docs, or onboarding copy</item>
+    <item>Add a playful visual annotation without interactive chrome</item>
+    <item>Highlight a target with an optional mark while keeping children as the real content</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Conveying critical instructions, status, or validation that assistive tech must announce</item>
+    <item>Interactive tooltips or popovers that need focus and keyboard behavior</item>
+    <item>Layouts that clip overflow and cannot leave room for the arrow and label</item>
+  </when_not_to_use>
+  <prop name="arrowOffsetX" kind="react">
+    <description>Horizontal offset for the arrow pseudo (`--vui-annotate-arrow-x`).</description>
+  </prop>
+  <prop name="arrowOffsetY" kind="react">
+    <description>Vertical offset for the arrow pseudo (`--vui-annotate-arrow-y`).</description>
+  </prop>
+  <prop name="color" kind="react">
+    <description>Highlight token driving arrow, label, and optional mark color via `--vui-annotate-color`.</description>
+  </prop>
+  <prop name="labelGap" kind="react">
+    <description>Gap between arrow and label on all sides via `--vui-annotate-label-gap`.</description>
+  </prop>
+  <prop name="labelMaxWidth" kind="react">
+    <description>Max width for the label pseudo via `--vui-annotate-label-max-width`.</description>
+  </prop>
+  <prop name="mark" kind="react">
+    <description>When true, applies a highlighter mark behind the wrapped content.</description>
+  </prop>
+  <prop name="note" kind="react">
+    <description>Decorative label rendered in a presentational note span (not announced). Do not put critical information here — assistive tech does not announce the note.</description>
+  </prop>
+  <prop name="rotate" kind="react">
+    <description>Rotation for the label (and composed transforms) via `--vui-annotate-rotate`.</description>
+  </prop>
+  <prop name="side" kind="react">
+    <description>Places the decorative arrow and label relative to the wrapped content.</description>
+  </prop>
+  <prop name="targetGap" kind="react">
+    <description>Gap between the target and the arrow via `--vui-annotate-target-gap`.</description>
+  </prop>
+  <prop name="textAlign" kind="react">
+    <description>Text alignment for the note via `--vui-annotate-text-align`.</description>
+  </prop>
+  <prop name="textOffsetX" kind="react">
+    <description>Horizontal nudge for the note part (translateX on the inner nudge wrapper).</description>
+  </prop>
+  <prop name="textOffsetY" kind="react">
+    <description>Vertical nudge for the note part (translateY on the inner nudge wrapper).</description>
+  </prop>
+  <prop name="zIndex" kind="react">
+    <description>Stacking order for arrow and note via `--vui-annotate-z-index`. Same value on both parts.</description>
+  </prop>
+  <css_var suffix="arrow-x">
+    <description>Horizontal arrow offset.</description>
+  </css_var>
+  <css_var suffix="arrow-y">
+    <description>Vertical arrow offset.</description>
+  </css_var>
+  <css_var suffix="color">
+    <description>Arrow, note, and mark accent color. Defaults to var(--global-foreground).</description>
+  </css_var>
+  <css_var suffix="label-gap">
+    <description>Gap between arrow and note on all sides.</description>
+  </css_var>
+  <css_var suffix="label-max-width">
+    <description>Max width for the note part.</description>
+  </css_var>
+  <css_var suffix="rotate">
+    <description>Note rotation angle.</description>
+  </css_var>
+  <css_var suffix="target-gap">
+    <description>Gap between the target and the arrow.</description>
+  </css_var>
+  <css_var suffix="text-align">
+    <description>Text alignment for the note. Defaults to start.</description>
+  </css_var>
+  <css_var suffix="text-x">
+    <description>Legacy horizontal note offset custom property. Prefer textOffsetX from React.</description>
+  </css_var>
+  <css_var suffix="text-y">
+    <description>Legacy vertical note offset custom property. Prefer textOffsetY from React.</description>
+  </css_var>
+  <css_var suffix="z-index">
+    <description>Stacking order for arrow and note. Defaults to auto.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="annotate">
+  <do>Call out a word or phrase in marketing, docs, or onboarding copy</do>
+  <do>Add a playful visual annotation without interactive chrome</do>
+  <do>Highlight a target with an optional mark while keeping children as the real content</do>
+  <dont>Using note as the only source of instructions or status</dont>
+  <dont>Nesting Annotate inside overflow-hidden parents without padding for the arrow</dont>
+  <dont>Expecting the label to participate in hit-testing or selection</dont>
+  <dont>Adding position:relative on Annotate — it breaks CSS anchor position-area placement</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="autocomplete">
+  <rule>Provide label or aria-label so the input has an accessible name</rule>
+  <rule>Wire description and error copy through the field pattern so assistive tech gets helper text</rule>
+  <rule>Keep empty and status slots mounted; update their children when messaging changes</rule>
+</a11y>

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

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="autocomplete" title="Autocomplete" category="form" shared_contract="autocomplete">
+  <summary>Field-wrapped free-form suggest input with Textfield chrome and Select-like popup list.</summary>
+  <exports>
+    <export name="Autocomplete" />
+  </exports>
+  <related>
+    <ref id="textfield" />
+    <ref id="select" />
+    <ref id="fieldset" />
+    <ref id="stack" />
+    <ref id="surface" />
+    <ref id="spinner" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/autocomplete#api-reference" />
+</meta>

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

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="autocomplete">
+  <example title="Autocomplete structure">
+    <tsx><![CDATA[<Autocomplete>
+  <Autocomplete.Item value="…">…</Autocomplete.Item>
+  <Autocomplete.Group label="…" items={[…]}>
+    <Autocomplete.Collection>
+      {(item) => <Autocomplete.Item value={item}>…</Autocomplete.Item>}
+    </Autocomplete.Collection>
+  </Autocomplete.Group>
+</Autocomplete>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="autocomplete">
+  <when_to_use>
+    <item>Suggest options while allowing free-form text in the input</item>
+    <item>Filterable tag, movie, or docs search with optional empty and status copy</item>
+    <item>Grouped suggestion lists via Autocomplete.Group and Collection</item>
+    <item>Async or limited result lists that need polite status announcements</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>Remembered selection from a closed list — use Select (or Combobox when available)</item>
+    <item>Command palette, grid picker, or virtualized lists — separate surfaces on Base UI Autocomplete</item>
+    <item>Wrapping a lone Autocomplete in Fieldset when its own label is sufficient</item>
+  </when_not_to_use>
+  <prop name="children" kind="react">
+    <description>List content: static Item, Group, or Collection nodes, or a Base UI list render function.</description>
+  </prop>
+  <prop name="container" kind="react">
+    <description>Portal mount node (iframe body, shadow root, or app overlay root). Omit for Base UI default (`document.body` from the module window — iframe hosts must pass the iframe document body explicitly).</description>
+  </prop>
+  <prop name="description" kind="react">
+    <description>Helper copy rendered with `Field.Description` and `Text` while the field is valid.</description>
+  </prop>
+  <prop name="empty" kind="react">
+    <description>Content rendered inside baked `Autocomplete.Empty` when the filtered list has no items.</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.</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-autocomplete-input-height)`. Omitted / `false` keeps the browser fixed default.</description>
+  </prop>
+  <prop name="Group.label" kind="react">
+    <description>Accessible group label rendered with `Autocomplete.GroupLabel`.</description>
+  </prop>
+  <prop name="Item.addon" kind="react">
+    <description>Decorative leading node rendered before the item label.</description>
+  </prop>
+  <prop name="Item.addonAlign" kind="react">
+    <description>Vertical alignment of the addon relative to the item label row.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible label rendered with shared internal `FieldLabel`.</description>
+  </prop>
+  <prop name="placeholder" kind="react">
+    <description>Placeholder text shown in the input when empty.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the autocomplete input.</description>
+  </prop>
+  <prop name="startAddon" kind="react">
+    <description>Leading decoration (prefix text, icon). Not a second field control.</description>
+  </prop>
+  <prop name="status" kind="react">
+    <description>Content rendered inside baked `Autocomplete.Status` (async / limit messaging). Keep the slot mounted; update children when status changes.</description>
+  </prop>
+  <css_var suffix="control-group-background">
+    <description>Autocomplete control group background.</description>
+  </css_var>
+  <css_var suffix="control-group-border-color">
+    <description>Autocomplete control group border color; invalid state overrides.</description>
+  </css_var>
+  <css_var suffix="control-group-border-radius">
+    <description>Autocomplete control group corner radius.</description>
+  </css_var>
+  <css_var suffix="control-group-color">
+    <description>Autocomplete control group foreground color.</description>
+  </css_var>
+  <css_var suffix="input-height">
+    <description>Autocomplete control group block size.</description>
+  </css_var>
+  <css_var suffix="list-border-radius">
+    <description>Popup list border radius custom property on the popup root.</description>
+  </css_var>
+  <css_var suffix="list-padding">
+    <description>Popup list padding custom property used for scroll padding.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="autocomplete">
+  <do>Suggest options while allowing free-form text in the input</do>
+  <do>Filterable tag, movie, or docs search with optional empty and status copy</do>
+  <do>Grouped suggestion lists via Autocomplete.Group and Collection</do>
+  <do>Async or limited result lists that need polite status announcements</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <dont>Expecting Select-like closed selection state</dont>
+  <dont>Leaving the input without label or aria-label</dont>
+  <dont>Conditionally unmounting Empty or Status instead of updating their children</dont>
+</usage>

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

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="avatar">
+  <rule>Provide meaningful alt text when the image conveys identity</rule>
+  <rule>Use fallback text or initials when the image is unavailable</rule>
+</a11y>

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

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="avatar" title="Avatar" category="layout" shared_contract="avatar">
+  <summary>Circular identity image or fallback for users, entities, or profile chips.</summary>
+  <exports>
+    <export name="Avatar" />
+  </exports>
+  <related>
+    <ref id="skeleton" />
+  </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/avatar#api-reference" />
+</meta>

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

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

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

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="avatar">
+  <when_to_use>
+    <item>Show a user or entity photo with text or image fallback</item>
+    <item>Display profile chips from x-small through large sizes</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Interactive controls or navigation</item>
+    <item>Non-identity imagery without a fallback plan</item>
+  </when_not_to_use>
+  <prop name="alt" kind="react">
+    <description>Supplies alternative text for the avatar image.</description>
+  </prop>
+  <prop name="fallback" kind="react">
+    <description>Supplies the content shown when the image is absent or fails to load.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered avatar root element.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Selects the rendered avatar footprint.</description>
+  </prop>
+  <prop name="src" kind="react">
+    <description>Supplies the avatar image source URL.</description>
+  </prop>
+  <css_var suffix="background">
+    <description>Root background fill behind image or fallback.</description>
+  </css_var>
+  <css_var suffix="foreground">
+    <description>Root foreground color for fallback content.</description>
+  </css_var>
+  <css_var suffix="radius">
+    <description>Corner radius on the root; size presets also adjust this.</description>
+  </css_var>
+  <css_var suffix="size">
+    <description>Avatar inline and block size on the root.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="avatar">
+  <do>Show a user or entity photo with text or image fallback</do>
+  <do>Display profile chips from x-small through large sizes</do>
+  <dont>Relying on Avatar children for layout sizing</dont>
+  <dont>Omitting meaningful alt text when the image conveys identity</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="avatar-group">
+  <rule>Provide meaningful alt text on each avatar image when identity matters</rule>
+  <rule>Treat overflow content such as +3 or +9938 as summary text rather than an interactive affordance</rule>
+  <rule>Keep decorative avatars on empty alt text when the surrounding context already labels the group</rule>
+</a11y>

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

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="avatar-group" title="AvatarGroup" category="layout" shared_contract="avatar-group">
+  <summary>Overlapping avatar stack with shared sizing, directional layout, and an optional overflow pill.</summary>
+  <exports>
+    <export name="AvatarGroup" />
+  </exports>
+  <related>
+    <ref id="avatar" />
+  </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/avatar-group/patterns.xml

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

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

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="avatar-group">
+  <when_to_use>
+    <item>Show a compact list of people or entities with consistent avatar sizing</item>
+    <item>Display overlapping identity clusters in horizontal or vertical layouts</item>
+    <item>Collapse long avatar lists into a final overflow pill such as +15 or +9938</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Interactive chip collections that need per-item actions</item>
+    <item>Mixed avatar sizes inside one group</item>
+  </when_not_to_use>
+  <prop name="avatars" kind="react">
+    <description>Supplies the avatar payloads rendered by the group in DOM order.</description>
+  </prop>
+  <prop name="direction" kind="react">
+    <description>Chooses whether avatars overlap across the inline or block axis.</description>
+  </prop>
+  <prop name="maxVisible" kind="react">
+    <description>Limits how many real avatars render before the optional overflow pill is appended. Omitted, zero, and negative values are ignored.</description>
+  </prop>
+  <prop name="overflowText" kind="react">
+    <description>Supplies the content rendered inside the optional overflow pill when truncation is active.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Selects the shared avatar footprint for every rendered avatar.</description>
+  </prop>
+  <css_var suffix="gap-size">
+    <description>Cutout gap used by overlap clip-path math.</description>
+  </css_var>
+  <css_var suffix="item-radius">
+    <description>Corner radius applied to grouped avatar items.</description>
+  </css_var>
+  <css_var suffix="overlap-distance">
+    <description>Negative margin overlap between adjacent avatars.</description>
+  </css_var>
+  <css_var suffix="size">
+    <description>Rendered avatar size used for overlap layout.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="avatar-group">
+  <do>Show a compact list of people or entities with consistent avatar sizing</do>
+  <do>Display overlapping identity clusters in horizontal or vertical layouts</do>
+  <do>Collapse long avatar lists into a final overflow pill such as +15 or +9938</do>
+  <dont>Passing per-avatar size values instead of using the group size prop</dont>
+  <dont>Expecting AvatarGroup to derive hidden-count labels instead of passing overflowText directly</dont>
+  <dont>Expecting grouped avatars to always render as circles — items keep theme radius/squircle via --vui-avatar-group-item-radius</dont>
+  <dont>Using non-positive maxVisible values expecting truncation</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="badge">
+  <rule>The status dot is a decorative ::after pseudo — not exposed to assistive tech</rule>
+  <rule>Do not rely on the dot alone for status; keep real meaning in the child&apos;s accessible name or nearby text</rule>
+  <rule>Children retain native semantics; Badge itself is a presentational div wrap</rule>
+  <rule>Enter/exit motion (hole↔dot, reverse on hide) is suppressed under prefers-reduced-motion</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="badge" title="Badge" category="feedback" shared_contract="badge">
+  <summary>Decorative status-dot overlay that wraps a child, with optional radial mask cutout on the child around the corner dot.</summary>
+  <exports>
+    <export name="Badge" />
+  </exports>
+  <related>
+    <ref id="avatar" />
+    <ref id="avatar-group" />
+    <ref id="chip" />
+    <ref id="annotate" />
+  </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/badge/patterns.xml

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

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

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="badge">
+  <when_to_use>
+    <item>Show online/offline or presence on an Avatar or icon without changing the child component API</item>
+    <item>Mark a control as needing attention with a small corner indicator</item>
+    <item>Keep Chip for labeled text badges; use Badge only for the status-dot overlay</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Conveying critical status that assistive tech must announce — put real meaning in the child name or nearby text</item>
+    <item>Labeled text badges or tags — use Chip</item>
+    <item>Count or text inside a pill — out of scope for v1</item>
+  </when_not_to_use>
+  <prop name="color" kind="react">
+    <description>Highlight token driving the status-dot color via `--vui-badge-color`.</description>
+  </prop>
+  <prop name="position" kind="react">
+    <description>Places the status dot on a corner of the wrapped content.</description>
+  </prop>
+  <prop name="show" kind="react">
+    <description>When true, shows the decorative status dot and applies the radial mask cutout. Enter: hole expands, then the dot scales in. Exit: reverse (dot then hole).</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Diameter of the status dot via `--vui-badge-size`.</description>
+  </prop>
+  <css_var suffix="color">
+    <description>Status-dot accent color. Defaults to var(--global-primary).</description>
+  </css_var>
+  <css_var suffix="position-x">
+    <description>Horizontal status-dot anchor. Position presets set it to 0% for start or 100% for end.</description>
+  </css_var>
+  <css_var suffix="position-y">
+    <description>Vertical status-dot anchor. Position presets set it to 0% for top or 100% for bottom.</description>
+  </css_var>
+  <css_var suffix="size">
+    <description>Status-dot diameter. Defaults to 0.5rem.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="badge">
+  <do>Show online/offline or presence on an Avatar or icon without changing the child component API</do>
+  <do>Mark a control as needing attention with a small corner indicator</do>
+  <do>Keep Chip for labeled text badges; use Badge only for the status-dot overlay</do>
+  <dont>Using the visible dot as the only source of status for assistive tech</dont>
+  <dont>Wrapping multiple element children when only one should receive the radial mask cutout</dont>
+  <dont>Expecting the dot to participate in hit-testing</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="beam">
+  <rule>Root stays in the accessibility tree; bloom layer is empty div</rule>
+  <rule>Beam is not a focus or status indicator — consumer owns accessible names and state</rule>
+  <rule>Offscreen instances pause animations without firing activate/deactivate</rule>
+  <rule>prefers-reduced-motion disables motion and leaves a static resting look</rule>
+</a11y>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="beam" title="Beam" category="effect" shared_contract="beam">
+  <summary>Decorative animated border, line, or pulse glow on a transparent Surface shell (radius only). Put the visual card as children. CSS-module geometry plus shared ~30fps pulse rAF for pulse variants. Memory/CPU cost — use sparingly.</summary>
+  <exports>
+    <export name="Beam" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="glow" />
+    <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/beam/patterns.xml

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