@viraui/react 2026.6.0 → 2026.6.2

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

@@ -1,7 +1,101 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="text">
-  <example title="Text structure">
-    <tsx><![CDATA[<Text>…</Text>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app + design-kitchen preview-grid — cleaned (no handlers, no i18n, no app-only chrome). -->
+
+  <example title="Auth muted lead">
+    <tsx><![CDATA[
+<Stack vPadding={[0, 'l']} rowGap="xl">
+  <Title size="1" render={<h1 />} maxWidth="32rem" lineHeight="s">
+    Design systems that ship
+  </Title>
+  <Text size="2xl" tone="muted" maxWidth="32rem">
+    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>
+  </example>
+
+  <example title="Card section blurb">
+    <tsx><![CDATA[
+<Stack rowGap="xs">
+  <Title size="6" render={<h2 />}>
+    Payout Threshold
+  </Title>
+  <Text tone="muted" size="s">
+    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>
+  </example>
+
+  <example title="Nested weight + tone">
+    <tsx><![CDATA[
+<Text lineHeight="s" render={<p />}>
+  <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>
+  </example>
+
+  <example title="Mono range labels">
+    <tsx><![CDATA[
+<Stack columnGap="s" direction="row" hAlign="space-between" vAlign="center">
+  <Text family="mono" size="xs" tone="muted">
+    $50 (MIN)
+  </Text>
+  <Text family="mono" size="xs" tone="muted">
+    $10,000 (MAX)
+  </Text>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `payout-threshold`. `family="mono"` + muted xs for metric chrome.</notes>
+  </example>
+
+  <example title="Form success paragraph">
+    <tsx><![CDATA[
+<Text render={<p />}>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>
+  </example>
+
+  <example title="Empty-state centered">
+    <tsx><![CDATA[
+<Stack hAlign="center" rowGap="m">
+  <Title align="center" size="5" render={<h3 />}>
+    No Team Members
+  </Title>
+  <Text size="s" align="center" maxWidth="14rem" tone="muted">
+    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>
+  </example>
+
+  <example title="Claimable balance rows">
+    <tsx><![CDATA[
+<Stack rowGap="m">
+  <Stack direction="row" hAlign="space-between">
+    <Text size="s" tone="muted">
+      Net Royalties
+    </Text>
+    <Text family="mono" size="s">
+      $0.00
+    </Text>
+  </Stack>
+  <Stack direction="row" hAlign="space-between">
+    <Text size="s" tone="muted">
+      Total Ready to Claim
+    </Text>
+    <Text family="mono" size="s" weight="semibold">
+      $0.00 USD
+    </Text>
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `claimable-balance`. Label/value rows: muted label + mono value; semibold for totals.</notes>
   </example>
 </patterns>

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

@@ -2,12 +2,14 @@
 <props surface="text">
   <when_to_use>
     <item>Body copy with semantic tone (including brand `primary`) and token-backed typography</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 with fluid clamp sizing (gated by --effect-fluid-typography; off → fixed at --font-scale-body-* for that size)</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>
   </when_to_use>
   <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>
   </when_not_to_use>
   <prop name="align" kind="react">
     <description>Aligns text using logical alignment values.</description>
@@ -21,6 +23,9 @@
   <prop name="family" kind="react">
     <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>
+  </prop>
   <prop name="fontWidth" kind="react">
     <description>Overrides font width as a percentage (100 = normal); maps to `font-stretch` and `wdth`.</description>
   </prop>
@@ -46,16 +51,16 @@
     <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`). Fluid clamp between prev step and this size’s --font-scale-body-* token is on when --effect-fluid-typography is empty; set the theme effect to initial to lock at that body scale token. size xs is always fixed.</description>
+    <description>Selects a semantic body typography size from the active theme scale (`4xl` \| `3xl` \| `2xl` \| `xl` \| `l` \| `m` \| `s` \| `xs`). Default locks at that size’s --font-scale-body-* token; 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>
   </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>
   </prop>
   <prop name="tracking" kind="react">
-    <description>Sets letter spacing on the rendered copy.</description>
+    <description>Sets letter-spacing on the rendered copy via `--vui-text-letter-spacing`. Prefer this prop over CSS `letter-spacing` / Tailwind tracking utilities on the same Text root.</description>
   </prop>
   <prop name="transform" kind="react">
-    <description>Applies a text-transform on the rendered copy.</description>
+    <description>Applies CSS `text-transform` on the rendered copy via `--vui-text-text-transform` (`uppercase` \| `lowercase` \| `capitalize` \| …). Prefer this prop over CSS `text-transform` on the same Text root.</description>
   </prop>
   <prop name="trim" kind="react">
     <description>Trims text box whitespace at the chosen edge when the browser supports `text-box`. Pass `false` to disable text-box trim.</description>
@@ -72,58 +77,58 @@
   <prop name="whiteSpace" kind="react">
     <description>Controls white-space preservation and wrapping behavior.</description>
   </prop>
-  <css_var suffix="align">
+  <prop name="align" kind="css">
     <description>Text alignment on the root.</description>
-  </css_var>
-  <css_var suffix="font-family">
+  </prop>
+  <prop name="font-family" kind="css">
     <description>Font family; family prop presets via data attributes.</description>
-  </css_var>
-  <css_var suffix="font-opsz">
+  </prop>
+  <prop name="font-opsz" kind="css">
     <description>Optical size axis on the root (variable fonts).</description>
-  </css_var>
-  <css_var suffix="font-size">
-    <description>Body font size; size prop presets via data attributes. Defaults to the theme body scale token for that size; clamp (prev step→token) applies only when --effect-fluid-typography is on.</description>
-  </css_var>
-  <css_var suffix="font-weight">
+  </prop>
+  <prop name="font-size" kind="css">
+    <description>Body font size; size prop presets via data attributes. Defaults to the theme body scale token for that size; clamp (prev step→token) applies only when --effect-fluid-typography is on and `fluid` is true (Text defaults fluid false).</description>
+  </prop>
+  <prop name="font-weight" kind="css">
     <description>Font weight on the root; keyword presets or numeric via weight prop.</description>
-  </css_var>
-  <css_var suffix="font-width">
+  </prop>
+  <prop name="font-width" kind="css">
     <description>Font width percentage on the root (font-stretch + wdth).</description>
-  </css_var>
-  <css_var suffix="line-height">
+  </prop>
+  <prop name="line-height" kind="css">
     <description>Line height; lineHeight prop presets via data attributes.</description>
-  </css_var>
-  <css_var suffix="letter-spacing">
-    <description>Letter spacing on the root.</description>
-  </css_var>
-  <css_var suffix="literal-color">
+  </prop>
+  <prop name="letter-spacing" kind="css">
+    <description>Letter spacing on the root. Prefer the `tracking` React prop; set this hook only when theming beyond the prop.</description>
+  </prop>
+  <prop name="literal-color" kind="css">
     <description>Literal color override on the root.</description>
-  </css_var>
-  <css_var suffix="max-width">
+  </prop>
+  <prop name="max-width" kind="css">
     <description>Max inline size of the text root.</description>
-  </css_var>
-  <css_var suffix="padding-block-end">
+  </prop>
+  <prop name="padding-block-end" kind="css">
     <description>Block-end padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-block-start">
+  </prop>
+  <prop name="padding-block-start" kind="css">
     <description>Block-start padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-inline-end">
+  </prop>
+  <prop name="padding-inline-end" kind="css">
     <description>Inline-end padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-inline-start">
+  </prop>
+  <prop name="padding-inline-start" kind="css">
     <description>Inline-start padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="trim">
+  </prop>
+  <prop name="trim" kind="css">
     <description>Text-box trim mode on the root.</description>
-  </css_var>
-  <css_var suffix="trim-type">
+  </prop>
+  <prop name="trim-type" kind="css">
     <description>Text-box trim basis on the root.</description>
-  </css_var>
-  <css_var suffix="text-transform">
-    <description>Text transform on the root.</description>
-  </css_var>
-  <css_var suffix="white-space">
+  </prop>
+  <prop name="text-transform" kind="css">
+    <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>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,7 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="text">
-  <do>Body copy with semantic tone (including brand `primary`) and token-backed typography</do>
-  <do>Helper, label, or inline copy inside other components</do>
-  <do>Mono or body family text with fluid clamp sizing (gated by --effect-fluid-typography; off → fixed at --font-scale-body-* for that size)</do>
-  <dont>Using Text for headings instead of Title</dont>
+  <do>Body copy, helpers, and labels — semantic `tone` before literal `color` or raw theme vars</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>
+  <dont>Using Text for headings — use Title (`render` for h1–h6)</dont>
+  <dont>Inventing CSS `letter-spacing` / `text-transform` / `width: 100%` when `tracking` / `transform` / Stack `fullWidth` cover it</dont>
+  <dont>Setting body color with raw `--global-*` when `tone` covers the role</dont>
 </usage>

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

@@ -1,7 +1,53 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="textarea">
-  <example title="Textarea structure">
-    <tsx><![CDATA[<Textarea />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: preview-grid — cleaned (no handlers). -->
+
+  <example title="Notes with resize + fitContent">
+    <tsx><![CDATA[
+<Stack rowGap="l" hPadding="s" vPadding="s">
+  <Textarea
+    label="Notes"
+    placeholder="Add any notes for this payout configuration..."
+    rows={4}
+    resize="vertical"
+    fitContent
+  />
+  <Button>Save Threshold</Button>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `payout-threshold`. `resize="vertical"` + `fitContent`; Stack owns panel gap.</notes>
+  </example>
+
+  <example title="Disabled on nested surface">
+    <tsx><![CDATA[
+<Stack rowGap="s" hPadding="s" expandChildren>
+  <Textarea
+    disabled
+    label="Notes"
+    rows={3}
+    defaultValue="Disabled helper content on nested surface."
+  />
+  <Button disabled>Primary</Button>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `disabled-surface-contrast`. Disabled Textarea inherits surface contrast; no custom CSS.</notes>
+  </example>
+
+  <example title="Labeled section under Fieldset">
+    <tsx><![CDATA[
+<Fieldset label="Launch notes">
+  <Stack rowGap="m">
+    <Textarea
+      name="summary"
+      label="Summary"
+      description="One line shown in the dashboard."
+      placeholder="e.g. Production API"
+      rows={3}
+    />
+    <Textarea name="details" label="Details" rows={5} resize="vertical" />
+  </Stack>
+</Fieldset>
+]]></tsx>
+    <notes>From Fieldset stories (`WithTextarea`). Section legend on Fieldset; each Textarea keeps its own label.</notes>
   </example>
 </patterns>

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

@@ -11,6 +11,7 @@
     <item>Single-line input — use Textfield</item>
     <item>Addon slots like Textfield startAddon or endAddon</item>
     <item>Wrapping a lone Textarea in Fieldset when its own label is sufficient</item>
+    <item>Forcing panel width with CSS `width: 100%` — wrap in Stack with `fullWidth` (see stack units)</item>
   </when_not_to_use>
   <prop name="description" kind="react">
     <description>Helper copy rendered with `Field.Description` and `Text` while the field is valid.</description>
@@ -27,13 +28,13 @@
   <prop name="resize" kind="react">
     <description>Native CSS `resize` for the control, serialized to `data-resize`. Omitted keeps resize disabled (`none`); accepts any valid `CSSProperties[&apos;resize&apos;]` value such as `&quot;vertical&quot;`, `&quot;horizontal&quot;`, or `&quot;both&quot;`.</description>
   </prop>
-  <css_var suffix="input-border-radius">
+  <prop name="input-border-radius" kind="css">
     <description>Corner radius for the BasicInput textarea control (also drives field label/description inline padding).</description>
-  </css_var>
-  <css_var suffix="min-block-size">
+  </prop>
+  <prop name="min-block-size" kind="css">
     <description>Minimum block size of the BasicInput textarea control.</description>
-  </css_var>
-  <css_var suffix="padding-block">
+  </prop>
+  <prop name="padding-block" kind="css">
     <description>Block padding on the BasicInput textarea control.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,10 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="textarea">
   <do>Multi-line text entry with label, description, and error</do>
-  <do>Optional native CSS resize (vertical, horizontal, both, and other valid resize values)</do>
-  <do>Content-sized growth via fitContent</do>
-  <do>Native textarea attributes through the field control</do>
-  <do>One or more Textareas inside Fieldset when they belong to a labeled form section with other fields</do>
-  <dont>Using Textarea for single-line values</dont>
+  <do>Form section: Fieldset legend + one or more Textareas (and sibling Textfield/Select) — Stack owns `rowGap`; each Textarea keeps its own `label`</do>
+  <do>Fill a form column via a parent Stack `fullWidth` / `expandChildren` (Textarea has no `fullWidth` prop) — not CSS `width: 100%`</do>
+  <do>Notes + submit: Stack `rowGap` wrapping Textarea then Button — no panel width CSS</do>
+  <do>Optional native CSS `resize` via the `resize` prop; content-sized growth via `fitContent`</do>
+  <dont>Using Textarea for single-line values — use Textfield</dont>
+  <dont>Expecting Textfield `startAddon` / `endAddon` slots — Textarea has none</dont>
+  <dont>Inventing `width: 100%` / `w-full` CSS on Textarea when a parent Stack `fullWidth` can own the fill</dont>
   <dont>Expecting unsupported size or variant props</dont>
+  <dont>Wrapping a lone Textarea in Fieldset when its own label is enough</dont>
 </usage>

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

@@ -1,7 +1,167 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="textfield">
-  <example title="Textfield structure">
-    <tsx><![CDATA[<Textfield />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app + preview-grid — cleaned (no handlers, Controllers, i18n). -->
+
+  <example title="Inline email (login)">
+    <tsx><![CDATA[
+<form>
+  <Stack direction="row" columnGap="m" rowGap="m" hAlign="start" vAlign="start" wrap>
+    <Textfield
+      type="email"
+      autoComplete="email"
+      placeholder="your@email.com"
+      size={30}
+      aria-label="Email"
+      startAddon={<EnvelopeSparkle />}
+    />
+    <Stack direction="row" vAlign="center" columnGap="m">
+      <Button type="submit">Send magic link</Button>
+      or
+      <ButtonLink variant="secondary" href="#">
+        Get ViraUI Pro
+      </ButtonLink>
+    </Stack>
+  </Stack>
+</form>
+]]></tsx>
+    <notes>From `auth/login-form`. Wrap row for field + CTA cluster. Addon is decorative; strip react-hook-form Controller / i18n.</notes>
+  </example>
+
+  <example title="Read-only with swatch + end addon">
+    <tsx><![CDATA[
+<Textfield
+  readOnly
+  label="Primary"
+  value="oklch(0.62 0.18 250)"
+  fullWidth
+  startAddon={<LineSwatch aria-hidden color="oklch(0.62 0.18 250)" />}
+  endAddon={<IconButton aria-label="Lock color" icon={<Lock />} size="s" variant="flat" type="button" />}
+/>
+]]></tsx>
+    <notes>From `common/color-picker`. `fullWidth` on Textfield — not CSS width. Buttons in addons need `type="button"`.</notes>
+  </example>
+
+  <example title="Dialog paste + invalid">
+    <tsx><![CDATA[
+<Dialog.Sheet title="Import preset" description="Paste preset code." showCloseButton headerAlign="center">
+  <Stack rowGap="m" hAlign="center" hPadding="m" vPadding={['s', 0]}>
+    <Textfield
+      size={40}
+      placeholder="Paste preset…"
+      aria-label="Preset code"
+      invalid
+      error="Invalid preset code"
+    />
+    <Stack direction="row" hAlign="end" columnGap="s">
+      <Button>Apply</Button>
+      <Dialog.Close render={<Button variant="secondary">Cancel</Button>} />
+    </Stack>
+  </Stack>
+</Dialog.Sheet>
+]]></tsx>
+    <notes>From `editor/import-preset-dialog`. Field copy via `error` / `invalid`; no module CSS.</notes>
+  </example>
+
+  <example title="Fit-content copy row (export)">
+    <tsx><![CDATA[
+<Stack vPadding={['s', '3xl']}>
+  <Textfield
+    fitContent
+    readOnly
+    aria-label="Preset share code"
+    value="vira-preset-abc123"
+    endAddon={
+      <IconButton aria-label="Copy preset code" icon={<Duplicate />} size="s" variant="flat" type="button" />
+    }
+  />
+</Stack>
+]]></tsx>
+    <notes>From `editor/export-dialog`. `fitContent` grows inline with value; end addon is chrome only.</notes>
+  </example>
+
+  <example title="Shipping address grid">
+    <tsx><![CDATA[
+<Stack rowGap="l" hPadding="m" vPadding="m">
+  <Textfield label="Street address" required defaultValue="123 Main Street" />
+  <Textfield label="Apt / Suite" defaultValue="Apt 4B" />
+  <Stack columnGap="m" direction="row" expandChildren>
+    <Textfield label="City" defaultValue="San Francisco" />
+    <Textfield label="ZIP Code" defaultValue="94102" />
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `shipping-address`. Row pairs use Stack `expandChildren` — not width CSS on fields.</notes>
+  </example>
+
+  <example title="Invite row + link with end addon">
+    <tsx><![CDATA[
+<Stack rowGap="s">
+  <Stack columnGap="s" direction="row" vAlign="end" expandChildren>
+    <Textfield aria-label="Invite email" defaultValue="alex@example.com" />
+    {/* role Select sibling */}
+  </Stack>
+  <Textfield
+    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" />
+    }
+  />
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `invite-team`. End-aligned row for email + role; link field keeps copy action in `endAddon`.</notes>
+  </example>
+
+  <example title="Search with start addon">
+    <tsx><![CDATA[
+<Stack columnGap="m" direction="row" vAlign="center" hAlign="space-between">
+  <Textfield
+    type="search"
+    aria-label="Search holdings or tickers"
+    placeholder="Search holdings or tickers..."
+    startAddon={<Magnifier size={16} />}
+  />
+  <Stack columnGap="xs" direction="row">
+    <Button variant="secondary">Stocks</Button>
+    <Button variant="secondary">ETFs</Button>
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `holdings`. Leading magnifier is `startAddon`, not a second control.</notes>
+  </example>
+
+  <example title="Currency prefix + verify end addon">
+    <tsx><![CDATA[
+<Stack rowGap="m">
+  <Textfield label="Amount to Invest" defaultValue="1,000.00" startAddon={<>$</>} />
+  <Textfield
+    label="Account Holder Name"
+    defaultValue="Synthetic Horizons Music LLC"
+    endAddon={
+      <Button size="s" variant="secondary" addon={<ShieldCheck />} aria-label="Verify" type="button">
+        Verify
+      </Button>
+    }
+  />
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `buy-investment` + `payout-preferences`. Prefix text / action button live in addon slots.</notes>
+  </example>
+
+  <example title="Read-only clone URL">
+    <tsx><![CDATA[
+<Surface border="all" radius="m" hPadding="m" vPadding="m">
+  <Stack rowGap="m">
+    <Textfield
+      aria-label="Repository clone URL"
+      readOnly
+      value="https://github.com/vira-soft/vira-ui.git"
+      endAddon={<Duplicate size={16} />}
+    />
+    <Text tone="muted">Clone using the web URL.</Text>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From preview-grid `clone-repository`. Read-only value + trailing glyph; no handlers.</notes>
   </example>
 </patterns>

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

@@ -11,6 +11,7 @@
     <item>Custom size or variant props — fixed medium treatment</item>
     <item>Wrapping a lone Textfield in Fieldset when its own label is sufficient — Fieldset is for multi-field sections or shared legends</item>
     <item>Using Fieldset instead of the Textfield label for a single control</item>
+    <item>Inventing CSS `width: 100%` / `w-full` when the `fullWidth` prop covers it</item>
   </when_not_to_use>
   <prop name="description" kind="react">
     <description>Helper copy rendered with `Field.Description` and `Text` while the field is valid.</description>
@@ -25,7 +26,7 @@
     <description>When `true`, sets `field-sizing: content` so the control grows inline with its value. Block chrome stays `var(--vui-textfield-input-height)`. Omitted / `false` keeps the browser fixed default.</description>
   </prop>
   <prop name="fullWidth" kind="react">
-    <description>When `true`, root and control group take `inline-size: 100%`.</description>
+    <description>When `true`, root and control group take `inline-size: 100%`. Prefer this prop over CSS `width: 100%` / `w-full` on the Textfield root. For controls without a `fullWidth` prop (e.g. Button), use a parent Stack `fullWidth` / `expandChildren` instead.</description>
   </prop>
   <prop name="label" kind="react">
     <description>Visible label rendered with shared internal `FieldLabel`.</description>
@@ -33,19 +34,19 @@
   <prop name="startAddon" kind="react">
     <description>Leading decoration (prefix text, icon). Not a second field control.</description>
   </prop>
-  <css_var suffix="control-group-background">
+  <prop name="control-group-background" kind="css">
     <description>Textfield control group background.</description>
-  </css_var>
-  <css_var suffix="control-group-border-color">
+  </prop>
+  <prop name="control-group-border-color" kind="css">
     <description>Textfield control group border color.</description>
-  </css_var>
-  <css_var suffix="control-group-border-radius">
+  </prop>
+  <prop name="control-group-border-radius" kind="css">
     <description>Textfield control group corner radius.</description>
-  </css_var>
-  <css_var suffix="control-group-color">
+  </prop>
+  <prop name="control-group-color" kind="css">
     <description>Textfield control group foreground color.</description>
-  </css_var>
-  <css_var suffix="input-height">
+  </prop>
+  <prop name="input-height" kind="css">
     <description>Textfield control group block size.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,9 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="textfield">
   <do>Single-line text, email, password, or similar native input types</do>
-  <do>Start or end addon slots inside the shared control group</do>
+  <do>Login/signup swap: Tabs panels with Textfield(s) + Button (+ optional Fieldset) inside Stack/Surface — Stack gap/`fullWidth`/`expandChildren` only; 0 custom CSS</do>
+  <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>Label, description, and error copy with validation states</do>
-  <do>Several related Textfields grouped under one section legend as Fieldset children (e.g. billing details)</do>
-  <dont>Passing unsupported size or variant props</dont>
+  <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 unsupported size or variant props — fixed medium treatment</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>