@viraui/react 2026.8.0 → 2026.9.1

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[
@@ -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

@@ -8,12 +8,14 @@
     <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">
@@ -26,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,8 +2,11 @@
 <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>
@@ -13,7 +16,7 @@
   <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/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>

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

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="text" title="Text" category="typography" shared_contract="text">
-  <summary>Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `balanced`).</summary>
+  <summary>Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `wrap`).</summary>
   <exports>
     <export name="Text" />
   </exports>

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

@@ -6,15 +6,15 @@
   <example title="Auth muted lead (readable measure)">
     <tsx><![CDATA[
 <Stack vPadding={[0, 'l']} rowGap="xl" maxWidth="70ch">
-  <Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" balanced>
+  <Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" wrap="balance">
     Design systems that ship
   </Title>
-  <Text size="2xl" tone="muted" maxWidth="68ch" balanced>
+  <Text size="2xl" tone="muted" maxWidth="68ch" wrap="balance">
     Login to create custom ViraUI themes, access prompts and more.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From `auth/login-view`. Cap ~10–12 words/line with `maxWidth` in `ch` scaled to size (`2xl` wider than `s`); `balanced` on short wrapping hero copy; `lineHeight="s"` on large Title. Prefer `ch` over rem. No CSS width/line-height.</notes>
+    <notes>From `auth/login-view`. Cap ~10–12 words/line with `maxWidth` in `ch` scaled to size (`2xl` wider than `s`); `wrap="balance"` on short even-rag hero copy (default `pretty` covers most body); `lineHeight="s"` on large Title. Prefer `ch` over rem. No CSS width/line-height.</notes>
   </example>
 
   <example title="Card section blurb">
@@ -23,12 +23,12 @@
   <Title size="6" render={<h2 />}>
     Payout Threshold
   </Title>
-  <Text tone="muted" size="s" maxWidth="45ch" balanced>
+  <Text tone="muted" size="s" maxWidth="45ch">
     Set the minimum balance required before a payout is triggered.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `payout-threshold` (+ preferences / workspace-usage). Default pairing: Title + muted `size="s"` Text; short blurb prefers `maxWidth` in `ch` + `balanced`.</notes>
+    <notes>From preview-grid `payout-threshold` (+ preferences / workspace-usage). Default pairing: Title + muted `size="s"` Text; short blurb prefers `maxWidth` in `ch` (default `wrap="pretty"`).</notes>
   </example>
 
   <example title="Nested weight + tone">
@@ -52,16 +52,16 @@
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `payout-threshold`. `family="mono"` + muted xs for metric chrome — single-line; no `balanced`.</notes>
+    <notes>From preview-grid `payout-threshold`. `family="mono"` + muted xs for metric chrome — single-line; prefer `whiteSpace="nowrap"` when overflow risk; do not use `wrap="nowrap"` for metrics.</notes>
   </example>
 
   <example title="Form success paragraph">
     <tsx><![CDATA[
-<Text render={<p />} maxWidth="60ch" balanced>
+<Text render={<p />} maxWidth="60ch">
   Check your email — we sent a link to your@email.com
 </Text>
 ]]></tsx>
-    <notes>From `auth/login-form` acknowledged state. `render={<p />}` for block semantics; short wrap prefers `balanced` + `ch` measure.</notes>
+    <notes>From `auth/login-form` acknowledged state. `render={<p />}` for block semantics; short wrap relies on default `pretty` + `ch` measure.</notes>
   </example>
 
   <example title="Prose link">
@@ -76,15 +76,15 @@
   <example title="Empty-state centered">
     <tsx><![CDATA[
 <Stack hAlign="center" rowGap="m" maxWidth="36ch">
-  <Title align="center" size="5" render={<h3 />} balanced>
+  <Title align="center" size="5" render={<h3 />} wrap="balance">
     No Team Members
   </Title>
-  <Text size="s" align="center" maxWidth="40ch" tone="muted" balanced>
+  <Text size="s" align="center" maxWidth="40ch" tone="muted" wrap="balance">
     Invite your team to collaborate on this project.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `empty-team`. Centered muted copy with `maxWidth` in `ch` + `balanced`; Stack owns column cap / centering.</notes>
+    <notes>From preview-grid `empty-team`. Centered muted copy with `maxWidth` in `ch` + `wrap="balance"` for even rag; Stack owns column cap / centering.</notes>
   </example>
 
   <example title="Claimable balance rows">

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

@@ -2,7 +2,7 @@
 <props surface="text">
   <when_to_use>
     <item>Body copy with semantic tone (including brand `primary`) and token-backed typography</item>
-    <item>Readable UI measure (~10–12 words/line) via `maxWidth` / parent Stack `maxWidth` **scaled to `size`** (smaller → narrower), `lineHeight` matched to size, and `balanced` on short wrapping paragraphs</item>
+    <item>Readable UI measure (~10–12 words/line) via `maxWidth` / parent Stack `maxWidth` **scaled to `size`** (smaller → narrower), `lineHeight` matched to size, and `wrap` (default `pretty`; `balance` on short even-rag blurbs)</item>
     <item>Letter-spacing via `tracking` or text-transform via `transform` — prefer props over CSS on the Text root</item>
     <item>Helper, label, or inline copy inside other components</item>
     <item>Mono or body family text; size locked by default (`fluid` false → --font-scale-body-*); pass `fluid` for viewport clamp (also gated by theme `--effect-fluid-typography`)</item>
@@ -11,14 +11,11 @@
     <item>Headings or display typography — use Title</item>
     <item>Heading semantics without an appropriate render root</item>
     <item>Long-form heading-aware article rhythm — use Prose (keep a reading column)</item>
-    <item>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap: balance` / `width: 100%` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `balanced` / parent Stack `fullWidth` cover the need</item>
+    <item>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap` / `width: 100%` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `wrap` / parent Stack `fullWidth` cover the need</item>
   </when_not_to_use>
   <prop name="align" kind="react">
     <description>Aligns text using logical alignment values. Omit so `text-align` inherits from the parent.</description>
   </prop>
-  <prop name="balanced" kind="react">
-    <description>Enables balanced wrapping for block-like copy. Prefer on short wrapping UI paragraphs (hero lead, empty state, card blurb); omit when single-line or intentional ragged.</description>
-  </prop>
   <prop name="color" kind="react">
     <description>Applies a literal color escape hatch when semantic `tone` is not used.</description>
   </prop>
@@ -77,7 +74,10 @@
     <description>Selects a semantic weight keyword or a numeric weight (`font-weight` + `wght` axis).</description>
   </prop>
   <prop name="whiteSpace" kind="react">
-    <description>Controls white-space preservation and wrapping behavior.</description>
+    <description>Controls white-space collapse/preserve (`white-space`). Prefer `whiteSpace=&quot;nowrap&quot;` for single-line metrics/chrome (also collapses spaces). For wrapping algorithm / even line lengths use `wrap` (`text-wrap`) — not this prop.</description>
+  </prop>
+  <prop name="wrap" kind="react">
+    <description>Controls CSS `text-wrap` (wrapping algorithm / wrap on-off). Default `pretty` for orphan-aware UI copy. Prefer `balance` on short multi-line heads/blurbs that need even line lengths. Use `wrap=&quot;nowrap&quot;` only when you need no wrap without changing white-space collapse; prefer `whiteSpace=&quot;nowrap&quot;` for metrics.</description>
   </prop>
   <prop name="align" kind="css">
     <description>Text alignment on the root when the `align` prop is set; omitted inherits parent `text-align`.</description>
@@ -131,6 +131,9 @@
     <description>Text transform on the root. Prefer the `transform` React prop; set this hook only when theming beyond the prop.</description>
   </prop>
   <prop name="white-space" kind="css">
-    <description>White-space behavior on the root.</description>
+    <description>White-space behavior on the root (`--vui-text-white-space`). Prefer the `whiteSpace` React prop.</description>
+  </prop>
+  <prop name="wrap" kind="css">
+    <description>Text-wrap on the root (`--vui-text-wrap`). Prefer the `wrap` React prop; default `pretty`.</description>
   </prop>
 </props>

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

@@ -3,7 +3,7 @@
   <do>Body copy, helpers, and labels — semantic `tone` before literal `color` or raw theme vars</do>
   <do>Readable UI measure: aim ~10–12 words per line — `maxWidth` / Stack `maxWidth` **scales with `size`** (smaller type → narrower column; larger → wider); prefer **`ch`** in patterns/examples (not `rem`); never one fixed ch for every size; no full-bleed wrapping blurbs</do>
   <do>Match `lineHeight` to size/context (`m` default on root; `l` when open; `s` for dense chrome); omit `lineHeight`/`size` on nested Text so the outer Text owns type</do>
-  <do>Prefer `balanced` on short wrapping paragraphs (hero lead, empty state, card blurb); omit when single-line or intentional ragged</do>
+  <do>Default `wrap` is `pretty` (orphan-aware). Prefer `wrap=&quot;balance&quot;` on short multi-line blurbs that need even line lengths; use `whiteSpace=&quot;nowrap&quot;` for single-line metrics (not `wrap=&quot;nowrap&quot;` unless you must keep space collapse unchanged)</do>
   <do>Omit `align` so copy inherits parent `text-align`; pass `align` only to override</do>
   <do>Card / settings section blurb: Stack `rowGap` + Title heading + muted `size=&quot;s&quot;` Text — no invent CSS gap</do>
   <do>Settings row: Stack `direction=&quot;row&quot;` + Text label + Switch/Checkbox (or nest Text inside Switch `label`) — Surface for chrome</do>
@@ -16,7 +16,7 @@
   <do>Long articles / docs / privacy walls → Prose (not Text alone for heading-aware rhythm); still keep a reading column</do>
   <dont>Using Text for headings — use Title (`render` for h1–h6)</dont>
   <dont>Putting `data-no-link-style` on Text-as-a when the default underline hover is wanted</dont>
-  <dont>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap: balance` / `width: 100%` / `paddingBlock*` / `paddingInline*` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `balanced` / Stack `fullWidth` / `hPadding`/`vPadding` tuples cover it</dont>
+  <dont>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap` / `width: 100%` / `paddingBlock*` / `paddingInline*` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `wrap` / Stack `fullWidth` / `hPadding`/`vPadding` tuples cover it</dont>
   <dont>Setting body color with raw `--global-*` when `tone` covers the role</dont>
   <dont>Full-bleed marketing/UI paragraphs across a wide shell when a ~10–12-word measure fits</dont>
   <dont>Reusing a large-body shell (`~65ch`–`75ch` / wide rem) for small `size` copy — column width must track `size`</dont>

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

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="title" title="Title" category="typography" shared_contract="title">
-  <summary>Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `balanced`).</summary>
+  <summary>Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `wrap`).</summary>
   <exports>
     <export name="Title" />
   </exports>

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

@@ -5,11 +5,11 @@
 
   <example title="Auth hero heading (readable measure)">
     <tsx><![CDATA[
-<Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" balanced>
+<Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" wrap="balance">
   Ship real UI at the speed of thought.
 </Title>
 ]]></tsx>
-    <notes>From `auth/login-view`. Pair `size` with `render={<h1 />}`; cap measure in `ch`; `lineHeight="s"` + `balanced` on wrapping display. Prefer `ch` over rem. (Live app nests Typewriter inside; see typewriter patterns.)</notes>
+    <notes>From `auth/login-view`. Pair `size` with `render={<h1 />}`; cap measure in `ch`; `lineHeight="s"` + `wrap="balance"` on short even-rag display (default `pretty` covers most titles). Prefer `ch` over rem. (Live app nests Typewriter inside; see typewriter patterns.)</notes>
   </example>
 
   <example title="Card section heading">
@@ -18,21 +18,21 @@
   <Title size="6" render={<h2 />}>
     Preferences
   </Title>
-  <Text size="s" maxWidth="45ch" tone="muted" balanced>
+  <Text size="s" maxWidth="45ch" tone="muted">
     Manage your account settings and notifications.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `preferences` (+ payout-threshold, notifications, …). Dense card titles use `size="6"` + `h2`; blurb keeps `ch` measure + `balanced`.</notes>
+    <notes>From preview-grid `preferences` (+ payout-threshold, notifications, …). Dense card titles use `size="6"` + `h2`; blurb keeps `ch` measure (default `wrap="pretty"`).</notes>
   </example>
 
   <example title="Empty-state heading">
     <tsx><![CDATA[
-<Title align="center" size="5" render={<h3 />} balanced>
+<Title align="center" size="5" render={<h3 />} wrap="balance">
   No Team Members
 </Title>
 ]]></tsx>
-    <notes>From preview-grid `empty-team`. Centered mid-size heading; prefer `balanced` when the title wraps; pair with muted Text below.</notes>
+    <notes>From preview-grid `empty-team`. Centered mid-size heading; prefer `wrap="balance"` when the title wraps and needs even rag; pair with muted Text below.</notes>
   </example>
 
   <example title="Display metric">
@@ -46,7 +46,7 @@
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `daily-activity-goal`. `size="display"` for hero numerals; `whiteSpace="nowrap"` keeps metric on one line — skip `balanced`.</notes>
+    <notes>From preview-grid `daily-activity-goal`. `size="display"` for hero numerals; `whiteSpace="nowrap"` keeps metric on one line — prefer that over `wrap="nowrap"`.</notes>
   </example>
 
   <example title="Balance display">
@@ -69,7 +69,7 @@
   <Title size="4" render={<h3 />}>
     Colors
   </Title>
-  <Text size="s" tone="muted" maxWidth="48ch" balanced>
+  <Text size="s" tone="muted" maxWidth="48ch">
     Preview of theme voice, contrast, and color rhythm across accents.
   </Text>
 </Stack>

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

@@ -4,21 +4,18 @@
     <item>Headings and display text with title presets</item>
     <item>Semantic heading tags chosen explicitly through render</item>
     <item>Size and render paired together for most heading use cases</item>
-    <item>Readable wrapping titles: `maxWidth` (~10–12 words/line, **scaled to `size`** — smaller → narrower), `lineHeight` (`s` on large wrapping / inside Prose), and `balanced` on short multi-line heads</item>
+    <item>Readable wrapping titles: `maxWidth` (~10–12 words/line, **scaled to `size`** — smaller → narrower), `lineHeight` (`s` on large wrapping / inside Prose), and `wrap` (default `pretty`; `balance` on short even-rag heads)</item>
     <item>Letter-spacing via `tracking` or text-transform via `transform` — prefer props over CSS on the Title root</item>
     <item>Fluid clamp sizing across title appearance presets (theme `--effect-fluid-typography` or per-instance `fluid`; off → fixed at --font-scale-display / h-* for that size)</item>
   </when_to_use>
   <when_not_to_use>
     <item>Body copy — use Text</item>
     <item>Body or mono family typography</item>
-    <item>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap: balance` / `width: 100%` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `balanced` / parent Stack `fullWidth` cover the need</item>
+    <item>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap` / `width: 100%` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `wrap` / parent Stack `fullWidth` cover the need</item>
   </when_not_to_use>
   <prop name="align" kind="react">
     <description>Aligns text using logical alignment values. Omit so `text-align` inherits from the parent.</description>
   </prop>
-  <prop name="balanced" kind="react">
-    <description>Enables balanced wrapping for block-like titles. Prefer on short wrapping heads (hero, empty state, section); omit for single-line / `whiteSpace=&quot;nowrap&quot;` metrics.</description>
-  </prop>
   <prop name="color" kind="react">
     <description>Applies a literal color escape hatch.</description>
   </prop>
@@ -71,7 +68,10 @@
     <description>Overrides the size preset weight (`font-weight` + `wght` axis).</description>
   </prop>
   <prop name="whiteSpace" kind="react">
-    <description>Controls white-space preservation and wrapping behavior.</description>
+    <description>Controls white-space collapse/preserve (`white-space`). Prefer `whiteSpace=&quot;nowrap&quot;` for single-line metrics/chrome (also collapses spaces). For wrapping algorithm / even line lengths use `wrap` (`text-wrap`) — not this prop.</description>
+  </prop>
+  <prop name="wrap" kind="react">
+    <description>Controls CSS `text-wrap` (wrapping algorithm / wrap on-off). Default `pretty` for orphan-aware titles. Prefer `balance` on short multi-line heads that need even line lengths. Use `wrap=&quot;nowrap&quot;` only when you need no wrap without changing white-space collapse; prefer `whiteSpace=&quot;nowrap&quot;` for metrics.</description>
   </prop>
   <prop name="align" kind="css">
     <description>Title alignment on the root when the `align` prop is set; omitted inherits parent `text-align`.</description>
@@ -125,6 +125,9 @@
     <description>Text transform on the root. Prefer the `transform` React prop; set this hook only when theming beyond the prop.</description>
   </prop>
   <prop name="white-space" kind="css">
-    <description>White-space behavior on the root.</description>
+    <description>White-space behavior on the root (`--vui-title-white-space`). Prefer the `whiteSpace` React prop.</description>
+  </prop>
+  <prop name="wrap" kind="css">
+    <description>Text-wrap on the root (`--vui-title-wrap`). Prefer the `wrap` React prop; default `pretty`.</description>
   </prop>
 </props>

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

@@ -2,7 +2,7 @@
 <usage surface="title">
   <do>Headings and display type — pair `size` (visual preset) with `render={&lt;h1 /&gt;}`…`h6` for outline semantics (default root is `span`)</do>
   <do>Readable measure on wrapping titles: aim ~10–12 words per line — `maxWidth` / Stack `maxWidth` **scales with `size`** (smaller → narrower; larger → wider); prefer **`ch`** (not `rem`) in patterns/examples; large wrapping presets often `lineHeight=&quot;s&quot;`</do>
-  <do>Prefer `balanced` on short wrapping titles (hero, empty state, section head); omit when single-line / `whiteSpace=&quot;nowrap&quot;` metrics</do>
+  <do>Default `wrap` is `pretty`. Prefer `wrap=&quot;balance&quot;` on short multi-line heads that need even line lengths; use `whiteSpace=&quot;nowrap&quot;` for single-line metrics (not `wrap=&quot;nowrap&quot;` unless space collapse must stay unchanged)</do>
   <do>Omit `align` so the heading inherits parent `text-align`; pass `align` only to override</do>
   <do>Title inside Prose → `lineHeight=&quot;s&quot;`; long-form rhythm stays on Prose — not Stack `rowGap`</do>
   <do>Card / panel header: Stack `rowGap=&quot;xs&quot;` + Title + muted Text blurb — Surface for card chrome</do>
@@ -14,7 +14,7 @@
   <do>Title-as-prose-link (`render={&lt;a /&gt;}`) keeps preflight link chrome — omit `data-no-link-style`</do>
   <dont>Assuming `size` changes the HTML tag — choose `render` explicitly</dont>
   <dont>Using Title for long body paragraphs — use Text</dont>
-  <dont>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap: balance` / `width: 100%` / `paddingBlock*` / `paddingInline*` when props / Stack / `hPadding`/`vPadding` tuples cover it</dont>
-  <dont>Full-bleed wrapping headlines across a wide shell when a capped measure + `balanced` fits</dont>
+  <dont>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap` / `width: 100%` / `paddingBlock*` / `paddingInline*` when props / Stack / `hPadding`/`vPadding` tuples cover it</dont>
+  <dont>Full-bleed wrapping headlines across a wide shell when a capped measure + `wrap` fits</dont>
   <dont>One fixed wide measure for every Title `size` — smaller presets need a narrower column for ~10–12 words/line</dont>
 </usage>

package/dist/specs/foundation/attributes.xml

@@ -138,9 +138,8 @@
   <attr name="data-vibrant">
     <presence>boolean attribute; value ignored</presence>
     <effect>
-      When the active theme sets --effect-vibrancy, applies vibrancy backdrop-filter (brightness/blur/saturate). Surface with data-vibrant translucifies its fill via component CSS: it doesn't apply a background color to the element, that still need to be set by the consumer.
-      Only the  urface component applies the correct `color` prop based on the presence of the attribute. For custom styles you need to set the background color explicitly if you need one.
-      In built-in themes, the applied backdrop-filter is different based on the active theme mode: light or dark.
+      When the active theme sets --effect-vibrancy, applies vibrancy backdrop-filter (blur/saturate). Surface with data-vibrant translucifies its fill via component CSS: it doesn't apply a background color to the element, that still need to be set by the consumer.
+      Only the Surface component applies the correct `color` prop based on the presence of the attribute. For custom styles you need to set the background color explicitly if you need one.
     </effect>
     <values>
       <value>(boolean presence)</value>
@@ -152,7 +151,6 @@
       <gotcha>Surface</gotcha>
       <gotcha>--effect-vibrancy</gotcha>
       <gotcha>--vibrancy-blur</gotcha>
-      <gotcha>--vibrancy-brightness</gotcha>
   </attr>
   <attr name="data-layout-fixed">
     <presence>boolean attribute on table elements</presence>

package/dist/specs/foundation/theme-topics.xml

@@ -45,9 +45,9 @@
     <agent>Theme-level gates. Runtime polarity/details: toggles.xml. Do not invent alternate effect hooks.</agent>
   </topic>
   <topic id="vibrancy" surface="theme">
-    <pattern>--vibrancy-blur | --vibrancy-brightness</pattern>
-    <summary>Vibrancy glass params; blur is a numeric amount consumed as pixels, brightness is a percent string.</summary>
-    <agent>Theme params for data-vibrant hosts when --effect-vibrancy is on. Do not hand-roll backdrop-filter.</agent>
+    <pattern>--vibrancy-blur</pattern>
+    <summary>Vibrancy glass blur amount; numeric value consumed as pixels in data-vibrant backdrop-filter (with fixed saturate).</summary>
+    <agent>Theme param for data-vibrant hosts when --effect-vibrancy is on. Do not hand-roll backdrop-filter.</agent>
   </topic>
   <topic id="radius" surface="theme">
     <pattern>--radius-* | --corner-shape</pattern>

package/dist/specs/foundation/toggles.xml

@@ -5,13 +5,13 @@
     <when>html registers polarity via contrast-color(var(--global-background)) so light backgrounds resolve to black and dark backgrounds to white; container name is root (see core.css).</when>
     <when>data-mode=&quot;light&quot; forces --is-light-mode: black and color-scheme: light; data-mode=&quot;dark&quot; forces white and color-scheme: dark.</when>
     <when>data-mode=&quot;inverted&quot; flips color-scheme against the root value: @container root style(--is-light-mode: black) → dark; style(--is-light-mode: white) → light.</when>
-    <when>Component/preflight CSS branches on polarity with @container root style(--is-light-mode: black) or white — e.g. vibrancy brightness, holofoil mix-blend, Button/Chip secondary fills. Do not invent alternate light/dark hooks.</when>
+    <when>Component/preflight CSS branches on polarity with @container root style(--is-light-mode: black) or white — e.g. holofoil mix-blend, Button/Chip secondary fills. Do not invent alternate light/dark hooks.</when>
   </toggle>
   <toggle name="--effect-shadows">
     <when>Empty/unset enables data-elevation box-shadow stacks; set to initial to disable. Preflight gates with @container root not style(--effect-shadows: initial). Do not hand-roll box-shadow.</when>
   </toggle>
   <toggle name="--effect-vibrancy">
-    <when>Empty/unset enables data-vibrant backdrop filters; set to initial to disable. Preflight gates with @container root not style(--effect-vibrancy: initial); vibrancy may further branch on --is-light-mode. Do not hand-roll backdrop-filter.</when>
+    <when>Empty/unset enables data-vibrant backdrop filters; set to initial to disable. Preflight gates with @container root not style(--effect-vibrancy: initial). Do not hand-roll backdrop-filter.</when>
   </toggle>
   <toggle name="--effect-corner-shape">
     <when>Empty/unset enables theme corner-shape on *; set to initial to disable. Preflight gates with @container root not style(--effect-corner-shape: initial) and applies var(--__corner-shape, var(--corner-shape)). Pair with --corner-shape token.</when>

package/dist/specs/index.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<index package="@viraui/react" version="2026.8.0" generated="2026-10-14T16:23:26.846Z">
+<index package="@viraui/react" version="2026.9.1" generated="2026-10-15T08:18:55.911Z">
   <categories>
     <category id="layout" />
     <category id="action" />
@@ -312,7 +312,7 @@
     </units>
   </entry>
   <entry id="prose" category="typography" title="Prose">
-    <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>
+    <summary>Text-wall grouping region (articles, docs, privacy) with heading-aware em rhythm, region `wrap` (default `pretty`), and reading column via parent Stack `maxWidth` sized for body Text `size`.</summary>
     <units>
       <unit kind="meta" href="components/prose/meta.xml" />
       <unit kind="a11y" href="components/prose/a11y.xml" />
@@ -442,7 +442,7 @@
     </units>
   </entry>
   <entry id="text" category="typography" title="Text">
-    <summary>Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `balanced`).</summary>
+    <summary>Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `wrap`).</summary>
     <units>
       <unit kind="meta" href="components/text/meta.xml" />
       <unit kind="a11y" href="components/text/a11y.xml" />
