@viraui/react 2026.6.5 → 2026.7.0-next.1

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

@@ -19,7 +19,7 @@
     <description>Effect family: rotating border, bottom line travel, or pulse breathe (outside/inside).</description>
   </prop>
   <prop name="size" kind="react">
-    <description>Border-only size preset (small compact / medium card). Ignored for other variants.</description>
+    <description>Size preset for border geometry and pulse-inside inner glow band (small compact / medium card). Ignored for line and pulse-outside.</description>
   </prop>
   <prop name="color" kind="react">
     <description>Beam color: primary → --global-primary, highlight token name → --highlight-*, colorful → upstream neon multi-stop RGB palette.</description>
@@ -81,10 +81,31 @@
   <prop name="hue" kind="css">
     <description>Pulse hue drift angle written by the shared pulse driver.</description>
   </prop>
+  <prop name="hue-base" kind="css">
+    <description>Base hue for hue-rotate filters on glow layers.</description>
+  </prop>
+  <prop name="stroke-opacity" kind="css">
+    <description>Opacity of the stroke/conic layer; variant CSS may override.</description>
+  </prop>
+  <prop name="inner-opacity" kind="css">
+    <description>Opacity of the inner glow layer; variant CSS may override.</description>
+  </prop>
+  <prop name="bloom-opacity" kind="css">
+    <description>Opacity of the bloom layer; variant CSS may override.</description>
+  </prop>
   <prop name="pulse-glow-sx" kind="css">
     <description>Per-axis X scale for pulse-outside glow geometry relative to a 350×140 reference.</description>
   </prop>
   <prop name="pulse-glow-sy" kind="css">
     <description>Per-axis Y scale for pulse-outside glow geometry relative to a 350×140 reference.</description>
   </prop>
+  <prop name="pulse-glow-boost" kind="css">
+    <description>Extra pulse-outside glow intensity multiplier (internal default 1; not a React prop).</description>
+  </prop>
+  <prop name="core-blur" kind="css">
+    <description>Core glow blur radius (BorderBeam glowSize=1 default).</description>
+  </prop>
+  <prop name="bloom-blur" kind="css">
+    <description>Bloom layer blur radius (BorderBeam glowSize=1 default).</description>
+  </prop>
 </props>

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

@@ -5,6 +5,7 @@
   <do>Pick `variant` for the job: `border` spin, `line` travel, `pulse-outside` / `pulse-inside` breathe — use Glow instead when the highlight should follow the pointer</do>
   <do>Use sparingly as a focal accent — shared pulse rAF still paints per instance; prefer one Beam per view</do>
   <dont>Treating Beam as Surface color/padding/border chrome — nest Surface/Stack children for the real card</dont>
+  <dont>Confusing prefers-reduced-motion (static rest stays visible) with `animate={false}` (effect fades away)</dont>
   <dont>Relying on Beam for keyboard focus or status — decorative only</dont>
   <dont>Expecting theme light/dark auto-tuning — colors are token-driven and theme-agnostic</dont>
   <dont>Scattering many Beam instances on one page</dont>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="disclosure">
