@viraui/react 2026.3.11 → 2026.4.1

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="skeleton">
+  <do>Fixed-dimension pulse blocks while content loads</do>
+  <do>Avatar or media placeholders with explicit width and height</do>
+  <do>Skeleton.Overlay when placeholder layout should match incoming typography without layout shift</do>
+  <do>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)</do>
+  <dont>Using Skeleton.Overlay without real content structure to size against</dont>
+  <dont>Putting aria-busy on Skeleton instead of the surrounding loading region</dont>
+  <dont>Expecting view-transition wipe without wrapper `viewTransitionName: &apos;skeleton-overlay&apos;` (prefer CSS class, not inline style)</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="slider">
+  <rule>Provide label or aria-label; when label is omitted, name thumbs with thumbLabel</rule>
+  <rule>Range sliders need distinct accessible names for each thumb</rule>
+  <rule>Keep keyboard adjustment and value feedback available through native slider semantics</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="slider" title="Slider" category="form" shared_contract="slider">
+  <summary>Field-wrapped range input supporting single-thumb or two-thumb range selection.</summary>
+  <exports>
+    <export name="Slider" />
+  </exports>
+  <related>
+    <ref id="textfield" />
+    <ref id="stack" />
+    <ref id="text" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/slider#api-reference" />
+</meta>

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

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

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

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="slider">
+  <when_to_use>
+    <item>Numeric value selection on a horizontal or vertical axis</item>
+    <item>Range selection with two thumbs</item>
+    <item>Field label, description, and error copy like Textfield</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Fixed pixel track lengths — Slider fills its container</item>
+    <item>Custom size or variant props — single medium treatment</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Helper copy rendered with `Field.Description` and `Text` while the field is valid.</description>
+  </prop>
+  <prop name="error" kind="react">
+    <description>Error copy rendered with `Field.Error` and `Text` in the same slot as `description`.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible label rendered with shared internal `FieldLabel`.</description>
+  </prop>
+  <prop name="required" kind="react">
+    <description>Marks the slider as required and shows a required indicator on the label.</description>
+  </prop>
+  <prop name="renderValue" kind="react">
+    <description>Shows the current value beside the label. Pass `true` for Base UI default formatting inside styled `Text`, or a function matching `Slider.Value` `children` to own the value slot (no `Text`).</description>
+  </prop>
+  <prop name="thumbAriaLabel" kind="react">
+    <description>Accessible name for the thumb when `label` is omitted. Pass a string to name the first thumb (single-thumb slider, or the minimum thumb on a range). Pass a two-element tuple to name each range thumb in order; on a single-thumb slider only the first tuple value is applied.</description>
+  </prop>
+  <css_var suffix="progress-background">
+    <description>Slider filled progress color.</description>
+  </css_var>
+  <css_var suffix="thumb-background">
+    <description>Slider thumb fill color.</description>
+  </css_var>
+  <css_var suffix="thumb-size">
+    <description>Slider thumb size.</description>
+  </css_var>
+  <css_var suffix="track-background">
+    <description>Slider track background color.</description>
+  </css_var>
+  <css_var suffix="track-size">
+    <description>Slider track thickness.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="slider">
+  <do>Numeric value selection on a horizontal or vertical axis</do>
+  <do>Range selection with two thumbs</do>
+  <do>Field label, description, and error copy like Textfield</do>
+  <dont>Wrapping Slider.Control and Slider.Value in extra layout inside Slider.Root</dont>
+  <dont>Overriding Slider.Indicator position in CSS</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="spinner">
+  <rule>Set aria-hidden on decorative Spinner instances; the component does not hide itself by default</rule>
+  <rule>Parent control or region must expose loading with aria-busy or visible status text</rule>
+  <rule>Do not use Spinner alone as the only page-level loading announcement</rule>
+  <rule>Keep the control label stable while loading overlays appear</rule>
+</a11y>

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

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="spinner" title="Spinner" category="feedback" shared_contract="spinner">
+  <summary>Decorative SVG pulsing loading indicator used inside interactive components.</summary>
+  <exports>
+    <export name="Spinner" />
+  </exports>
+  <related>
+    <ref id="button" />
+    <ref id="icon-button" />
+  </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/spinner/patterns.xml

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

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

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="spinner">
+  <when_to_use>
+    <item>Inline loading overlay inside Button or IconButton</item>
+    <item>Decorative in-progress indicator explicitly hidden from assistive technology</item>
+    <item>Loading feedback where the parent exposes the accessible status</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Standalone accessible loading status without explicit labeling on a parent</item>
+    <item>Page-level loading when a labeled region is not provided</item>
+  </when_not_to_use>
+  <prop name="color" kind="react">
+    <description>Overrides the spinner fill color.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Sets the rendered spinner size.</description>
+  </prop>
+  <prop name="variant" kind="react">
+    <description>Visual animation style.</description>
+  </prop>
+  <css_var suffix="size">
+    <description>Spinner glyph size on the root.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="spinner">
+  <do>Inline loading overlay inside Button or IconButton</do>
+  <do>Decorative in-progress indicator explicitly hidden from assistive technology</do>
+  <do>Loading feedback where the parent exposes the accessible status</do>
+  <dont>Using Spinner alone as the only loading announcement for a page</dont>
+  <dont>Embedding animation rules outside the component stylesheet</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="stack">
+  <rule>Stack is presentational — choose render roots that preserve correct semantics (button, list, heading)</rule>
+  <rule>Keep reading order aligned with visual order when using direction and wrap</rule>
+  <rule>Do not use Stack alone to imply grouping; use landmarks or headings where needed</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="stack" title="Stack" category="layout" shared_contract="stack">
+  <summary>Flex layout primitive for arranging children with token spacing, alignment, and padding; optionally enables a named CSS container query context (`stack`) via `enableContainer`.</summary>
+  <exports>
+    <export name="Stack" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="grid" />
+    <ref id="masonry" />
+    <ref id="separator" />
+  </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/stack/patterns.xml

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

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

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="stack">
+  <when_to_use>
+    <item>Column or row layouts with token gap and alignment</item>
+    <item>Composing screens and component internals without custom flex CSS</item>
+    <item>Custom native root through render while keeping data-stack hooks</item>
+    <item>Style descendants with `@container stack` queries when layout, gap, or typography should respond to the Stack&apos;s own inline-size instead of the viewport (set `enableContainer` on the Stack you&apos;re querying)</item>
+    <item>Centered max-width shells: parent `hAlign=&quot;center&quot;` + child `fullWidth` + `maxWidth`</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Cases where a single component already owns required flex chrome</item>
+    <item>Expecting direct children to grow on the main axis without setting `expandChildren`</item>
+    <item>Expecting this stack to fill parent inline size under non-stretch alignment without `fullWidth` (or an explicit `inlineSize`)</item>
+    <item>Using `enableContainer` inside complex masonry-like layouts when you don&apos;t need container queries (inline-size containment can change nested layout)</item>
+  </when_not_to_use>
+  <prop name="columnGap" kind="react">
+    <description>Sets the gap between flex columns using the Vira space token scale.</description>
+  </prop>
+  <prop name="enableContainer" kind="react">
+    <description>Opt-in named CSS container query context for this Stack (enables `container: stack / inline-size` on the root via `data-stack-container`). Required for `@container stack (min-width: ...)` rules to react to this Stack inline-size. Warning: inline-size containment can affect nested layout (e.g. cards inside Masonry). Use only when you need container queries against this specific Stack.</description>
+  </prop>
+  <prop name="direction" kind="react">
+    <description>Renders children across rows or columns using the chosen flex direction.</description>
+  </prop>
+  <prop name="expandChildren" kind="react">
+    <description>Makes direct children grow along the flex main axis (`flex-grow`). Default `false`. Orthogonal to `fullWidth` (children grow vs this root&apos;s inline size). A child opts out with its own `data-grow=&quot;false&quot;`; ancestor `data-grow` does not inherit into nested stacks.</description>
+  </prop>
+  <prop name="fullWidth" kind="react">
+    <description>Sets `inline-size: 100%` on the stack root so it fills the parent&apos;s inline size. Default `false`. Use with `maxWidth` under a parent `hAlign=&quot;center&quot;` for a fluid capped centered shell. Does not grow children — use `expandChildren` for that.</description>
+  </prop>
+  <prop name="hAlign" kind="react">
+    <description>Aligns content on the horizontal axis from the consumer point of view.</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="inline" kind="react">
+    <description>Displays the stack as `inline-flex` instead of `flex`.</description>
+  </prop>
+  <prop name="maxWidth" kind="react">
+    <description>Applies a maximum width value to the stack root.</description>
+  </prop>
+  <prop name="minWidth" kind="react">
+    <description>Applies a minimum width value to the stack root.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered stack root element.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `div` root using Base UI render semantics.</description>
+  </prop>
+  <prop name="rowGap" kind="react">
+    <description>Sets the gap between flex rows using the Vira space token scale.</description>
+  </prop>
+  <prop name="vAlign" kind="react">
+    <description>Aligns content on the vertical axis from the consumer point of view.</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="wrap" kind="react">
+    <description>Allows direct children to wrap onto additional lines when space is constrained.</description>
+  </prop>
+  <css_var suffix="column-gap">
+    <description>Flex column gap on the root.</description>
+  </css_var>
+  <css_var suffix="h-align">
+    <description>Logical horizontal flex alignment hook.</description>
+  </css_var>
+  <css_var suffix="max-width">
+    <description>Max inline size of the stack root.</description>
+  </css_var>
+  <css_var suffix="min-width">
+    <description>Min inline size of the stack 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="row-gap">
+    <description>Flex row gap on the root.</description>
+  </css_var>
+  <css_var suffix="v-align">
+    <description>Logical vertical flex alignment hook.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="stack">
+  <do>Column or row layouts with token gap and alignment</do>
+  <do>Composing screens and component internals without custom flex CSS</do>
+  <do>Custom native root through render while keeping data-stack hooks</do>
+  <do>Style descendants with `@container stack` queries when layout, gap, or typography should respond to the Stack&apos;s own inline-size instead of the viewport (set `enableContainer` on the Stack you&apos;re querying)</do>
+  <do>Centered max-width shells: parent `hAlign=&quot;center&quot;` + child `fullWidth` + `maxWidth`</do>
+  <dont>Assuming Stack expands direct children by default — pass `expandChildren` when children should grow along the flex main axis</dont>
+  <dont>Using `expandChildren` to fill parent width under `hAlign=&quot;center&quot;` — that is `fullWidth` on the child stack (self `inline-size`), not child flex-grow</dont>
+  <dont>Putting `data-grow=&quot;false&quot;` on an ancestor to control nested expandChildren — set it on the child that should not grow</dont>
+  <dont>Re-declaring primitive flex container rules in app CSS when Stack can own the layout</dont>
+  <dont>Using viewport media queries when @container stack queries against the rendered Stack inline-size would match the design intent</dont>
+  <dont>Combining `fullWidth` with `inline` — prefer block flex when the root must fill parent inline size</dont>
+</usage>

