@viraui/react 2026.3.11 → 2026.4.0

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

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="popover">
+  <do>Anchored quick actions or contextual hints next to a triggering control</do>
+  <do>Lightweight forms or confirmations that float beside the trigger without blocking the page</do>
+  <do>Multi-trigger panels that swap content with direction-aware animations using `Popover.createHandle` and trigger `payload`</do>
+  <do>Hover-revealed hints via `openOnHover` with `delay` and `closeDelay`</do>
+  <do>Fully custom popup chrome via `Sheet` `unstyled` composed with `Popover.Title` and `Popover.Description`</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <dont>Opening a popover without `title` copy for assistive technologies</dont>
+  <dont>Rendering heavy or scroll-bound content that belongs in a Dialog</dont>
+  <dont>Expecting `Popover.Arrow` (it is intentionally not exported or rendered)</dont>
+</usage>

package/dist/specs/components/progressive-blur/a11y.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="progressive-blur">
+  <rule>ProgressiveBlur is decorative — the root hardcodes `aria-hidden=&quot;true&quot;` (not overridable via props)</rule>
+  <rule>Parent surface or region must expose any meaningful label or busy state</rule>
+  <rule>Consumer must position the root non-static (for example `position: relative`/`absolute`/`fixed`) and own inset, z-index, and sizing — ProgressiveBlur does not create a containing block</rule>
+</a11y>

package/dist/specs/components/progressive-blur/meta.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="progressive-blur" title="ProgressiveBlur" category="effect" shared_contract="progressive-blur">
+  <summary>Decorative stacked backdrop-filter overlay that ramps blur from one edge toward the opposite edge.</summary>
+  <exports>
+    <export name="ProgressiveBlur" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="static-noise" />
+  </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/progressive-blur/patterns.xml

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

package/dist/specs/components/progressive-blur/props.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="progressive-blur">
+  <when_to_use>
+    <item>Edge scrims on cards, sheets, heroes, or scroll regions where content should fade into blur</item>
+    <item>Glass or vibrant surfaces that need directional legibility without a hard blur cutoff</item>
+    <item>Decorative atmosphere where the parent owns semantics and layout positioning</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Standalone loading or status feedback without a labeled parent region</item>
+    <item>Large full-viewport stacks with many simultaneous high-radius blur layers</item>
+    <item>Cases where a single uniform backdrop blur is sufficient</item>
+  </when_not_to_use>
+  <prop name="blur" kind="react">
+    <description>Sets the maximum blur radius applied to the first layer at the selected edge.</description>
+  </prop>
+  <prop name="direction" kind="react">
+    <description>Selects the edge where maximum blur starts and fades toward the opposite edge.</description>
+  </prop>
+  <prop name="easing" kind="react">
+    <description>Selects the easing curve used to distribute blur factors across internal layers.</description>
+  </prop>
+  <prop name="steps" kind="react">
+    <description>Sets the number of internal blur layers. Values are clamped to `2..16`.</description>
+  </prop>
+  <css_var suffix="amount">
+    <description>Sets the maximum blur radius applied to the first layer at the selected edge.</description>
+  </css_var>
+</props>

