@viraui/react 2026.6.5 → 2026.7.0-next.0

package/dist/index.js

@@ -6,6 +6,7 @@ import { Autocomplete } from "./components/autocomplete/autocomplete.js";
 import { Avatar } from "./components/avatar/avatar.js";
 import { AvatarGroup } from "./components/avatar-group/avatar-group.js";
 import { Badge } from "./components/badge/badge.js";
+import { Surface } from "./components/surface/surface.js";
 import { Beam } from "./components/beam/beam.js";
 import { Bleed } from "./components/bleed/bleed.js";
 import { BreakpointsProvider } from "./components/breakpoints/breakpoints-provider.js";
@@ -28,7 +29,6 @@ import { getElevationProps } from "./core/elevation/get-elevation-props.js";
 import { Elevator } from "./components/elevator/elevator.js";
 import { Fieldset } from "./components/fieldset/fieldset.js";
 import { FitText } from "./components/fit-text/fit-text.js";
-import { Surface } from "./components/surface/surface.js";
 import { Glow } from "./components/glow/glow.js";
 import { Grid } from "./components/grid/grid.js";
 import { IconButton } from "./components/icon-button/icon-button.js";
@@ -46,9 +46,12 @@ import { MenuSeparator } from "./components/menu/menu-separator.js";
 import { MenuSubmenuTrigger } from "./components/menu/menu-submenu-trigger.js";
 import { Menu, MenuSubmenu, MenuTrigger } from "./components/menu/menu.js";
 import { Meter } from "./components/meter/meter.js";
+import { Textfield } from "./components/textfield/textfield.js";
+import { OTPField } from "./components/otp-field/otp-field.js";
 import { PopoverSheet } from "./components/popover/popover-sheet.js";
 import { Popover, PopoverClose, PopoverDescription, PopoverTitle, PopoverTrigger } from "./components/popover/popover.js";
 import { ProgressiveBlur } from "./components/progressive-blur/progressive-blur.js";
+import { Prose } from "./components/prose/prose.js";
 import { Radio } from "./components/radio/radio.js";
 import { RadioGroup } from "./components/radio/radio-group.js";
 import { Select } from "./components/select/select.js";
@@ -60,7 +63,6 @@ import { StaticNoise } from "./components/static-noise/static-noise.js";
 import { Switch } from "./components/switch/switch.js";
 import { Tabs } from "./components/tabs/tabs.js";
 import { Textarea } from "./components/textarea/textarea.js";
-import { Textfield } from "./components/textfield/textfield.js";
 import { Title } from "./components/title/title.js";
 import { Toast } from "./components/toast/toast.js";
 import { ToggleButton } from "./components/toggle-button/toggle-button.js";
@@ -68,4 +70,4 @@ import { ToggleGroup } from "./components/toggle-group/toggle-group.js";
 import { Typewriter } from "./components/typewriter/typewriter.js";
 import { TooltipContent } from "./components/tooltip/tooltip-content.js";
 import { Tooltip, TooltipProvider, TooltipTrigger } from "./components/tooltip/tooltip.js";
-export { Accordion, Annotate, Autocomplete, Avatar, AvatarGroup, Badge, Beam, Bleed, BreakpointsProvider, Button, ButtonLink, Checkbox, CheckboxGroup, Chip, ClampText, Dialog, DialogClose, DialogIndent, DialogIndentBackground, DialogSheet, DialogTrigger, ELEVATION_DEFAULTS, Elevator, Fieldset, FitText, Glow, Grid, IconButton, IconButtonLink, LinearProgress, Masonry, Menu, MenuCheckboxItem, MenuGroup, MenuItem, MenuLinkItem, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Meter, Popover, PopoverClose, PopoverDescription, PopoverSheet, PopoverTitle, PopoverTrigger, ProgressiveBlur, Radio, RadioGroup, Select, Separator, Shimmer, Skeleton, Slider, Spinner, Stack, StaticNoise, Surface, Switch, Tabs, Text, Textarea, Textfield, Title, Toast, ToggleButton, ToggleGroup, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Typewriter, getElevationProps, useBreakpoints };
+export { Accordion, Annotate, Autocomplete, Avatar, AvatarGroup, Badge, Beam, Bleed, BreakpointsProvider, Button, ButtonLink, Checkbox, CheckboxGroup, Chip, ClampText, Dialog, DialogClose, DialogIndent, DialogIndentBackground, DialogSheet, DialogTrigger, ELEVATION_DEFAULTS, Elevator, Fieldset, FitText, Glow, Grid, IconButton, IconButtonLink, LinearProgress, Masonry, Menu, MenuCheckboxItem, MenuGroup, MenuItem, MenuLinkItem, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Meter, OTPField, Popover, PopoverClose, PopoverDescription, PopoverSheet, PopoverTitle, PopoverTrigger, ProgressiveBlur, Prose, Radio, RadioGroup, Select, Separator, Shimmer, Skeleton, Slider, Spinner, Stack, StaticNoise, Surface, Switch, Tabs, Text, Textarea, Textfield, Title, Toast, ToggleButton, ToggleGroup, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Typewriter, getElevationProps, useBreakpoints };

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

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <a11y surface="beam">
-  <rule>Root stays in the accessibility tree; bloom layer is empty div</rule>
+  <rule>Root stays in the accessibility tree; bloom layer is an empty decorative div with aria-hidden</rule>
   <rule>Beam is not a focus or status indicator — consumer owns accessible names and state</rule>
