@viraui/react 2026.6.0 → 2026.6.1

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

@@ -1,7 +1,101 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="fieldset">
-  <example title="Fieldset structure">
-    <tsx><![CDATA[<Fieldset label="…">…</Fieldset>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: preview-grid + Fieldset stories — cleaned (no handlers). Use render={&lt;RadioGroup /&gt;} / CheckboxGroup — not invented Fieldset parts. -->
+
+  <example title="Billing Textfields section">
+    <tsx><![CDATA[
+<Surface border="all" radius="m" hPadding="l" vPadding="l">
+  <Fieldset label="Billing details">
+    <Stack vPadding="m" rowGap="m">
+      <Textfield name="company" label="Company" placeholder="Enter company name" />
+      <Textfield name="taxId" label="Tax ID" placeholder="Enter fiscal number" />
+    </Stack>
+  </Fieldset>
+</Surface>
+]]></tsx>
+    <notes>From Fieldset stories `Default`. Legend on Fieldset; each Textfield keeps its own label. Stack owns gap.</notes>
+  </example>
+
+  <example title="RadioGroup via render">
+    <tsx><![CDATA[
+<Field.Root name="spacing">
+  <Fieldset
+    label="Spacing preset"
+    description="Choose the spacing preset for this workspace."
+    render={<RadioGroup<'default' | 'comfortable' | 'compact'> defaultValue="comfortable" />}
+  >
+    <Radio label="Default" value="default" />
+    <Radio label="Comfortable" value="comfortable" />
+    <Radio label="Compact" value="compact" />
+  </Fieldset>
+</Field.Root>
+]]></tsx>
+    <notes>From Fieldset stories `WithRadioGroup`. Merge RadioGroup through `render`; group copy needs `Field.Root` ancestor.</notes>
+  </example>
+
+  <example title="Receiving method radio cards">
+    <tsx><![CDATA[
+<Field.Root name="receiving-method">
+  <Fieldset label="Receiving Method" render={<RadioGroup defaultValue="bank-transfer" />}>
+    <Stack columnGap="m" vAlign="start" direction="row" expandChildren>
+      <Surface border="all" radius="s" color={2}>
+        <Radio
+          description="SWIFT / IBAN"
+          id="receiving-method-bank-transfer"
+          label="Bank Transfer"
+          value="bank-transfer"
+          hPadding="m"
+          vPadding="m"
+        />
+      </Surface>
+      <Surface border="all" radius="s">
+        <Radio
+          description="Instant Payout"
+          id="receiving-method-paypal"
+          label="PayPal"
+          value="paypal"
+          hPadding="m"
+          vPadding="m"
+        />
+      </Surface>
+    </Stack>
+  </Fieldset>
+</Field.Root>
+]]></tsx>
+    <notes>From preview-grid `payout-preferences`. Card chrome is Surface; Fieldset only owns legend + RadioGroup merge.</notes>
+  </example>
+
+  <example title="Disabled Mode Fieldset">
+    <tsx><![CDATA[
+<Field.Root disabled name="mode">
+  <Fieldset disabled label="Mode" render={<RadioGroup disabled defaultValue="manual" />}>
+    <Radio label="Auto" value="auto" />
+    <Radio label="Manual" value="manual" />
+  </Fieldset>
+</Field.Root>
+]]></tsx>
+    <notes>From preview-grid `disabled-surface-contrast`. Disabled Fieldset + RadioGroup together under disabled `Field.Root`.</notes>
+  </example>
+
+  <example title="Plan cards with group error">
+    <tsx><![CDATA[
+<Field.Root dirty invalid name="plan">
+  <Fieldset
+    label="Plan"
+    error="Select a plan to continue."
+    render={<RadioGroup />}
+  >
+    <Stack expandChildren rowGap="s">
+      <Surface border="all" radius="m">
+        <Radio description="For getting started." hPadding="m" id="plan-free" label="Free" value="free" vPadding="m" />
+      </Surface>
+      <Surface border="all" radius="m">
+        <Radio description="For growing teams." hPadding="m" id="plan-pro" label="Pro" value="pro" vPadding="m" />
+      </Surface>
+    </Stack>
+  </Fieldset>
+</Field.Root>
+]]></tsx>
+    <notes>From Fieldset stories `WithRadioCardLayout`. Group `error` requires `Field.Root`; strip controlled selection handlers from the hint.</notes>
   </example>
 </patterns>

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

@@ -1,11 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="fieldset">
-  <do>Section legends for multiple related fields — billing details with Textfield, Textarea, or Select children</do>
+  <do>Section legends for multiple related fields — billing/shipping with Textfield, Textarea, or Select children; Stack owns gap inside</do>
+  <do>Login/signup (or similar) tab panels: optional Fieldset around related Textfields + Button inside Tabs — Stack/Surface layout only; 0 custom CSS</do>
   <do>Choice groups that need a shared legend, group description, or group error — Field.Root &gt; Fieldset render={&lt;RadioGroup&lt;Value&gt; /&gt;} or render={&lt;CheckboxGroup /&gt;}</do>
-  <do>Group validation and helper copy that require a Field.Root ancestor plus Fieldset description or error</do>
-  <do>Type-safe radio unions via RadioGroup&lt;&apos;ssd&apos; | &apos;hdd&apos;&gt; merged through Fieldset render</do>
-  <do>Shared legend plus optional group description/error for a form block — border/section chrome belongs on Surface or the consumer</do>
-  <dont>Wrapping Fieldset.Root in Stack render — breaks Base UI render merge with RadioGroup or CheckboxGroup</dont>
+  <do>Type-safe radio unions via RadioGroup&lt;&apos;ssd&apos; | &apos;hdd&apos;&gt; merged through Fieldset `render`</do>
+  <do>Shared legend plus optional group description/error — border/section chrome belongs on Surface (or Stack `render={&lt;Surface /&gt;}`), not Fieldset</do>
+  <dont>Wrapping a lone Textfield, Textarea, Select, Radio, or Checkbox in Fieldset when its own label is enough</dont>
   <dont>Expecting description or error on Fieldset without a Field.Root ancestor</dont>
+  <dont>Wrapping Fieldset.Root in Stack `render` — breaks Base UI render merge with RadioGroup or CheckboxGroup</dont>
+  <dont>Putting group legend, description, or validation on RadioGroup or CheckboxGroup props — those belong on Fieldset (with Field.Root when validating)</dont>
   <dont>Omitting RadioGroup&lt;Value&gt; generics when option values are a restricted union</dont>
 </usage>

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

@@ -1,7 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="fit-text">
-  <example title="FitText structure">
-    <tsx><![CDATA[<FitText>…</FitText>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
-  </example>
+  <!-- Skip: zero viraui-app and design-kitchen usage. Package stories cover Title/Text children + maxFontSize; no consumer extract to promote. -->
 </patterns>

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

@@ -13,7 +13,7 @@
   <prop name="maxFontSize" kind="react">
     <description>Caps the fitted font size using any valid CSS length string.</description>
   </prop>
-  <css_var suffix="max-font-size">
+  <prop name="max-font-size" kind="css">
     <description>Upper bound for the fitted font size on the display slot.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,9 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="fit-text">
-  <do>Headlines or short copy that should fill a constrained inline width</do>
-  <do>Multi-line display type broken with br (or equivalent) inside Title, Text, or native markup</do>
-  <do>Resize-friendly marketing/hero type without JS measurement</do>
-  <dont>Expecting automatic line breaks without br or block structure in children</dont>
-  <dont>Putting interactive controls inside FitText (duplicate trees and inert reference)</dont>
-  <dont>Using FitText for truncation or ellipsis</dont>
+  <do>Short headlines that fill a constrained inline width — wrap Title (or Text) as children inside a width-owned Surface / Stack</do>
+  <do>Multi-line display: put `&lt;br /&gt;` (or block structure) inside Title/Text children — FitText does not invent line breaks</do>
+  <do>Cap growth with `maxFontSize` CSS length when the fitted size must not exceed a bound</do>
+  <do>Pick FitText to scale; ClampText to truncate with ellipsis; Title alone when size preset is enough without width-fit</do>
+  <dont>Using FitText for truncation or ellipsis — use ClampText</dont>
+  <dont>Expecting automatic wrapping without `br` or block children</dont>
+  <dont>Putting interactive controls inside FitText — children render twice; reference tree is `aria-hidden` + `inert`</dont>
+  <dont>Long body copy that should reflow at a fixed type size — use Text</dont>
 </usage>

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

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="glow" title="Glow" category="effect" shared_contract="glow">
-  <summary>Decorative pointer-driven border highlight on a transparent Surface shell (radius only). Put the visual card as children; a shared rAF tracker paints CSS variables without React re-renders. Memory-heavy — use sparingly (rarely).</summary>
+  <summary>Decorative pointer-driven border highlight on a transparent Surface shell (radius only). Put the visual card as children; a shared rAF tracker paints CSS variables without React re-renders. Memory/CPU-heavy — use sparingly; prefer one focal instance per view.</summary>
   <exports>
     <export name="Glow" />
   </exports>

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

@@ -1,7 +1,78 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="glow">
-  <example title="Glow structure">
-    <tsx><![CDATA[<Glow>{children}</Glow>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no portal props, no menu handlers). -->
+
+  <example title="Pointer glow report row">
+    <tsx><![CDATA[
+<Glow radius="full" borderOffset={0} borderWidth={1} proximity={10}>
+  <Surface overflow="hidden" color={2} hPadding="m" radius="full" vPadding="m">
+    <Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
+      <Stack rowGap="s">
+        <Text weight="semibold">Q2 payout report</Text>
+        <Text size="s" tone="muted">
+          PDF · Updated 2 hours ago · 14 pages
+        </Text>
+      </Stack>
+
+      <Menu>
+        <Menu.Trigger
+          render={
+            <IconButton
+              aria-label="More actions for Q2 payout report"
+              icon={<DotsVertical size={16} />}
+              pill
+              size="s"
+              variant="flat"
+            />
+          }
+        />
+        <Menu.Popup align="end" side="bottom">
+          <Menu.Item>Rename</Menu.Item>
+          <Menu.Item>Duplicate</Menu.Item>
+          <Menu.Item>Archive</Menu.Item>
+          <Menu.Separator />
+          <Menu.Item sentiment="destructive">Delete</Menu.Item>
+        </Menu.Popup>
+      </Menu>
+    </Stack>
+  </Surface>
+</Glow>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/menu-more` ReportRow. Glow wraps the pill Surface; pointer-driven border only. Drop preview portal props. Compose Surface as children — Glow is decoration.</notes>
+  </example>
+
+  <example title="Report list with glow rows">
+    <tsx><![CDATA[
+<Surface overflow="hidden" border="all" color={1} radius="l">
+  <Stack rowGap="m" hPadding="m" vPadding="m">
+    <Stack rowGap="xs">
+      <Title size="6" render={<h2 />}>
+        Recent reports
+      </Title>
+      <Text size="s" tone="muted">
+        IconButton more-menu on each export row — rename, archive, or delete.
+      </Text>
+    </Stack>
+
+    <Stack rowGap="s">
+      <Glow radius="full" borderOffset={0} borderWidth={1} proximity={10}>
+        <Surface overflow="hidden" color={2} hPadding="m" radius="full" vPadding="m">
+          <Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
+            <Stack rowGap="s">
+              <Text weight="semibold">SEPA batch export</Text>
+              <Text size="s" tone="muted">
+                CSV · Generated yesterday · 1,284 rows
+              </Text>
+            </Stack>
+            {/* trailing IconButton menu */}
+          </Stack>
+        </Surface>
+      </Glow>
+      {/* more Glow rows */}
+    </Stack>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/menu-more` list shell. Stack of Glow-wrapped rows inside a card Surface. Reserve Glow for rare focal lists — do not default-decorate every card.</notes>
   </example>
 </patterns>

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

@@ -47,28 +47,28 @@
   <prop name="angleLag" kind="react">
     <description>CSS transition duration in milliseconds for the pointer-driven starting angle. Soft follow by default; set 0 for instant snap.</description>
   </prop>
-  <css_var suffix="starting-angle">
+  <prop name="starting-angle" kind="css">
     <description>Conic gradient start angle in degrees (unitless number). Pointer tracker writes a continuous unwrapped value.</description>
-  </css_var>
-  <css_var suffix="angle-lag">
+  </prop>
+  <prop name="angle-lag" kind="css">
     <description>Transition duration for `--vui-glow-starting-angle`.</description>
-  </css_var>
-  <css_var suffix="active-opacity">
+  </prop>
+  <prop name="active-opacity" kind="css">
     <description>Current glow opacity from proximity tracking. Written by the shared tracker.</description>
-  </css_var>
-  <css_var suffix="spread">
+  </prop>
+  <prop name="spread" kind="css">
     <description>Angular width of the highlighted arc.</description>
-  </css_var>
-  <css_var suffix="border-width">
+  </prop>
+  <prop name="border-width" kind="css">
     <description>Masked glow border ring width.</description>
-  </css_var>
-  <css_var suffix="border-color">
+  </prop>
+  <prop name="border-color" kind="css">
     <description>Masked border ring color under the highlight.</description>
-  </css_var>
-  <css_var suffix="border-offset">
+  </prop>
+  <prop name="border-offset" kind="css">
     <description>Glow ring offset from the surface edge.</description>
-  </css_var>
-  <css_var suffix="color">
+  </prop>
+  <prop name="color" kind="css">
     <description>Glow fill (solid color or gradient).</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="glow">
-  <do>Wrap a Surface (or other content) that should highlight toward the pointer</do>
-  <do>Grid of glow shells that share one pointer highlight path</do>
-  <do>Nested glow inside a padded Surface using radius=&quot;auto&quot;</do>
-  <dont>Relying on Glow for keyboard focus visibility</dont>
-  <dont>Treating Glow as the visual card (color/padding) instead of composing Surface children</dont>
-  <dont>Setting overflow:hidden on an ancestor Surface when outer glow must remain visible</dont>
+  <do>Wrap a Surface (and nested Stack content) that should highlight toward the pointer — Glow is a transparent Surface shell (`radius` only)</do>
+  <do>Compose list/report rows: Glow around a pill Surface with Stack row + Text + Menu/IconButton trailing actions</do>
+  <do>Use `radius=&quot;auto&quot;` when Glow sits inside a padded ancestor Surface so corners stay concentric</do>
+  <do>Share one pointer path across a small Grid/Stack of glow shells via `globalHighlight` — still keep the set focal, not every card</do>
+  <do>Use sparingly — pointer tracking is memory/CPU-heavy; prefer one focal highlight (or a small shared-tracker grid) per view</do>
+  <dont>Treating Glow as the visual card — nest Surface/Stack for color, padding, and content</dont>
+  <dont>Relying on Glow for keyboard focus or status — decorative only</dont>
+  <dont>Setting `overflow=&quot;hidden&quot;` on an ancestor Surface when an outer ring (`borderOffset` negative) must remain visible</dont>
   <dont>Expecting soft bloom Light layer — Glow is border-ring only</dont>
-  <dont>Using many Glow instances on one page — memory- and CPU-heavy</dont>
   <dont>Expecting continuous spin — use Beam instead</dont>
 </usage>

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

@@ -1,9 +1,92 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="grid">
-  <example title="Grid structure">
-    <tsx><![CDATA[<Grid>
-  <Grid.Item>…</Grid.Item>
-</Grid>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no i18n, no app-only chrome). -->
+
+  <example title="Fixed-breadth preview wall">
+    <tsx><![CDATA[
+<Grid
+  columns={6}
+  colMinWidth="min(calc(var(--space-m) * 23), 28rem)"
+  columnGap="xl"
+  rowGap="xl"
+  aria-label="Component examples"
+>
+  <Grid.Item>
+    <Stack rowGap="xl">{/* column A cards */}</Stack>
+  </Grid.Item>
+  <Grid.Item>
+    <Stack rowGap="xl">{/* column B cards */}</Stack>
+  </Grid.Item>
+  <Grid.Item column="span 2">
+    <Grid columns={2} rowGap="xl" columnGap="xl">
+      <Grid.Item>
+        <Stack rowGap="xl">{/* nested column */}</Stack>
+      </Grid.Item>
+      <Grid.Item>
+        <Stack rowGap="xl">{/* nested column */}</Stack>
+      </Grid.Item>
+      <Grid.Item column="span 2">{/* full-width nested block */}</Grid.Item>
+    </Grid>
+  </Grid.Item>
+</Grid>
+]]></tsx>
+    <notes>From `editor/preview-grid/preview-grid`. `columns` + explicit `colMinWidth` → fixed-breadth tracks that scroll in overflow parents. Nest Grids; use `column="span N"` for spans — not custom `grid-column` CSS.</notes>
+  </example>
+
+  <example title="Icon toolbar matrix">
+    <tsx><![CDATA[
+<Surface border="all" color={1} radius="l" hPadding="m" vPadding="m">
+  <Grid columns={7} rows={6} columnGap="m" rowGap="m">
+    <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
+      <IconButton aria-label="Home" icon={<House size={22} aria-hidden />} variant="flat" />
+    </Grid.Item>
+    <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
+      <IconButton aria-label="Search" icon={<Magnifier size={22} aria-hidden />} variant="flat" />
+    </Grid.Item>
+    <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
+      <IconButton aria-label="Settings" icon={<Gear size={22} aria-hidden />} variant="flat" />
+    </Grid.Item>
+    {/* more IconButtons… */}
+  </Grid>
+  <Stack hAlign="center" vPadding={['l', 's']} expandChildren>
+    <Chip variant="blue">+3000 more icons</Chip>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/action-toolbar`. Fixed `columns`/`rows` matrix; `Grid.Item render={&lt;Stack …/&gt;}` centers each glyph. Drop Tooltip handle plumbing from the hint.</notes>
+  </example>
+
+  <example title="Decorative 3-column backdrop">
+    <tsx><![CDATA[
+<Grid aria-hidden columnGap="m" vPadding="xl" columns={3} rowGap="m">
+  <Grid.Item>
+    <Elevator resting={1}>
+      <Surface border="all" overflow="hidden" radius="l">
+        <Stack hPadding="m" rowGap="s" vPadding="m">
+          <Skeleton animate={false} aria-hidden height="8rem" radius="m" width="100%" />
+          <Skeleton animate={false} aria-hidden height="1rem" radius="full" width="70%" />
+        </Stack>
+      </Surface>
+    </Elevator>
+  </Grid.Item>
+  <Grid.Item>{/* tile */}</Grid.Item>
+  <Grid.Item>{/* tile */}</Grid.Item>
+  {/* repeat to fill 3×3 */}
+</Grid>
+]]></tsx>
+    <notes>From `prompts/prompts-info-state` backdrop. Bare `columns={3}` uses fluid `1fr` tracks. Absolute positioning of the wall stays in shell CSS — Grid owns tracks/gaps only.</notes>
+  </example>
+
+  <example title="Full-width item span">
+    <tsx><![CDATA[
+<Grid columns={2} columnGap="xl" rowGap="xl">
+  <Grid.Item>{/* card */}</Grid.Item>
+  <Grid.Item>{/* card */}</Grid.Item>
+  <Grid.Item fullWidth>{/* banner spanning both tracks */}</Grid.Item>
+  <Grid.Item>{/* card */}</Grid.Item>
+  <Grid.Item>{/* card */}</Grid.Item>
+</Grid>
+]]></tsx>
+    <notes>Prefer `Grid.Item fullWidth` (or `column="span 2"`) over inventing `width: 100%` / `grid-column` CSS on children. Mirrors nested span usage in preview-grid.</notes>
   </example>
 </patterns>

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

@@ -33,7 +33,7 @@
     <description>Spans the item across every row track (`grid-row: 1 / -1`). Wins over `row` when both are set.</description>
   </prop>
   <prop name="Item.fullWidth" kind="react">
-    <description>Spans the item across every column track (`grid-column: 1 / -1`). Wins over `column` when both are set.</description>
+    <description>Spans the item across every column track (`grid-column: 1 / -1`). Wins over `column` when both are set. Prefer this over inventing `width: 100%` / `grid-column` CSS on the item.</description>
   </prop>
   <prop name="Item.ref" kind="react">
     <description>Ref forwarded to the rendered item root element.</description>
@@ -65,37 +65,37 @@
   <prop name="vPadding" kind="react">
     <description>Sets block padding using one token for both sides or a `[start, end]` tuple.</description>
   </prop>
-  <css_var suffix="column-gap">
+  <prop name="column-gap" kind="css">
     <description>Grid column gap on the root.</description>
-  </css_var>
-  <css_var suffix="column-min-w">
+  </prop>
+  <prop name="column-min-w" kind="css">
     <description>Minimum column track width for auto-fill/auto-fit track sizing, and the fixed track breadth when `columns` is set with an explicit `colMinWidth`.</description>
-  </css_var>
-  <css_var suffix="column-size">
+  </prop>
+  <prop name="column-size" kind="css">
     <description>Resolved column track size (`minmax` formula) used by auto-fill/fit.</description>
-  </css_var>
-  <css_var suffix="columns">
+  </prop>
+  <prop name="columns" kind="css">
     <description>Fixed column track count when `columns` is set and filling is inactive; bare `columns` sizes tracks as `minmax(0, 1fr)`; with explicit `colMinWidth`, tracks use `var(--vui-grid-column-min-w)` under `data-grid-fixed-breadth`.</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>Grid row gap on the root.</description>
-  </css_var>
-  <css_var suffix="row-min-h">
+  </prop>
+  <prop name="row-min-h" kind="css">
     <description>Minimum row track size when fixed rows are enabled.</description>
-  </css_var>
-  <css_var suffix="rows">
+  </prop>
+  <prop name="rows" kind="css">
     <description>Fixed row track count when `rows` is set.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,10 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="grid">
-  <do>Responsive card or tile walls that need true CSS Grid tracks (auto-fill/fit or fixed columns)</do>
-  <do>Fixed-count columns that keep a given track breadth — pair `columns` with an explicit `colMinWidth` so a parent with `overflow: auto` can scroll</do>
-  <do>Layouts where items must span full row or full column tracks</do>
+  <do>Responsive card or tile walls that need true CSS Grid tracks (auto-fill/fit or fixed columns) — prefer over inventing `grid-template` CSS</do>
+  <do>Compose tiles as Elevator → Surface → Stack (title/body/actions) inside `Grid.Item` — Grid owns tracks/gaps; Stack owns card internals</do>
+  <do>Fixed-count columns with explicit `colMinWidth` so a parent with `overflow: auto` can scroll</do>
+  <do>Span tracks with `Item.fullWidth` / `Item.fullHeight` — not inventing `grid-column` / `width: 100%` CSS on items</do>
+  <do>Center cell content via `Grid.Item render={&lt;Stack hAlign=&quot;center&quot; vAlign=&quot;center&quot; /&gt;}` (e.g. IconButton toolbars) — one node, no cell CSS</do>
   <do>Token-spaced grids with optional axis padding without custom grid CSS</do>
   <dont>Using Masonry when you need explicit row/column placement or full-width/full-height spans</dont>
-  <dont>Re-declaring grid-template and gap in app CSS when Grid can own the layout</dont>
-  <dont>Setting both fullWidth and column (or fullHeight and row) and expecting the explicit placement to win — full-* data attrs override</dont>
+  <dont>Re-declaring `grid-template` and `gap` in app CSS when Grid can own the layout</dont>
+  <dont>Inventing CSS `gap` / `padding` on this root when public spacing props cover it</dont>
+  <dont>Setting both `fullWidth` and `column` (or `fullHeight` and `row`) and expecting the explicit placement to win — full-* data attrs override</dont>
+  <dont>Using Grid for simple one-axis flex spacing — prefer Stack</dont>
 </usage>

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

@@ -1,11 +1,102 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="icon-button">
-  <example title="IconButton structure">
-    <tsx><![CDATA[<IconButton icon={<Plus />} aria-label="Add" />]]></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="Canvas zoom cluster">
+    <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 flat IconButton row inside Surface. Absolute overlay position is shell CSS — Stack owns the row. Always set `aria-label`.</notes>
   </example>
-  <example title="IconButtonLink structure">
-    <tsx><![CDATA[<IconButtonLink href="#" icon={<Plus />} aria-label="Add" />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+
+  <example title="Toolbar grid (flat)">
+    <tsx><![CDATA[
+<Surface border="all" color={1} radius="l" hPadding="m" vPadding="m">
+  <Grid columns={7} rows={2} columnGap="m" rowGap="m">
+    <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
+      <IconButton aria-label="Bold" icon={<TextBold />} variant="flat" />
+    </Grid.Item>
+    <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
+      <IconButton aria-label="Italic" icon={<TextItalic />} variant="flat" />
+    </Grid.Item>
+    {/* more tools… */}
+  </Grid>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/action-toolbar`. Flat IconButton per cell; Tooltip.Trigger may wrap the control in the app — omit kitchen portal chrome here.</notes>
+  </example>
+
+  <example title="Textfield endAddon copy">
+    <tsx><![CDATA[
+<Textfield
+  aria-label="Invite link"
+  value="https://app.example.com/invite/abc"
+  endAddon={
+    <IconButton aria-label="Copy invite link" icon={<ArrowUpRight />} size="s" variant="secondary" />
+  }
+/>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/invite-team`. Compact secondary IconButton as field `endAddon`.</notes>
+  </example>
+
+  <example title="Menu trigger (pill)">
+    <tsx><![CDATA[
+<Menu>
+  <Menu.Trigger
+    render={
+      <IconButton
+        aria-label="More actions"
+        icon={<DotsVertical />}
+        pill
+        size="s"
+        variant="flat"
+      />
+    }
+  />
+  <Menu.Popup align="end" side="bottom">
+    <Menu.Item>Rename</Menu.Item>
+    <Menu.Item>Duplicate</Menu.Item>
+    <Menu.Separator />
+    <Menu.Item sentiment="destructive">Delete</Menu.Item>
+  </Menu.Popup>
+</Menu>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/menu-more`. Pill flat IconButton as `Menu.Trigger` via `render`.</notes>
+  </example>
+
+  <example title="Card close (secondary)">
+    <tsx><![CDATA[
+<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 preferences card" icon={<Xmark />} size="s" variant="secondary" />
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/preferences` (+ payout-preferences same close pattern). Header trailing chrome.</notes>
+  </example>
+
+  <example title="Dialog step adjusters">
+    <tsx><![CDATA[
+<Stack direction="row" vAlign="center" columnGap="m" hAlign="center">
+  <IconButton aria-label="Decrease goal" icon={<Minus />} size="l" variant="secondary" />
+  <Title size="1" render={<span />}>
+    8,000
+  </Title>
+  <IconButton aria-label="Increase goal" icon={<Plus />} size="l" variant="secondary" />
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/daily-activity-goal` dialog. Large secondary IconButtons flanking a value.</notes>
   </example>
 </patterns>