+  <rule>Trigger is the disclosing control; Base UI wires expanded/controls relationship to the Panel</rule>
+  <rule>Accessible name comes from Trigger children, or explicit aria-label / aria-labelledby when icon-only</rule>
+  <rule>Trigger icons are decorative (aria-hidden); open/closed is communicated via Base UI attributes/ARIA, not icon alone</rule>
+  <rule>Disabled root ignores pointer and keyboard activation</rule>
+  <rule>prefers-reduced-motion disables Panel height and icon interpolate transitions; open/close still works</rule>
+  <rule>Do not re-apply widget role/aria that Base UI Collapsible already emits</rule>
+</a11y>

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

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="disclosure" title="Disclosure" category="layout" shared_contract="disclosure">
+  <summary>Single-section expand/collapse wrapping Base UI Collapsible. Default Trigger is Surface with render → Collapsible Trigger; Panel is a height motion shell with no default content padding. Use Accordion for multi-item lists.</summary>
+  <exports>
+    <export name="Disclosure" />
+  </exports>
+  <related>
+    <ref id="accordion" />
+    <ref id="surface" />
+    <ref id="toggle-button" />
+    <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/collapsible#api-reference" />
+</meta>

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

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="disclosure">
+  <example title="Default Surface Trigger + Panel">
+    <tsx><![CDATA[
+<Disclosure>
+  <Disclosure.Trigger hPadding="m" radius="m" vPadding="m">
+    Shipping details
+  </Disclosure.Trigger>
+  <Disclosure.Panel>
+    <Stack hPadding="m" vPadding="m">
+      <Text tone="muted">Orders ship within 2 business days.</Text>
+    </Stack>
+  </Disclosure.Panel>
+</Disclosure>
+]]></tsx>
+    <notes>Default Trigger = Surface with render → Collapsible.Trigger; hoverColor defaults to 2. Panel is motion-only — pad children in the story/app.</notes>
+  </example>
+
+  <example title="Custom icons with interpolate">
+    <tsx><![CDATA[
+<Disclosure>
+  <Disclosure.Trigger
+    hPadding="m"
+    interpolateIcons
+    openIcon={<Xmark size="1rem" />}
+    radius="m"
+    restingIcon={<Plus size="1rem" />}
+    vPadding="m"
+  >
+    Advanced
+  </Disclosure.Trigger>
+  <Disclosure.Panel>
+    <Stack hPadding="m" vPadding="m">
+      {/* advanced controls */}
+    </Stack>
+  </Disclosure.Panel>
+</Disclosure>
+]]></tsx>
+    <notes>ToggleButton-style resting/open icons; interpolate opt-in. For multi-item lists use Accordion instead.</notes>
+  </example>
+
+  <example title="Custom Trigger render">
+    <tsx><![CDATA[
+<Disclosure>
+  <Disclosure.Trigger render={<Button variant="secondary" />}>
+    Show more
+  </Disclosure.Trigger>
+  <Disclosure.Panel>
+    <Text>Extra details</Text>
+  </Disclosure.Panel>
+</Disclosure>
+]]></tsx>
+    <notes>Consumer render replaces the whole Surface + primitive compose; Surface defaults do not apply.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="disclosure">
+  <when_to_use>
+    <item>Single-section progressive disclosure (show more, optional details, FAQ item alone)</item>
+    <item>Expand/collapse one block with Surface chrome Trigger and optional icon pair</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Multi-item collapsible lists — use Accordion</item>
+    <item>Expecting default Panel content padding — Panel is a motion shell only</item>
+    <item>Primary navigation that should use links, Tabs, or routes</item>
+  </when_not_to_use>
+  <prop name="Trigger.restingIcon" kind="react">
+    <description>Decorative icon while the panel is closed. Defaults to ChromeChevronEnd when both icon slots are omitted.</description>
+  </prop>
+  <prop name="Trigger.openIcon" kind="react">
+    <description>Decorative icon while the panel is open. Defaults to ChromeChevronDown when both icon slots are omitted. When only restingIcon is set, that icon shows in both states.</description>
+  </prop>
+  <prop name="Trigger.interpolateIcons" kind="react">
+    <description>When dual icons are present, crossfade and light-rotate between them (`data-interpolate=&quot;true&quot;`). When false, swap instantly with no transition.</description>
+  </prop>
+  <prop name="Trigger.iconPosition" kind="react">
+    <description>Logical side of the label where the icon slot sits (`start` | `end`). Default `end`.</description>
+  </prop>
+  <prop name="Trigger.color" kind="react">
+    <description>Surface resting background on the default Trigger host. Omitted on consumer Trigger render.</description>
+  </prop>
+  <prop name="Trigger.hoverColor" kind="react">
+    <description>Surface hover background on the default Trigger host. Defaults to level 2 when omitted. Skipped when consumer supplies Trigger render.</description>
+  </prop>
+  <prop name="Trigger.border" kind="react">
+    <description>Surface contrast border on the default Trigger host.</description>
+  </prop>
+  <prop name="Trigger.borderStyle" kind="react">
+    <description>Surface border style when border is set on the default Trigger host.</description>
+  </prop>
+  <prop name="Trigger.radius" kind="react">
+    <description>Surface corner radius on the default Trigger host.</description>
+  </prop>
+  <prop name="Trigger.hPadding" kind="react">
+    <description>Surface inline padding on the default Trigger host. Defaults to `m` when omitted. Skipped when consumer supplies Trigger render.</description>
+  </prop>
+  <prop name="Trigger.vPadding" kind="react">
+    <description>Surface block padding on the default Trigger host. Defaults to `s` when omitted. Skipped when consumer supplies Trigger render.</description>
+  </prop>
+  <prop name="Trigger.render" kind="react">
+    <description>Replaces the whole default Surface + Collapsible Trigger compose with a custom host.</description>
+  </prop>
+  <prop name="Panel.hiddenUntilFound" kind="react">
+    <description>Allows browser find-in-page to expand the panel; Base UI Collapsible Panel pass-through.</description>
+  </prop>
+  <prop name="Panel.keepMounted" kind="react">
+    <description>Keeps the panel in the DOM while closed; Base UI Collapsible Panel pass-through.</description>
+  </prop>
+</props>

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="disclosure">
+  <do>Compose `Disclosure` + `Disclosure.Trigger` + `Disclosure.Panel` for a single expandable section</do>
+  <do>Spread Surface chrome on Trigger (`color`, `hoverColor`, `border`, `radius`, padding) when using the default host</do>
+  <do>Supply Panel children layout (Stack/padding) yourself — Panel has no default content padding</do>
+  <do>Use `restingIcon` / `openIcon` / `interpolateIcons` for ToggleButton-style icon pairs; omit both for chrome chevron End/Down</do>
+  <do>Pass Trigger `render` when replacing the Surface compose entirely</do>
+  <dont>Using Accordion for a single section — Accordion is multi-item</dont>
+  <dont>Expecting Accordion-like default Panel padding from Disclosure.Panel</dont>
+  <dont>Relying on icon animation alone for open/closed meaning under reduced motion</dont>
+</usage>

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

