@viraui/react 2026.6.0 → 2026.6.1

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

@@ -1,7 +1,72 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="beam">
-  <example title="Beam structure">
-    <tsx><![CDATA[<Beam>{children}</Beam>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no form handlers, no i18n, no backdrop Grid CSS). -->
+
+  <example title="CTA line beam (login)">
+    <tsx><![CDATA[
+<form>
+  <Stack direction="row" columnGap="m" rowGap="m" hAlign="start" vAlign="start" wrap>
+    <Textfield type="email" placeholder="your@email.com" size={30} aria-label="Email" />
+    <Stack direction="row" vAlign="center" columnGap="m">
+      <Button type="submit">Send magic link</Button>
+      or
+      <Beam variant="line" radius="m" strength={0.8} duration="5s">
+        <ButtonLink variant="secondary" href="#">
+          Get ViraUI Pro
+        </ButtonLink>
+      </Beam>
+    </Stack>
+  </Stack>
+</form>
+]]></tsx>
+    <notes>From `auth/login-form`. Beam wraps the secondary CTA only — line travel under the link. Drop react-hook-form / toast wiring.</notes>
+  </example>
+
+  <example title="Icon card beam (distribute)">
+    <tsx><![CDATA[
+<Surface overflow="hidden" border="all" color={1} radius="l">
+  <Stack rowGap="l" hPadding="l" vPadding={['2xl', '2xl']} hAlign="center">
+    <Beam radius="m" variant="line" color="primary">
+      <Surface color={2} border="all" radius="auto" hPadding="m" vPadding="m">
+        {/* leading icon */}
+      </Surface>
+    </Beam>
+
+    <Stack rowGap="s" hAlign="center">
+      <Title align="center" size="4" render={<h4 />}>
+        Distribute Track
+      </Title>
+      <Text size="s" align="center" maxWidth="18rem" tone="muted">
+        Upload your first master to start reaching listeners on Spotify, Apple Music, and more.
+      </Text>
+    </Stack>
+
+    <Button>Create Release</Button>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/distribute-track`. Beam around a nested Surface icon tile; `color="primary"` + `variant="line"`. Compose Surface as children — Beam is decoration only.</notes>
+  </example>
+
+  <example title="Empty-state icon beam">
+    <tsx><![CDATA[
+<Stack hAlign="center" vAlign="center" rowGap="l" render={<div role="status" />}>
+  <Beam radius="full" variant="line">
+    <Surface aria-hidden color={1} border="all" hPadding="m" radius="full" vPadding="m">
+      {/* icon */}
+    </Surface>
+  </Beam>
+
+  <Stack hAlign="center" maxWidth="36ch" rowGap="s">
+    <Title align="center" render={<h2 />} size="3">
+      No prompts yet
+    </Title>
+    <Text align="center" render={<p />} maxWidth="28ch" tone="muted">
+      Generate or import a prompt to get started.
+    </Text>
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>From `prompts/prompts-info-state` foreground. Full-radius Beam around the empty-state icon Surface. Drop decorative backdrop Grid / absolute CSS from this hint.</notes>
   </example>
 </patterns>

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

@@ -54,37 +54,37 @@
   <prop name="onDeactivate" kind="react">
     <description>Fired when the fade-out animation completes.</description>
   </prop>
-  <css_var suffix="angle">
+  <prop name="angle" kind="css">
     <description>Conic / travel start angle animated by border and line variants.</description>
-  </css_var>
-  <css_var suffix="opacity">
+  </prop>
+  <prop name="opacity" kind="css">
     <description>Fade opacity driven by fade-in / fade-out keyframes.</description>
-  </css_var>
-  <css_var suffix="duration">
+  </prop>
+  <prop name="duration" kind="css">
     <description>Spin / travel duration (and pulse period scale input).</description>
-  </css_var>
-  <css_var suffix="strength">
+  </prop>
+  <prop name="strength" kind="css">
     <description>Overall beam layer strength multiplier.</description>
-  </css_var>
-  <css_var suffix="brightness">
+  </prop>
+  <prop name="brightness" kind="css">
     <description>Brightness filter multiplier.</description>
-  </css_var>
-  <css_var suffix="saturation">
+  </prop>
+  <prop name="saturation" kind="css">
     <description>Saturation filter multiplier.</description>
-  </css_var>
-  <css_var suffix="hue-range">
+  </prop>
+  <prop name="hue-range" kind="css">
     <description>Hue-rotate oscillation range for non-static colors.</description>
-  </css_var>
-  <css_var suffix="color">
+  </prop>
+  <prop name="color" kind="css">
     <description>Resolved beam token color (primary or highlight). Colorful mode uses multi-stop internals.</description>
-  </css_var>
-  <css_var suffix="hue">
+  </prop>
+  <prop name="hue" kind="css">
     <description>Pulse hue drift angle written by the shared pulse driver.</description>
-  </css_var>
-  <css_var suffix="pulse-glow-sx">
+  </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>
-  </css_var>
-  <css_var suffix="pulse-glow-sy">
+  </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>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="beam">
-  <do>Highlight a focal Surface with a traveling border beam</do>
-  <do>Bottom-edge line travel under a card or panel</do>
-  <do>Breathing pulse glow inside or outside a Surface</do>
-  <do>Token-colored or colorful multi-stop decorative emphasis</do>
-  <dont>Relying on Beam for keyboard focus visibility</dont>
-  <dont>Treating Beam as the visual card instead of composing Surface children</dont>
+  <do>Wrap a visual Surface (often with `radius=&quot;auto&quot;`) or CTA as children — Beam is a transparent Surface shell (`radius` only), never the card chrome</do>
+  <do>Compose inside Stack/Surface layouts: line beam under a ButtonLink, or around an icon Surface in an empty-state / distribute card</do>
+  <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>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>Using many pulse Beam instances on one page — shared rAF still paints per instance</dont>
+  <dont>Scattering many Beam instances on one page</dont>
 </usage>

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

@@ -1,7 +1,58 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="bleed">
-  <example title="Bleed structure">
-    <tsx><![CDATA[<Bleed>…</Bleed>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no i18n, no app-only chrome). -->
+
+  <example title="Bleed divider between controls">
+    <tsx><![CDATA[
+<Stack rowGap="m" hPadding="s" vPadding="xs">
+  {/* control A */}
+  <Bleed amount="s">
+    <Separator />
+  </Bleed>
+  {/* control B */}
+</Stack>
+]]></tsx>
+    <notes>From `editor/sidebar/sidebar`. `amount="s"` cancels parent `hPadding="s"` so the Separator spans edge-to-edge inside the section body.</notes>
+  </example>
+
+  <example title="Full-width double rule (prompts)">
+    <tsx><![CDATA[
+<Stack rowGap="4xl" hPadding="m" vPadding="3xl">
+  <Stack rowGap="l" hPadding="l">
+    <Text tone="muted" size="s" transform="uppercase" tracking="0.2rem">
+      Prompts
+    </Text>
+    <Title size="1" render={<h1 />} maxWidth="20ch" lineHeight="s">
+      Generate and reuse prompt packs
+    </Title>
+    <Text maxWidth="60ch" tone="muted" render={<p />}>
+      Keep intro copy inset while the rule below breaks out of page padding.
+    </Text>
+  </Stack>
+  <Bleed amount="m">
+    <Separator variant="double" size="l" />
+  </Bleed>
+  <Stack hPadding="l">{/* tabs */}</Stack>
+</Stack>
+]]></tsx>
+    <notes>From `app/(hub)/prompts/page`. `amount="m"` matches outer Stack `hPadding="m"` so the double Separator hits the page edges.</notes>
+  </example>
+
+  <example title="Bleed trailing addon">
+    <tsx><![CDATA[
+<Surface color={2} hoverColor={3} radius="m" vPadding="s">
+  <Stack direction="row" vAlign="center" hAlign="space-between" columnGap="s" hPadding="m" vPadding={[0, 's']}>
+    <Text size="xs" weight="semibold">
+      Colors
+    </Text>
+    <Bleed amount="s">
+      <Button variant="flat" size="s">
+        Reset
+      </Button>
+    </Bleed>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/sidebar/sidebar` section `addon`. Bleed lets the reset control sit flush toward the Surface edge without shrinking header padding for the title.</notes>
   </example>
 </patterns>

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

@@ -16,7 +16,7 @@
   <prop name="full" kind="react">
     <description>Bleeds content to the viewport edges and ignores `amount`.</description>
   </prop>
-  <css_var suffix="amount">
+  <prop name="amount" kind="css">
     <description>Bleed distance on the root via `margin: 0 calc(var(--vui-bleed-amount, 0) * -1)` (negative inline, zero block).</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,10 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="bleed">
-  <do>Edge-to-edge media or dividers inside padded Surface or Stack containers</do>
+  <do>Edge-to-edge media or dividers inside padded Surface or Stack — match `amount` to the parent&apos;s `hPadding` token</do>
+  <do>Bleed a Separator across a padded Stack/Surface section so the rule hits the chrome edges without dropping parent padding for siblings</do>
+  <do>Flush trailing controls (e.g. flat Button) toward a Surface edge via Bleed while keeping title Stack padding intact</do>
   <do>Hero bands or callouts that should break out of card padding</do>
-  <do>Full-bleed sections that span the viewport width from a centered layout</do>
+  <do>Full-bleed sections that span the viewport width from a centered layout — `full` ignores `amount`</do>
   <dont>Nesting multiple full bleeds without checking ancestor overflow</dont>
-  <dont>Using Bleed to compensate for missing Stack padding instead of fixing layout composition</dont>
+  <dont>Using Bleed to compensate for missing Stack/Surface padding instead of fixing layout composition</dont>
   <dont>Applying full bleed inside narrow overflow-hidden cards without testing clipping</dont>
   <dont>Expecting full bleed `margin-left` to flip automatically in RTL</dont>
+  <dont>Inventing negative-margin CSS on Separator/Button when Bleed `amount` covers the breakout</dont>
 </usage>

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

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="breakpoints" title="BreakpointsProvider" category="layout" shared_contract="breakpoints">
-  <summary>Client provider plus `useBreakpoints` for mobile-first viewport min-width matches. Defaults are hardcoded em thresholds, not theme tokens.</summary>
+  <summary>Client provider plus `useBreakpoints` for mobile-first viewport min-width matches. Defaults are hardcoded em thresholds, not theme tokens. Style-only CSS should reuse the same map lengths.</summary>
   <exports>
     <export name="BreakpointsProvider" />
   </exports>

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

@@ -1,9 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="breakpoints">
-  <example title="BreakpointsProvider structure">
-    <tsx><![CDATA[<BreakpointsProvider>
-  {children}
-</BreakpointsProvider>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
-  </example>
+  <!-- Skip: zero viraui-app and design-kitchen usage. Stories are MatchesProbe / matchMedia harness only — no consumer compose to promote. -->
 </patterns>

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

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <props surface="breakpoints">
   <when_to_use>
-    <item>Swap or hide React markup when the viewport crosses named breakpoints</item>
+    <item>Mobile-first viewport work: narrow base, enhance at larger min-width matches</item>
+    <item>Swap or hide React markup, or change Vira props, when the viewport crosses named breakpoints</item>
     <item>Read one flag with `useBreakpoints(&apos;small&apos;)` so unrelated breakpoint flips skip work</item>
     <item>Override the full map with the `breakpoints` prop for product-specific thresholds</item>
   </when_to_use>
   <when_not_to_use>
-    <item>Layout that CSS `@media` or container queries can own without branching markup</item>
+    <item>Style-only changes CSS `@media (min-width)` can own — still use this map’s em lengths, not a parallel px system</item>
+    <item>Container-sized layout — use CSS `@container`, not this hook</item>
     <item>Calling `useBreakpoints` outside this provider</item>
     <item>Reading design-token CSS variables for breakpoint widths</item>
   </when_not_to_use>

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

@@ -1,9 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="breakpoints">
-  <do>Swap or hide React markup when the viewport crosses named breakpoints</do>
+  <do>Wrap the app (or subtree) in `BreakpointsProvider`; call `useBreakpoints` inside to swap/hide React trees or change Vira props by viewport</do>
+  <do>Compose mobile-first: narrow Stack/Surface/Grid layout as the base; enhance when a min-width flag becomes true</do>
   <do>Read one flag with `useBreakpoints(&apos;small&apos;)` so unrelated breakpoint flips skip work</do>
-  <do>Override the full map with the `breakpoints` prop for product-specific thresholds</do>
+  <do>For layout that follows a Stack&apos;s own inline-size, use Stack `enableContainer` + `@container stack` — not this viewport hook</do>
+  <do>For CSS-only style changes, write `@media (min-width: …)` using the same em lengths as this provider map</do>
+  <do>Override the full map with the `breakpoints` prop for product-specific thresholds (replaces defaults entirely)</do>
   <dont>Using `useBreakpoints` without wrapping the tree in `BreakpointsProvider`</dont>
+  <dont>Using this hook for container-sized layout — that is Stack/Surface `@container`, not viewport matches</dont>
   <dont>Merging a sparse custom map onto defaults — the `breakpoints` prop replaces the whole map</dont>
   <dont>Putting the provider in a Server Component module — wrap it in a Client Component (`&apos;use client&apos;`)</dont>
+  <dont>Inventing parallel px breakpoints (`768px`, `1024px`) or ad-hoc `matchMedia` beside this map</dont>
+  <dont>Desktop-first `max-width` media as the primary responsive strategy</dont>
+  <dont>Reading theme design-token widths as breakpoint thresholds</dont>
+  <dont>Branching React markup with CSS `@media` alone when props or tree structure must change — use the hook</dont>
 </usage>

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

@@ -1,11 +1,129 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="button">
-  <example title="Button structure">
-    <tsx><![CDATA[<Button>Save</Button>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no app-only chrome, no CSS that reinvents Stack props). -->
+
+  <example title="Hub nav (ButtonLink)">
+    <tsx><![CDATA[
+<Stack render={<nav />} direction="row" vAlign="center" columnGap="xs">
+  <ButtonLink size="s" variant="secondary" href="/hub">
+    Hub
+  </ButtonLink>
+  <ButtonLink size="s" variant="flat" href="/studio">
+    Studio
+  </ButtonLink>
+  <ButtonLink size="s" variant="flat" href="/prompts">
+    Prompts
+  </ButtonLink>
+</Stack>
+]]></tsx>
+    <notes>From `common/hub-header/hub-nav`. Active route uses `variant="secondary"`; others `flat`. App wraps Next `Link` via `render` — plain `href` fine for this hint.</notes>
   </example>
-  <example title="ButtonLink structure">
-    <tsx><![CDATA[<ButtonLink href="#">Save</ButtonLink>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+
+  <example title="Login form CTA + ButtonLink">
+    <tsx><![CDATA[
+<form>
+  <Stack direction="row" columnGap="m" rowGap="m" hAlign="start" vAlign="start" wrap>
+    <Textfield type="email" placeholder="your@email.com" size={30} aria-label="Email" />
+    <Stack direction="row" vAlign="center" columnGap="m">
+      <Button type="submit">Send magic link</Button>
+      or
+      <ButtonLink variant="secondary" href="#">
+        Get ViraUI Pro
+      </ButtonLink>
+    </Stack>
+  </Stack>
+</form>
+]]></tsx>
+    <notes>From `auth/login-form`. Submit `Button` beside secondary `ButtonLink`. Drop Beam / RHF / loading chrome from this hint.</notes>
+  </example>
+
+  <example title="Sign out (loading)">
+    <tsx><![CDATA[
+<Button type="button" variant="secondary" loading>
+  Sign out
+</Button>
+]]></tsx>
+    <notes>From `auth/sign-out-button`. `loading` keeps width while async work runs. No handler in the pattern.</notes>
+  </example>
+
+  <example title="Dialog action strip (export)">
+    <tsx><![CDATA[
+<Stack direction="row" hAlign="center" columnGap="m">
+  <Button size="l" addon={<FileDownload />}>
+    Download
+  </Button>
+  <ButtonLink size="l" variant="secondary" href="#" addon={<ShareUpRight />}>
+    Share
+  </ButtonLink>
+  <Button size="l" variant="secondary" addon={<Code2 />}>
+    View code
+  </Button>
+</Stack>
+]]></tsx>
+    <notes>From `editor/export-dialog`. Centered equal-feeling action row — Button + ButtonLink + Button. Gap via Stack, not per-button width CSS.</notes>
+  </example>
+
+  <example title="Dialog form actions (import)">
+    <tsx><![CDATA[
+<Dialog.Sheet title="Import preset" description="Paste preset code." showCloseButton headerAlign="center">
+  <Stack rowGap="m" hAlign="center" hPadding="m" vPadding={['s', 0]}>
+    <Textfield size={40} placeholder="Paste preset…" aria-label="Preset code" />
+    <Stack direction="row" hAlign="end" columnGap="s">
+      <Button>Apply</Button>
+      <Dialog.Close render={<Button variant="secondary">Cancel</Button>} />
+    </Stack>
+  </Stack>
+</Dialog.Sheet>
+]]></tsx>
+    <notes>From `editor/import-preset-dialog`. Trailing action row; Cancel via `Dialog.Close render={&lt;Button /&gt;}`. Trigger elsewhere uses `addon` + secondary.</notes>
+  </example>
+
+  <example title="Flat addon links (clone)">
+    <tsx><![CDATA[
+<Stack hAlign="start" rowGap="2xs">
+  <Button addon={<CircleImage size={18} />} variant="flat" size="s">
+    Open with GitHub Desktop
+  </Button>
+  <Button addon={<ArrowDown size={18} />} variant="flat" size="s">
+    Download ZIP
+  </Button>
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/clone-repository`. Leading `addon` + flat small buttons stacked with Stack gap.</notes>
+  </example>
+
+  <example title="Full-width primary CTA">
+    <tsx><![CDATA[
+<Surface color={2} hPadding="l" vPadding="m" radius="auto">
+  <Stack rowGap="m" expandChildren>
+    <Button>Review Order</Button>
+    <Text align="center" tone="muted" size="s">
+      Trades are typically executed within minutes during market hours.
+    </Text>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/buy-investment`. `expandChildren` stretches Button — never `width: 100%` / `w-full` on the button.</notes>
+  </example>
+
+  <example title="Footer secondary + primary">
+    <tsx><![CDATA[
+<Surface color={2} hPadding="l" vPadding="m">
+  <Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
+    <Button variant="secondary">Reset</Button>
+    <Button>Save Preferences</Button>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/preferences` footer. Opposite ends via `space-between`.</notes>
+  </example>
+
+  <example title="Chip addon (inverted on primary)">
+    <tsx><![CDATA[
+<Button variant="primary" addon={<Chip data-mode="inverted">New</Chip>} addonPosition="end" pill>
+  Notifications
+</Button>
+]]></tsx>
+    <notes>From button stories + `props.xml` / `usage.xml`. Primary Chip on primary Button needs `data-mode="inverted"` so chip fill contrasts the button.</notes>
   </example>
 </patterns>

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

@@ -10,6 +10,7 @@
   <when_not_to_use>
     <item>Icon-only actions without a visible label — use IconButton</item>
     <item>Navigation or non-button semantics — use ButtonLink</item>
+    <item>Forcing full panel width with CSS `width: 100%` / `w-full` — wrap in Stack with `fullWidth` and/or `expandChildren` (see stack units)</item>
   </when_not_to_use>
   <prop name="addon" kind="react">
     <description>Decorative addon rendered alongside the button label. Pass any React element; use a named icon from `@viraui/icons/react` or `&lt;Chip /&gt;` for status chips.</description>
@@ -50,52 +51,52 @@
   <prop name="variant" kind="react">
     <description>Selects the visual treatment matching Button. (button-link)</description>
   </prop>
-  <css_var suffix="background">
+  <prop name="background" kind="css">
     <description>Button fill; variant and state selectors preset this.</description>
-  </css_var>
-  <css_var suffix="color">
+  </prop>
+  <prop name="color" kind="css">
     <description>Button label and icon color.</description>
-  </css_var>
-  <css_var suffix="height">
+  </prop>
+  <prop name="height" kind="css">
     <description>Button block size; size prop presets via data attributes.</description>
-  </css_var>
-  <css_var suffix="icon-size">
+  </prop>
+  <prop name="icon-size" kind="css">
     <description>Addon icon size inside the button.</description>
-  </css_var>
-  <css_var suffix="padding-block">
+  </prop>
+  <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button.</description>
-  </css_var>
-  <css_var suffix="padding-inline">
+  </prop>
+  <prop name="padding-inline" kind="css">
     <description>Horizontal padding inside the button.</description>
-  </css_var>
-  <css_var suffix="radius">
+  </prop>
+  <prop name="radius" kind="css">
     <description>Corner radius; pill sets full radius via data-pill.</description>
-  </css_var>
-  <css_var suffix="spinner-color">
+  </prop>
+  <prop name="spinner-color" kind="css">
     <description>Loading spinner color on the root.</description>
-  </css_var>
-  <css_var suffix="background">
+  </prop>
+  <prop name="background" kind="css">
     <description>Button fill; variant and state selectors preset this. (button-link)</description>
-  </css_var>
-  <css_var suffix="color">
+  </prop>
+  <prop name="color" kind="css">
     <description>Button label and icon color. (button-link)</description>
-  </css_var>
-  <css_var suffix="height">
+  </prop>
+  <prop name="height" kind="css">
     <description>Button block size; size prop presets via data attributes. (button-link)</description>
-  </css_var>
-  <css_var suffix="icon-size">
+  </prop>
+  <prop name="icon-size" kind="css">
     <description>Addon icon size inside the button. (button-link)</description>
-  </css_var>
-  <css_var suffix="padding-block">
+  </prop>
+  <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button. (button-link)</description>
-  </css_var>
-  <css_var suffix="padding-inline">
+  </prop>
+  <prop name="padding-inline" kind="css">
     <description>Horizontal padding inside the button. (button-link)</description>
-  </css_var>
-  <css_var suffix="radius">
+  </prop>
+  <prop name="radius" kind="css">
     <description>Corner radius; pill sets full radius via data-pill. (button-link)</description>
-  </css_var>
-  <css_var suffix="spinner-color">
+  </prop>
+  <prop name="spinner-color" kind="css">
     <description>Loading spinner color on the root. (button-link)</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,18 +1,18 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="button">
-  <do>Labeled actions with text and optional leading or trailing addon</do>
-  <do>Primary, secondary, flat, or destructive visual treatments</do>
-  <do>Capsule-shaped actions via pill when a fully rounded button fits the layout</do>
-  <do>Async actions that need a stable width while loading</do>
-  <do>Primary Chip addons inside a primary Button — set data-mode=&quot;inverted&quot; on the Chip so its background contrasts the button fill</do>
-  <do>Actions that navigate (href or router Link) but should look like Button</do>
-  <do>Same size, variant, addon, pill, and loading chrome as Button without button semantics</do>
-  <do>Compose with Next.js Link or React Router Link via the render prop</do>
+  <do>Labeled actions with text and optional leading or trailing `addon`</do>
+  <do>Primary, secondary, flat, or destructive treatments; use `pill` for capsule shape</do>
+  <do>Async actions that need stable width while `loading`</do>
+  <do>Login / signup / form submit rows: Stack + Textfield(s) (+ optional Tabs / Fieldset) + submit Button — gap and align via Stack, no custom CSS</do>
+  <do>Full-bleed or equal-width Buttons: wrap in Stack with `fullWidth` and/or `expandChildren` — never per-Button width CSS</do>
+  <do>Dialog / sheet action strips: Stack row of Button + ButtonLink; Cancel via `Dialog.Close render={&lt;Button variant=&quot;secondary&quot; /&gt;}`</do>
+  <do>Primary Chip addons inside a primary Button — set `data-mode=&quot;inverted&quot;` on the Chip so its fill contrasts</do>
+  <do>Navigation that should look like Button — use ButtonLink (framework Link via `render`)</do>
   <dont>Using Button without children as icon-only — prefer IconButton</dont>
-  <dont>Using Button with render={&lt;a /&gt;} for links — Base UI enforces button semantics; use ButtonLink</dont>
+  <dont>Using Button with `render={&lt;a /&gt;}` for links — Base UI enforces button semantics; use ButtonLink</dont>
+  <dont>Inventing `width: 100%` / `w-full` / `.fullWidth` / `flex: 1` CSS on Button when a parent Stack can own the fill</dont>
   <dont>Duplicating icon size on every addon slot — Button CSS sizes SVG descendants</dont>
-  <dont>Mixing pill with custom border-radius overrides that fight data-pill styling</dont>
-  <dont>Primary Chip addon inside a primary Button without data-mode=&quot;inverted&quot; — chip background matches the button fill and disappears</dont>
-  <dont>Using Button with render={&lt;a /&gt;} instead of ButtonLink</dont>
-  <dont>Forcing role=button on a link</dont>
+  <dont>Mixing `pill` with custom border-radius overrides that fight `data-pill` styling</dont>
+  <dont>Primary Chip addon inside a primary Button without `data-mode=&quot;inverted&quot;` — chip fill matches the button and disappears</dont>
+  <dont>Forcing `role=&quot;button&quot;` on a link</dont>
 </usage>