@viraui/react 2026.3.10 → 2026.4.0

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>

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>