@@ -50,4 +50,16 @@
 ]]></tsx>
     <notes>From preview-grid `daily-activity-goal` nested tips sheet. Meter for score-within-range; LinearProgress stays on the live activity track outside the dialog.</notes>
   </example>
+
+  <example title="Highlight variants">
+    <tsx><![CDATA[
+<Stack rowGap="m">
+  <Meter label="Health" renderValue value={92} variant="green" />
+  <Meter label="Latency" renderValue value={38} variant="yellow" />
+  <Meter label="Errors" renderValue value={12} variant="red" />
+  <Meter label="Quota" renderValue value={64} variant="blue" />
+</Stack>
+]]></tsx>
+    <notes>`variant` highlight tokens tint track wash + indicator together (Chip-aligned). Default `primary` keeps brand indicator + contrast track.</notes>
+  </example>
 </patterns>

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

@@ -4,6 +4,7 @@
     <item>Use for storage usage, battery level, capacity, or score within a known range.</item>
     <item>Use with a label when the metric needs a visible name.</item>
     <item>Use with `renderValue` when the formatted value should appear beside the label.</item>
+    <item>Use highlight `variant` values when the track and indicator should share a semantic color.</item>
   </when_to_use>
   <when_not_to_use>
     <item>Use LinearProgress for in-progress tasks or indeterminate work.</item>
@@ -19,12 +20,18 @@
   <prop name="renderValue" kind="react">
     <description>Shows the current value beside the label. Pass `true` for Base UI default formatting, or a function matching `Meter.Value` `children` to customize the printed label.</description>
   </prop>
+  <prop name="variant" kind="react">
+    <description>Selects track and indicator colors. `primary` uses brand primary on the indicator; highlight token names tint both track (wash) and indicator via `--highlight-*`, matching Chip highlight variants.</description>
+  </prop>
   <prop name="indicator-color" kind="css">
     <description>Determinate meter indicator color.</description>
   </prop>
   <prop name="track-background" kind="css">
     <description>Meter track background color.</description>
   </prop>
+  <prop name="track-opacity" kind="css">
+    <description>Highlight variant track wash opacity mix against the indicator color.</description>
+  </prop>
   <prop name="track-size" kind="css">
     <description>Meter track thickness on the root.</description>
   </prop>

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