@@ -472,7 +472,7 @@
     </units>
   </entry>
   <entry id="title" category="typography" title="Title">
-    <summary>Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `balanced`).</summary>
+    <summary>Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `wrap`).</summary>
     <units>
       <unit kind="meta" href="components/title/meta.xml" />
       <unit kind="a11y" href="components/title/a11y.xml" />
@@ -598,18 +598,6 @@
       <unit kind="pattern" href="patterns/compose-layout-first.xml" />
     </units>
   </entry>
-  <entry id="equal-width-actions" category="pattern" title="Equal-width action row">
-    <summary>Span or share space with Stack `fullWidth` and/or `expandChildren` (and control `fullWidth` when the surface owns it). Orthogonal: `fullWidth` sizes the Stack; `expandChildren` grows direct children …</summary>
-    <units>
-      <unit kind="pattern" href="patterns/equal-width-actions.xml" />
-    </units>
-  </entry>
-  <entry id="page-chrome" category="pattern" title="Page chrome with Stack render">
-    <summary>Own page/section flex with Stack. Pick semantic tags (`header`, `main`, `nav`, `section`, …) via `render={&amp;lt;tag /&amp;gt;}` — keep Stack as the layout engine. CSS modules may set min-block-size / scrol…</summary>
-    <units>
-      <unit kind="pattern" href="patterns/page-chrome.xml" />
-    </units>
-  </entry>
   <entry id="settings-panel" category="pattern" title="Settings panel (Surface + Stack)">
     <summary>Wrap a settings block in Surface for fill/border/radius/padding; nest Stack for child gaps and rows. Compose the settings-row pattern inside for label+control rows. Prefer props over CSS for spacing …</summary>
     <units>
