@viraui/react 2026.7.1 → 2026.9.0

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

@@ -48,17 +48,17 @@
                 aria-label="Repository clone URL"
                 readOnly
                 value="https://github.com/vira-soft/vira-ui.git"
-                endAddon={<Duplicate size={16} />}
+                endAddon={<Duplicate />}
               />
               <Text tone="muted">Clone using the web URL.</Text>
             </Stack>
           </Surface>
 
           <Stack hAlign="start" rowGap="2xs">
-            <Button addon={<CircleImage size={18} />} variant="flat" size="s">
+            <Button addon={<CircleImage />} variant="flat" size="s">
               Open with GitHub Desktop
             </Button>
-            <Button addon={<ArrowDown size={18} />} variant="flat" size="s">
+            <Button addon={<ArrowDown />} variant="flat" size="s">
               Download ZIP
             </Button>
           </Stack>

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

@@ -13,7 +13,7 @@
     <description>Horizontal alignment of tab list within root Stack.</description>
   </prop>
   <prop name="Tab.addon" kind="react">
-    <description>Decorative addon rendered alongside the tab label.</description>
+    <description>Decorative addon rendered alongside the tab label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="Tab.addonPosition" kind="react">
     <description>Controls whether the addon appears before or after the label.</description>

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

@@ -4,8 +4,9 @@
   <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>Decorative `Tab` `addon` / `addonPosition` beside a visible text label</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>
   <dont>Trying to compose a separate public `Tabs.Indicator`; the indicator is owned by `Tabs.List`</dont>
   <dont>Inventing panel width/gap/padding CSS when Stack inside `Tabs.Panel` can own spacing and fill</dont>
   <dont>Vertical tab layouts in v1 styled targets</dont>

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

@@ -1,11 +1,12 @@
 <?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, and responsive body sizing.</summary>
+  <summary>Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `balanced`).</summary>
   <exports>
     <export name="Text" />
   </exports>
   <related>
     <ref id="title" />
+    <ref id="prose" />
     <ref id="clamp-text" />
   </related>
   <units>

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

@@ -1,19 +1,20 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="text">
   <!-- Sources: viraui-app + design-kitchen preview-grid — cleaned (no handlers, no i18n, no app-only chrome). -->
+  <!-- Type measure: prefer maxWidth in `ch` (not rem) — scaled to size for ~10–12 words/line. -->
 