@@ -4,10 +4,12 @@
   <do>Labeled metrics: `label` + `renderValue` + optional `description`; tune print with Base UI `format` / `locale`</do>
   <do>Workspace stacks: Stack `rowGap` of Meters — or nest one Meter inside Surface for sheet / tip chrome</do>
   <do>Rich labels: pass a Stack row (icon + text) as `label` when needed — no custom label CSS</do>
+  <do>Color-coded metrics via highlight `variant` (`green`, `red`, `yellow`, …) or default `primary` — tints track wash + indicator like Chip</do>
   <do>Prefer LinearProgress for in-progress or indeterminate tasks (`value={null}`) — Meter has no indeterminate mode</do>
   <dont>Using Meter as an interactive value control — use Slider</dont>
   <dont>Using Meter for indeterminate or in-progress work — use LinearProgress</dont>
   <dont>Modeling invalid or disabled meter state — Base UI Meter exposes neither</dont>
   <dont>Hiding the metric name when multiple meters share a view</dont>
   <dont>Passing `value={null}` — Meter `value` is required `number`</dont>
+  <dont>Reinventing highlight track/indicator colors with raw `--highlight-*` CSS when `variant` covers the token</dont>
 </usage>

package/dist/specs/components/number-field/a11y.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="number-field">
+  <rule>Visible `label` on `NumberField` names the numeric input via Field.Label / htmlFor.</rule>
+  <rule>Description uses Field description / `aria-describedby` while valid.</rule>
+  <rule>Error copy shares the helper slot and replaces description while invalid and dirty (same as Textfield).</rule>
+  <rule>Internal steppers are icon-only IconButtons named `Decrement` and `Increment`.</rule>
+  <rule>Label scrub is optional chrome (`labelScrub`, default true when label present). Disable with `labelScrub={false}` or omit label.</rule>
+  <rule>Focus order follows `stepperPlacement`: split → decrement, input, increment; grouped → input then both. Grouped visual side follows document direction (inline-end).</rule>
+  <rule>When `description` is a string, NumberField sets `aria-roledescription` on the numeric input to that string; otherwise Base UI default remains.</rule>
+</a11y>

package/dist/specs/components/number-field/meta.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="number-field" title="NumberField" category="form" shared_contract="number-field">
+  <summary>Single public NumberField with Field chrome, internal IconButton steppers, and optional label scrub. Group / Decrement / Increment / ScrubArea stay internal.</summary>
+  <exports>
+    <export name="NumberField" />
+  </exports>
+  <related>
+    <ref id="textfield" />
+    <ref id="icon-button" />
+    <ref id="fieldset" />
+    <ref id="text" />
+    <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/number-field#api-reference" />
+</meta>

package/dist/specs/components/number-field/patterns.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="number-field">
+  <example title="Labeled amount">
+    <tsx><![CDATA[
+<NumberField
+  defaultValue={100}
+  label="Amount"
+  description="Enter the amount in your local currency."
+/>
+]]></tsx>
+    <notes>Default split steppers. Label scrub on when label is present.</notes>
+  </example>
+
+  <example title="Form name + bounds">
+    <tsx><![CDATA[
+<Form>
+  <NumberField name="quantity" defaultValue={1} min={0} max={99} step={1} label="Quantity" />
+</Form>
+]]></tsx>
+    <notes>`name` / min / max / step / label on NumberField. `Form` is `@base-ui/react/form`.</notes>
+  </example>
+
+  <example title="Stepper placement grouped">
+    <tsx><![CDATA[
+<NumberField defaultValue={5} label="Count" stepperPlacement="grouped" />
+]]></tsx>
+    <notes>Both steppers at inline-end (LTR right / RTL left). Steppers are fixed secondary IconButtons.</notes>
+  </example>
+
+  <example title="Full width input grow">
+    <tsx><![CDATA[
+<NumberField defaultValue={25} label="Amount" fullWidth />
+]]></tsx>
+    <notes>Row fills the column; only the numeric input flex-grows.</notes>
+  </example>
+
+  <example title="Plain label without scrub">
+    <tsx><![CDATA[
+<NumberField defaultValue={10} label="Amount" labelScrub={false} />
+]]></tsx>
+    <notes>Field label without ScrubArea.</notes>
+  </example>
+</patterns>

