@viraui/react 2026.7.1 → 2026.9.0

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

@@ -18,7 +18,7 @@
               </Text>
             </Stack>
           </Stack>
-          <ChevronExpandY aria-hidden size={16} />
+          <ChevronExpandY aria-hidden />
         </Stack>
       </Stack>
     }
@@ -36,15 +36,15 @@
       </Stack>
     </Stack>
     <Menu.Separator />
-    <Menu.Item addon={<StarUpgrade aria-hidden size={16} />}>Upgrade to Pro</Menu.Item>
+    <Menu.Item addon={<StarUpgrade aria-hidden />}>Upgrade to Pro</Menu.Item>
     <Menu.Separator />
     <Menu.Group label="Settings">
-      <Menu.Item addon={<BadgeCheck aria-hidden size={16} />}>Account</Menu.Item>
-      <Menu.Item addon={<CreditCards aria-hidden size={16} />}>Billing</Menu.Item>
-      <Menu.Item addon={<Bell aria-hidden size={16} />}>Notifications</Menu.Item>
+      <Menu.Item addon={<BadgeCheck aria-hidden />}>Account</Menu.Item>
+      <Menu.Item addon={<CreditCards aria-hidden />}>Billing</Menu.Item>
+      <Menu.Item addon={<Bell aria-hidden />}>Notifications</Menu.Item>
     </Menu.Group>
     <Menu.Separator />
-    <Menu.Item addon={<ArrowDoorOut aria-hidden size={16} />} sentiment="destructive">
+    <Menu.Item addon={<ArrowDoorOut aria-hidden />} sentiment="destructive">
       Log out
     </Menu.Item>
   </Menu.Popup>
@@ -58,24 +58,24 @@
 <Menu>
   <Menu.Trigger
     render={
-      <Button size="s" addon={<ChevronDown aria-hidden size={16} />} variant="secondary">
+      <Button size="s" addon={<ChevronDown aria-hidden />} variant="secondary">
         Actions
       </Button>
     }
   />
   <Menu.Popup align="end" side="bottom">
     <Menu.Group label="Edit">
-      <Menu.Item addon={<Pencil aria-hidden size={16} />} note="⌘E">
+      <Menu.Item addon={<Pencil aria-hidden />} note="⌘E">
         Rename report
       </Menu.Item>
-      <Menu.Item addon={<Duplicate aria-hidden size={16} />} note="⌘D">
+      <Menu.Item addon={<Duplicate aria-hidden />} note="⌘D">
         Duplicate
       </Menu.Item>
-      <Menu.Item addon={<Archive aria-hidden size={16} />}>Archive</Menu.Item>
+      <Menu.Item addon={<Archive aria-hidden />}>Archive</Menu.Item>
     </Menu.Group>
     <Menu.Separator />
     <Menu.Group label="View">
-      <Menu.CheckboxItem addon={<Eye aria-hidden size={16} />} checked>
+      <Menu.CheckboxItem addon={<Eye aria-hidden />} checked>
         Show totals row
       </Menu.CheckboxItem>
       <Menu.CheckboxItem>Compact table rows</Menu.CheckboxItem>
@@ -88,7 +88,7 @@
     </Menu.RadioGroup>
     <Menu.Separator />
     <Menu.Submenu>
-      <Menu.SubmenuTrigger addon={<Link aria-hidden size={16} />}>Share</Menu.SubmenuTrigger>
+      <Menu.SubmenuTrigger addon={<Link aria-hidden />}>Share</Menu.SubmenuTrigger>
       <Menu.Popup side="inline-end">
         <Menu.LinkItem href="#">Copy link</Menu.LinkItem>
         <Menu.Item note="⌘⇧E">Export PDF</Menu.Item>
@@ -96,7 +96,7 @@
       </Menu.Popup>
     </Menu.Submenu>
     <Menu.Separator />
