@viraui/react 2026.3.10 → 2026.4.0

package/dist/specs/components/clamp-text/meta.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="clamp-text" title="ClampText" category="typography" shared_contract="clamp-text">
+  <summary>Presentational utility that truncates overflowing copy to a fixed line count.</summary>
+  <exports>
+    <export name="ClampText" />
+  </exports>
+  <related>
+    <ref id="text" />
+    <ref id="title" />
+  </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/clamp-text/patterns.xml

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

package/dist/specs/components/clamp-text/props.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="clamp-text">
+  <when_to_use>
+    <item>Single- or multi-line ellipsis in constrained layouts</item>
+    <item>Clamp Text or Title roots through render</item>
+    <item>Inline or block clamped typography</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Full text must remain visible without truncation</item>
+    <item>Heading semantics without composing Title through render</item>
+  </when_not_to_use>
+  <prop name="inline" kind="react">
+    <description>Uses inline `-webkit-inline-box` display instead of block `-webkit-box`.</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered clamp text root element.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `span` root using Base UI render semantics.</description>
+  </prop>
+  <prop name="rows" kind="react">
+    <description>Sets how many lines of text remain visible before truncation.</description>
+  </prop>
+  <css_var suffix="rows">
+    <description>WebKit line-clamp row count on the root.</description>
+  </css_var>
+</props>