package/dist/specs/components/number-field/props.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="number-field">
+  <when_to_use>
+    <item>Numeric values with optional increment/decrement and label scrub</item>
+    <item>Form fields that submit a number via `name` (min/max/step/format on the same NumberField)</item>
+    <item>Textfield-aligned label / description / error with Field validation</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Exposing Group / Decrement / Increment / ScrubArea as public parts — they stay internal</item>
+    <item>Textfield start/end addon API or custom stepper children in v1</item>
+    <item>Exposing a NumberField size or variant prop — steppers stay fixed IconButton `size=&quot;s&quot;` / `variant=&quot;secondary&quot;`</item>
+    <item>Composing a public `NumberField.Input` — chrome and steppers live on NumberField</item>
+  </when_not_to_use>
+  <prop name="description" kind="react">
+    <description>Helper copy rendered with `Field.Description` and `Text` while the field is valid. When a string, also sets `aria-roledescription` on the numeric input.</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 invalid and dirty.</description>
+  </prop>
+  <prop name="fitContent" kind="react">
+    <description>When `true`, sets `field-sizing: content` on the numeric input only. Steppers stay intrinsic.</description>
+  </prop>
+  <prop name="fullWidth" kind="react">
+    <description>When `true`, field and control row fill the column; only the numeric input flex-grows. Steppers stay intrinsic. Prefer over CSS `width: 100%` on the field.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible label rendered with shared internal `FieldLabel`. Hosts scrub when `labelScrub` is true.</description>
+  </prop>
+  <prop name="labelScrub" kind="react">
+    <description>When `true` (default) and `label` is set, wrap the label in Base UI scrub. When `false` or no label, plain field label.</description>
+  </prop>
+  <prop name="stepperPlacement" kind="react">
+    <description>Where steppers sit relative to the input: `split` (default, button|input|button) or `grouped` (both at inline-end; physical right in LTR, left in RTL via document direction).</description>
+  </prop>
+</props>

package/dist/specs/components/number-field/usage.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="number-field">
+  <do>Use a single `NumberField` for value/min/max/step/name plus label/helper/steppers</do>
+  <do>Put Field validation props (`invalid`, `dirty`, `touched`, `validate`, …) on NumberField</do>
+  <do>Steppers are fixed IconButton `size=&quot;s&quot;` / `variant=&quot;secondary&quot;` with uniform addon padding — do not expose variant/size</do>
+  <do>Use `fullWidth` when the numeric input should grow; steppers stay compact</do>
+  <do>Turn off label scrub with `labelScrub={false}` when drag-on-label is unwanted</do>
+  <dont>Export or compose public Group / Decrement / Increment / ScrubArea / ScrubAreaCursor</dont>
+  <dont>Compose a public `NumberField.Input` — there is no Input part</dont>
+  <dont>Add Textfield start/end addon API or custom stepper children in v1</dont>
+  <dont>Invent CSS width hacks when `fullWidth` / `fitContent` cover sizing</dont>
+</usage>

package/dist/specs/components/otp-field/a11y.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="otp-field">
+  <rule>One Field: visible `label` names the first slot via Field.Label / htmlFor. Do not put aria-label on the first Input.</rule>
+  <rule>Slots after the first get `aria-label` `Character N of {length}` in English when the consumer omits `aria-label`. Consumer `aria-label` wins when passed.</rule>
+  <rule>Description and error copy live on the OTPField root helper slot (dirty+invalid), not per slot.</rule>
+  <rule>`OTPField.Separator` is a separator, not an input, and is not counted in `length`.</rule>
+  <rule>Slot host is always a native `input`. Chrome is Textfield `controlOnly` (no second Field).</rule>
+  <rule>Focus ring is per active slot (`:focus`). Input `data-focused` means any slot is focused — do not paint chrome from it.</rule>
+  <rule>Invalid wiggle is one-shot chrome only. Error copy / `aria-invalid` still name the error. Reduced motion skips the animation.</rule>
+</a11y>