@@ -622,10 +610,4 @@
       <unit kind="pattern" href="patterns/settings-row.xml" />
     </units>
   </entry>
-  <entry id="stack-as-surface" category="pattern" title="Stack as Surface (avoid extra DOM)">
-    <summary>When a flex cluster also needs Surface chrome (border, color, radius, padding), prefer `Stack render={&amp;lt;Surface … /&amp;gt;}` so layout + chrome share one root. Put gap/align/`fullWidth`/`expandChildre…</summary>
-    <units>
-      <unit kind="pattern" href="patterns/stack-as-surface.xml" />
-    </units>
-  </entry>
 </index>

package/dist/specs/patterns/compose-layout-first.xml

@@ -10,7 +10,7 @@
     <ref id="bleed" units="meta,usage" />
   </uses>
   <do>Prefer Vira layout roots (`Stack`, `Grid`, `Masonry`, `Bleed`, `Surface`) and their public props for every consumer layout. Treat `Stack` as the default box: an enriched `div` (flex + gap/padding/align/`fullWidth`/`render`/…) — prefer it over bare wrapper `div`s even for simple nesting. Compose **with** these parts; default custom CSS = **app chrome** the system does not own. Prefer another Vira component (e.g. `Surface` for border/fill/radius) or `render` merge over a CSS class for chrome the library already owns. Do not open a CSS module to reshape a Vira control unless the consumer **expressly asked** for that override (still read `props`/`usage` first; a future override layer will formalize hooks).</do>
-  <dont>Do not invent bare wrapper `div`s (or `display:flex` / `display:grid` / CSS `gap` / `padding` / `paddingBlock*` / `paddingInline*` / `width` / `inline-size` / border/radius chrome on raw tags or Vira control roots) when `Stack` or another layout primitive / `Surface` / a public `fullWidth` or `hPadding`/`vPadding` tuple covers it. Do not skip composition to reach for a one-off stylesheet — including size-fill classNames that would do nothing on fixed-size controls. Do not pass `render` that restates a component&apos;s default root (e.g. Stack `render={&lt;div /&gt;}`) — omit `render` unless the host changes.</dont>
+  <dont>Do not invent bare wrapper `div`s (or `display:flex` / `display:grid` / CSS `gap` / `padding` / `paddingBlock*` / `paddingInline*` / `width` / `height` / `inline-size` / `block-size: 100%` / border/radius chrome on raw tags or Vira control roots) when `Stack` or another layout primitive / `Surface` / a public `fullWidth`/`fullHeight`/`expandChildren` + stretch align (Stack `patterns.xml`) or `hPadding`/`vPadding` tuple covers it. Do not skip composition to reach for a one-off stylesheet — including size-fill classNames that would do nothing on fixed-size controls. Do not pass `render` that restates a component&apos;s default root (e.g. Stack `render={&lt;div /&gt;}`) — omit `render` unless the host changes.</dont>
   <tsx><![CDATA[
 {/* Flex row + panel chrome: one DOM node via Stack render={<Surface />} */}
 <Stack