-  <example title="Auth muted lead">
+  <example title="Auth muted lead (readable measure)">
     <tsx><![CDATA[
-<Stack vPadding={[0, 'l']} rowGap="xl">
-  <Title size="1" render={<h1 />} maxWidth="32rem" lineHeight="s">
+<Stack vPadding={[0, 'l']} rowGap="xl" maxWidth="70ch">
+  <Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" balanced>
     Design systems that ship
   </Title>
-  <Text size="2xl" tone="muted" maxWidth="32rem">
+  <Text size="2xl" tone="muted" maxWidth="68ch" balanced>
     Login to create custom ViraUI themes, access prompts and more.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From `auth/login-view`. Large muted body under Title; `maxWidth` on Text — no CSS width.</notes>
+    <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>
   </example>
 
   <example title="Card section blurb">
@@ -22,22 +23,22 @@
   <Title size="6" render={<h2 />}>
     Payout Threshold
   </Title>
-  <Text tone="muted" size="s">
+  <Text tone="muted" size="s" maxWidth="45ch" balanced>
     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.</notes>
+    <notes>From preview-grid `payout-threshold` (+ preferences / workspace-usage). Default pairing: Title + muted `size="s"` Text; short blurb prefers `maxWidth` in `ch` + `balanced`.</notes>
   </example>
 
   <example title="Nested weight + tone">
     <tsx><![CDATA[
-<Text lineHeight="s" render={<p />}>
+<Text lineHeight="s" render={<p />} maxWidth="60ch">
   <Text weight="semibold">Code reviews</Text>{' '}
   <Text tone="muted">with full codebase context to catch hard-to-find bugs.</Text>
 </Text>
 ]]></tsx>
-    <notes>From preview-grid `vercel-agent`. Outer Text owns paragraph/`lineHeight`; nested Text carry weight/tone — no span CSS.</notes>
+    <notes>From preview-grid `vercel-agent`. Outer Text owns paragraph/`lineHeight`/`maxWidth` (`ch`); nested Text carry weight/tone — omit nested lineHeight/size.</notes>
   </example>
 
   <example title="Mono range labels">
@@ -51,14 +52,16 @@
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `payout-threshold`. `family="mono"` + muted xs for metric chrome.</notes>
+    <notes>From preview-grid `payout-threshold`. `family="mono"` + muted xs for metric chrome — single-line; no `balanced`.</notes>
   </example>
 
   <example title="Form success paragraph">
     <tsx><![CDATA[
-<Text render={<p />}>Check your email — we sent a link to your@email.com</Text>
+<Text render={<p />} maxWidth="60ch" balanced>
+  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; default body size/tone.</notes>
+    <notes>From `auth/login-form` acknowledged state. `render={<p />}` for block semantics; short wrap prefers `balanced` + `ch` measure.</notes>
   </example>
 
   <example title="Prose link">
@@ -72,16 +75,16 @@
 
   <example title="Empty-state centered">
     <tsx><![CDATA[
-<Stack hAlign="center" rowGap="m">
-  <Title align="center" size="5" render={<h3 />}>
+<Stack hAlign="center" rowGap="m" maxWidth="36ch">
+  <Title align="center" size="5" render={<h3 />} balanced>
     No Team Members
   </Title>
-  <Text size="s" align="center" maxWidth="14rem" tone="muted">
+  <Text size="s" align="center" maxWidth="40ch" tone="muted" balanced>
     Invite your team to collaborate on this project.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `empty-team`. Centered muted copy with `maxWidth` — Stack owns alignment.</notes>
+    <notes>From preview-grid `empty-team`. Centered muted copy with `maxWidth` in `ch` + `balanced`; Stack owns column cap / centering.</notes>
   </example>
 
   <example title="Claimable balance rows">

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

@@ -2,6 +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>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>
@@ -9,13 +10,14 @@
   <when_not_to_use>
     <item>Headings or display typography — use Title</item>
     <item>Heading semantics without an appropriate render root</item>
-    <item>Inventing CSS `letter-spacing` / `text-transform` / `width: 100%` when `tracking` / `transform` / parent Stack `fullWidth` cover the need</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>
   </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.</description>
+    <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>
@@ -24,7 +26,7 @@
     <description>Selects the semantic font family for body copy and inline code-like text.</description>
   </prop>
   <prop name="fluid" kind="react">
-    <description>Enables viewport fluid clamp sizing for this instance. Default false locks at this size’s --font-scale-body-* token. Pass true for fluid page/body copy. Theme --effect-fluid-typography: initial still locks all Text globally. size xs stays fixed either way (min=max).</description>
+    <description>Enables viewport fluid clamp sizing for this instance. Default false locks at this size’s --font-scale-body-* token. Pass true for fluid page/body copy. Theme --effect-fluid-typography: initial still locks all Text globally. size s and xs stay fixed either way (min=max); fluid clamp starts at m.</description>
   </prop>
   <prop name="fontWidth" kind="react">
     <description>Overrides font width as a percentage (100 = normal); maps to `font-stretch` and `wdth`.</description>
@@ -33,10 +35,10 @@
     <description>Sets inline padding using one token for both sides or a `[start, end]` tuple (`0` allowed). Prefer the tuple for one-sided inset — never `style`/`paddingInline*` CSS when this prop covers it.</description>
   </prop>
   <prop name="lineHeight" kind="react">
-    <description>Controls line height through foundation leading tokens. Root Text without lineHeight uses leading `m`; omit on nested Text so line-height inherits the outer Text.</description>
+    <description>Controls line height through foundation leading tokens. Root Text without lineHeight uses leading `m` (`l` when open; `s` for dense chrome); omit on nested Text so line-height inherits the outer Text. Prefer this prop over CSS `line-height`.</description>
   </prop>
   <prop name="maxWidth" kind="react">
-    <description>Constrains the maximum inline size of the rendered text block.</description>
+    <description>Constrains the maximum inline size of the rendered text block. Prefer for readable UI measure (~10–12 words/line) over CSS `max-width`. Prefer **`ch`** (not `rem`) in patterns/examples. Width tracks `size` — smaller type → narrower cap (`xs`/`s` much tighter than `xl`/`2xl`); never one fixed ch for every size. Shared columns may use parent Stack `maxWidth` sized for the dominant body `size`.</description>
   </prop>
   <prop name="opticalSize" kind="react">
     <description>Overrides the optical size (`opsz`) axis on variable fonts; static fonts keep `font-optical-sizing: auto`.</description>
@@ -51,7 +53,7 @@
     <description>Enables text selection on the rendered copy.</description>
   </prop>
   <prop name="size" kind="react">
-    <description>Selects a semantic body typography size from the active theme scale (`4xl` \| `3xl` \| `2xl` \| `xl` \| `l` \| `m` \| `s` \| `xs`). Root Text without size locks at body `m`; omit size on nested Text so font-size inherits the outer Text. Fluid clamp (prev step→token) applies when `fluid` is true and --effect-fluid-typography is empty. Theme effect initial still locks all Text. size xs is always fixed (min=max).</description>
+    <description>Selects a semantic body typography size from the active theme scale (`4xl` \| `3xl` \| `2xl` \| `xl` \| `l` \| `m` \| `s` \| `xs`). Root Text without size locks at body `m`; omit size on nested Text so font-size inherits the outer Text. Fluid clamp (prev step→token) applies when `fluid` is true and --effect-fluid-typography is empty. Theme effect initial still locks all Text. size s and xs are always fixed (min=max); fluid starts at m.</description>
   </prop>
   <prop name="tone" kind="react">
     <description>Sets the semantic text color role when no literal `color` override is used. `default` inherits; `primary` → `--global-primary`; `muted` → `--global-muted`; `interactive` → `--global-interactive-text`; `positive` / `informative` / `danger` / `warning` → `--highlight-green` / `--highlight-blue` / `--highlight-red` / `--highlight-yellow`.</description>

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

@@ -1,17 +1,23 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="text">
   <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>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>
   <do>Label/value metric rows: Stack row `hAlign=&quot;space-between&quot;` + muted Text label + `family=&quot;mono&quot;` Text value</do>
   <do>Loading placeholder copy: nest Shimmer inside Text (parent region owns `aria-busy`) — not Skeleton for final-dimension text</do>
   <do>Hero / status motion: nest Typewriter inside Text when body tone/size should drive the typed line</do>
   <do>Ellipsis: ClampText `render={&lt;Text … /&gt;}` — FitText when copy must scale to fill width instead of truncate</do>
-  <do>Letter-spacing via `tracking`; text-transform via `transform`; width via `maxWidth` or parent Stack `fullWidth`</do>
-  <do>Omit `align` so copy inherits parent `text-align`; pass `align` only to override</do>
+  <do>Letter-spacing via `tracking`; text-transform via `transform`; width via `maxWidth` or parent Stack `fullWidth`/`maxWidth`</do>
   <do>Inline prose link: `Text render={&lt;a href=… /&gt;}` — keeps preflight link chrome (no `data-no-link-style`)</do>
+  <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` / `width: 100%` / `paddingBlock*` / `paddingInline*` when `tracking` / `transform` / Stack `fullWidth` / `hPadding`/`vPadding` tuples cover it</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>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>
 </usage>

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

@@ -104,7 +104,7 @@
     aria-label="Invite link"
     defaultValue="https://app.co/invite/x8f2k"
     endAddon={
-      <IconButton aria-label="Copy invite link" icon={<ArrowUpRight size={16} />} size="s" variant="secondary" type="button" />
+      <IconButton aria-label="Copy invite link" icon={<ArrowUpRight />} size="s" variant="secondary" type="button" />
     }
   />
 </Stack>
@@ -119,7 +119,7 @@
     type="search"
     aria-label="Search holdings or tickers"
     placeholder="Search holdings or tickers..."
-    startAddon={<Magnifier size={16} />}
+    startAddon={<Magnifier />}
   />
   <Stack columnGap="xs" direction="row">
     <Button variant="secondary">Stocks</Button>
@@ -156,7 +156,7 @@
       aria-label="Repository clone URL"
       readOnly
       value="https://github.com/vira-soft/vira-ui.git"
-      endAddon={<Duplicate size={16} />}
+      endAddon={<Duplicate />}
     />
     <Text tone="muted">Clone using the web URL.</Text>
   </Stack>

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

@@ -22,7 +22,7 @@
     <description>Helper copy rendered with `Field.Description` and `Text` while the field is valid.</description>
   </prop>
   <prop name="endAddon" kind="react">
-    <description>Trailing decoration (icon, button). Buttons must use `type=&quot;button&quot;`.</description>
+    <description>Trailing decoration (icon, button). Buttons must use `type=&quot;button&quot;`. Omit glyph `size` / width / height on icons unless expressly overriding; IconButton/Button hosts own SVG size via CSS.</description>
   </prop>
   <prop name="error" kind="react">
     <description>Error copy rendered with `Field.Error` and `Text` in the same slot as `description`. Replaces description while the field is invalid and dirty. Validation messages from `validate` are shown by `Field.Error` even when this prop is omitted (also requires dirty).</description>
@@ -37,7 +37,7 @@
     <description>Visible label rendered with shared internal `FieldLabel`.</description>
   </prop>
   <prop name="startAddon" kind="react">
-    <description>Leading decoration (prefix text, icon). Not a second field control.</description>
+    <description>Leading decoration (prefix text, icon). Not a second field control. Omit glyph `size` / width / height on icons unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="control-group-background" kind="css">
     <description>Textfield control group background.</description>

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

@@ -5,12 +5,13 @@
   <do>Several related Textfields under one Fieldset legend (e.g. billing) — each field keeps its own `label`</do>
   <do>Equal-width form rows (city/ZIP, email + Select): parent Stack `direction=&quot;row&quot;` + `expandChildren` — not width CSS on children</do>
   <do>Span the form column with Textfield `fullWidth` — open props before inventing width CSS</do>
-  <do>`startAddon` / `endAddon` for prefix text, icons, or actions inside the control group — IconButton/Button addons use `size=&quot;s&quot;` and `type=&quot;button&quot;`</do>
+  <do>`startAddon` / `endAddon` for prefix text, icons, or actions inside the control group — IconButton/Button addons use control `size=&quot;s&quot;` and `type=&quot;button&quot;`; omit glyph `size` / width / height on icons (library default)</do>
   <do>Label, description, and error copy with validation states</do>
   <do>Compose the control inside another Field with `controlOnly` — native `size` / `fitContent` still apply; skip a second Field.Root</do>
   <dont>Multi-line entry — use Textarea</dont>
   <dont>Inventing `width: 100%` / `w-full` CSS on the Textfield root when `fullWidth` covers it</dont>
   <dont>Passing visual size or variant props — chrome is fixed medium. Native HTML `size` on the input is allowed</dont>
+  <dont>Passing `size={16}` / width / height on every addon icon — prefer icon-library default; IconButton/Button hosts own glyph size via CSS</dont>
   <dont>Expecting a focus ring when focus is only on addon controls</dont>
   <dont>Wrapping a lone Textfield in Fieldset when its own label is enough</dont>
 </usage>

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

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

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

@@ -1,14 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="title">
   <!-- Sources: viraui-app + design-kitchen preview-grid — cleaned (no handlers, no i18n). -->
+  <!-- Type measure: prefer maxWidth in `ch` (not rem) — scaled to size for ~10–12 words/line. -->
 
-  <example title="Auth hero heading">
+  <example title="Auth hero heading (readable measure)">
     <tsx><![CDATA[
-<Title size="1" render={<h1 />} maxWidth="32rem" lineHeight="s">
+<Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" balanced>
   Ship real UI at the speed of thought.
 </Title>
 ]]></tsx>
-    <notes>From `auth/login-view`. Pair `size` with `render={<h1 />}` — visual preset and heading semantics stay intentional. (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"` + `balanced` on wrapping display. Prefer `ch` over rem. (Live app nests Typewriter inside; see typewriter patterns.)</notes>
   </example>
 
   <example title="Card section heading">
@@ -17,21 +18,21 @@
   <Title size="6" render={<h2 />}>
     Preferences
   </Title>
-  <Text size="s" maxWidth="18rem" tone="muted">
+  <Text size="s" maxWidth="45ch" tone="muted" balanced>
     Manage your account settings and notifications.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `preferences` (+ payout-threshold, notifications, …). Dense card titles use `size="6"` + `h2`.</notes>
+    <notes>From preview-grid `preferences` (+ payout-threshold, notifications, …). Dense card titles use `size="6"` + `h2`; blurb keeps `ch` measure + `balanced`.</notes>
   </example>
 
   <example title="Empty-state heading">
     <tsx><![CDATA[
-<Title align="center" size="5" render={<h3 />}>
+<Title align="center" size="5" render={<h3 />} balanced>
   No Team Members
 </Title>
 ]]></tsx>
-    <notes>From preview-grid `empty-team`. Centered mid-size heading; pair with muted Text below.</notes>
+    <notes>From preview-grid `empty-team`. Centered mid-size heading; prefer `balanced` when the title wraps; pair with muted Text below.</notes>
   </example>
 
   <example title="Display metric">
@@ -45,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.</notes>
+    <notes>From preview-grid `daily-activity-goal`. `size="display"` for hero numerals; `whiteSpace="nowrap"` keeps metric on one line — skip `balanced`.</notes>
   </example>
 
   <example title="Balance display">
@@ -68,11 +69,11 @@
   <Title size="4" render={<h3 />}>
     Colors
   </Title>
-  <Text size="s" tone="muted">
+  <Text size="s" tone="muted" maxWidth="48ch" balanced>
     Preview of theme voice, contrast, and color rhythm across accents.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From design-kitchen `theme-preview` (+ `base-theme-selector` label scale). Mid panel titles use `size="4"` + `h3`.</notes>
+    <notes>From design-kitchen `theme-preview` (+ `base-theme-selector` label scale). Mid panel titles use `size="4"` + `h3`; supporting Text keeps `ch` measure.</notes>
   </example>
 </patterns>

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

@@ -4,19 +4,20 @@
     <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>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` / `width: 100%` when `tracking` / `transform` / parent Stack `fullWidth` cover the need</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>
   </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.</description>
+    <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>
@@ -31,10 +32,10 @@
     <description>Sets inline padding using one token for both sides or a `[start, end]` tuple (`0` allowed). Prefer the tuple for one-sided inset — never `style`/`paddingInline*` CSS when this prop covers it.</description>
   </prop>
   <prop name="lineHeight" kind="react">
-    <description>Controls line height through foundation leading tokens.</description>
+    <description>Controls line height through foundation leading tokens. Default `m`; prefer `s` on large wrapping titles and always inside Prose. Prefer this prop over CSS `line-height`.</description>
   </prop>
   <prop name="maxWidth" kind="react">
-    <description>Constrains the maximum inline size of the rendered text block.</description>
+    <description>Constrains the maximum inline size of the rendered text block. Prefer for readable wrapping titles (~10–12 words/line) over CSS `max-width`. Prefer **`ch`** (not `rem`) in patterns/examples. Width tracks `size` — smaller presets → narrower cap; never one fixed measure for every Title size. Shared columns may use parent Stack `maxWidth` instead.</description>
   </prop>
   <prop name="opticalSize" kind="react">
     <description>Overrides the optical size (`opsz`) axis on variable fonts; static fonts keep `font-optical-sizing: auto`.</description>

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

@@ -1,15 +1,20 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <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>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>
   <do>Auth / hero cycle: nest Typewriter inside Title (`preserveSpace`, caret props) so display preset + heading tag stay on the parent</do>
   <do>Loading title copy: nest Shimmer inside Title — parent region owns busy semantics</do>
   <do>Truncation: ClampText `render={&lt;Title size=… render={&lt;h* /&gt;} /&gt;}` — FitText wraps Title when short headlines must fill a constrained width</do>
   <do>Fluid clamp across presets (`fluid` / theme `--effect-fluid-typography`); pass `fluid={false}` inside chrome or dense UI</do>
-  <do>Letter-spacing via `tracking`; text-transform via `transform`; width via `maxWidth` or parent Stack `fullWidth`</do>
-  <do>Omit `align` so the heading inherits parent `text-align`; pass `align` only to override</do>
+  <do>Letter-spacing via `tracking`; text-transform via `transform`; width via `maxWidth` or parent Stack `fullWidth`/`maxWidth`</do>
   <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` / `width: 100%` / `paddingBlock*` / `paddingInline*` when props / Stack / `hPadding`/`vPadding` tuples cover it</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>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/patterns.xml

@@ -22,8 +22,8 @@
     render={
       <ToggleButton
         aria-label="Lock in shuffle"
-        restingIcon={<LockOpen2 aria-hidden size="1rem" />}
-        pressedIcon={<Lock aria-hidden size="1rem" color="var(--global-primary)" />}
+        restingIcon={<LockOpen2 aria-hidden />}
+        pressedIcon={<Lock aria-hidden color="var(--global-primary)" />}
         variant="flat"
         pressedVariant="secondary"
       />
@@ -43,7 +43,7 @@
       <ToggleButton
         aria-label="Sync light and dark"
         size="s"
-        restingIcon={<DarkLight aria-hidden size="1rem" />}
+        restingIcon={<DarkLight aria-hidden />}
         variant="flat"
         pressedVariant="primary"
       />
@@ -60,8 +60,8 @@
 <Badge show color="yellow">
   <ToggleButton
     aria-label="Mute notifications"
-    restingIcon={<BellSlash aria-hidden size={16} />}
-    pressedIcon={<BellOn aria-hidden size={16} />}
+    restingIcon={<BellSlash aria-hidden />}
+    pressedIcon={<BellOn aria-hidden />}
     size="s"
     interpolateIcons
     variant="secondary"
@@ -77,7 +77,7 @@
   <ToggleButton
     value="light"
     aria-label="Light"
-    restingIcon={<Sun aria-hidden size="1rem" />}
+    restingIcon={<Sun aria-hidden />}
     variant="flat"
     size="s"
     pressedVariant="secondary"
@@ -85,7 +85,7 @@
   <ToggleButton
     value="dark"
     aria-label="Dark"
-    restingIcon={<MoonStars aria-hidden size="1rem" />}
+    restingIcon={<MoonStars aria-hidden />}
     variant="flat"
     size="s"
     pressedVariant="secondary"
@@ -93,7 +93,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/toggle-button/props.xml

@@ -20,13 +20,13 @@
     <description>Applies a fully rounded pill shape to the button.</description>
   </prop>
   <prop name="pressedIcon" kind="react">
-    <description>Icon shown while the toggle is pressed.</description>
+    <description>Icon shown while the toggle is pressed. Omit glyph `size` / width / height — host CSS sizes SVG via `--vui-button-icon-size`.</description>
   </prop>
   <prop name="pressedVariant" kind="react">
     <description>Visual variant while the toggle is pressed.</description>
   </prop>
   <prop name="restingIcon" kind="react">
-    <description>Icon shown while the toggle is not pressed.</description>
+    <description>Icon shown while the toggle is not pressed. Omit glyph `size` / width / height — host CSS sizes SVG via `--vui-button-icon-size`.</description>
   </prop>
   <prop name="size" kind="react">
     <description>Controls the visual button size.</description>
@@ -44,7 +44,7 @@
     <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.</description>
+    <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>

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

@@ -3,12 +3,14 @@
   <do>Toolbar pin, favorite, mute, or lock toggles identified only by icon</do>
   <do>Compact on/off controls that share IconButton size, variant, and loading model</do>
   <do>Two-state actions where pressed state should swap the visible glyph via `restingIcon` / `pressedIcon`</do>
+  <do>Omit `size` / width / height on `restingIcon` / `pressedIcon` glyphs — host CSS sizes SVG via `--vui-button-icon-size`; set glyph size only to expressly override</do>
   <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>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>
+  <dont>Passing `size={16}` / `size=&quot;1rem&quot;` (or width/height) on every icon slot glyph — ToggleButton CSS sizes SVG descendants</dont>
   <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

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