package/dist/specs/components/otp-field/meta.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="otp-field" title="OTPField" category="form" shared_contract="otp-field">
+  <summary>Field-wrapped one-time code slots. Default slots compose Textfield controlOnly; one label/helper on OTPField.</summary>
+  <exports>
+    <export name="OTPField" />
+  </exports>
+  <related>
+    <ref id="textfield" />
+    <ref id="fieldset" />
+    <ref id="text" />
+    <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/otp-field#api-reference" />
+</meta>

package/dist/specs/components/otp-field/patterns.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="otp-field">
+  <example title="Labeled six-slot code">
+    <tsx><![CDATA[
+<OTPField
+  length={6}
+  label="Verification code"
+  description="Enter the 6-character code we sent to your device."
+>
+  {Array.from({ length: 6 }, (_, slotIndex) => (
+    <OTPField.Input key={`character-${slotIndex + 1}`} />
+  ))}
+</OTPField>
+]]></tsx>
+    <notes>Explicit Inputs. First slot uses the field label; later slots get generated names.</notes>
+  </example>
+
+  <example title="Form name + autoSubmit">
+    <tsx><![CDATA[
+<Form>
+  <OTPField length={6} name="verificationCode" label="Verification code" autoSubmit>
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+  </OTPField>
+</Form>
+]]></tsx>
+    <notes>One concatenated form value. `autoSubmit` submits when complete. `Form` is `@base-ui/react/form`.</notes>
+  </example>
+
+  <example title="Grouped slots with Separator">
+    <tsx><![CDATA[
+<OTPField length={6} label="Verification code">
+  <Stack columnGap="s" direction="row">
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+  </Stack>
+  <OTPField.Separator />
+  <Stack columnGap="s" direction="row">
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+  </Stack>
+</OTPField>
+]]></tsx>
+    <notes>Separator is not an input and is not counted in `length`. Stack owns group gaps.</notes>
+  </example>
+
+  <example title="Equal-grow in a form column">
+    <tsx><![CDATA[
+<OTPField length={6} label="Verification code" fullWidth>
+  <OTPField.Input />
+  <OTPField.Input />
+  <OTPField.Input />
+  <OTPField.Input />
+  <OTPField.Input />
+  <OTPField.Input />
+</OTPField>
+]]></tsx>
+    <notes>Default hugs. `fullWidth` fills the column and grows slots equally.</notes>
+  </example>
+</patterns>

