@create-ui/cli 0.5.8 → 0.6.0

package/dist/skills/createui/reference/status-badge.md

@@ -0,0 +1,89 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/status-badge.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/status-badge.md -->
+
+# status-badge
+
+Tiny presence dot only, no built-in label; 12 status colors and xs/sm/md sizes, place text beside it yourself
+
+Install: `npx @create-ui/cli add status-badge`
+
+## Import
+
+```tsx
+import { StatusBadge } from "@/components/ui/status-badge"
+```
+
+Also exported: `statusBadgeVariants`
+
+## StatusBadge props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| danger \| success \| warning \| info \| highlighted \| away \| verified \| cyan \| lime \| neutral \| white` (Error tone is \"danger\" (there is no \"error\" or \"destructive\" key); \"white\" is the only variant that drops the built-in outline ring, for use on dark surfaces) | `primary` |
+| size | `xs \| sm \| md` (Fixed pixel diameters (xs 4px, sm 6px, md 8px); standalone, no Field/InputGroup size cascade) | `md` |
+
+Extends `React.ComponentProps<"span">`.
+
+## Examples
+
+From `status-badge-demo`:
+
+```tsx
+import { StatusBadge } from "@/components/ui/status-badge"
+
+export default function StatusBadgeDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-4">
+      <div className="flex items-center gap-2">
+        <StatusBadge variant="success" />
+        <span className="text-body text-sm">Online</span>
+      </div>
+      <div className="flex items-center gap-2">
+        <StatusBadge variant="away" />
+        <span className="text-body text-sm">Away</span>
+      </div>
+      <div className="flex items-center gap-2">
+        <StatusBadge variant="danger" />
+        <span className="text-body text-sm">Offline</span>
+      </div>
+    </div>
+  )
+}
+```
+
+From `status-badge-in-avatar`:
+
+```tsx
+import { StatusBadge } from "@/components/ui/status-badge"
+
+export default function StatusBadgeInAvatar() {
+  return (
+    <div className="flex flex-wrap items-center gap-6">
+      <div className="relative">
+        <div className="from-light to-weak size-10 rounded-full bg-gradient-to-br" />
+        <StatusBadge variant="success" className="absolute right-0 bottom-0" />
+      </div>
+      <div className="relative">
+        <div className="from-light to-weak size-10 rounded-full bg-gradient-to-br" />
+        <StatusBadge variant="away" className="absolute right-0 bottom-0" />
+      </div>
+      <div className="relative">
+        <div className="from-light to-weak size-10 rounded-full bg-gradient-to-br" />
+        <StatusBadge variant="neutral" className="absolute right-0 bottom-0" />
+      </div>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view status-badge` or MCP `get_item_examples_from_registries` with "status-badge-demo" / "status-badge-example".
+
+## When to use
+StatusBadge is a dot-only presence/state indicator (a single `<span role="status">` circle): online dots on avatars, live markers on rows, status legends. It carries no text; a sibling label or the host element gives it meaning. If the indicator needs a label or count use Badge, for transient events use Toast, and for loading use Spinner.
+
+## Gotchas
+- Do not pass children; the component renders a fixed-size dot (`size-1`/`1.5`/`2`, i.e. 4-8px) and any content would overflow the box. Render the label as a sibling in a flex row: `<StatusBadge variant="success" /> <span>Online</span>`.
+- A white outline ring (`outline-static-white outline`) is built into every variant so the dot stays legible layered over avatars; only the `white` variant removes it (`outline-0`). Do not re-add `ring-*` or borders to fake this.
+- Avatar pinning is manual composition: wrap the avatar in `relative` and position the badge with `className="absolute right-0 bottom-0"`. There is no `position`/anchor prop.
+- This is not shadcn's `Badge`: no text slot and no `asChild`.
+- `role="status"` is hardcoded, but the dot has no announced content, so pair it with a visible text label or put `aria-label` on the surrounding element.
+- No `data-variant`/`data-size` attributes are emitted; CSS targeting goes through `data-slot="status-badge"` plus classes. `shrink-0` is built in, so it will not squash in tight flex rows.

package/dist/skills/createui/reference/switch-group.md