-    <Menu.Item addon={<Trash aria-hidden size={16} />} sentiment="destructive">
+    <Menu.Item addon={<Trash aria-hidden />} sentiment="destructive">
       Delete report
     </Menu.Item>
   </Menu.Popup>
@@ -119,7 +119,7 @@
       render={
         <IconButton
           aria-label="More actions for Q2 payout report"
-          icon={<DotsVertical size={16} />}
+          icon={<DotsVertical />}
           pill
           size="s"
           variant="flat"
@@ -127,11 +127,11 @@
       }
     />
     <Menu.Popup align="end" side="bottom">
-      <Menu.Item addon={<Pencil aria-hidden size={16} />}>Rename</Menu.Item>
-      <Menu.Item addon={<Duplicate aria-hidden size={16} />}>Duplicate</Menu.Item>
-      <Menu.Item addon={<Archive aria-hidden size={16} />}>Archive</Menu.Item>
+      <Menu.Item addon={<Pencil aria-hidden />}>Rename</Menu.Item>
+      <Menu.Item addon={<Duplicate aria-hidden />}>Duplicate</Menu.Item>
+      <Menu.Item addon={<Archive aria-hidden />}>Archive</Menu.Item>
       <Menu.Separator />
-      <Menu.Item addon={<Trash aria-hidden size={16} />} sentiment="destructive">
+      <Menu.Item addon={<Trash aria-hidden />} sentiment="destructive">
         Delete
       </Menu.Item>
     </Menu.Popup>

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

@@ -16,7 +16,7 @@
     <item>Rich non-menu panels with forms or free layout (use Popover / Dialog — do not wrap Menu in Popover)</item>
   </when_not_to_use>
   <prop name="CheckboxItem.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="CheckboxItem.note" kind="react">
     <description>End-aligned secondary text (e.g. keyboard shortcut) before the check indicator. Rendered muted `xs`.</description>
@@ -28,7 +28,7 @@
     <description>Accessible group label rendered with `Menu.GroupLabel`.</description>
   </prop>
   <prop name="Item.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="Item.note" kind="react">
     <description>End-aligned secondary text (e.g. keyboard shortcut). Rendered muted `xs`.</description>
@@ -37,7 +37,7 @@
     <description>Visual sentiment. `destructive` uses highlight-red wash + text.</description>
   </prop>
   <prop name="LinkItem.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="LinkItem.note" kind="react">
     <description>End-aligned secondary text (e.g. keyboard shortcut). Rendered muted `xs`.</description>
@@ -55,7 +55,7 @@
     <description>Optional accessible group label rendered with `Menu.GroupLabel`.</description>
   </prop>
   <prop name="RadioItem.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="RadioItem.note" kind="react">
     <description>End-aligned secondary text (e.g. keyboard shortcut) before the check indicator. Rendered muted `xs`.</description>
@@ -64,7 +64,7 @@
     <description>Visual sentiment. `destructive` uses highlight-red wash + text.</description>
   </prop>
   <prop name="SubmenuTrigger.addon" kind="react">
-    <description>Decorative leading node rendered before the item label.</description>
+    <description>Decorative leading node rendered before the item label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="SubmenuTrigger.sentiment" kind="react">
     <description>Visual sentiment. `destructive` uses highlight-red wash + text.</description>

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

@@ -6,10 +6,12 @@
   <do>Account / user chip: `Menu.Trigger` as Surface/Stack (Avatar + Text) opening `Menu.Popup` with static profile header plus Items</do>
   <do>Detached or multi-trigger menus via `Menu.createHandle`</do>
   <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on `Menu.Popup`</do>
+  <do>Omit `size` / width / height on Item / LinkItem / checkbox / radio / submenu `addon` icons — prefer icon-library default; set only to expressly override</do>
   <dont>Expecting `Menu.Arrow`, `Menu.Backdrop`, or public Portal/Positioner/Viewport exports</dont>