package/dist/specs/components/static-noise/a11y.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="static-noise">
+  <rule>StaticNoise 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 owns position, inset, z-index, and sizing for the overlay placement</rule>
+</a11y>

package/dist/specs/components/static-noise/meta.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="static-noise" title="StaticNoise" category="effect" shared_contract="static-noise">
+  <summary>Decorative SVG turbulence noise overlay for textured surfaces and hero sections. Memory-heavy — use sparingly (rarely).</summary>
+  <exports>
+    <export name="StaticNoise" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <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/static-noise/patterns.xml

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

package/dist/specs/components/static-noise/props.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="static-noise">
+  <when_to_use>
+    <item>Subtle grain or texture overlay on cards, panels, or hero sections</item>
+    <item>Glass or vibrant surfaces that need visual depth without extra content</item>
+    <item>Decorative atmosphere where the parent owns semantics and layout positioning</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Default decoration on many surfaces — memory cost is high; reserve for rare focal moments</item>
+    <item>Standalone loading or status feedback without a labeled parent region</item>
+    <item>Critical readable content where contrast has not been verified</item>
+    <item>Large numbers of simultaneous full-viewport overlays on the same page</item>
+  </when_not_to_use>
+  <prop name="animate" kind="react">
+    <description>Animates the internal turbulence filter by cycling `feTurbulence` seed values.</description>
+  </prop>
+  <prop name="baseFrequency" kind="react">
+    <description>Sets the SVG turbulence `baseFrequency` for the internal noise filter.</description>
+  </prop>
+  <prop name="mixBlendMode" kind="react">
+    <description>Sets the rendered overlay mix blend mode.</description>
+  </prop>
+  <prop name="opacity" kind="react">
+    <description>Sets the rendered overlay opacity.</description>
+  </prop>
+
+</props>

