@viraui/react 2026.9.0 → 2026.10.0-next.0

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

@@ -6,10 +6,11 @@
   <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;`; 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>
+  <do>Default Prose `wrap` is `pretty` (inherits to children). Prefer `wrap=&quot;balance&quot;` only when short multi-line blocks in the region need even line lengths; single-line metrics use child Text/Title `whiteSpace=&quot;nowrap&quot;`</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>
+  <dont>Wrapping a short UI blurb in Prose “for leading” — use Text/Title `lineHeight` / `maxWidth` / `wrap` instead</dont>
 </usage>

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

@@ -12,6 +12,9 @@
   <prop name="listAlignment" kind="react">
     <description>Horizontal alignment of tab list within root Stack.</description>
   </prop>
+  <prop name="size" kind="react">
+    <description>Shared visual size for tab items (`Button`) and the active indicator footprint. Values match `Button` size (`s` | `m` | `l`). Default `m`.</description>
+  </prop>
   <prop name="Tab.addon" kind="react">
     <description>Decorative addon rendered alongside the tab label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>

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

@@ -4,6 +4,7 @@
   <do>Login/signup (or similar) form swap: wrap Tabs in Surface; panels hold Stack with Textfield(s) + Button (+ optional Fieldset) — use Stack `rowGap` / `fullWidth` / `expandChildren` and Textfield `fullWidth`; invent 0 width/gap CSS</do>
   <do>Compound order: `Tabs.List` → `Tabs.Tab`(s), then `Tabs.Viewport` → `Tabs.Panel`(s) with matching `value`</do>
   <do>Fill list chrome with `listAlignment=&quot;stretch&quot;`; center/end via `listAlignment` on the root</do>
+  <do>Set shared tab + indicator scale with root `size` (`m` default; `s` / `l` match `Button`)</do>
   <do>Decorative `Tab` `addon` / `addonPosition` beside a visible text label — omit glyph `size` / width / height unless expressly overriding</do>
   <dont>Using addons as the only visible label for a tab</dont>
   <dont>Passing `size={16}` on every Tab `addon` icon by habit — prefer icon-library default</dont>

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/components/toggle-button/props.xml

@@ -7,9 +7,11 @@
     <item>Temporally swap icons after user interactions with temporal pressed state, like copy feedback.</item>
   </when_to_use>
   <when_not_to_use>
+    <item>Labeled / visible-text toggles — use ToggleTextButton</item>
     <item>Settings-style on/off fields — use Switch</item>
     <item>One-shot actions with no pressed state — use IconButton</item>
   </when_not_to_use>
+
   <prop name="interpolateIcons" kind="react">
     <description>When `pressedIcon` is set, crossfade and rotate between resting and pressed icons (`data-interpolate=&quot;true&quot;`). When `false`, swap instantly with no transition.</description>
   </prop>

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

@@ -7,6 +7,7 @@
   <do>Temporal pressed feedback (e.g. copy) with optional `interpolateIcons` crossfade</do>
   <do>Segmented toolbars: nest ToggleButtons with `value` inside ToggleGroup; label each control and the group</do>
   <do>Optional chrome: wrap with Tooltip.Trigger / Badge — keep the accessible name on the ToggleButton</do>
+  <dont>Labeled / visible-text toggles — use ToggleTextButton (do not stuff text into the icon-only API)</dont>
   <dont>Using IconButton for persistent or temporal pressed toolbar state</dont>
   <dont>Using Switch for compact icon-only toolbar toggles</dont>
   <dont>Passing `icon` or `render` — ToggleButton owns icon swap and Toggle render wiring; use `restingIcon` / `pressedIcon`</dont>
@@ -14,3 +15,4 @@
   <dont>Omitting `value` on ToggleButton children inside a ToggleGroup</dont>
   <dont>Omitting both `aria-label` and `aria-labelledby`</dont>
 </usage>
+

package/dist/specs/components/toggle-group/patterns.xml

@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="toggle-group">
-  <!-- Sources: viraui-app — cleaned (no handlers, no i18n, no theme store). Compound: ToggleGroup + ToggleButton children with value. -->
+  <!-- Sources: viraui-app — cleaned (no handlers, no i18n, no theme store). Compound: ToggleGroup + ToggleButton and/or ToggleTextButton children with value. -->
+
 
   <example title="Mode switcher chrome">
     <tsx><![CDATA[

package/dist/specs/components/toggle-group/usage.xml

@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="toggle-group">
-  <do>Segmented icon toolbars such as text alignment, formatting, or mode switchers</do>
-  <do>Single- or multi-select pressed states across related ToggleButton items (`value` / `defaultValue` as `string[]`)</do>
-  <do>Compose only ToggleButton children — each child needs a `value` plus `aria-label` / `aria-labelledby`</do>
+  <do>Segmented toolbars such as text alignment, formatting, or mode switchers</do>
+  <do>Single- or multi-select pressed states across related ToggleButton and/or ToggleTextButton items (`value` / `defaultValue` as `string[]`)</do>
+  <do>Compose ToggleButton and/or ToggleTextButton children — each child needs a `value`; icon-only children also need `aria-label` / `aria-labelledby`</do>
   <do>Label the group root with `aria-label` or `aria-labelledby`</do>
   <do>Optional Surface chrome around the group for bordered toolbar shells — Stack gap is owned by ToggleGroup</do>
-  <dont>Omitting `value` on ToggleButton children inside a group</dont>
+  <dont>Omitting `value` on ToggleButton / ToggleTextButton children inside a group</dont>
   <dont>Using Switch for icon-only toolbar toggle sets</dont>
   <dont>Using ToggleGroup for tabbed panel navigation — use Tabs</dont>
-  <dont>Using ToggleGroup for a lone one-off toggle — use ToggleButton alone</dont>
+  <dont>Using ToggleGroup for a lone one-off toggle — use ToggleButton or ToggleTextButton alone</dont>
   <dont>Embedding Surface chrome inside the component — wrap demos or app chrome at the consumer</dont>
 </usage>

package/dist/specs/components/toggle-text-button/a11y.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="toggle-text-button">
+  <rule>Prefer accessible name from visible text children</rule>
+  <rule>Empty or whitespace-only children require aria-label or aria-labelledby</rule>
+  <rule>Base UI Toggle exposes aria-pressed on the rendered button</rule>
+  <rule>Addon is decorative (aria-hidden) unless it is the sole content path — prefer text label; icon-only → ToggleButton</rule>
+  <rule>Keep the accessible name stable when loading state changes</rule>
+</a11y>

package/dist/specs/components/toggle-text-button/meta.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="toggle-text-button" title="ToggleTextButton" category="action" shared_contract="button">
+  <summary>Labeled two-state toggle on Base UI Toggle with Button chrome; visible text children, optional addon / pressedVariant; no resting/pressed icon pair.</summary>
+  <exports>
+    <export name="ToggleTextButton" />
+  </exports>
+  <related>
+    <ref id="button" />
+    <ref id="toggle-button" />
+    <ref id="toggle-group" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/toggle#api-reference" />
+</meta>

package/dist/specs/components/toggle-text-button/patterns.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="toggle-text-button">
+  <example title="Labeled press">
+    <tsx><![CDATA[
+<ToggleTextButton variant="flat" pressedVariant="primary">
+  Bold
+</ToggleTextButton>
+]]></tsx>
+    <notes>Visible text supplies the accessible name. Default resting `variant` is `flat`; set `pressedVariant` for pressed chrome.</notes>
+  </example>
+
+  <example title="Addon + label">
+    <tsx><![CDATA[
+<ToggleTextButton
+  addon={<Bell aria-hidden />}
+  addonPosition="start"
+  pressedVariant="secondary"
+>
+  Notify
+</ToggleTextButton>
+]]></tsx>
+    <notes>Button addon is decorative; keep the text label for naming. Omit glyph size props — Button CSS sizes via `--vui-button-icon-size`.</notes>
+  </example>
+
+  <example title="Mixed ToggleGroup">
+    <tsx><![CDATA[
+<ToggleGroup aria-label="Editor options" defaultValue={['bold']}>
+  <ToggleTextButton value="bold" pressedVariant="secondary">
+    Bold
+  </ToggleTextButton>
+  <ToggleTextButton value="notify" addon={<Bell aria-hidden />} pressedVariant="secondary">
+    Notify
+  </ToggleTextButton>
+  <ToggleButton
+    value="lock"
+    aria-label="Lock"
+    restingIcon={<Lock aria-hidden />}
+    pressedVariant="secondary"
+  />
+</ToggleGroup>
+]]></tsx>
+    <notes>ToggleGroup children may be ToggleTextButton and/or ToggleButton; each needs `value`. Icon-only siblings still need `aria-label`.</notes>
+  </example>
+</patterns>

package/dist/specs/components/toggle-text-button/props.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="toggle-text-button">
+  <when_to_use>
+    <item>Labeled toolbar or settings toggles with visible text</item>
+    <item>Two-state actions that share Button size, variant, addon, loading, and pill chrome</item>
+    <item>ToggleGroup segments that need a text label instead of an icon-only control</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Icon-only two-state controls — use ToggleButton</item>
+    <item>Settings-style on/off fields without button chrome — use Switch</item>
+    <item>One-shot actions with no pressed state — use Button</item>
+  </when_not_to_use>
+  <prop name="addon" kind="react">
+    <description>Decorative addon rendered alongside the button label. Pass any React element; use a named icon from `@viraui/icons/react` or `&lt;Chip /&gt;` for status chips. Omit glyph `size` / width / height — Button CSS sizes SVG via `--vui-button-icon-size`.</description>
+  </prop>
+  <prop name="addonPosition" kind="react">
+    <description>Controls whether the addon appears before or after the label.</description>
+  </prop>
+  <prop name="loading" kind="react">
+    <description>Shows a centered spinner overlay while preserving the original content width.</description>
+  </prop>
+  <prop name="pill" kind="react">
+    <description>Applies a fully rounded pill shape to the button.</description>
+  </prop>
+  <prop name="pressedVariant" kind="react">
+    <description>Visual variant while the toggle is pressed.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Controls the visual button size.</description>
+  </prop>
+  <prop name="variant" kind="react">
+    <description>Visual variant while the toggle is not pressed.</description>
+  </prop>
+  <prop name="background" kind="css">
+    <description>Button fill; variant and state selectors preset this.</description>
+  </prop>
+  <prop name="color" kind="css">
+    <description>Button label and icon color.</description>
+  </prop>
+  <prop name="height" kind="css">
+    <description>Button block size; size prop presets via data attributes.</description>
+  </prop>
+  <prop name="icon-size" kind="css">
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode.</description>
+  </prop>
+  <prop name="padding-block" kind="css">
+    <description>Vertical padding inside the button.</description>
+  </prop>
+  <prop name="padding-inline" kind="css">
+    <description>Horizontal padding inside the button.</description>
+  </prop>
+  <prop name="radius" kind="css">
+    <description>Corner radius; pill sets full radius via data-pill.</description>
+  </prop>
+  <prop name="spinner-color" kind="css">
+    <description>Loading spinner color on the root.</description>
+  </prop>
+</props>

package/dist/specs/components/toggle-text-button/usage.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="toggle-text-button">
+  <do>Labeled toolbar, filter, or settings toggles with visible text children</do>
+  <do>Optional Button `addon` / `addonPosition` / `size` / `loading` / `pill` chrome beside the label</do>
+  <do>Resting `variant` default `flat`; optional `pressedVariant` when pressed</do>
+  <do>Segmented toolbars: nest ToggleTextButton (and/or ToggleButton) with `value` inside ToggleGroup; label the group</do>
+  <do>Omit glyph `size` / width / height on `addon` — host CSS sizes SVG via `--vui-button-icon-size`</do>
+  <dont>Icon-only two-state controls — use ToggleButton with `restingIcon` / `pressedIcon`</dont>
+  <dont>Passing `restingIcon`, `pressedIcon`, `interpolateIcons`, or `render` — not part of this API</dont>
+  <dont>Omitting `value` on ToggleTextButton children inside a ToggleGroup</dont>
+  <dont>Empty/whitespace children without `aria-label` or `aria-labelledby`</dont>
+  <dont>Using Switch when Button chrome and pressed variant are the desired pattern</dont>
+</usage>

package/dist/specs/index.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<index package="@viraui/react" version="2026.9.0" generated="2026-10-15T06:47:40.657Z">
+<index package="@viraui/react" version="2026.10.0-next.0" generated="2026-10-16T09:58:59.523Z">
   <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" />
@@ -511,6 +511,16 @@
       <unit kind="patterns" href="components/toggle-group/patterns.xml" />
     </units>
   </entry>
+  <entry id="toggle-text-button" category="action" title="ToggleTextButton">
+    <summary>Labeled two-state toggle on Base UI Toggle with Button chrome; visible text children, optional addon / pressedVariant; no resting/pressed icon pair.</summary>
+    <units>
+      <unit kind="meta" href="components/toggle-text-button/meta.xml" />
+      <unit kind="a11y" href="components/toggle-text-button/a11y.xml" />
+      <unit kind="props" href="components/toggle-text-button/props.xml" />
+      <unit kind="usage" href="components/toggle-text-button/usage.xml" />
+      <unit kind="patterns" href="components/toggle-text-button/patterns.xml" />
+    </units>
+  </entry>
   <entry id="typewriter" category="typography" title="Typewriter">
     <summary>Decorative inline typewriter animation that inherits typography and color from a parent text primitive.</summary>
     <units>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viraui/react",
-  "version": "2026.9.0",
+  "version": "2026.10.0-next.0",
   "private": false,
   "files": [
     "dist"
@@ -28,7 +28,7 @@
   },
   "devDependencies": {
     "@base-ui/react": ">=1.8.0",
-    "@viraui/foundation": "2026.9.0",
+    "@viraui/foundation": "2026.10.0-next.0",
     "@viraui/icons": "2026.1.0",
     "@viraui/postcss-config": "2026.0.0",
     "@viraui/tsconfig": "2026.0.0",