+  <dont>Passing `size={16}` on every menu `addon` icon by habit — omit unless expressly overriding the library default</dont>
   <dont>Closing checkbox/radio items on click by default when the menu should stay open for multi-toggle — pass `closeOnClick` only when a single pick should dismiss</dont>
   <dont>Using physical left/right CSS that breaks RTL submenu chevrons</dont>
-  <dont>Expecting RTL item rows / left-opening submenus without Base UI `DirectionProvider direction=&quot;rtl&quot;` plus app `dir=&quot;rtl&quot;` on a portal ancestor (usually `&lt;html&gt;` / document root — a local wrapper alone does not reach body-mounted popups)</dont>
+  <dont>Expecting RTL item rows / left-opening submenus without `@viraui/react` `DirectionProvider direction=&quot;rtl&quot;` plus app `dir=&quot;rtl&quot;` on a portal ancestor (usually `&lt;html&gt;` / document root — a local wrapper alone does not reach body-mounted popups)</dont>
   <dont>Nesting Menu inside Popover for an account menu — Menu already owns portal, positioning, and listbox keyboard behavior</dont>
   <dont>Putting focusable controls (inputs, nested buttons) in `Menu.Popup` outside `Menu.Item` / `Menu.LinkItem` / checkbox / radio / submenu trigger parts — use Popover or Dialog for forms</dont>
   <dont>Using Menu for form-field single-select from a long list — use Select</dont>

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

@@ -25,7 +25,7 @@
     value={91}
     label={
       <Stack direction="row" columnGap="xs" vAlign="center">
-        <Sun aria-hidden size={16} />
+        <Sun aria-hidden />
         <span>Backup health</span>
       </Stack>
     }

package/dist/specs/components/progressive-blur/usage.xml

@@ -4,8 +4,10 @@
   <do>Edge scrim on glass / `data-vibrant` Surface heroes, sheets, or scroll regions where content should fade into blur</do>
   <do>Keep semantics and layout on Surface/Stack/Title/Text children underneath — ProgressiveBlur is decorative atmosphere only</do>
   <do>Use sparingly — stacked `backdrop-filter` is GPU/memory-heavy; prefer one focal overlay per view</do>
+  <do>Match a rounded Surface by setting `border-radius` on the ProgressiveBlur root — layers inherit it</do>
   <dont>Leaving the ProgressiveBlur root `position: static` so absolute layers escape the intended overlay box</dont>
   <dont>Driving layout size or scroll behavior from inside the overlay</dont>
   <dont>Scattering ProgressiveBlur across many cards or stacking full-viewport instances</dont>
   <dont>Using ProgressiveBlur as standalone loading or status feedback without a labeled parent region</dont>
+  <dont>Nesting under an ancestor that pairs overflow clipping with border-radius (e.g. Surface `overflow="hidden"` + `radius`) — Chromium drops masked backdrop-filter; leave Surface overflow alone and scroll on an inner node</dont>
 </usage>

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

@@ -1,6 +1,6 @@
 <?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>
+  <summary>Text-wall grouping region (articles, docs, privacy) with heading-aware em rhythm; reading column via parent Stack `maxWidth` sized for body Text `size`.</summary>
   <exports>
     <export name="Prose" />
   </exports>

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

@@ -2,17 +2,41 @@
 <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>