package/dist/specs/components/progressive-blur/usage.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="progressive-blur">
+  <do>Edge scrims on cards, sheets, heroes, or scroll regions where content should fade into blur</do>
+  <do>Glass or vibrant surfaces that need directional legibility without a hard blur cutoff</do>
+  <do>Decorative atmosphere where the parent owns semantics and layout positioning</do>
+  <dont>Stacking many full-viewport ProgressiveBlur instances on one screen</dont>
+  <dont>Driving layout size or scroll behavior from inside the overlay component</dont>
+  <dont>Embedding layout positioning rules inside the component stylesheet</dont>
+  <dont>Leaving the ProgressiveBlur root `position: static` so absolute layers escape the intended overlay box</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="radio">
+  <rule>Wrap options in RadioGroup so the group exposes a shared name</rule>
+  <rule>Provide visible label or aria-label on each option so radios have accessible names</rule>
+  <rule>Surface group invalid state and error copy through Field.Root and Fieldset, not individual Radio options</rule>
+</a11y>

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

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="radio" title="Radio" category="form" shared_contract="radio">
+  <summary>Mutually exclusive choice within a RadioGroup, with optional per-option label and helper text.</summary>
+  <exports>
+    <export name="Radio" />
+  </exports>
+  <related>
+    <ref id="fieldset" />
+    <ref id="checkbox" />
+    <ref id="surface" />
+    <ref id="stack" />
+  </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/radio#api-reference" />
+</meta>

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

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

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

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="radio">
+  <when_to_use>
+    <item>Single selection from a small set of related options inside RadioGroup</item>
+    <item>RadioGroup alone inside Field.Root when each Radio has its own label and no shared group legend is needed</item>
+    <item>Field.Root &gt; Fieldset render={&lt;RadioGroup&lt;Value&gt; /&gt;} when the group needs a shared legend, description, or error</item>
+    <item>Card-style or custom layouts where each option is wrapped in Surface or consumer markup</item>
+    <item>Typed option unions with RadioGroup&lt;&apos;ssd&apos; | &apos;hdd&apos;&gt; for value, defaultValue, and onValueChange safety</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Independent boolean toggles (use Checkbox or Switch)</item>
+    <item>Multi-select sets (use CheckboxGroup)</item>
+    <item>Options rendered outside a RadioGroup wrapper</item>
+    <item>Assuming Fieldset is mandatory for every RadioGroup — add Fieldset only for shared legend or group copy</item>
+    <item>Group legend, description, or validation on RadioGroup props — use Field.Root and Fieldset instead</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Helper copy rendered with `Field.Description` and `Text` for this option.</description>
+  </prop>
+  <prop name="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 radio size.</description>
+  </prop>
+  <prop name="vPadding" kind="react">
+    <description>Sets block padding using one token for both sides or a `[start, end]` tuple.</description>
+  </prop>
+  <css_var suffix="background">
+    <description>Radio control background color.</description>
+  </css_var>
+  <css_var suffix="border-color">
+    <description>Radio control border color; resting default is transparent (same as Checkbox); checked, invalid, and disabled states override.</description>
+  </css_var>
+  <css_var suffix="indicator-color">
+    <description>Radio selected-disk indicator color.</description>
+  </css_var>
+  <css_var suffix="size">
+    <description>Radio control size; size presets adjust footprint.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="radio">
+  <do>Single selection from a small set of related options inside RadioGroup</do>
+  <do>RadioGroup alone inside Field.Root when each Radio has its own label and no shared group legend is needed</do>
+  <do>Field.Root &gt; Fieldset render={&lt;RadioGroup&lt;Value&gt; /&gt;} when the group needs a shared legend, description, or error</do>
+  <do>Card-style or custom layouts where each option is wrapped in Surface or consumer markup</do>
+  <do>Typed option unions with RadioGroup&lt;&apos;ssd&apos; | &apos;hdd&apos;&gt; for value, defaultValue, and onValueChange safety</do>
+  <dont>Rendering Radio outside RadioGroup</dont>
+  <dont>Putting invalid or error on a single Radio instead of the enclosing Field.Root and Fieldset</dont>
+  <dont>Omitting the RadioGroup generic when option value props form a restricted union</dont>
+  <dont>Importing @viraui/react/radio/radio.css or other component CSS subpaths in consumer bootstrap</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="select">
+  <rule>Provide label or aria-label on the trigger so the field has an accessible name</rule>
+  <rule>Wire description and error copy through the field pattern so assistive tech gets helper text</rule>
+  <rule>Keep list options keyboard reachable; do not trap focus outside the popup pattern</rule>
+</a11y>

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

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="select" title="Select" category="form" shared_contract="select">
+  <summary>Field-wrapped single-select dropdown with grouped options and field copy.</summary>
+  <exports>
+    <export name="Select" />
+  </exports>
+  <related>
+    <ref id="autocomplete" />
+    <ref id="fieldset" />
+    <ref id="textfield" />
+    <ref id="stack" />
+    <ref id="surface" />
+  </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/select#api-reference" />
+</meta>

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

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

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