@@ -0,0 +1,122 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/switch-group.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/switch-group.md -->
+
+# switch-group
+
+Field wrapper that labels a Switch and cascades variant, size, shape, thumbType and ioTrigger; placement left or right
+
+Install: `npx @create-ui/cli add switch-group`
+
+## Import
+
+```tsx
+import { SwitchGroup } from "@/components/ui/switch-group"
+```
+
+Also exported: `switchGroupVariants`
+
+## SwitchGroup props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `SwitchVariant` | `primary` |
+| size | `xs \| sm \| md` (Sets the Field label scale and the child Switch size via context; Field's own size and orientation props are stripped from the API (orientation is locked horizontal)) | `md` |
+| shape | `SwitchShape` | `pill` |
+| thumbType | `SwitchThumbType` | `short` |
+| ioTrigger | `boolean` | `false` |
+| placement | `left \| right` (right is a CSS-only flip (flex-row-reverse); keep the Switch first in the DOM either way) | `left` |
+
+Extends `React.ComponentProps<typeof Field>`.
+
+## Examples
+
+From `switch-group-demo`:
+
+```tsx
+import { FieldContent } from "@/components/ui/field"
+import { Label, LabelDescription, LabelMain } from "@/components/ui/label"
+import { Switch } from "@/components/ui/switch"
+import { SwitchGroup } from "@/components/ui/switch-group"
+
+export default function SwitchGroupDemo() {
+  return (
+    <SwitchGroup className="w-[340px]">
+      <Switch id="sw-demo" defaultChecked />
+      <FieldContent>
+        <LabelMain>
+          <Label htmlFor="sw-demo">Push notifications</Label>
+          <LabelDescription>
+            Get alerts the moment something happens on your account.
+          </LabelDescription>
+        </LabelMain>
+      </FieldContent>
+    </SwitchGroup>
+  )
+}
+```
+
+From `switch-group-disabled`:
+
+```tsx
+import { FieldContent } from "@/components/ui/field"
+import { Label, LabelDescription, LabelMain } from "@/components/ui/label"
+import { Switch } from "@/components/ui/switch"
+import { SwitchGroup } from "@/components/ui/switch-group"
+
+export default function SwitchGroupDisabled() {
+  return (
+    <div className="flex flex-col gap-6">
+      <SwitchGroup disabled className="w-[340px]">
+        <Switch id="sw-disabled-on" checked disabled />
+        <FieldContent>
+          <LabelMain>
+            <Label htmlFor="sw-disabled-on">Push notifications</Label>
+            <LabelDescription>
+              Disabled state cascades to label and description.
+            </LabelDescription>
+          </LabelMain>
+        </FieldContent>
+      </SwitchGroup>
+
+      <SwitchGroup disabled className="w-[340px]">
+        <Switch id="sw-disabled-off" checked={false} disabled />
+        <FieldContent>
+          <LabelMain>
+            <Label htmlFor="sw-disabled-off">Marketing emails</Label>
+            <LabelDescription>
+              The unchecked row reads muted too.
+            </LabelDescription>
+          </LabelMain>
+        </FieldContent>
+      </SwitchGroup>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view switch-group` or MCP `get_item_examples_from_registries` with "switch-group-demo" / "switch-group-example".
+
+## When to use
+One labelled switch row for settings that apply the moment they flip: notification preferences, feature flags, privacy toggles. Stack several SwitchGroups in a column for a settings panel. Do NOT use it inside a submit-to-save form (use CheckboxGroup), for one-of-many selection (use RadioGroup), or for a bare unlabelled toggle in a toolbar or table cell (use Switch directly).
+
+## Gotchas
+- Despite the name, SwitchGroup is a single row, not a multi-switch container, and it renders no Switch of its own. There is no SwitchGroupItem; you compose the anatomy yourself:
+
+```tsx
+<SwitchGroup>
+  <Switch id="x" />
+  <FieldContent>
+    <LabelMain>
+      <Label htmlFor="x">Title</Label>
+      <LabelDescription>Optional helper.</LabelDescription>
+    </LabelMain>
+    <FieldFooter>{/* optional, e.g. TextLink */}</FieldFooter>
+  </FieldContent>
+</SwitchGroup>
+```
+
+- The child Switch resolves each look prop as explicit prop ?? SwitchContext ?? default, so any prop set directly on the Switch silently overrides the group; configure looks on the group and keep the Switch bare except id/checked/disabled.
+- The context the group provides carries variant, size, shape, thumbType, ioTrigger only. SwitchGroup has no thumbIcon prop and never forwards one; set thumbIcon on the Switch itself.
+- Label association is manual: the Field root is a role="group" div, not a label, so always pair Switch id with Label htmlFor.
+- For a disabled row, set disabled on BOTH the group (label/description fade via Field) and the child Switch (the actual control), as in switch-group-disabled.
+- The label block must sit inside FieldContent: Field only top-aligns the switch when a direct [data-slot=field-content] child exists (has-[] selector), so loose Label siblings sit in a row and break the stacking.
+- SwitchGroup is a Field, so its root is full-width: placed inline (e.g. the right side of a justify-between header or toolbar) it wraps onto its own full-width line unless you constrain it with an explicit width (className="w-auto", max-w-*, or a fixed width).

package/dist/skills/createui/reference/switch.md

@@ -0,0 +1,75 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/switch.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/switch.md -->
+
+# switch
+
+Toggle switch; variant primary/info/neutral/inverse/semantic, thumbType short/long, ioTrigger and thumbIcon options
+
+Install: `npx @create-ui/cli add switch`
+
+## Import
+
+```tsx
+import { Switch } from "@/components/ui/switch"
+```
+
+Also exported: `SwitchContext`, `switchVariants`
+
+## Switch props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| info \| neutral \| inverse \| semantic` (semantic = red when off, green when on (accept/reject patterns)) | `primary` |
+| size | `md \| sm \| xs` | `md` |
+| shape | `pill \| rounded` | `pill` |
+| thumbType | `short \| long` (long is a statically wider thumb and track; checked travel distance is unchanged) | `short` |
+| ioTrigger | `boolean` (aria-hidden I/O glyphs in the track: line when on, circle when off) | `false` |
+| thumbIcon | `boolean` (aria-hidden check/close icons inside the thumb) | `false` |
+
+Extends `React.ComponentProps<typeof SwitchPrimitive.Root>`.
+
+## Examples
+
+From `switch-demo`:
+
+```tsx
+import { Switch } from "@/components/ui/switch"
+
+export default function SwitchDemo() {
+  return (
+    <div className="flex items-center gap-3">
+      <Switch defaultChecked />
+      <Switch />
+    </div>
+  )
+}
+```
+
+From `switch-thumb-icon`:
+
+```tsx
+import { Switch } from "@/components/ui/switch"
+
+export default function SwitchThumbIcon() {
+  return (
+    <div className="flex items-center gap-4">
+      <Switch thumbIcon defaultChecked />
+      <Switch thumbIcon />
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view switch` or MCP `get_item_examples_from_registries` with "switch-demo" / "switch-example".
+
+## When to use
+
+A single standalone on/off control. A boolean that only commits on form submit is `Checkbox`. A switch with a label and description in one apply-immediately row is `SwitchGroup` (it wraps `Field orientation="horizontal"` and feeds `SwitchContext`); do not hand-roll that row from `Field` + `Switch`. Exception: inside a submit-to-save form that deliberately uses toggles, `SwitchGroup` is wrong - compose `Field size="md" orientation="horizontal"` + `FieldContent` (`FieldLabel` + `FieldDescription`) + `Switch`, as in the field-composition example.
+
+## Gotchas
+
+- Every visual prop resolves `prop ?? SwitchContext ?? default`. `SwitchGroup` provides context for `variant`/`size`/`shape`/`thumbType`/`ioTrigger`, so set those on the group, not the inner Switch. `thumbIcon` is NOT in the group context; set it on the Switch itself. For an ad-hoc cluster, wrap in the exported `SwitchContext.Provider`.
+- `Field` size does NOT cascade here: Switch reads only `SwitchContext`, never Field's context. In a plain `Field` row, set `size` on the Switch itself.
+- Do not pass children to `<Switch>`; it renders its own thumb/icon internals and silently replaces anything you pass. The label lives outside (`Label htmlFor` + `id`, or `aria-label`).
+- Track width is a fixed pixel value per `size` x `thumbType`, and the checked `translate-x` is fixed per `size` (22/18/14px). Overriding width via `className` desyncs the thumb travel; change `size`/`thumbType` instead.
+- The clickable area is silently enlarged by an `after:` pseudo-element (12px horizontally, 8px vertically past the track); keep other clickable controls clear of that zone.
+- Error state comes from passing `aria-invalid` (persistent red outline), not from a variant.

package/dist/skills/createui/reference/tab-menu.md

@@ -0,0 +1,165 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/tab-menu.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/tab-menu.md -->
+
+# tab-menu
+
+Navigation tab list with no content panels; vertical/horizontal button and line variants, leadingIcon/trailingIcon items
+
+Install: `npx @create-ui/cli add tab-menu`
+
+## Import
+
+```tsx
+import { TabMenu, TabMenuItem } from "@/components/ui/tab-menu"
+```
+
+Also exported: `tabMenuVariants`, `tabMenuItemVariants`
+
+## TabMenu props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `vertical-button \| vertical-line \| horizontal-line \| horizontal-button` | `vertical-button` |
+| size | `sm \| md \| lg` | `md` |
+| indicator | `left \| top \| bottom` (line variants render no active line without it; designed pairings: vertical-button+left, vertical-line/horizontal-line+top|bottom; horizontal-button takes none) | - |
+| value | `string` | - |
+| defaultValue | `string` | - |
+| onValueChange | `(value: string) => void` | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## TabMenuItem props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | `false` |
+| value | `string` | - |
+| selected | `boolean` (overrides value matching; use for route-driven tabs where the pathname decides) | - |
+| leadingIcon | `ReactNode` | - |
+| trailingIcon | `ReactNode` | - |
+| label | `ReactNode` (the label slot; bare children are NOT the label (they render as extra content next to it, e.g. a Badge)) | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## Icons
+
+Icons go through icon props - never as children next to text, and never with sizing classes (the component sizes icons per `size`): `TabMenuItem` (`leadingIcon` / `trailingIcon`). Import icons from `@create-ui/assets/icons` (Remix `Ri*`).
+
+## Examples
+
+From `tab-menu-demo`:
+
+```tsx
+import {
+  RiBankCardFill,
+  RiInboxLine,
+  RiInformationFill,
+  RiSettings6Fill,
+} from "@create-ui/assets/icons"
+
+import { TabMenu, TabMenuItem } from "@/components/ui/tab-menu"
+
+export default function TabMenuDemo() {
+  return (
+    <TabMenu
+      variant="horizontal-line"
+      indicator="bottom"
+      size="lg"
+      defaultValue="activity"
+    >
+      <TabMenuItem
+        value="overview"
+        leadingIcon={<RiInformationFill />}
+        label="Overview"
+      />
+      <TabMenuItem
+        value="activity"
+        leadingIcon={<RiInboxLine />}
+        label="Activity"
+      />
+      <TabMenuItem
+        value="billing"
+        leadingIcon={<RiBankCardFill />}
+        label="Billing"
+      />
+      <TabMenuItem
+        value="settings"
+        leadingIcon={<RiSettings6Fill />}
+        label="Settings"
+      />
+    </TabMenu>
+  )
+}
+```
+
+From `tab-menu-with-badge`:
+
+```tsx
+import {
+  RiBankCardFill,
+  RiInboxLine,
+  RiSettings6Fill,
+} from "@create-ui/assets/icons"
+
+import { Badge } from "@/components/ui/badge"
+import { StatusBadge } from "@/components/ui/status-badge"
+import { TabMenu, TabMenuItem } from "@/components/ui/tab-menu"
+
+export default function TabMenuWithBadge() {
+  return (
+    <TabMenu
+      className="w-[320px]"
+      variant="vertical-button"
+      size="lg"
+      defaultValue="activity"
+    >
+      <TabMenuItem
+        value="activity"
+        leadingIcon={<RiInboxLine />}
+        label="Activity"
+      >
+        <Badge variant="info" appearance="soft" size="sm">
+          12
+        </Badge>
+      </TabMenuItem>
+      <TabMenuItem
+        value="billing"
+        leadingIcon={<RiBankCardFill />}
+        label="Billing"
+      >
+        <Badge variant="success" appearance="soft" size="sm">
+          New
+        </Badge>
+      </TabMenuItem>
+      <TabMenuItem
+        value="settings"
+        leadingIcon={<RiSettings6Fill />}
+        label="Settings"
+      >
+        <StatusBadge variant="primary" size="md" />
+      </TabMenuItem>
+    </TabMenu>
+  )
+}
+```
+
+More: `npx @create-ui/cli view tab-menu` or MCP `get_item_examples_from_registries` with "tab-menu-demo" / "tab-menu-example".
+
+## When to use
+
+Tab-style navigation: settings sidebars, section switchers, routed nav as links. TabMenu renders the tab list only; there are no content-panel components, so render panels yourself keyed by the active value (`{tab === "billing" && <BillingPanel />}`). For 2-5 inline mutually exclusive options without rich item content, use SegmentedControl instead.
+
+## Gotchas
+
+- There is no shadcn-style `Tabs` / `TabsList` / `TabsTrigger` / `TabsContent` set; do not invent one. `TabMenu` itself owns the value (`defaultValue`, or controlled `value` + `onValueChange`) and that is the whole API.
+- Text goes in the `label` prop; bare children are NOT the label, they render as extra content beside it (the badge slot, see tab-menu-with-badge). Icons only via `leadingIcon` / `trailingIcon`, never as children.
+- `asChild` needs exactly one non-Fragment element child or it silently falls back to a plain `<button>`. The child's own text becomes the label (`label` is only a fallback when the child has no children) and the extra-children badge slot is unavailable; icons stay as props on `TabMenuItem`:
+
+```tsx
+<TabMenuItem asChild value="billing" leadingIcon={<RiBankCardFill />}>
+  <Link href="/billing">Billing</Link>
+</TabMenuItem>
+```
+
+- Line variants show no active marker beyond text color unless `indicator` is set; button variants (`vertical-button`, `horizontal-button`) get the sliding `bg-weak` pill automatically.
+- This is not ARIA tabs: a `role="group"` of `aria-pressed` buttons where every item is its own Tab stop; there is no arrow-key roving like Radix Tabs. asChild items get no `aria-pressed`; their `disabled` maps to `aria-disabled` + `tabIndex={-1}`.
+- An item `onClick` that calls `event.preventDefault()` blocks the value commit; `disabled` items skip both `onClick` and `onValueChange`.

package/dist/skills/createui/reference/text-link.md

@@ -0,0 +1,84 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/text-link.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/text-link.md -->
+
+# text-link
+
+Inline anchor link with six color variants; underline, visited and disabled states, leadingIcon/trailingIcon, asChild
+
+Install: `npx @create-ui/cli add text-link`
+
+## Import
+
+```tsx
+import { TextLink } from "@/components/ui/text-link"
+```
+
+Also exported: `textLinkVariants`
+
+## TextLink props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| inverse \| danger \| success \| info` | `primary` |
+| size | `xs \| sm \| md \| lg` | `md` |
+| visited | `boolean` (Prop-controlled only (purple-500 text, violet underline); the component never reacts to the CSS :visited pseudo-class) | `false` |
+| disabled | `boolean` (Sets aria-disabled, tabIndex=-1 and pointer-events-none but keeps href; remove href yourself if the target is meaningless) | `false` |
+| asChild | `boolean` (The child's own children become the label; TextLink clones the child and re-injects the label wrapped in its content/underline/icon spans) | `false` |
+| leadingIcon | `ReactNode` | - |
+| trailingIcon | `ReactNode` | - |
+| underline | `boolean` (Renders a hairline span (data-slot=text-link-underline), not text-decoration; base forces no-underline, so use this prop, never the Tailwind underline class) | `false` |
+
+Extends `React.ComponentProps<"a">`.
+
+## Icons
+
+Icons go through icon props - never as children next to text, and never with sizing classes (the component sizes icons per `size`): `TextLink` (`leadingIcon` / `trailingIcon`). Import icons from `@create-ui/assets/icons` (Remix `Ri*`).
+
+## Examples
+
+From `text-link-demo`:
+
+```tsx
+import { TextLink } from "@/components/ui/text-link"
+
+export default function TextLinkDemo() {
+  return <TextLink href="#">Read the documentation</TextLink>
+}
+```
+
+From `text-link-in-prose`:
+
+```tsx
+import { TextLink } from "@/components/ui/text-link"
+
+export default function TextLinkInProse() {
+  return (
+    <p className="text-paragraph-md text-body max-w-prose">
+      Create UI ships components as source files you copy into your project.
+      Start with the{" "}
+      <TextLink href="#" underline>
+        installation guide
+      </TextLink>{" "}
+      to scaffold a new app, then browse the{" "}
+      <TextLink href="#">component reference</TextLink> to see every primitive
+      in one place.
+    </p>
+  )
+}
+```
+
+More: `npx @create-ui/cli view text-link` or MCP `get_item_examples_from_registries` with "text-link-demo" / "text-link-example".
+
+## When to use
+Inline link inside body copy, list items, table cells, and helper text, where the control must read as text in the line, not as a button. Renders a native `<a>` by default, or slots a router link (`next/link` etc.) via `asChild`. Do not use it when the control needs a filled hit area (use `Button`, optionally `asChild` over an `<a>`), for menu rows (`DropdownMenuItem`), or for breadcrumb trails (`BreadcrumbItem`).
+
+## Gotchas
+- There is no `as` prop: the root is always `<a>` unless `asChild` swaps in the child element. For a non-navigation click action, slot a `<button>` via `asChild`.
+- `asChild` is smarter than a plain shadcn Slot: icons and `underline` still work because TextLink extracts the child's children as the label and clones the child with its own internal spans. The child must be a single valid element:
+```tsx
+<TextLink asChild underline trailingIcon={<RiArrowRightSLine />}>
+  <Link href="/docs">Continue</Link>
+</TextLink>
+```
+- The label span is `whitespace-nowrap`: a multi-word link mid-sentence never wraps and can overflow narrow prose containers; keep labels short or override on `[data-slot=text-link-content]`.
+- Focus is an `outline-*` treatment (transparent at rest, colored on focus-visible) per the system-wide outline rule; do not add `ring-*` via className.
+- The label span carries small per-size horizontal padding (`px-0.5` to `px-1.5`), so the link text never sits perfectly flush with adjacent prose.

package/dist/skills/createui/reference/textarea.md

@@ -0,0 +1,50 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/textarea.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/textarea.md -->
+
+# textarea
+
+Multi-line text input; size and state inherit from Field, resizable x/y/both with custom grip, loading spinner overlay
+
+Install: `npx @create-ui/cli add textarea`
+
+## Import
+
+```tsx
+import { Textarea } from "@/components/ui/textarea"
+```
+
+Also exported: `textareaVariants`
+
+## Textarea props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` | `sm` |
+| resizable | `x \| y \| both` (Use this prop, never resize-x/resize-y classes; base is resize-none and the prop hides the webkit grip and overlays the custom corner glyph.) | - |
+| loading | `boolean` (Makes the textarea readOnly + aria-busy with pointer-events-none, NOT disabled; it stays in the tab order and its value still submits.) | - |
+
+Extends `React.ComponentProps<"textarea">`.
+
+## Examples
+
+From `textarea-demo`:
+
+```tsx
+import { Textarea } from "@/components/ui/textarea"
+
+export default function TextareaDemo() {
+  return <Textarea placeholder="Write something..." />
+}
+```
+
+More: `npx @create-ui/cli view textarea` or MCP `get_item_examples_from_registries` with "textarea-demo" / "textarea-example".
+
+## When to use
+Multi-line free text: bios, messages, feedback, descriptions, comments. For single-line input use `Input`. Never place a raw `Textarea` inside an `InputGroup`; use `InputGroupTextarea` there, since the group manages size and state through its own context.
+
+## Gotchas
+- Field cascade: `size`, `loading`, and `disabled` resolve as explicit prop ?? Field context ?? default, so explicit props win. `invalid` is OR-combined instead: `<Field invalid>` alone flips the error styling, sets `aria-invalid`, and renders the warning icon, and `aria-invalid={false}` on the textarea cannot cancel it.
+- The DOM shape changes with state: a `data-slot="textarea-wrapper"` div only exists when `resizable` is set or a status icon (loading/invalid) is showing; otherwise the bare `<textarea>` is returned. `className` always lands on the textarea itself, but parent-selector CSS can break across states.
+- `loading` is not `disabled`: it sets `readOnly`, `aria-busy`, and `pointer-events-none`. If you need the field skipped on submit, set `disabled` too. When `loading` and invalid are both true, the spinner wins over the warning icon.
+- Resize must go through the `resizable` prop. Adding `resize-y` via `className` shows the native browser grip with no design-system glyph; the prop hides the webkit resizer and grid-stacks the custom corner icon.
+- The status icon (spinner / `RiErrorWarningLine`) renders bottom-LEFT inside the textarea and is `aria-hidden`; spinner size auto-pairs with the textarea size. Communicate the actual error text via `FieldHelper`, not the icon.
+- Base height is `min-h-[132px]`, so small `rows` values have no visible effect; override height with a `min-h-*` class.