+{/* Body defaults to size m → mid reading column (not the xl band); prefer ch */}
+<Stack maxWidth="60ch" fullWidth>
+  <Prose render={<article />}>
+    <Title size="2" lineHeight="s" render={<h2 />}>
+      Heading-aware document rhythm
+    </Title>
+    <Text render={<p />} lineHeight="l">
+      Direct heading and paragraph children pick up Prose gaps. Type stays on Title and Text. Column width follows body
+      size — not the full viewport.
+    </Text>
+    <Text render={<p />}>A second paragraph uses the block gap, not the heading-end gap.</Text>
+  </Prose>
+</Stack>
+]]></tsx>
+    <notes>Default `gap="l"`. Landmark via `render={<article />}`. Title in Prose uses `lineHeight="s"`. Stack `maxWidth` in `ch` tracks body Text size (~10–12 words/line). Prefer `ch` over rem. Do not wrap these blocks in Stack for rhythm.</notes>
+  </example>
+
+  <example title="Privacy / docs text wall">
+    <tsx><![CDATA[
+{/* Dense body size s → narrower column than default m; prefer ch */}
+<Stack maxWidth="48ch" fullWidth>
+  <Prose render={<article />} gap="l">
+    <Title size="2" lineHeight="s" render={<h2 />}>
+      Privacy policy
+    </Title>
+    <Text size="s" render={<p />} lineHeight="l">
+      Long legal paragraphs use Prose for block gaps. Leading stays on Text. Smaller body size → narrower Stack maxWidth.
+    </Text>
+    <Text size="s" render={<p />}>
+      Following paragraphs omit lineHeight when m is fine. Prefer render p for outline rhythm.
+    </Text>
+  </Prose>
+</Stack>
 ]]></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>
+    <notes>Text-wall path: Prose for rhythm + Stack measure sized for body `size` (here `s` → narrower than `m`). Not for short card blurbs — those stay Text/Title props (`maxWidth` / `balanced`).</notes>
   </example>
 
   <example title="Density and region align">

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

@@ -1,12 +1,14 @@
 <?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>Text walls — articles, docs, privacy/terms, long editorial — 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>
+    <item>Reading column via parent Stack `maxWidth` sized for the body Text `size` (smaller → narrower; not one fixed `65ch`–`75ch`); edge-to-edge wall of text is not OK</item>
   </when_to_use>
   <when_not_to_use>
     <item>UI chrome spacing (cards, toolbars, form rows) — use Stack `rowGap` / `columnGap`</item>
+    <item>Short card/hero blurbs “for leading” — use Text/Title `lineHeight` / `maxWidth` / `balanced`</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>

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

@@ -1,12 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="prose">
+  <do>Use for text walls — articles, docs, privacy/terms, long editorial — not every card blurb (those stay Text/Title + Stack)</do>
   <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>Keep a reading column: wrap Prose in Stack `maxWidth` in **`ch`** sized for the **body Text `size`** (smaller type → narrower; `m` mid band; large body → wider — not one fixed band for every article); prefer `ch` over rem; edge-to-edge wall of text is not OK</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>
+  <do>Leave type on Title/Text; Title inside Prose uses `lineHeight=&quot;s&quot;`; body leading via Text `lineHeight` per block (`m` / `l` / `s`); 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>
+  <dont>Wrapping a short UI blurb in Prose “for leading” — use Text/Title `lineHeight` / `maxWidth` / `balanced` instead</dont>
 </usage>

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

@@ -64,7 +64,7 @@
   defaultValue="round"
   items={cornerShapeItems}
   alignListWithTrigger={false}
-  addon={<ChevronExpandY aria-hidden size="1rem" />}
+  addon={<ChevronExpandY aria-hidden />}
 >
   <Select.Option value="round">Round</Select.Option>
   <Select.Option value="squircle">Squircle</Select.Option>
@@ -109,7 +109,7 @@
   <Select.Option value="blue" addon={<Stack direction="row" columnGap="2xs">{/* swatches */}</Stack>}>
     Blue
   </Select.Option>
-  <Select.Option value="custom" addon={<EyeDropper aria-hidden size={10} />}>
+  <Select.Option value="custom" addon={<EyeDropper aria-hidden />}>
     Custom
   </Select.Option>
 </Select>

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

@@ -15,7 +15,7 @@
     <item>Wrapping a lone Select in Fieldset when its own label is sufficient</item>
   </when_not_to_use>
   <prop name="addon" kind="react">
