@viraui/react 2026.5.0 → 2026.6.1

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

@@ -1,8 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="slider">
-  <do>Numeric value selection on a horizontal or vertical axis</do>
-  <do>Range selection with two thumbs</do>
-  <do>Field label, description, and error copy like Textfield</do>
-  <dont>Wrapping Slider.Control and Slider.Value in extra layout inside Slider.Root</dont>
-  <dont>Overriding Slider.Indicator position in CSS</dont>
+  <do>Numeric single-thumb or two-thumb range selection — public `Slider` wraps Field.Root; pass `label` / `description` / `error` like Textfield</do>
+  <do>Show the live value with `renderValue` (`true` for default Text formatting, or a function that owns the value slot)</do>
+  <do>Min/max captions under a labeled Slider — sibling Text in a Stack row (`hAlign=&quot;space-between&quot;`); do not invent track length CSS</do>
+  <do>External label beside the track — Stack `direction=&quot;row&quot;` `expandChildren` + labeled Text + Slider with `aria-label` / `thumbAriaLabel`</do>
+  <do>Bracketed continuum — Text endcaps with `data-shrink={false}` and Slider filling the middle via parent Stack</do>
+  <do>Vertical bands — `orientation=&quot;vertical&quot;` inside a sized Stack host (`blockSize` / flex grow); band name as sibling Text</do>
+  <dont>Fixed pixel track lengths — Slider fills its container; grow via Stack `expandChildren` or a sized host</dont>
+  <dont>Custom size or variant props — single medium treatment</dont>
+  <dont>Leaving thumbs unnamed when `label` is omitted — pass `thumbAriaLabel` (and usually `aria-label`)</dont>
+  <dont>Overriding Slider Indicator position in CSS</dont>
+  <dont>Reassembling internal Control/Value parts — use the public `Slider` export only</dont>
 </usage>

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