@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="select">
+  <when_to_use>
+    <item>Choose one value from a predefined list with label and helper copy</item>
+    <item>Grouped or separated option lists</item>
+    <item>Rich option rows with a leading decorative addon and multi-line label content</item>
+    <item>Trigger chrome aligned with Textfield control shell</item>
+    <item>Select fields inside Fieldset when they share a section legend with other inputs</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>Multiple selection</item>
+    <item>Free-form filterable suggestions — use Autocomplete</item>
+    <item>Combobox selection state, or custom anchor positioning</item>
+    <item>Wrapping a lone Select in Fieldset when its own label is sufficient</item>
+  </when_not_to_use>
+  <prop name="addon" kind="react">
+    <description>Trigger addon rendered inside `Select.Icon`. Pass any React node; use a named icon from `@viraui/icons/react` for content icons.</description>
+  </prop>
+  <prop name="alignListWithTrigger" kind="react">
+    <description>When `true`, aligns the list popup width with the trigger via Base UI `alignItemWithTrigger`. Prefer `false` when options use a leading `addon`.</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="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="Group.label" kind="react">
+    <description>Accessible group label rendered with `Select.GroupLabel`.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible label rendered with shared internal `FieldLabel`.</description>
+  </prop>
+  <prop name="modal" kind="react">
+    <description>When `true`, open select locks page scroll and blocks outside pointer interaction (Base UI modal). Vira defaults to non-modal so the page stays scrollable.</description>
+  </prop>
+  <prop name="Option.addon" kind="react">
+    <description>Decorative leading node rendered before the option label.</description>
+  </prop>
+  <prop name="Option.addonAlign" kind="react">
+    <description>Vertical alignment of the addon relative to the option label row.</description>
+  </prop>
+  <prop name="Option.indicator" kind="react">
+    <description>Custom indicator node rendered when the option is selected.</description>
+  </prop>
+  <prop name="placeholder" kind="react">
+    <description>Placeholder text shown in the trigger when no value is selected.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the select trigger button.</description>
+  </prop>
+  <css_var suffix="control-group-background">
+    <description>Trigger background fill.</description>
+  </css_var>
+  <css_var suffix="control-group-border-color">
+    <description>Trigger border color; invalid state overrides.</description>
+  </css_var>
+  <css_var suffix="control-group-border-radius">
+    <description>Trigger corner radius.</description>
+  </css_var>
+  <css_var suffix="control-group-color">
+    <description>Trigger text and icon color.</description>
+  </css_var>
+  <css_var suffix="input-height">
+    <description>Select trigger block size.</description>
+  </css_var>
+  <css_var suffix="list-border-radius">
+    <description>list border radius custom property on the component root.</description>
+  </css_var>
+  <css_var suffix="list-padding">
+    <description>list padding custom property on the component root.</description>
+  </css_var>
+  <css_var suffix="trigger-padding-inline-end">
+    <description>Trigger inline-end padding.</description>
+  </css_var>
+  <css_var suffix="trigger-padding-inline-start">
+    <description>Trigger inline-start padding.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="select">
+  <do>Choose one value from a predefined list with label and helper copy</do>
+  <do>Grouped or separated option lists</do>
+  <do>Rich option rows with a leading decorative addon and multi-line label content</do>
+  <do>Trigger chrome aligned with Textfield control shell</do>
+  <do>Select fields inside Fieldset when they share a section legend with other inputs</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <dont>Expecting multi-select or combobox behavior</dont>
+  <dont>Leaving the trigger without label or aria-label</dont>
+  <dont>Never set the size prop (if present) of Buttons, IconButtons or other interactive elements passed as addon other than small</dont>
+  <dont>Using the Select component as a combobox, use Autocomplete instead.</dont>
+  <dont>Leaving alignListWithTrigger enabled when options have a leading addon</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="separator">
+  <rule>Standalone line is a native hr (implicit separator); orientation is visual via data-separator-orientation and Stack direction</rule>
+  <rule>Menu.Separator / Select.Separator own a11y through Base UI (Menu: role separator + aria-orientation; Select listbox: role presentation)</rule>
+  <rule>Use render to swap the line root element when needed</rule>
+</a11y>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="separator" title="Separator" category="layout" shared_contract="separator">
+  <summary>Thematic or content divider with horizontal or vertical orientation, token padding, and preset line thickness.</summary>
+  <exports>
+    <export name="Separator" />
+  </exports>
+  <related>
+    <ref id="stack" />
+    <ref id="surface" />
+    <ref id="select" />
+  </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/separator/patterns.xml

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

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

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="separator">
+  <when_to_use>
+    <item>Dividing sections within a page or panel</item>
+    <item>Vertical dividers in toolbars, menus, or button groups</item>
+    <item>Separating list items or stacked content blocks</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Select dropdown option dividers — use Select.Separator</item>
+    <item>Surface borders or card outlines — use Surface border props</item>
+  </when_not_to_use>
+  <prop name="hPadding" kind="react">
+    <description>Sets inline padding on the Stack wrapper using one token for both sides or a `[start, end]` tuple.</description>
+  </prop>
+  <prop name="orientation" kind="react">
+    <description>Sets the separator line direction.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered line root element.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `hr` line root using Base UI render semantics.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Sets the line thickness preset.</description>
+  </prop>
+  <prop name="variant" kind="react">
+    <description>Sets the separator line variant through `--vui-separator-border-style`.</description>
+  </prop>
+  <prop name="vPadding" kind="react">
+    <description>Sets block padding on the Stack wrapper using one token for both sides or a `[start, end]` tuple.</description>
+  </prop>
+  <css_var suffix="border-style">
+    <description>Separator line border style.</description>
+  </css_var>
+  <css_var suffix="size">
+    <description>Separator line thickness.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="separator">
+  <do>Dividing sections within a page or panel</do>
+  <do>Vertical dividers in toolbars, menus, or button groups</do>
+  <do>Separating list items or stacked content blocks</do>
+  <dont>Using Select.Separator for general layout dividers</dont>
+  <dont>Replacing Surface borders with Separator for container chrome</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="shimmer">
+  <rule>Shimmer renders real text content — do not mark it aria-hidden</rule>
+  <rule>Announce loading on the surrounding region with aria-busy or live text</rule>
+  <rule>Reduced motion disables the sweep and restores normal text rendering</rule>
+</a11y>

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

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

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

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

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