-    <description>Trigger addon rendered inside `Select.Icon`. Pass any React node; use a named icon from `@viraui/icons/react` for content icons.</description>
+    <description>Trigger addon rendered inside `Select.Icon`. Pass any React node; use a named icon from `@viraui/icons/react` for content icons. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="alignListWithTrigger" kind="react">
     <description>When `true`, aligns the list popup width with the trigger via Base UI `alignItemWithTrigger`. Prefer `false` when options use a leading `addon`. On desktop, Base UI also scroll-locks the page while open when this is `true` (keeps the selected item aligned with the trigger) — independent of `modal`.</description>
@@ -39,7 +39,7 @@
     <description>When `true`, open select locks page scroll and blocks outside pointer interaction (Base UI modal). Default `false` skips the modal backdrop/outside pointer block, but page scroll can still lock when `alignListWithTrigger` is `true` (Base UI coupling).</description>
   </prop>
   <prop name="Option.addon" kind="react">
-    <description>Decorative leading node rendered before the option label.</description>
+    <description>Decorative leading node rendered before the option label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="Option.addonAlign" kind="react">
     <description>Vertical alignment of the addon relative to the option label row.</description>

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

@@ -11,6 +11,7 @@
   <dont>Leaving the trigger without `label` or `aria-label`</dont>
   <dont>Inventing `width: 100%` / `w-full` CSS on Select when a parent Stack `fullWidth` / `expandChildren` can own the fill</dont>
   <dont>Leaving `alignListWithTrigger` enabled when options have a leading addon — prefer `alignListWithTrigger={false}`</dont>
+  <dont>Passing `size={16}` / `size=&quot;1rem&quot;` on every trigger or Option `addon` icon by habit — omit unless expressly overriding the icon-library default</dont>
   <dont>Assuming `modal={false}` alone keeps page scroll — Base UI also scroll-locks while `alignListWithTrigger` is true on desktop</dont>
   <dont>Wrapping a lone Select in Fieldset when its own label is enough</dont>
 </usage>

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

@@ -24,7 +24,7 @@
 <Surface color={2} radius="l" hPadding="m" vPadding="m">
   <Stack columnGap="m" direction="row" vAlign="center" expandChildren>
     <Stack data-grow={false} minWidth="13ch" direction="row" columnGap="s" vAlign="center">
-      <Sun size={16} />
+      <Sun />
       <Text weight="semibold" whiteSpace="nowrap">
         Brightness
       </Text>

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

@@ -16,7 +16,7 @@
     <description>Sets the rendered spinner size.</description>
   </prop>
   <prop name="variant" kind="react">
-    <description>Visual animation style.</description>
+    <description>Visual animation style. Catalog: arc, atom, blocks, bouncing-dots, cascade, circular-dots, classic, classic-v2, clock, comet, compass, dual, eclipse, flip, gather, leap, linear-dots, loading, morph, orbit, pulse, radar, ring, ripple, slide, snake, swirl, trace, wave. Legacy aliases: bars→wave, dot-grid→blocks, dots→eclipse.</description>
   </prop>
   <prop name="size" kind="css">
     <description>Spinner glyph size on the root.</description>

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

@@ -3,7 +3,7 @@
   <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>