package/dist/specs/components/otp-field/props.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="otp-field">
+  <when_to_use>
+    <item>One-time codes, verification codes, and recovery codes as a single labeled field</item>
+    <item>Numeric, alphanumeric, or masked slot entry with form `name` submit of the concatenated value</item>
+    <item>Grouped slot rows with `OTPField.Separator` and Stack, not a `groups` prop</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Auto-generating Inputs from `length` — always list one `OTPField.Input` per slot</item>
+    <item>Per-slot label, description, or error — Field chrome is on OTPField only</item>
+    <item>Swapping the slot host via `render` — host is always a native `input`; chrome is Textfield `controlOnly`</item>
+    <item>Inventing CSS `width: 100%` on slots when OTPField `fullWidth` covers equal-grow</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`. Replaces description while the field is invalid and dirty.</description>
+  </prop>
+  <prop name="fullWidth" kind="react">
+    <description>When `true`, the field is `inline-size: 100%` and the inner slot Stack uses `fullWidth` + `expandChildren` so slots grow equally. Prefer this over CSS `width: 100%` on slots.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Visible label rendered with shared internal `FieldLabel`. Names the first slot.</description>
+  </prop>
+  <prop name="length" kind="react">
+    <description>Required slot count for clamp, complete, and hidden validation markup. Does not spawn Inputs — list exactly this many `OTPField.Input` children.</description>
+  </prop>
+</props>

package/dist/specs/components/otp-field/usage.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="otp-field">
+  <do>List exactly `length` `OTPField.Input` children (Array.from or explicit)</do>
+  <do>Put `label` / `description` / `error` on `OTPField`</do>
+  <do>Let the first slot take the field label; later slots get generated `Character N of {length}` unless you pass `aria-label`</do>
+  <do>Group slots with Stack + `OTPField.Separator` when the code is shown as chunks</do>
+  <do>Span the form column with `OTPField` `fullWidth` so slots grow equally</do>
+  <do>Keep error copy on `OTPField` — invalid wiggle is extra chrome, not the only signal</do>
+  <dont>Pass `render` on Input — slot is always a native `input`; chrome is Textfield `controlOnly`</dont>
+  <dont>Put label/description/error on each slot</dont>
+  <dont>Expect `OTPField` to auto-generate Inputs from `length`</dont>
+  <dont>Invent a `groups` prop or width CSS on slots when Stack / `fullWidth` cover layout</dont>
+</usage>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="prose">
+  <rule>Prose is grouping, not a widget — do not set a role on the root</rule>
+  <rule>Default root is a generic `div`; it does not require an accessible name</rule>
+  <rule>Landmark semantics only when the consumer replaces the root (`render={&lt;article /&gt;}` or similar) and names the landmark if needed</rule>
+  <rule>Children keep their own roles (headings, lists, links); Prose does not restyle or re-role them</rule>
+</a11y>

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

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="prose" title="Prose" category="typography" shared_contract="prose">
+  <summary>Grouping region that applies heading-aware em rhythm to direct document blocks.</summary>
+  <exports>
+    <export name="Prose" />
+  </exports>
+  <related>
+    <ref id="text" />
+    <ref id="title" />
+    <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/prose/patterns.xml

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="prose">
+  <example title="Article with Title and Text">
+    <tsx><![CDATA[
+<Prose render={<article />}>
+  <Title size="2" lineHeight="s" render={<h2 />}>
+    Heading-aware document rhythm
+  </Title>
+  <Text render={<p />}>
+    Direct heading and paragraph children pick up Prose gaps. Type stays on Title and Text.
+  </Text>
+  <Text render={<p />}>A second paragraph uses the block gap, not the heading-end gap.</Text>
+</Prose>
+]]></tsx>
+    <notes>Default `gap="l"`. Landmark via `render={<article />}`. Title in Prose uses `lineHeight="s"`. Do not wrap these blocks in Stack for rhythm.</notes>
+  </example>
+
+  <example title="Density and region align">
+    <tsx><![CDATA[
+<Prose gap="s" align="center">
+  <Title size="3" lineHeight="s" render={<h3 />}>
+    Compact notes
+  </Title>
+  <Text render={<p />}>One Prose `align` sets the region. Omit Title/Text `align` so they inherit.</Text>
+</Prose>
+]]></tsx>
+    <notes>`s` &lt; `m` &lt; `l`. `align` maps to `--vui-prose-align` + `text-align` on the root. Title `lineHeight="s"`.</notes>
+  </example>
+
+  <example title="Line height on body">
+    <tsx><![CDATA[
+<Prose>
+  <Title size="2" lineHeight="s" render={<h2 />}>
+    Tight heading, chosen body leading
+  </Title>
+  <Text render={<p />} lineHeight="l">
+    Headings in Prose stay on Title `lineHeight="s"`. Body leading is a Text prop — this paragraph uses `l`.
+  </Text>
+  <Text render={<p />} lineHeight="s">
+    A following paragraph can use `lineHeight="s"` when the article should sit denser.
+  </Text>
+</Prose>
+]]></tsx>
+    <notes>Prose does not own leading. Title inside Prose → `lineHeight="s"`. Text `lineHeight` per block.</notes>
+  </example>
+
+  <example title="Span hosts stay out">
+    <tsx><![CDATA[
+<Prose>
+  <Title size="4" lineHeight="s">
+    This Title is a span — no Prose heading gap
+  </Title>
+  <Text>This Text is a span — no Prose block gap.</Text>
+  <Text render={<p />}>This paragraph is a matching block.</Text>
+</Prose>
+]]></tsx>
+    <notes>Default Title/Text hosts are `span`. Use `render` for h1–h6 / `p` when they should join rhythm. Title still `lineHeight="s"`.</notes>
+  </example>
+</patterns>