@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="shimmer">
+  <when_to_use>
+    <item>Loading placeholder copy inside Text or Title</item>
+    <item>Animated text shimmer while awaiting async content</item>
+    <item>Muted loading labels that keep the final text dimensions</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Block or fixed-dimension placeholders without text content</item>
+    <item>Standalone accessible loading status without a surrounding aria-busy region</item>
+    <item>Replacing Skeleton for non-text layout placeholders</item>
+  </when_not_to_use>
+  <prop name="angle" kind="react">
+    <description>Sets the shimmer gradient angle offset using any valid CSS angle string.</description>
+  </prop>
+  <prop name="duration" kind="react">
+    <description>Sets the shimmer sweep duration using any valid CSS time string.</description>
+  </prop>
+  <prop name="highlightColor" kind="react">
+    <description>Overrides the shimmer highlight color when relative base lightness tuning is not used.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered shimmer root element.</description>
+  </prop>
+  <prop name="spread" kind="react">
+    <description>Sets the shimmer highlight spread using any valid CSS length string.</description>
+  </prop>
+  <css_var suffix="angle">
+    <description>Shimmer gradient angle offset.</description>
+  </css_var>
+  <css_var suffix="duration">
+    <description>Shimmer animation duration.</description>
+  </css_var>
+  <css_var suffix="highlight">
+    <description>Shimmer highlight color.</description>
+  </css_var>
+  <css_var suffix="spread">
+    <description>Shimmer highlight spread width.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="shimmer">
+  <do>Loading placeholder copy inside Text or Title</do>
+  <do>Animated text shimmer while awaiting async content</do>
+  <do>Muted loading labels that keep the final text dimensions</do>
+  <dont>Putting aria-busy on Shimmer instead of the surrounding loading region</dont>
+  <dont>Using Shimmer without children text content</dont>
+  <dont>Using Shimmer for block placeholders better served by Skeleton</dont>
+</usage>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="skeleton">
+  <rule>Skeleton and Skeleton.Overlay are decorative (aria-hidden) — announce loading on the surrounding region with aria-busy or live text</rule>
+  <rule>Overlay children stay aria-hidden; the parent loading region owns busy state</rule>
+  <rule>Do not put aria-busy on Skeleton itself</rule>
+  <rule>Replace skeleton with real content as soon as data is ready</rule>
+  <rule>prefers-reduced-motion disables the pulse animation and keeps a static surface</rule>
+</a11y>

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

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="skeleton" title="Skeleton" category="feedback" shared_contract="skeleton">
+  <summary>Decorative opacity pulse block sized by props, or Overlay sized by hidden child content.</summary>
+  <exports>
+    <export name="Skeleton" />
+  </exports>
+  <related>
+    <ref id="avatar" />
+    <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/skeleton/patterns.xml

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

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