+  <do>Pair any Spinner `variant` (catalog or legacy `bars` / `dot-grid` / `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>

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

@@ -1,6 +1,71 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="stack">
   <!-- Sources: viraui-app/components — cleaned (no handlers, no app-only chrome, no CSS that reinvents Stack props). -->
+  <!-- Stack-owned recipes live HERE (local patterns unit). Core `specs/patterns/*` = true multi-surface screen recipes only. -->
+
+  <example title="Stack as Surface (one DOM node)">
+    <tsx><![CDATA[
+{/* Preferred: layout + chrome share one root */}
+<Stack
+  direction="row"
+  columnGap="s"
+  vAlign="center"
+  fullWidth
+  render={<Surface border="all" color={1} radius="m" hPadding="m" vPadding="s" />}
+>
+  <Text size="sm" color="muted">
+    Status
+  </Text>
+  <Chip>Active</Chip>
+</Stack>
+]]></tsx>
+    <notes>Gap/align/`fullWidth`/`expandChildren` on Stack; `border`/`color`/`radius`/padding on Surface in `render`. Nest Surface→Stack only when separate roots are required (Elevator, concentric Surfaces). Never invent border/radius CSS on Stack.</notes>
+  </example>
+
+  <example title="Equal-width action row">
+    <tsx><![CDATA[
+{/* Full-bleed column CTAs */}
+<Stack fullWidth rowGap="s">
+  <Button>Continue</Button>
+  <Button variant="secondary">Cancel</Button>
+</Stack>
+
+{/* Equal-width row actions — children grow on the main axis. Add fullWidth when this Stack must fill parent width */}
+<Stack expandChildren direction="row" columnGap="s">
+  <Button>Continue</Button>
+  <Button variant="secondary">Cancel</Button>
+</Stack>
+]]></tsx>
+    <notes>`fullWidth` sizes this Stack; `expandChildren` grows children on the main axis. Never invent `width: 100%` / `flex: 1` CSS on Button. Both-axes fill → examples below (not height CSS).</notes>
+  </example>
+
+  <example title="Page chrome (semantic hosts)">
+    <tsx><![CDATA[
+<Stack rowGap="m" expandChildren>
+  <Stack
+    direction="row"
+    hAlign="space-between"
+    vAlign="center"
+    columnGap="m"
+    hPadding="m"
+    vPadding="m"
+    render={<header />}
+  >
+    <Title render={<h1 />}>Settings</Title>
+    <Button>Save</Button>
+  </Stack>
+  <Stack direction="row" columnGap="m" expandChildren render={<main />}>
+    <Stack rowGap="xs" hPadding="s" vPadding="s" render={<nav aria-label="Settings" />}>
+      {/* nav links */}
+    </Stack>
+    <Stack rowGap="l" expandChildren>
+      {/* content */}
+    </Stack>
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>Semantic tags via `render` — Stack stays the layout engine. CSS may set `min-block-size` / scroll; never `display:flex`. Omit `render={&lt;div /&gt;}` (default host).</notes>
+  </example>
 
   <example title="App header (hub)">
     <tsx><![CDATA[
@@ -73,10 +138,10 @@
   {/* brand */}
   <Stack rowGap="xl" vAlign="center">
     <Stack vPadding={[0, 'l']} rowGap="xl">
-      <Title size="1" render={<h1 />} maxWidth="32rem" lineHeight="s">
+      <Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s">
         Design systems that ship
       </Title>
-      <Text size="2xl" tone="muted" maxWidth="32rem">
+      <Text size="2xl" tone="muted" maxWidth="68ch">
         Sign in to continue to the studio.
       </Text>
     </Stack>
@@ -216,7 +281,7 @@
     <Title align="center" size="5" render={<h3 />}>
       No Team Members
     </Title>
-    <Text size="s" align="center" maxWidth="14rem" tone="muted">
+    <Text size="s" align="center" maxWidth="40ch" tone="muted">
       Invite your team to collaborate on this project.
     </Text>
     <Button>Invite Members</Button>
@@ -236,7 +301,7 @@
           <Title size="6" render={<h2 />}>
             Preferences
           </Title>
-          <Text size="s" maxWidth="18rem" tone="muted">
+          <Text size="s" maxWidth="45ch" tone="muted">
             Manage your account settings and notifications.
           </Text>
         </Stack>
@@ -360,4 +425,37 @@
 ]]></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>
+
+  <example title="Row panels fill both axes">
+    <tsx><![CDATA[
+{/* Parent must be sized (viewport shell, fullHeight ancestor, …). No height CSS on Stack/children. */}
+<Stack direction="row" columnGap="s" expandChildren fullHeight vAlign="stretch">
+  <Stack rowGap="s" hPadding="m" vPadding="m">
+    {/* sidebar / panel A */}
+  </Stack>
+  <Stack rowGap="m" hPadding="m" vPadding="m" expandChildren>
+    {/* main / panel B */}
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>Canonical horizontal both-axes fill (Stack-owned). Main = `expandChildren`; cross = `vAlign=&quot;stretch&quot;`; root block size = `fullHeight`. Never `style`/`className` height on Stack or children.</notes>
+  </example>
+
+  <example title="Column sections fill both axes">
+    <tsx><![CDATA[
+{/* Parent must be sized. Children share height + fill width — props only. */}
+<Stack rowGap="s" expandChildren fullWidth fullHeight hAlign="stretch">
+  <Stack direction="row" columnGap="m" vAlign="center" hPadding="m" vPadding="s">
+    {/* header strip */}
+  </Stack>
+  <Stack rowGap="m" hPadding="m" vPadding="m" expandChildren>
+    {/* grow body */}
+  </Stack>
+  <Stack direction="row" columnGap="s" hPadding="m" vPadding="s" data-grow="false">
+    {/* footer actions — opt out of main-axis grow */}
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>Canonical vertical both-axes fill (Stack-owned). Main = `expandChildren`; cross = `hAlign=&quot;stretch&quot;`; root = `fullWidth` + `fullHeight`. Footer uses `data-grow=&quot;false&quot;` so only the body expands.</notes>
+  </example>
 </patterns>

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

@@ -6,13 +6,16 @@
     <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>Readable type columns: `maxWidth` in **`ch`** around Text/Title/Prose for ~10–12 words/line — width **tracks body `size`** (smaller → narrower; prefer `ch` over rem; never one fixed band for every size)</item>
     <item>Full-bleed or equal-width action clusters (Buttons, etc.): `fullWidth` and/or `expandChildren` instead of per-child width CSS</item>
+    <item>Children fill both axes in a sized parent — see this surface `patterns.xml`: row = `direction=&quot;row&quot;` + `expandChildren` + `fullHeight` + `vAlign=&quot;stretch&quot;`; column = `expandChildren` + `fullWidth` + `fullHeight` + `hAlign=&quot;stretch&quot;` — never invent `height`/`width` / `block-size`/`inline-size: 100%` 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%` / `inline-size: 100%` / `w-full` / size-fill className on content-sized children (Button, Chip, …) when this Stack can own fill via `fullWidth` / `expandChildren` — or on fixed-size children (IconButton) where width CSS is useless</item>
+    <item>Expecting this stack to fill parent block size without `fullHeight` (or an explicit `blockSize`)</item>
+    <item>Inventing `width`/`height` / `inline-size`/`block-size: 100%` / `w-full` / size-fill className on this Stack or content-sized children when `fullWidth` / `fullHeight` / `expandChildren` + stretch align cover it (see `patterns.xml`) — or on fixed-size children (IconButton) where size CSS is useless</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">
@@ -25,10 +28,13 @@
     <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`. 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>
+    <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. Cross-axis fill stays on `hAlign` / `vAlign=&quot;stretch&quot;` (which prop is cross depends on `direction`). Orthogonal to `fullWidth` / `fullHeight` (children grow vs this root&apos;s 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="fullHeight" kind="react">
+    <description>Sets `block-size: 100%` on the stack root so it fills the parent&apos;s block size. Default `false`. Prefer this over `style`/`className` `height` / `block-size: 100%` on this Stack. Pair with `expandChildren` and cross-axis `hAlign`/`vAlign=&quot;stretch&quot;` so children fill both axes without per-child size CSS. Orthogonal to `expandChildren` and `fullWidth`.</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`. 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>
+    <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. Pair with `fullHeight` when the root must fill both parent axes. 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>

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

@@ -2,17 +2,21 @@
 <usage surface="stack">
   <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>Flex + Surface chrome on one node via `render={&lt;Surface … /&gt;}` — prefer over a CSS border class or an extra wrapper (see this surface `patterns.xml` — 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 (see `patterns.xml`)</do>
+  <do>Children fill **both** axes inside a sized parent — this surface `patterns.xml` (never invent size-fill CSS):
+    row → `direction=&quot;row&quot;` + `expandChildren` + `fullHeight` + `vAlign=&quot;stretch&quot;` (share width + fill height);
+    column → `expandChildren` + `fullWidth` + `fullHeight` + `hAlign=&quot;stretch&quot;` (share height + fill width)</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>Readable type column: Stack `maxWidth` in **`ch`** around Text/Title/Prose sized for the dominant body `size` (~10–12 words/line; smaller → narrower) — prefer `ch` over rem; never one fixed ch for every size</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>Passing `render={&lt;div /&gt;}` (or any host that matches Stack&apos;s default root) — omit `render`; use it only for a different host (`header`, `Surface`, …)</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%` / `inline-size: 100%` / `w-full` / `.fullWidth` / size-fill `className` on content-sized children when this Stack can own the fill — or when children are intentionally fixed-size (e.g. IconButton)</dont>
+  <dont>Inventing `width`/`height` / `inline-size`/`block-size: 100%` / `w-full` / size-fill `className` on this Stack or content-sized children when `fullWidth` / `fullHeight` / `expandChildren` + stretch align can own the fill — or when children are intentionally fixed-size (e.g. IconButton)</dont>
   <dont>Inventing CSS `gap` / `padding` / `paddingBlock*` / `paddingInline*` / side paddings (`style` or className) when public spacing props cover it — one-sided inset uses `hPadding`/`vPadding` `[start, end]` tuples (e.g. `vPadding={[0, &apos;l&apos;]}`), not `paddingBlockEnd: &apos;1rem&apos;`</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>

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

@@ -30,7 +30,7 @@
     <ToggleButton
       value="light"
       aria-label="Light"
-      restingIcon={<Sun aria-hidden size="1rem" />}
+      restingIcon={<Sun aria-hidden />}
       variant="flat"
       size="s"
       pressedVariant="secondary"
@@ -38,7 +38,7 @@
     <ToggleButton
       value="dark"
       aria-label="Dark"
-      restingIcon={<MoonStars aria-hidden size="1rem" />}
+      restingIcon={<MoonStars aria-hidden />}
       variant="flat"
       size="s"
       pressedVariant="secondary"
@@ -46,7 +46,7 @@
     <ToggleButton
       value="system"
       aria-label="System"
-      restingIcon={<DarkLight aria-hidden size="1rem" />}
+      restingIcon={<DarkLight aria-hidden />}
       variant="flat"
       size="s"
       pressedVariant="secondary"

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

@@ -2,7 +2,7 @@
 <usage surface="surface">
   <do>Group content with base-level background and contrast border — nest Stack for child gaps (Surface has no gap prop)</do>
   <do>Login/signup shell: Surface (or `Stack render={&lt;Surface … /&gt;}`) hosts Tabs + Textfield(s) + Button (+ optional Fieldset) — chrome + layout via props, 0 custom CSS</do>
-  <do>Accept Stack as host via their `render={&lt;Surface … /&gt;}` so border/fill/radius share one DOM node — prefer over inventing chrome CSS (see package pattern `stack-as-surface`)</do>
+  <do>Accept Stack as host via their `render={&lt;Surface … /&gt;}` so border/fill/radius share one DOM node — prefer over inventing chrome CSS (see Stack `patterns.xml` — Stack as Surface)</do>
   <do>Settings / preferences panels: Surface card + Stack body + Switch/Checkbox rows (optionally padded inner Surfaces) + Button footer strip</do>
   <do>Frosted glass panels with `data-vibrant` — omit `color` for page-level shell or pass `color` for a tinted fill</do>
   <do>Compose with Elevator for animated elevation — Surface has no `elevation` prop</do>