package/dist/specs/components/clamp-text/usage.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="clamp-text">
+  <do>Single- or multi-line ellipsis in constrained layouts</do>
+  <do>Clamp Text or Title roots through render</do>
+  <do>Inline or block clamped typography</do>
+  <dont>Using ClampText as a heading primitive without Title render</dont>
+  <dont>Expecting children-driven sizing instead of rows</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="dialog">
+  <rule>Always pass `title`; add `description` when the heading alone is not enough context</rule>
+  <rule>Compose `Dialog.Close` with an accessible name when a visible close control is needed</rule>
+  <rule>Use `Dialog.Close` for footer actions that should dismiss the sheet</rule>
+  <rule>For non-modal Dialogs (`modal={false}` with `disablePointerDismissal`), the Sheet backdrop is omitted automatically — do not expect a scrim</rule>
+</a11y>

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

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="dialog" title="Dialog" category="overlay" shared_contract="dialog">
+  <summary>Compound drawer sheet with `Dialog.Trigger`, `Dialog.Sheet`, `Dialog.Close`, and Base UI pass-through `Dialog.Provider`, `Dialog.Indent`, and `Dialog.IndentBackground` for app-shell indent effects.</summary>
+  <exports>
+    <export name="Dialog" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="button" />
+    <ref id="icon-button" />
+    <ref id="stack" />
+    <ref id="elevator" />
+  </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/drawer#api-reference" />
+</meta>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="dialog">
+  <example title="Dialog structure">
+    <tsx><![CDATA[<Dialog.Provider>
+  <Dialog.IndentBackground />
+  <Dialog.Indent>
+    …
+    <Dialog>
+      <Dialog.Trigger />
+      <Dialog.Sheet title="…">
+        …
+        <Dialog.Close />
+      </Dialog.Sheet>
+    </Dialog>
+  </Dialog.Indent>
+</Dialog.Provider>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="dialog">
+  <when_to_use>
+    <item>Focused tasks or confirmations that interrupt the current page without navigation</item>
+    <item>Short forms or read-only content that needs a modal layer above the app</item>
+    <item>Bottom sheets where swipe dismissal or snap points are useful (pass `snapPoints`, `snapPoint`/`onSnapPointChange`, or `defaultSnapPoint` directly on `Dialog`)</item>
+    <item>Drill-down sheet flows (for example settings sub-pages) by nesting a `Dialog` inside `Dialog.Sheet` children</item>
+    <item>App-shell indent effects by wrapping page content in `Dialog.Provider`, `Dialog.IndentBackground`, and `Dialog.Indent`</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>Small anchored hints or quick actions that should use Popover or Menu</item>
+    <item>Highly custom sheet anatomy that needs primitive-level composition</item>
+    <item>Centered modal layouts that should not slide from the screen edge</item>
+  </when_not_to_use>
+  <prop name="Sheet.children" kind="react">
+    <description>Optional body content rendered below the description.</description>
+  </prop>
+  <prop name="Sheet.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="Sheet.description" kind="react">
+    <description>Supporting copy announced with the title.</description>
+  </prop>
+  <prop name="Sheet.fitContent" kind="react">
+    <description>Centers the sheet horizontally within the viewport.</description>
+  </prop>
+  <prop name="Sheet.headerAlign" kind="react">
+    <description>Aligns the header stack and title/description text (`start` | `center` | `end`).</description>
+  </prop>
+  <prop name="Sheet.maxContentWidth" kind="react">
+    <description>Optional maximum width of the content area.</description>
+  </prop>
+  <prop name="Sheet.maxHeight" kind="react">
+    <description>Maximum block size of the sheet panel.</description>
+  </prop>
+  <prop name="Sheet.showCloseButton" kind="react">
+    <description>Whether to show the close button.</description>
+  </prop>
+  <prop name="Sheet.showHandle" kind="react">
+    <description>Whether to show the drag handle above the sheet header.</description>
+  </prop>
+  <prop name="Sheet.title" kind="react">
+    <description>Accessible dialog title rendered as the modal heading.</description>
+  </prop>
+  <css_var suffix="max-block-size">
+    <description>Max block size of Dialog.Sheet popup root.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="dialog">
+  <do>Focused tasks or confirmations that interrupt the current page without navigation</do>
+  <do>Short forms or read-only content that needs a modal layer above the app</do>
+  <do>Bottom sheets where swipe dismissal or snap points are useful (pass `snapPoints`, `snapPoint`/`onSnapPointChange`, or `defaultSnapPoint` directly on `Dialog`)</do>
+  <do>Drill-down sheet flows (for example settings sub-pages) by nesting a `Dialog` inside `Dialog.Sheet` children</do>
+  <do>App-shell indent effects by wrapping page content in `Dialog.Provider`, `Dialog.IndentBackground`, and `Dialog.Indent`</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 sheet without `title` copy for assistive technologies</dont>
+  <dont>Relying only on backdrop press or swipe when a footer action is the primary close path</dont>
+  <dont>Using Dialog when a centered non-gesture modal is enough and a future Dialog primitive is available</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="elevator">
+  <rule>Elevation is visual only — do not use shadow depth as the only affordance for interactivity</rule>
+  <rule>Preserve child focus order and semantics; Elevator does not add a focusable node</rule>
+  <rule>Respect reduced-motion preferences when pairing animated elevation with motion</rule>
+</a11y>

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

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="elevator" title="Elevator" category="effect" shared_contract="elevator">
+  <summary>No-DOM elevation utility that merges shadow hooks onto valid element children.</summary>
+  <exports>
+    <export name="Elevator" />
+  </exports>
+  <related>
+    <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>
+</meta>

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

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

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

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="elevator">
+  <when_to_use>
+    <item>Apply resting and optional hover elevation to existing elements</item>
+    <item>Compose animated box-shadow transitions with data-elevation hooks</item>
+    <item>Use getElevationProps when you need the mapping directly</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>When you need a wrapper DOM node for layout or styling isolation</item>
+    <item>Non-element children that cannot receive merged props</item>
+  </when_not_to_use>
+  <prop name="children" kind="react">
+    <description>Element or elements that receive elevation hooks on their rendered root.</description>
+  </prop>
+  <prop name="direction" kind="react">
+    <description>Shadow cast direction mapped to `data-elevation-direction`.</description>
+  </prop>
+  <prop name="extraShadow" kind="react">
+    <description>Additional shadow layer mapped to the `--extra-shadow` custom property.</description>
+  </prop>
+  <prop name="hover" kind="react">
+    <description>Hover elevation level mapped to `data-elevation-hover`.</description>
+  </prop>
+  <prop name="resting" kind="react">
+    <description>Resting elevation level mapped to `data-elevation`.</description>
+  </prop>
+  <prop name="shadowColor" kind="react">
+    <description>Shadow color mapped to the `--shadow-color` custom property.</description>
+  </prop>
+
+</props>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="elevator">
+  <do>Apply resting and optional hover elevation to existing elements</do>
+  <do>Compose animated box-shadow transitions with data-elevation hooks</do>
+  <do>Use getElevationProps when you need the mapping directly</do>
+  <dont>Wrapping invalid or non-element nodes</dont>
+  <dont>Overwriting child transition shorthand without composing box-shadow</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="fieldset">
+  <rule>Map visible label to Fieldset.Legend so grouped controls share an accessible section name</rule>
+  <rule>Keep group invalid state on Field.Root and surface group error copy through Fieldset error</rule>
+  <rule>Pass disabled to `&lt;Fieldset disabled&gt;` when the whole section should ignore interaction</rule>
+</a11y>

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

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="fieldset" title="Fieldset" category="form" shared_contract="fieldset">
+  <summary>Semantic field grouping with shared legend and optional group helper copy.</summary>
+  <exports>
+    <export name="Fieldset" />
+  </exports>
+  <related>
+    <ref id="radio-group" />
+    <ref id="checkbox-group" />
+    <ref id="textfield" />
+    <ref id="textarea" />
+    <ref id="select" />
+    <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/fieldset#api-reference" />
+</meta>

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

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

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

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="fieldset">
+  <when_to_use>
+    <item>Section legends for multiple related fields — billing details with Textfield, Textarea, or Select children</item>
+    <item>Choice groups that need a shared legend, group description, or group error — Field.Root &gt; Fieldset render={&lt;RadioGroup&lt;Value&gt; /&gt;} or render={&lt;CheckboxGroup /&gt;}</item>
+    <item>Group validation and helper copy that require a Field.Root ancestor plus Fieldset description or error</item>
+    <item>Type-safe radio unions via RadioGroup&lt;&apos;ssd&apos; | &apos;hdd&apos;&gt; merged through Fieldset render</item>
+    <item>Shared legend plus optional group description/error for a form block — border/section chrome belongs on Surface or the consumer</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Every RadioGroup or CheckboxGroup by default — Fieldset is optional when options already have labels and no group copy is needed</item>
+    <item>Single Textfield, Textarea, Select, Radio, or Checkbox that already exposes its own label</item>
+    <item>Standalone RadioGroup or CheckboxGroup inside Field.Root with no shared legend — primitives are enough</item>
+    <item>Group legend, description, or validation on RadioGroup or CheckboxGroup props — those belong on Fieldset (with Field.Root when validating)</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Group helper copy rendered below the legend while valid. Requires a `Field.Root` ancestor for `FieldHelperCopy`.</description>
+  </prop>
+  <prop name="error" kind="react">
+    <description>Group error copy rendered below the legend when invalid. Requires a `Field.Root` ancestor.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible legend copy rendered with shared internal `FieldLabel`.</description>
+  </prop>
+
+</props>

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="fieldset">
+  <do>Section legends for multiple related fields — billing details with Textfield, Textarea, or Select children</do>
+  <do>Choice groups that need a shared legend, group description, or group error — Field.Root &gt; Fieldset render={&lt;RadioGroup&lt;Value&gt; /&gt;} or render={&lt;CheckboxGroup /&gt;}</do>
+  <do>Group validation and helper copy that require a Field.Root ancestor plus Fieldset description or error</do>
+  <do>Type-safe radio unions via RadioGroup&lt;&apos;ssd&apos; | &apos;hdd&apos;&gt; merged through Fieldset render</do>
+  <do>Shared legend plus optional group description/error for a form block — border/section chrome belongs on Surface or the consumer</do>
+  <dont>Wrapping Fieldset.Root in Stack render — breaks Base UI render merge with RadioGroup or CheckboxGroup</dont>
+  <dont>Expecting description or error on Fieldset without a Field.Root ancestor</dont>
+  <dont>Omitting RadioGroup&lt;Value&gt; generics when option values are a restricted union</dont>
+</usage>

package/dist/specs/components/fit-text/a11y.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="fit-text">
+  <rule>Children render twice; the reference copy is aria-hidden and inert so assistive tech sees one tree</rule>
+  <rule>Keep semantic roots on the visible children (Title render, heading elements, paragraphs)</rule>
+  <rule>Fitted size still respects user zoom because the ratio multiplies 1em</rule>
+</a11y>

package/dist/specs/components/fit-text/meta.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="fit-text" title="FitText" category="typography" shared_contract="fit-text">
+  <summary>CSS-only fit-to-width wrapper that scales children to fill available inline space.</summary>
+  <exports>
+    <export name="FitText" />
+  </exports>
+  <related>
+    <ref id="title" />
+    <ref id="text" />
+    <ref id="clamp-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>
+</meta>

package/dist/specs/components/fit-text/patterns.xml

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

package/dist/specs/components/fit-text/props.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="fit-text">
+  <when_to_use>
+    <item>Headlines or short copy that should fill a constrained inline width</item>
+    <item>Multi-line display type broken with br (or equivalent) inside Title, Text, or native markup</item>
+    <item>Resize-friendly marketing/hero type without JS measurement</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Long body copy that should wrap and reflow at a fixed type size</item>
+    <item>Truncation — use ClampText instead</item>
+    <item>Cases that need a JS-measured or observer-driven fit</item>
+  </when_not_to_use>
+  <prop name="maxFontSize" kind="react">
+    <description>Caps the fitted font size using any valid CSS length string.</description>
+  </prop>
+  <css_var suffix="max-font-size">
+    <description>Upper bound for the fitted font size on the display slot.</description>
+  </css_var>
+</props>

package/dist/specs/components/fit-text/usage.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="fit-text">
+  <do>Headlines or short copy that should fill a constrained inline width</do>
+  <do>Multi-line display type broken with br (or equivalent) inside Title, Text, or native markup</do>
+  <do>Resize-friendly marketing/hero type without JS measurement</do>
+  <dont>Expecting automatic line breaks without br or block structure in children</dont>
+  <dont>Putting interactive controls inside FitText (duplicate trees and inert reference)</dont>
+  <dont>Using FitText for truncation or ellipsis</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="glow">
+  <rule>Root stays in the accessibility tree; highlight is decorative CSS only</rule>
+  <rule>Glow is not a focus or status indicator — consumer owns accessible names and state</rule>
+  <rule>Highlight hides under coarse pointer / no-hover and under prefers-reduced-motion</rule>
+</a11y>

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

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="glow" title="Glow" category="effect" shared_contract="glow">
+  <summary>Decorative pointer-driven border highlight on a transparent Surface shell (radius only). Put the visual card as children; a shared rAF tracker paints CSS variables without React re-renders. Memory-heavy — use sparingly (rarely).</summary>
+  <exports>
+    <export name="Glow" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="beam" />
+    <ref id="shimmer" />
+    <ref id="progressive-blur" />
+  </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/glow/patterns.xml

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

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

@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="glow">
+  <when_to_use>
+    <item>Wrap a Surface (or other content) that should highlight toward the pointer</item>
+    <item>Grid of glow shells that share one pointer highlight path</item>
+    <item>Nested glow inside a padded Surface using radius=&quot;auto&quot;</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Default decoration on many cards — memory cost is high; reserve for rare focal moments</item>
+    <item>Static or continuously animated borders — use Surface border or Beam instead</item>
+    <item>Accessible status or focus indication — glow is decorative only</item>
+    <item>As a replacement for Surface color/padding — compose Surface as children</item>
+  </when_not_to_use>
+  <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="proximity" kind="react">
+    <description>Distance from the surface edge where the glow becomes fully active.</description>
+  </prop>
+  <prop name="spread" kind="react">
+    <description>Angular width of the highlighted arc (degrees, used as a unitless CSS number).</description>
+  </prop>
+  <prop name="opacity" kind="react">
+    <description>Resting opacity of the glow when the pointer is outside proximity.</description>
+  </prop>
+  <prop name="fitContent" kind="react">
+    <description>Shrinks the root to fit its content (`max-width: fit-content`).</description>
+  </prop>
+  <prop name="borderWidth" kind="react">
+    <description>Width of the masked glow border ring.</description>
+  </prop>
+  <prop name="borderColor" kind="react">
+    <description>Color of the masked border ring under the highlight.</description>
+  </prop>
+  <prop name="borderOffset" kind="react">
+    <description>Offset of the glow ring from the surface edge. Negative values place the ring outside.</description>
+  </prop>
+  <prop name="glowColor" kind="react">
+    <description>Overrides the glow gradient with a solid color or custom background value. Ignored when `rainbowColors` is true.</description>
+  </prop>
+  <prop name="globalHighlight" kind="react">
+    <description>Shares the highlight gradient across cards via `background-attachment: fixed`. Forced off when `rainbowColors` is true.</description>
+  </prop>
+  <prop name="rainbowColors" kind="react">
+    <description>Uses the multi-stop rainbow highlight gradient and disables global highlight attachment.</description>
+  </prop>
+  <prop name="angleLag" kind="react">
+    <description>CSS transition duration in milliseconds for the pointer-driven starting angle. Soft follow by default; set 0 for instant snap.</description>
+  </prop>
+  <css_var suffix="starting-angle">
+    <description>Conic gradient start angle in degrees (unitless number). Pointer tracker writes a continuous unwrapped value.</description>
+  </css_var>
+  <css_var suffix="angle-lag">
+    <description>Transition duration for `--vui-glow-starting-angle`.</description>
+  </css_var>
+  <css_var suffix="active-opacity">
+    <description>Current glow opacity from proximity tracking. Written by the shared tracker.</description>
+  </css_var>
+  <css_var suffix="spread">
+    <description>Angular width of the highlighted arc.</description>
+  </css_var>
+  <css_var suffix="border-width">
+    <description>Masked glow border ring width.</description>
+  </css_var>
+  <css_var suffix="border-color">
+    <description>Masked border ring color under the highlight.</description>
+  </css_var>
+  <css_var suffix="border-offset">
+    <description>Glow ring offset from the surface edge.</description>
+  </css_var>
+  <css_var suffix="color">
+    <description>Glow fill (solid color or gradient).</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="glow">
+  <do>Wrap a Surface (or other content) that should highlight toward the pointer</do>
+  <do>Grid of glow shells that share one pointer highlight path</do>
+  <do>Nested glow inside a padded Surface using radius=&quot;auto&quot;</do>
+  <dont>Relying on Glow for keyboard focus visibility</dont>
+  <dont>Treating Glow as the visual card (color/padding) instead of composing Surface children</dont>
+  <dont>Setting overflow:hidden on an ancestor Surface when outer glow must remain visible</dont>
+  <dont>Expecting soft bloom Light layer — Glow is border-ring only</dont>
+  <dont>Using many Glow instances on one page — memory- and CPU-heavy</dont>
+  <dont>Expecting continuous spin — use Beam instead</dont>
+</usage>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="grid">
+  <rule>Grid is presentational — choose render roots that preserve correct semantics (section, list, article)</rule>
+  <rule>DOM order follows source order; keep reading and keyboard order aligned with visual placement</rule>
+  <rule>Prefer Grid.Item render when list or article semantics matter for children</rule>
+</a11y>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="grid" title="Grid" category="layout" shared_contract="grid">
+  <summary>CSS Grid layout primitive for auto-fill/fit or fixed track layouts with token gaps, Stack-aligned padding, and item placement (`fullWidth` / `fullHeight` / column / row).</summary>
+  <exports>
+    <export name="Grid" />
+  </exports>
+  <related>
+    <ref id="stack" />
+    <ref id="masonry" />
+    <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>
+</meta>

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

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