@@ -1,7 +1,39 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="spinner">
-  <example title="Spinner structure">
-    <tsx><![CDATA[<Spinner aria-hidden />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components + preview-grid — cleaned (no handlers, no app-only chrome). -->
+
+  <example title="Inline search status (autocomplete)">
+    <tsx><![CDATA[
+<Stack columnGap="s" direction="row" vAlign="center">
+  <Spinner aria-hidden size="s" />
+  <Text size="xs" tone="muted">
+    Searching help center…
+  </Text>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `autocomplete-search` help-field `status`. Spinner is decorative (`aria-hidden`); visible text (or parent Autocomplete status) announces progress.</notes>
+  </example>
+
+  <example title="Chip end addon (deploying)">
+    <tsx><![CDATA[
+<Chip addon={<Spinner size="s" />} addonPosition="end" variant="blue">
+  Deploying
+</Chip>
+]]></tsx>
+    <notes>From preview-grid `environment-variables` deploy statuses. Small Spinner as Chip addon; Chip label carries the accessible name.</notes>
+  </example>
+
+  <example title="Footer status with Shimmer copy">
+    <tsx><![CDATA[
+<Surface color={2} hPadding="l" vPadding="m">
+  <Stack direction="row" vAlign="center" hAlign="start" columnGap="s">
+    <Spinner variant="dot-grid" size="s" aria-hidden />
+    <Text tone="muted" size="s">
+      <Shimmer>You have not met your targets yet.</Shimmer>
+    </Text>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From preview-grid `savings-targets` footer. Pair `variant="dot-grid"` with muted Shimmer text. Region/parent owns busy semantics — not the Spinner.</notes>
   </example>
 </patterns>

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

@@ -18,7 +18,7 @@
   <prop name="variant" kind="react">
     <description>Visual animation style.</description>
   </prop>
-  <css_var suffix="size">
+  <prop name="size" kind="css">
     <description>Spinner glyph size on the root.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="spinner">
-  <do>Inline loading overlay inside Button or IconButton</do>
-  <do>Decorative in-progress indicator explicitly hidden from assistive technology</do>
-  <do>Loading feedback where the parent exposes the accessible status</do>
-  <dont>Using Spinner alone as the only loading announcement for a page</dont>
-  <dont>Embedding animation rules outside the component stylesheet</dont>
+  <do>Button / IconButton async chrome: set `loading` on the control — it owns the Spinner overlay, width lock, and `aria-busy`</do>
+  <do>Standalone status: Stack row with Spinner `aria-hidden` + visible Text (or Autocomplete status) that names the work</do>
+  <do>Chip in-progress affordance: small Spinner as Chip `addon` (`addonPosition=&quot;end&quot;`) — Chip label stays the accessible name</do>
+  <do>Pair `variant=&quot;dot-grid&quot;` or `bars` / `dots` with muted Text / Shimmer in Surface footers when the parent region owns busy semantics</do>
+  <dont>Nesting a manual Spinner inside Button / IconButton when `loading` already injects one</dont>
+  <dont>Using Spinner alone as the only page-level loading announcement</dont>
+  <dont>Omitting `aria-hidden` on decorative standalone Spinners — the component does not hide itself</dont>
+  <dont>Expecting Spinner to expose accessible status without parent `aria-busy` or visible status text</dont>
 </usage>

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

@@ -1,7 +1,363 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="stack">
-  <example title="Stack structure">
-    <tsx><![CDATA[<Stack>…</Stack>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no app-only chrome, no CSS that reinvents Stack props). -->
+
+  <example title="App header (hub)">
+    <tsx><![CDATA[
+<Stack
+  render={<header />}
+  direction="row"
+  vAlign="center"
+  hAlign="space-between"
+  hPadding="m"
+  vPadding="m"
+  columnGap="s"
+>
+  <Stack direction="row" vAlign="center" columnGap="s">
+    {/* brand / logo */}
+  </Stack>
+
+  <Surface hPadding="xs" vPadding="xs" radius="m" border="all" data-vibrant>
+    <Surface radius="auto" color={1} hPadding="xs" vPadding="xs">
+      <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>
+    </Surface>
+  </Surface>
+
+  <Stack direction="row" vAlign="center" columnGap="s">
+    <Button size="s" variant="secondary">
+      Sign out
+    </Button>
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>From `common/hub-header` (+ `hub-nav`). Row `space-between` + nested row clusters. Nav lives in Surface chrome; Stack owns flex/gap. No custom CSS.</notes>
+  </example>
+
+  <example title="Inline form row (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
+      <ButtonLink variant="secondary" href="#">
+        Get ViraUI Pro
+      </ButtonLink>
+    </Stack>
+  </Stack>
+</form>
+]]></tsx>
+    <notes>From `auth/login-form`. Wrap row for field + CTA cluster. Pure Stack props — no module CSS.</notes>
+  </example>
+
+  <example title="Auth panel copy + form slot">
+    <tsx><![CDATA[
+<Stack
+  render={<section />}
+  hPadding="2xl"
+  vPadding="l"
+  hAlign="start"
+  expandChildren
+>
+  {/* brand */}
+  <Stack rowGap="xl" vAlign="center">
+    <Stack vPadding={[0, 'l']} rowGap="xl">
+      <Title size="1" render={<h1 />} maxWidth="32rem" lineHeight="s">
+        Design systems that ship
+      </Title>
+      <Text size="2xl" tone="muted" maxWidth="32rem">
+        Sign in to continue to the studio.
+      </Text>
+    </Stack>
+    {/* form */}
+  </Stack>
+  {/* footer chrome */}
+</Stack>
+]]></tsx>
+    <notes>From `auth/login-view` panel Stack. Layout/spacing via props; app keeps `min-block-size` / scroll on a module class — not flex/gap. Drop viewport grid shell from this hint.</notes>
+  </example>
+
+  <example title="Document shell (header + grow body)">
+    <tsx><![CDATA[
+<Stack>
+  <Stack>
+    {/* header */}
+    <Separator variant="dashed" size="m" />
+  </Stack>
+  <Stack data-grow="true" expandChildren>
+    {/* page content */}
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>From `layout/document-shell`. `expandChildren` + `data-grow` grow the body. Sticky / `100dvh` stay in CSS if needed — never reinvent flex or gap there.</notes>
+  </example>
+
+  <example title="Sidebar section">
+    <tsx><![CDATA[
+<Stack hPadding="m">
+  <Surface color={2} hoverColor={3} radius="m" vPadding="s">
+    <Stack rowGap="s" hPadding="m" vPadding={[0, 's']}>
+      <Stack direction="row" vAlign="center" hAlign="space-between" columnGap="s">
+        <Stack direction="row" vAlign="center" columnGap="s">
+          {/* section icon */}
+          <Text size="xs" weight="semibold">
+            Colors
+          </Text>
+        </Stack>
+        {/* trailing addon */}
+      </Stack>
+      <Text tone="muted" size="s">
+        Brand seed and highlight scales.
+      </Text>
+    </Stack>
+    <Stack rowGap="m" hPadding="s" vPadding="xs">
+      {/* controls */}
+    </Stack>
+  </Surface>
+</Stack>
+]]></tsx>
+    <notes>From `editor/sidebar/sidebar-section`. Header row + muted description + body stack. Optional `min-block-size` on header only — not gap/padding CSS.</notes>
+  </example>
+
+  <example title="Dialog form (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`. Centered column + trailing action row. No CSS.</notes>
+  </example>
+
+  <example title="Dialog action strip (export)">
+    <tsx><![CDATA[
+<Stack rowGap="m" hPadding="m" vPadding={['s', 0]}>
+  <Stack direction="row" hAlign="center" columnGap="m">
+    <Button size="l">Download</Button>
+    <ButtonLink size="l" variant="secondary" href="#">
+      Share
+    </ButtonLink>
+    <Button size="l" variant="secondary">
+      View code
+    </Button>
+  </Stack>
+  {/* optional preview / tabs below */}
+</Stack>
+]]></tsx>
+    <notes>From `editor/export-dialog` body. Centered equal-feeling action row via Stack alignment + gap — not per-button width CSS.</notes>
+  </example>
+
+  <example title="Toolbar chip (canvas zoom)">
+    <tsx><![CDATA[
+<Surface color={1} border="all" radius="m" vPadding="2xs" hPadding="2xs">
+  <Stack direction="row" vAlign="center">
+    <IconButton aria-label="Zoom out" icon={<Minus />} variant="flat" />
+    <IconButton aria-label="Reset zoom" icon={<FocusCenter />} variant="flat" />
+    <IconButton aria-label="Zoom in" icon={<Plus />} variant="flat" />
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/canvas/canvas-zoom`. Dense IconButton row inside Surface. Absolute overlay position is shell CSS — Stack only owns the row.</notes>
+  </example>
+
+  <example title="Empty / info state">
+    <tsx><![CDATA[
+<Stack hAlign="center" vAlign="center" rowGap="l" render={<div role="status" />}>
+  <Surface color={1} border="all" hPadding="m" vPadding="m" radius="full">
+    {/* icon */}
+  </Surface>
+  <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. Centered column + capped text stack. Drop decorative backdrop Grid/absolute CSS from this hint — that is shell, not Stack layout.</notes>
+  </example>
+
+  <example title="Empty team card">
+    <tsx><![CDATA[
+<Surface border="all" color={1} radius="l" hPadding="m" vPadding="m">
+  <Stack
+    rowGap="m"
+    hPadding="l"
+    vPadding="2xl"
+    hAlign="center"
+    render={<Surface border="all" borderStyle="dashed" radius="l" />}
+  >
+    <AvatarGroup
+      avatars={[
+        { alt: '', fallback: 'AL' },
+        { alt: '', fallback: 'MR' },
+        { alt: '', fallback: 'EV' },
+      ]}
+      size="m"
+    />
+    <Title align="center" size="5" render={<h3 />}>
+      No Team Members
+    </Title>
+    <Text size="s" align="center" maxWidth="14rem" tone="muted">
+      Invite your team to collaborate on this project.
+    </Text>
+    <Button>Invite Members</Button>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/empty-team`. Replaced inline dashed `style` with `Stack render={&lt;Surface borderStyle="dashed" …/&gt;}`. Drop Annotate/Badge kitchen chrome.</notes>
+  </example>
+
+  <example title="Preferences panel">
+    <tsx><![CDATA[
+<Surface overflow="hidden" border="all" color={1} radius="l">
+  <Stack rowGap="m">
+    <Stack rowGap="m" hPadding="m" vPadding="m">
+      <Stack columnGap="s" direction="row" hAlign="space-between" vAlign="start">
+        <Stack rowGap="xs">
+          <Title size="6" render={<h2 />}>
+            Preferences
+          </Title>
+          <Text size="s" maxWidth="18rem" tone="muted">
+            Manage your account settings and notifications.
+          </Text>
+        </Stack>
+        <IconButton aria-label="Close" icon={<Xmark />} size="s" variant="secondary" />
+      </Stack>
+
+      <Select label="Default Currency" value="usd">
+        <Select.Option value="usd">United States Dollar</Select.Option>
+        <Select.Option value="eur">Euro</Select.Option>
+      </Select>
+
+      <Surface vPadding="m">
+        <Switch label="Public Statistics" description="Allow others to see activity" />
+      </Surface>
+      <Surface vPadding="m">
+        <Switch label="Email Notifications" description="Monthly reports and updates" />
+      </Surface>
+    </Stack>
+
+    <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>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/preferences`. Header row + stacked controls + footer action row. Prefer Surface `overflow` prop over inline `style`.</notes>
+  </example>
+
+  <example title="Form panel (payout threshold)">
+    <tsx><![CDATA[
+<Surface border="all" color={1} radius="l" hPadding="s" vPadding="s">
+  <Stack rowGap="l" hPadding="s" vPadding="s">
+    <Stack rowGap="xs">
+      <Title size="6" render={<h2 />}>
+        Payout Threshold
+      </Title>
+      <Text tone="muted" size="s">
+        Set the minimum balance required before a payout is triggered.
+      </Text>
+    </Stack>
+
+    <Select label="Preferred Currency" value="usd">
+      <Select.Option value="usd">United States Dollar</Select.Option>
+      <Select.Option value="eur">Euro</Select.Option>
+    </Select>
+
+    <Stack rowGap="m">
+      <Slider label="Minimum Payout Amount" min={50} max={10000} step={50} value={2500} />
+      <Stack columnGap="s" direction="row" hAlign="space-between" vAlign="center">
+        <Text family="mono" size="xs" tone="muted">
+          $50 (MIN)
+        </Text>
+        <Text family="mono" size="xs" tone="muted">
+          $10,000 (MAX)
+        </Text>
+      </Stack>
+    </Stack>
+
+    <Textarea label="Notes" rows={4} resize="vertical" fitContent />
+    <Button variant="secondary">Save Threshold</Button>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/payout-threshold`. Nested Stacks for section gaps + min/max caption row. No custom layout CSS.</notes>
+  </example>
+
+  <example title="Directory list row">
+    <tsx><![CDATA[
+<Surface color={2} radius="m" hPadding="m" vPadding="m">
+  <Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
+    <Stack columnGap="m" direction="row" vAlign="center">
+      <Avatar alt="Sarah Chen" fallback="SC" size="s" />
+      <Stack rowGap="xs">
+        <Text weight="semibold">Sarah Chen</Text>
+        <Text size="s" tone="muted">
+          Product Design
+        </Text>
+      </Stack>
+    </Stack>
+    <Button size="s" variant="secondary">
+      Details
+    </Button>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/team-directory` row. Leading media + text column + trailing action — all Stack spacing/align.</notes>
+  </example>
+
+  <example title="Equal-width field pair (shipping)">
+    <tsx><![CDATA[
+<Stack rowGap="l" hPadding="m" vPadding="m">
+  <Stack rowGap="xs">
+    <Title size="6" render={<h2 />}>
+      Shipping Address
+    </Title>
+    <Text size="s" tone="muted">
+      Where should we deliver?
+    </Text>
+  </Stack>
+
+  <Textfield label="Street address" required />
+  <Textfield label="Apt / Suite" />
+
+  <Stack columnGap="m" direction="row" expandChildren>
+    <Textfield label="City" />
+    <Select label="State" value="california">
+      <Select.Option value="california">California</Select.Option>
+    </Select>
+  </Stack>
+
+  <Stack columnGap="m" direction="row" expandChildren>
+    <Textfield label="ZIP Code" />
+    <Select label="Country" value="united-states">
+      <Select.Option value="united-states">United States</Select.Option>
+    </Select>
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/shipping-address`. `expandChildren` on row Stacks shares width across field pairs — do not invent per-field `flex`/`width` CSS.</notes>
   </example>
 </patterns>

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

@@ -6,11 +6,13 @@
     <item>Custom native root through render while keeping data-stack hooks</item>
     <item>Style descendants with `@container stack` queries when layout, gap, or typography should respond to the Stack&apos;s own inline-size instead of the viewport (set `enableContainer` on the Stack you&apos;re querying)</item>
     <item>Centered max-width shells: parent `hAlign=&quot;center&quot;` + child `fullWidth` + `maxWidth`</item>
+    <item>Full-bleed or equal-width action clusters (Buttons, etc.): `fullWidth` and/or `expandChildren` instead of per-child width CSS</item>
   </when_to_use>
   <when_not_to_use>
     <item>Cases where a single component already owns required flex chrome</item>
     <item>Expecting direct children to grow on the main axis without setting `expandChildren`</item>
     <item>Expecting this stack to fill parent inline size under non-stretch alignment without `fullWidth` (or an explicit `inlineSize`)</item>
+    <item>Inventing `width: 100%` / `w-full` on content-sized children (Button, Chip, …) when this Stack can own fill via `fullWidth` / `expandChildren`</item>
     <item>Using `enableContainer` inside complex masonry-like layouts when you don&apos;t need container queries (inline-size containment can change nested layout)</item>
   </when_not_to_use>
   <prop name="columnGap" kind="react">
@@ -23,10 +25,10 @@
     <description>Renders children across rows or columns using the chosen flex direction.</description>
   </prop>
   <prop name="expandChildren" kind="react">
-    <description>Makes direct children grow along the flex main axis (`flex-grow`). Default `false`. Orthogonal to `fullWidth` (children grow vs this root&apos;s inline size). A child opts out with its own `data-grow=&quot;false&quot;`; ancestor `data-grow` does not inherit into nested stacks.</description>
+    <description>Makes direct children grow along the flex main axis (`flex-grow`). Default `false`. Use for equal-width row actions (Buttons, etc.) instead of inventing `width`/`flex` CSS on each child. Orthogonal to `fullWidth` (children grow vs this root&apos;s inline size). A child opts out with its own `data-grow=&quot;false&quot;`; ancestor `data-grow` does not inherit into nested stacks.</description>
   </prop>
   <prop name="fullWidth" kind="react">
-    <description>Sets `inline-size: 100%` on the stack root so it fills the parent&apos;s inline size. Default `false`. Use with `maxWidth` under a parent `hAlign=&quot;center&quot;` for a fluid capped centered shell. Does not grow children — use `expandChildren` for that.</description>
+    <description>Sets `inline-size: 100%` on the stack root so it fills the parent&apos;s inline size. Default `false`. Prefer this (plus cross-axis stretch) so content-sized children like Button span a panel — do not add `width: 100%` CSS on those children. Use with `maxWidth` under a parent `hAlign=&quot;center&quot;` for a fluid capped centered shell. Does not grow children — use `expandChildren` for that.</description>
   </prop>
   <prop name="hAlign" kind="react">
     <description>Aligns content on the horizontal axis from the consumer point of view.</description>
@@ -61,34 +63,34 @@
   <prop name="wrap" kind="react">
     <description>Allows direct children to wrap onto additional lines when space is constrained.</description>
   </prop>
-  <css_var suffix="column-gap">
+  <prop name="column-gap" kind="css">
     <description>Flex column gap on the root.</description>
-  </css_var>
-  <css_var suffix="h-align">
+  </prop>
+  <prop name="h-align" kind="css">
     <description>Logical horizontal flex alignment hook.</description>
-  </css_var>
-  <css_var suffix="max-width">
+  </prop>
+  <prop name="max-width" kind="css">
     <description>Max inline size of the stack root.</description>
-  </css_var>
-  <css_var suffix="min-width">
+  </prop>
+  <prop name="min-width" kind="css">
     <description>Min inline size of the stack root.</description>
-  </css_var>
-  <css_var suffix="padding-block-end">
+  </prop>
+  <prop name="padding-block-end" kind="css">
     <description>Block-end padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-block-start">
+  </prop>
+  <prop name="padding-block-start" kind="css">
     <description>Block-start padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-inline-end">
+  </prop>
+  <prop name="padding-inline-end" kind="css">
     <description>Inline-end padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-inline-start">
+  </prop>
+  <prop name="padding-inline-start" kind="css">
     <description>Inline-start padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="row-gap">
+  </prop>
+  <prop name="row-gap" kind="css">
     <description>Flex row gap on the root.</description>
-  </css_var>
-  <css_var suffix="v-align">
+  </prop>
+  <prop name="v-align" kind="css">
     <description>Logical vertical flex alignment hook.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,14 +1,20 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="stack">
-  <do>Column or row layouts with token gap and alignment</do>
-  <do>Composing screens and component internals without custom flex CSS</do>
-  <do>Custom native root through render while keeping data-stack hooks</do>
-  <do>Style descendants with `@container stack` queries when layout, gap, or typography should respond to the Stack&apos;s own inline-size instead of the viewport (set `enableContainer` on the Stack you&apos;re querying)</do>
-  <do>Centered max-width shells: parent `hAlign=&quot;center&quot;` + child `fullWidth` + `maxWidth`</do>
-  <dont>Assuming Stack expands direct children by default — pass `expandChildren` when children should grow along the flex main axis</dont>
-  <dont>Using `expandChildren` to fill parent width under `hAlign=&quot;center&quot;` — that is `fullWidth` on the child stack (self `inline-size`), not child flex-grow</dont>
-  <dont>Putting `data-grow=&quot;false&quot;` on an ancestor to control nested expandChildren — set it on the child that should not grow</dont>
-  <dont>Re-declaring primitive flex container rules in app CSS when Stack can own the layout</dont>
-  <dont>Using viewport media queries when @container stack queries against the rendered Stack inline-size would match the design intent</dont>
+  <do>Default structural box instead of a bare wrapper `div` — Stack owns flex + token gap/padding/align/`fullWidth`/`render`</do>
+  <do>Login/signup (or similar auth swap): host Tabs + Textfield(s) + Button (+ optional Fieldset) inside a Stack or `Stack render={&lt;Surface … /&gt;}` shell — props only, 0 custom CSS</do>
+  <do>Flex + Surface chrome on one node via `render={&lt;Surface … /&gt;}` — prefer over a CSS border class or an extra wrapper (see package pattern `stack-as-surface`)</do>
+  <do>Equal-width action or field clusters (Button, Chip, Textfield): `fullWidth` and/or `expandChildren` on this Stack — never per-child width CSS</do>
+  <do>Settings rows: Stack `direction=&quot;row&quot;` + Text (label/description column) + Switch or Checkbox — nest in Surface for panel chrome</do>
+  <do>Centered capped shells: parent `hAlign=&quot;center&quot;` + child Stack `fullWidth` + `maxWidth`</do>
+  <do>Semantic/native roots via `render` (`header`, `main`, `nav`, `section`, …) while keeping Stack as the layout engine</do>
+  <do>Opt into `@container stack` with `enableContainer` when layout should follow this Stack&apos;s inline-size, not the viewport</do>
+  <dont>Reaching for a plain wrapper `div` when Stack (optionally with `render` for a semantic tag) can own the box</dont>
+  <dont>Assuming Stack expands direct children by default — pass `expandChildren` when children should grow on the flex main axis</dont>
+  <dont>Using `expandChildren` to fill parent width under `hAlign=&quot;center&quot;` — that is `fullWidth` on the child Stack (self `inline-size`), not child flex-grow</dont>
+  <dont>Inventing `width: 100%` / `w-full` / `.fullWidth` CSS on content-sized children when this Stack can own the fill</dont>
+  <dont>Inventing CSS `gap` / `padding` on this root when public spacing props cover it</dont>
+  <dont>Putting `data-grow=&quot;false&quot;` on an ancestor to control nested `expandChildren` — set it on the child that should not grow</dont>
   <dont>Combining `fullWidth` with `inline` — prefer block flex when the root must fill parent inline size</dont>
+  <dont>Using viewport media queries when `@container stack` against this Stack&apos;s inline-size matches the design intent</dont>
+  <dont>Wrapping Fieldset.Root in Stack `render` — breaks Base UI render merge with RadioGroup / CheckboxGroup</dont>
 </usage>

package/dist/specs/components/static-noise/meta.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="static-noise" title="StaticNoise" category="effect" shared_contract="static-noise">
-  <summary>Decorative SVG turbulence noise overlay for textured surfaces and hero sections. Memory-heavy — use sparingly (rarely).</summary>
+  <summary>Decorative SVG turbulence noise overlay for textured surfaces and hero sections. Memory-heavy — use sparingly; prefer one focal instance per view.</summary>
   <exports>
     <export name="StaticNoise" />
   </exports>

package/dist/specs/components/static-noise/patterns.xml

@@ -1,7 +1,24 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="static-noise">
-  <example title="StaticNoise structure">
-    <tsx><![CDATA[<StaticNoise />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: packages/react/src/components/static-noise/static-noise.stories.tsx — cleaned (no gradient demo frame). -->
+
+  <example title="Grain on vibrant Surface">
+    <tsx><![CDATA[
+<Surface
+  border="all"
+  radius="xl"
+  data-vibrant
+  style={{ position: 'relative', inlineSize: 'min(22rem, 100%)' }}
+>
+  <Stack expandChildren hPadding="l" vPadding="l" rowGap="m">
+    <Title size="2" render={<h3 />}>
+      Atmospheric card
+    </Title>
+    <Text>Static noise adds subtle grain without affecting layout semantics.</Text>
+  </Stack>
+  <StaticNoise style={{ position: 'absolute', inset: 0, zIndex: 10 }} />
+</Surface>
+]]></tsx>
+    <notes>From `SurfaceOverlay`. Parent owns positioning (`relative` + absolute overlay). `StaticNoise` is decorative (`aria-hidden`); keep instances few.</notes>
   </example>
 </patterns>

package/dist/specs/components/static-noise/usage.xml

@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="static-noise">
-  <do>Subtle grain or texture overlay on cards, panels, or hero sections</do>
-  <do>Glass or vibrant surfaces that need visual depth without extra content</do>
-  <do>Decorative atmosphere where the parent owns semantics and layout positioning</do>
-  <dont>Treating StaticNoise as cheap wallpaper — it is memory-heavy; prefer few instances</dont>
+  <do>Absolute overlay on a Surface (often `data-vibrant`) whose parent owns `position: relative` / inset / z-index — nest Title/Text in a Stack underneath for real content</do>
+  <do>Subtle grain on a focal card, panel, or hero — StaticNoise is decorative atmosphere, not chrome</do>
+  <do>Use sparingly — SVG turbulence is memory-heavy; prefer one focal overlay per view</do>
+  <dont>Treating StaticNoise as cheap wallpaper on every card</dont>
   <dont>Stacking many full-viewport StaticNoise instances on one screen</dont>
   <dont>Using StaticNoise as the only loading announcement for a page</dont>
-  <dont>Embedding layout positioning rules inside the component stylesheet</dont>
+  <dont>Expecting StaticNoise to own layout sizing or positioning — parent Surface/Stack owns the box</dont>
 </usage>