@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="skeleton">
+  <when_to_use>
+    <item>Fixed-dimension pulse blocks while content loads</item>
+    <item>Avatar or media placeholders with explicit width and height</item>
+    <item>Skeleton.Overlay when placeholder layout should match incoming typography without layout shift</item>
+    <item>View-transition wipe reveal for `Skeleton.Overlay`, with `viewTransitionName: &apos;skeleton-overlay&apos;` on the wrapper around skeleton+loaded content (prefer CSS class, not inline style)</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Inline text shimmer effects (use Shimmer)</item>
+    <item>Standalone accessible loading status without a surrounding aria-busy region</item>
+  </when_not_to_use>
+  <prop name="animate" kind="react">
+    <description>Enables the opacity pulse animation.</description>
+  </prop>
+  <prop name="radius" kind="react">
+    <description>Sets the corner radius from the Vira radius token scale.</description>
+  </prop>
+  <prop name="duration" kind="react">
+    <description>Sets the pulse duration from the Vira duration token scale.</description>
+  </prop>
+  <prop name="height" kind="react">
+    <description>Sets the skeleton block size using any valid CSS size string.</description>
+  </prop>
+  <prop name="minHeight" kind="react">
+    <description>Sets the skeleton minimum block size using any valid CSS size string.</description>
+  </prop>
+  <prop name="minWidth" kind="react">
+    <description>Sets the skeleton minimum inline size using any valid CSS size string.</description>
+  </prop>
+  <prop name="Overlay.animate" kind="react">
+    <description>Enables the opacity pulse animation on the overlay root.</description>
+  </prop>
+  <prop name="Overlay.radius" kind="react">
+    <description>Sets the overlay corner radius from the Vira radius token scale.</description>
+  </prop>
+  <prop name="Overlay.children" kind="react">
+    <description>Content whose layout and dimensions define the overlay bounding box.</description>
+  </prop>
+  <prop name="Overlay.duration" kind="react">
+    <description>Sets the pulse duration from the Vira duration token scale.</description>
+  </prop>
+  <prop name="Overlay.ref" kind="react">
+    <description>Ref forwarded to the rendered overlay root element.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered skeleton root element.</description>
+  </prop>
+  <prop name="width" kind="react">
+    <description>Sets the skeleton inline size using any valid CSS size string.</description>
+  </prop>
+  <css_var suffix="background">
+    <description>Skeleton placeholder background color.</description>
+  </css_var>
+  <css_var suffix="block-size">
+    <description>Skeleton block size.</description>
+  </css_var>
+  <css_var suffix="border-radius">
+    <description>Skeleton corner radius.</description>
+  </css_var>
+  <css_var suffix="duration">
+    <description>Pulse duration.</description>
+  </css_var>
+  <css_var suffix="inline-size">
+    <description>Skeleton inline size.</description>
+  </css_var>
+  <css_var suffix="min-block-size">
+    <description>Skeleton minimum block size.</description>
+  </css_var>
+  <css_var suffix="min-inline-size">
+    <description>Skeleton minimum inline size.</description>
+  </css_var>
+</props>