package/dist/specs/components/static-noise/usage.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="static-noise">
+  <do>Subtle grain or texture overlay on cards, panels, or hero sections</do>
+  <do>Glass or vibrant surfaces that need visual depth without extra content</do>
+  <do>Decorative atmosphere where the parent owns semantics and layout positioning</do>
+  <dont>Treating StaticNoise as cheap wallpaper — it is memory-heavy; prefer few instances</dont>
+  <dont>Stacking many full-viewport StaticNoise instances on one screen</dont>
+  <dont>Using StaticNoise as the only loading announcement for a page</dont>
+  <dont>Embedding layout positioning rules inside the component stylesheet</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="surface">
+  <rule>Surface is presentational — pair with headings or labels so grouped content is discoverable</rule>
+  <rule>Choose render roots with correct roles when Surface wraps interactive content</rule>
+  <rule>Do not rely on hover-only background changes as the only state indicator</rule>
+</a11y>

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

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="surface" title="Surface" category="layout" shared_contract="surface">
+  <summary>Presentational container with token background, optional border, radius, and padding; `data-vibrant` frosts the fill even without `color` (page shell via `--global-background`); nested surfaces use radius=&quot;auto&quot; for concentric corners; optionally enables a named CSS container query context (`surface`) via `enableContainer`.</summary>
+  <exports>
+    <export name="Surface" />
+  </exports>
+  <related>
+    <ref id="elevator" />
+    <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>
+</meta>

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="switch" title="Switch" category="form" shared_contract="switch">
+  <summary>Field-wrapped toggle control with medium or small track and optional field copy.</summary>
+  <exports>
+    <export name="Switch" />
+  </exports>
+  <related>
+    <ref id="textfield" />
+    <ref id="stack" />
+    <ref id="text" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/switch#api-reference" />
+</meta>

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

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