-  <rule>Offscreen instances pause animations without firing activate/deactivate</rule>
-  <rule>prefers-reduced-motion disables motion and leaves a static resting look</rule>
+  <rule>Offscreen instances set data-paused="true" and pause motion without firing activate/deactivate</rule>
+  <rule>prefers-reduced-motion keeps a static visible rest (no looping motion); animate=false still fades the effect away</rule>
 </a11y>

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/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/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,23 @@
+<?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 Root.</summary>
+  <exports>
+    <export name="OTPField" />
+    <export name="OTPField.Root" />
+    <export name="OTPField.Input" />
+    <export name="OTPField.Separator" />
+  </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.Root
+  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.Root>
+]]></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.Root length={6} name="verificationCode" label="Verification code" autoSubmit>
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+    <OTPField.Input />
+  </OTPField.Root>
+</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.Root 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.Root>
+]]></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.Root length={6} label="Verification code" fullWidth>
+  <OTPField.Input />
+  <OTPField.Input />
+  <OTPField.Input />
+  <OTPField.Input />
+  <OTPField.Input />
+  <OTPField.Input />
+</OTPField.Root>
+]]></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 Root 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 Root `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.Root` (or `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 Root `fullWidth` so slots grow equally</do>
+  <do>Keep error copy on Root — 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 Root 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>

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

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="prose">
+  <when_to_use>
+    <item>Long-form copy whose direct children are headings and blocks that need heading-aware vertical rhythm</item>
+    <item>Article, docs, or changelog regions where Stack `rowGap` would make heading→body and body→body the same</item>
+    <item>Optional `gap` density (`s` / `m` / `l`) and region `align` (Title/Text that omit `align` inherit it)</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>UI chrome spacing (cards, toolbars, form rows) — use Stack `rowGap` / `columnGap`</item>
+    <item>Restyling type, lists, links, or tables — stay on Title / Text / consumer CSS</item>
+    <item>Markdown parse or sanitize — Prose only spaces matching direct children</item>
+  </when_not_to_use>
+  <prop name="align" kind="react">
+    <description>Aligns the region using logical alignment values. Omit so `text-align` inherits from the parent. Title/Text children that omit `align` inherit this value.</description>
+  </prop>
+  <prop name="gap" kind="react">
+    <description>Em density for heading-aware vertical rhythm (`s` &lt; `m` &lt; `l`).</description>
+  </prop>
+  <prop name="ref" kind="react">
+    <description>Ref forwarded to the rendered prose root element.</description>
+  </prop>
+  <prop name="render" kind="react">
+    <description>Replaces the default `div` root using Base UI render semantics.</description>
+  </prop>
+  <prop name="align" kind="css">
+    <description>Region `text-align` (`--vui-prose-align`) when the `align` prop is set; omitted inherits parent `text-align`.</description>
+  </prop>
+  <prop name="gap-blocks" kind="css">
+    <description>Block sibling gap (`--vui-prose-gap-blocks`). Default `2em` (`l`); `s`/`m` assign smaller triples on the root.</description>
+  </prop>
+  <prop name="gap-heading-end" kind="css">
+    <description>Heading block-end gap (`--vui-prose-gap-heading-end`). Default `0.8em` (`l`).</description>
+  </prop>
+  <prop name="gap-heading-start" kind="css">
+    <description>Gap after a heading onto the next sibling (`--vui-prose-gap-heading-start`). Default `1.3em` (`l`).</description>
+  </prop>
+</props>

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

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="prose">
+  <do>Put headings and blocks as **direct** children — Title/Text with `render={&lt;h* /&gt;}` / `render={&lt;p /&gt;}`, plus native `ul`/`ol`/`blockquote` when needed</do>
+  <do>Pick `gap` `s` / `m` / `l` (default `l`) for density; `align` on Prose to set one `text-align` for the region (omit Title/Text `align` so they inherit)</do>
+  <do>Use `render={&lt;article /&gt;}` (or another landmark) when the region is the document landmark; name it if the landmark needs a name</do>
+  <do>Leave type on Title/Text; Title inside Prose uses `lineHeight=&quot;s&quot;`; override `--vui-prose-gap-*` on the Prose root only when the em triple must change</do>
+  <dont>Using Stack `rowGap` as article rhythm — one gap cannot split heading→body vs body→body</dont>
+  <dont>Expecting default Title/Text `span` hosts to join rhythm — they are not heading/block tags</dont>
+  <dont>Setting `as` — replace the root with `render` only</dont>
+  <dont>Setting `align` on every Title/Text inside Prose when one Prose `align` covers the region</dont>
+  <dont>Setting a widget `role` on Prose, or painting font/color/list/link chrome in Prose CSS</dont>
+</usage>

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

@@ -30,6 +30,9 @@
   <prop name="vPadding" kind="react">
     <description>Sets block padding on the Stack wrapper using one token for both sides or a `[start, end]` tuple.</description>
   </prop>
+  <prop name="maxWidth" kind="react">
+    <description>Caps the Stack wrapper inline size. Use for a short dash in a horizontal row.</description>
+  </prop>
   <prop name="border-style" kind="css">
     <description>Separator line border style.</description>
   </prop>

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

@@ -5,6 +5,7 @@
   <do>Bookend action strips — Separator above/below a Button row inside Surface (editor footers)</do>
   <do>Vertical gutters or toolbar splits — `orientation=&quot;vertical&quot;` in a row Stack beside content or Button groups</do>
   <do>Token thickness (`size`) and `variant` (e.g. dashed); space with Separator `hPadding`/`vPadding` or parent Stack gap — no custom border CSS</do>
+  <do>Short dash in a row — `maxWidth` token (Stack cap), not extra width CSS</do>
   <dont>Using Select.Separator for general layout dividers — that part is for Select option lists only</dont>
   <dont>Replacing Surface borders or card outlines with Separator — use Surface `border` props for container chrome</dont>
   <dont>Inventing divider margin/gap CSS when parent Stack `rowGap` / `columnGap` and Separator padding props cover spacing</dont>

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

@@ -12,7 +12,7 @@
     <item>Inventing CSS `letter-spacing` / `text-transform` / `width: 100%` when `tracking` / `transform` / parent Stack `fullWidth` cover the need</item>
   </when_not_to_use>
   <prop name="align" kind="react">
-    <description>Aligns text using logical alignment values.</description>
+    <description>Aligns text using logical alignment values. Omit so `text-align` inherits from the parent.</description>
   </prop>
   <prop name="balanced" kind="react">
     <description>Enables balanced wrapping for block-like copy.</description>
@@ -78,7 +78,7 @@
     <description>Controls white-space preservation and wrapping behavior.</description>
   </prop>
   <prop name="align" kind="css">
-    <description>Text alignment on the root.</description>
+    <description>Text alignment on the root when the `align` prop is set; omitted inherits parent `text-align`.</description>
   </prop>
   <prop name="font-family" kind="css">
     <description>Font family; family prop presets via data attributes.</description>

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

@@ -8,6 +8,7 @@
   <do>Hero / status motion: nest Typewriter inside Text when body tone/size should drive the typed line</do>
   <do>Ellipsis: ClampText `render={&lt;Text … /&gt;}` — FitText when copy must scale to fill width instead of truncate</do>
   <do>Letter-spacing via `tracking`; text-transform via `transform`; width via `maxWidth` or parent Stack `fullWidth`</do>
+  <do>Omit `align` so copy inherits parent `text-align`; pass `align` only to override</do>
   <do>Inline prose link: `Text render={&lt;a href=… /&gt;}` — keeps preflight link chrome (no `data-no-link-style`)</do>
   <dont>Using Text for headings — use Title (`render` for h1–h6)</dont>
   <dont>Putting `data-no-link-style` on Text-as-a when the default underline hover is wanted</dont>

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

@@ -8,6 +8,7 @@
     <ref id="autocomplete" />
     <ref id="fieldset" />
     <ref id="textarea" />
+    <ref id="otp-field" />
     <ref id="select" />
     <ref id="text" />
   </related>

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

@@ -5,14 +5,19 @@
     <item>Start or end addon slots inside the shared control group</item>
     <item>Label, description, and error copy with validation states</item>
     <item>Several related Textfields grouped under one section legend as Fieldset children (e.g. billing details)</item>
+    <item>Control chrome inside another Field (`controlOnly`) — native `size` / `fitContent` still apply</item>
   </when_to_use>
   <when_not_to_use>
     <item>Multi-line entry — use Textarea</item>
-    <item>Custom size or variant props — fixed medium treatment</item>
+    <item>Custom visual size or variant props — fixed medium treatment (native HTML `size` is allowed)</item>
     <item>Wrapping a lone Textfield in Fieldset when its own label is sufficient — Fieldset is for multi-field sections or shared legends</item>
     <item>Using Fieldset instead of the Textfield label for a single control</item>
     <item>Inventing CSS `width: 100%` / `w-full` when the `fullWidth` prop covers it</item>
+    <item>`controlOnly` as a standalone labeled field — omit it when you need Field chrome</item>
   </when_not_to_use>
+  <prop name="controlOnly" kind="react">
+    <description>When `true`, skip Field.Root / label / helper. Control group + input only. Use inside another Field (OTP slots). Native `size` and `fitContent` still apply. `label`, `description`, and `error` are ignored.</description>
+  </prop>
   <prop name="description" kind="react">
     <description>Helper copy rendered with `Field.Description` and `Text` while the field is valid.</description>
   </prop>

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

@@ -7,9 +7,10 @@
   <do>Span the form column with Textfield `fullWidth` — open props before inventing width CSS</do>
   <do>`startAddon` / `endAddon` for prefix text, icons, or actions inside the control group — IconButton/Button addons use `size=&quot;s&quot;` and `type=&quot;button&quot;`</do>
   <do>Label, description, and error copy with validation states</do>
+  <do>Compose the control inside another Field with `controlOnly` — native `size` / `fitContent` still apply; skip a second Field.Root</do>
   <dont>Multi-line entry — use Textarea</dont>
   <dont>Inventing `width: 100%` / `w-full` CSS on the Textfield root when `fullWidth` covers it</dont>
-  <dont>Passing unsupported size or variant props — fixed medium treatment</dont>
+  <dont>Passing visual size or variant props — chrome is fixed medium. Native HTML `size` on the input is allowed</dont>
   <dont>Expecting a focus ring when focus is only on addon controls</dont>
   <dont>Wrapping a lone Textfield in Fieldset when its own label is enough</dont>
 </usage>

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

@@ -13,7 +13,7 @@
     <item>Inventing CSS `letter-spacing` / `text-transform` / `width: 100%` when `tracking` / `transform` / parent Stack `fullWidth` cover the need</item>
   </when_not_to_use>
   <prop name="align" kind="react">
-    <description>Aligns text using logical alignment values.</description>
+    <description>Aligns text using logical alignment values. Omit so `text-align` inherits from the parent.</description>
   </prop>
   <prop name="balanced" kind="react">
     <description>Enables balanced wrapping for block-like titles.</description>
@@ -73,7 +73,7 @@
     <description>Controls white-space preservation and wrapping behavior.</description>
   </prop>
   <prop name="align" kind="css">
-    <description>Title alignment on the root.</description>
+    <description>Title alignment on the root when the `align` prop is set; omitted inherits parent `text-align`.</description>
   </prop>
   <prop name="font-family" kind="css">
     <description>Heading font family on the root.</description>

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

@@ -7,6 +7,7 @@
   <do>Truncation: ClampText `render={&lt;Title size=… render={&lt;h* /&gt;} /&gt;}` — FitText wraps Title when short headlines must fill a constrained width</do>
   <do>Fluid clamp across presets (`fluid` / theme `--effect-fluid-typography`); pass `fluid={false}` inside chrome or dense UI</do>
   <do>Letter-spacing via `tracking`; text-transform via `transform`; width via `maxWidth` or parent Stack `fullWidth`</do>
+  <do>Omit `align` so the heading inherits parent `text-align`; pass `align` only to override</do>
   <do>Title-as-prose-link (`render={&lt;a /&gt;}`) keeps preflight link chrome — omit `data-no-link-style`</do>
   <dont>Assuming `size` changes the HTML tag — choose `render` explicitly</dont>
   <dont>Using Title for long body paragraphs — use Text</dont>