@create-ui/cli 0.5.7 → 0.5.9

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

@@ -0,0 +1,157 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/pagination.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/pagination.md -->
+
+# pagination
+
+Page navigation with first/prev/next/last actions and ellipsis; compact or ButtonGroup-backed compact-grouped variant
+
+Install: `npx @create-ui/cli add pagination`
+
+## Import
+
+```tsx
+import { Pagination, PaginationContent, PaginationLink, PaginationFirst, PaginationPrevious, PaginationNext, PaginationLast, PaginationEllipsis } from "@/components/ui/pagination"
+```
+
+## Pagination props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `compact \| compact-grouped` (compact-grouped renders PaginationContent as a soft md ButtonGroup (one fused surface); compact renders standalone buttons with gap-1.) | `compact-grouped` |
+| shape | `rounded \| pill` (Settable on the root Pagination only; children have no shape prop and pick it up from context.) | `rounded` |
+
+Extends `React.ComponentProps<"nav">`.
+
+## PaginationLink props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+| isActive | `boolean` (Writes aria-current=page and data-active; in compact-grouped it maps to ButtonGroupItem active with aria-pressed deliberately stripped.) | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## PaginationFirst props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## PaginationPrevious props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## PaginationNext props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## PaginationLast props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## Examples
+
+From `pagination-demo`:
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from "@/components/ui/pagination"
+
+export default function PaginationDemo() {
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationPrevious />
+        <PaginationLink>1</PaginationLink>
+        <PaginationLink>2</PaginationLink>
+        <PaginationLink isActive>3</PaginationLink>
+        <PaginationEllipsis />
+        <PaginationLink>10</PaginationLink>
+        <PaginationNext />
+      </PaginationContent>
+    </Pagination>
+  )
+}
+```
+
+From `pagination-with-link`:
+
+```tsx
+"use client"
+
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from "@/components/ui/pagination"
+
+export default function PaginationWithLink() {
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationPrevious asChild>
+          <a href="?page=2" />
+        </PaginationPrevious>
+        <PaginationLink asChild>
+          <a href="?page=1">1</a>
+        </PaginationLink>
+        <PaginationLink asChild>
+          <a href="?page=2">2</a>
+        </PaginationLink>
+        <PaginationLink asChild isActive>
+          <a href="?page=3" aria-current="page">
+            3
+          </a>
+        </PaginationLink>
+        <PaginationEllipsis />
+        <PaginationLink asChild>
+          <a href="?page=10">10</a>
+        </PaginationLink>
+        <PaginationNext asChild>
+          <a href="?page=4" />
+        </PaginationNext>
+      </PaginationContent>
+    </Pagination>
+  )
+}
+```
+
+More: `npx @create-ui/cli view pagination` or MCP `get_item_examples_from_registries` with "pagination-demo" / "pagination-example".
+
+## When to use
+Numbered page navigation for long tables, search results, and archives where users jump between page ranges. Do not use it for switching sibling panels in place (use TabMenu), hierarchical trails (use Breadcrumb), or a plain prev/next pair without page numbers (use two Buttons). For a value-picking segmented control, use SegmentedControl or ButtonGroup directly.
+
+## Gotchas
+- There is no PaginationItem wrapper (shadcn habit): controls are direct children of PaginationContent. PaginationContent is mandatory; in the default compact-grouped variant it IS the ButtonGroup, so dropping it loses the fused surface and sizing.
+- PaginationLink renders a `<button type="button">` by default, not an `<a>` like shadcn. For URL navigation use asChild with an anchor or router Link; isActive keeps working because aria-current and active styling are forwarded onto the slotted element (see pagination-with-link).
+- First/Previous/Next/Last inject their default arrow icon even with asChild: pass an empty anchor and the icon plus the built-in "Go to ... page" aria-label are supplied automatically; any children of the slotted element are replaced by the icon. Without asChild, `children` replaces the icon instead.
+```tsx
+<PaginationNext asChild>
+  <a href="?page=4" />
+</PaginationNext>
+```
+- With asChild, `disabled` is not forwarded as a native attribute; the slotted element gets `aria-disabled` plus `tabIndex={-1}` and pointer-events-none styling, so disabled links stay in the DOM but become inert and unfocusable.
+- No size prop exists anywhere; compact-grouped is hard-wired to ButtonGroup soft/md and compact items to a fixed h-8. Do not try to pass size to the content or items.
+- PaginationEllipsis is presentational (`role="presentation"`, `aria-hidden`) with a built-in sr-only "More pages" hint; `children` only swaps the visible glyph. Render real PaginationLinks for clickable pages (see pagination-controlled for the windowing pattern).

package/dist/skills/createui/reference/password-strength.md

@@ -0,0 +1,70 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/password-strength.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/password-strength.md -->
+
+# password-strength
+
+Password meter with five segments driven by a 0-5 strength prop plus an optional checklist of rules
+
+Install: `npx @create-ui/cli add password-strength`
+
+## Import
+
+```tsx
+import { PasswordStrength } from "@/components/ui/password-strength"
+```
+
+## PasswordStrength props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Standalone prop - not inherited from Field or InputGroup context; mirror the sibling password field's size manually.) | `md` |
+| strength | `StrengthLevel` (How many of the 5 segments fill (0-5); the component computes nothing - derive the level from the password value yourself.) | `0` |
+| rules | `PasswordStrengthRule[]` (Omit (or pass an empty array) to hide the whole checklist section and its divider; each rule is just { label, met }.) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `input-group-password`:
+
+```tsx
+import { RiLock2Line } from "@create-ui/assets/icons"
+
+import { Field, FieldLabel } from "@/components/ui/field"
+import {
+  InputGroup,
+  InputGroupControl,
+  InputGroupSlot,
+} from "@/components/ui/input-group"
+
+export default function InputGroupPassword() {
+  return (
+    <Field className="max-w-100">
+      <FieldLabel htmlFor="input-group-password-input">Password</FieldLabel>
+      <InputGroup>
+        <InputGroupSlot>
+          <RiLock2Line />
+          <InputGroupControl
+            id="input-group-password-input"
+            type="password"
+            placeholder="••••••••••••"
+            defaultValue="mysecretpassword"
+          />
+        </InputGroupSlot>
+      </InputGroup>
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view password-strength` or MCP `get_item_examples_from_registries` with "password-strength-demo" / "password-strength-example".
+
+## When to use
+Read-only feedback card shown alongside a password field: a five-segment strength meter plus an optional "Your password must include:" checklist. It contains no input and no scoring algorithm, so pair it with a separate `InputGroup` + `InputGroupControl type="password"` (or `Input type="password"`) and recompute `strength`/`rules` on every change. For a generic completion bar use `Progress`; for the password field itself use `Input`/`InputGroup`, never this.
+
+## Gotchas
+- Fully controlled and dumb: no value prop, no onChange, no built-in zxcvbn-style scoring. You own the evaluation (e.g. count met rules) and pass the result in as `strength` and `rules`.
+- All copy is hardcoded English: the checklist heading "Your password must include:", the level labels ("Too Weak" through "Very Strong"), and the per-level meter colors (red/orange/yellow/lime/green). No props exist to relabel, localize, or recolor them.
+- `strength={0}` is the legitimate pristine state: all five segments render unfilled and the level label is omitted (only the "Password Strength" caption shows). Do not conditionally unmount the component to get an empty meter.
+- Rule icons are automatic: `met: true` renders a check (RiCheckFill), `met: false` a cross (RiCloseFill). You supply only `label` and `met`; there is no per-rule icon slot.
+- The checklist renders ABOVE the meter in DOM order (rules, divider, then meter); the meter section always renders, and the divider appears and disappears with the checklist.
+- Met rule rows carry `data-met` (absent when unmet); the root has `data-slot="password-strength"` and `data-size` as external styling hooks.

package/dist/skills/createui/reference/phone-input.md

@@ -0,0 +1,77 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/phone-input.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/phone-input.md -->
+
+# phone-input
+
+Phone number input with a country flag select and dial code prefix; onValueChange emits the E.164 value
+
+Install: `npx @create-ui/cli add phone-input`
+
+## Import
+
+```tsx
+import { PhoneInput } from "@/components/ui/phone-input"
+```
+
+## PhoneInput props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| defaultValue | `string` (E.164 or national digits; the dial code is stripped only when it matches the active country, so pair it with the matching defaultCountry) | - |
+| defaultCountry | `PhoneCountryCode` | `DE` |
+| country | `PhoneCountryCode` | - |
+| onCountryChange | `(country: PhoneCountryCode) => void` | - |
+| onValueChange | `(value: string, details: PhoneInputDetails) => void` (Emits the full E.164 string ('' when empty) plus { country, dialCode, nationalNumber }; re-fires immediately when the country changes) | - |
+| countries | `PhoneCountryConfig[]` (Subset or reorder the dropdown; build entries from PHONE_COUNTRIES exported by use-phone-input (default: every country, sorted by English name)) | - |
+| size | `xs \| sm \| md` (Omit inside Field; InputGroup resolves it from Field context (falls back to sm)) | - |
+| invalid | `boolean` | - |
+| disabled | `boolean` | - |
+| loading | `boolean` | - |
+| showHelperIcon | `boolean` | `true` |
+| helperIcon | `ReactNode` | - |
+| helperTooltip | `ReactNode` (Pass null to keep the helper icon without a tooltip; hide the icon entirely with showHelperIcon={false}) | `Enter your phone number without the country code.` |
+| className | `string` | - |
+| ref | `React.Ref<HTMLInputElement>` | - |
+
+Extends `React.ComponentProps<"input">`.
+
+## Examples
+
+From `input-group-phone`:
+
+```tsx
+"use client"
+
+import { Field, FieldLabel } from "@/components/ui/field"
+import { PhoneInput } from "@/components/ui/phone-input"
+
+export default function InputGroupPhone() {
+  return (
+    <Field className="max-w-md">
+      <FieldLabel htmlFor="input-group-phone">Phone Number</FieldLabel>
+      <PhoneInput
+        id="input-group-phone"
+        defaultCountry="US"
+        onValueChange={(value, { country }) => console.log(value, country)}
+      />
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view phone-input` or MCP `get_item_examples_from_registries` with "phone-input-demo" / "phone-input-example".
+
+## When to use
+Complete phone-number field: country flag select, display-only dial code prefix, auto-formatting national-digit input, and an E.164 value via onValueChange. Use it whenever a form collects a phone number; do not rebuild it from InputGroup + InputGroupSelect + CountryFlag, because it already is exactly that composition. For other prefix-plus-select combos (amount, currency) compose InputGroup directly, and for plain text use Input.
+
+## Gotchas
+- It renders its own InputGroup; never nest it inside another InputGroup. Wrap it in Field for the label, and leave size/invalid/disabled/loading unset there so they cascade from Field context.
+- The text value cannot be controlled: native value/onChange are stripped from the prop type. Seed with defaultValue and read through onValueChange. Only the country supports controlled mode (country + onCountryChange).
+- The country is never auto-detected from the value (unlike react-phone-number-input). The dial code in defaultValue is stripped only when it matches the active country, so an E.164 defaultValue must ship with the matching defaultCountry or the dial digits leak into the national number:
+
+```tsx
+<PhoneInput defaultCountry="US" defaultValue="+15551234567" />
+```
+
+- The visible input holds national digits only, live-formatted per country by libphonenumber's AsYouType; the dial code is a display-only span. The E.164 string exists solely in the onValueChange payload, and an empty input emits "" rather than the bare dial code.
+- Switching country keeps the typed digits and instantly re-fires onValueChange with the new dial code applied to the same national number.
+- Non-digit keystrokes are stripped on input; do not layer your own masking or formatting on top.

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

@@ -0,0 +1,158 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/progress.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/progress.md -->
+
+# progress
+
+Determinate progress as a line or circle via the type prop; solid or gradient appearance, value/max with animated fill
+
+Install: `npx @create-ui/cli add progress`
+
+## Import
+
+```tsx
+import { Progress } from "@/components/ui/progress"
+```
+
+Also exported: `progressLineVariants`
+
+## Progress props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| type | `line \| circle` | `line` |
+| variant | `primary \| info \| success \| warning \| danger \| away \| neutral \| neutral-static \| neutral-soft \| inverse \| inverse-static \| inverse-soft` | `primary` |
+| appearance | `solid \| gradient` | `solid` |
+| size | `xs \| sm \| md \| lg` (Line: bar thickness; circle: fixed outer diameter (12/16/20/24px) with matching stroke width) | `md` |
+| shape | `sharp \| pill` (Visual effect on line only; the circle ring renders identically and merely emits data-shape) | `pill` |
+| value | `number` | `0` |
+| max | `number` (Values <= 0 silently fall back to 100; value is clamped to 0..max for both fill width and aria-valuenow) | `100` |
+| duration | `number` (Line only; overrides the default 300ms ease-out width transition. type=circle discards it (the ring has no transition at all)) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `progress-demo`:
+
+```tsx
+import { Progress } from "@/components/ui/progress"
+
+export default function ProgressDemo() {
+  return (
+    <div className="flex items-center gap-8">
+      <div className="w-64">
+        <Progress value={42} />
+      </div>
+      <Progress type="circle" size="lg" value={42} />
+    </div>
+  )
+}
+```
+
+From `progress-upload`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+import {
+  RiCheckLine,
+  RiRefreshLine,
+  RiUploadCloud2Line,
+} from "@create-ui/assets/icons"
+
+import { Button } from "@/components/ui/button"
+import { Progress } from "@/components/ui/progress"
+
+const DURATION_MS = 2000
+
+type Status = "idle" | "uploading" | "done" | "error"
+
+export default function ProgressUpload() {
+  const [attempt, setAttempt] = React.useState(0)
+  const [status, setStatus] = React.useState<Status>("idle")
+  const [progress, setProgress] = React.useState(0)
+
+  React.useEffect(() => {
+    if (status !== "uploading") return
+
+    // First attempt fails to demo the retry flow, later attempts succeed.
+    const willFail = attempt === 1
+    const target = willFail ? 60 : 100
+
+    const raf = requestAnimationFrame(() => setProgress(target))
+    const timeout = setTimeout(
+      () => setStatus(willFail ? "error" : "done"),
+      DURATION_MS
+    )
+
+    return () => {
+      cancelAnimationFrame(raf)
+      clearTimeout(timeout)
+    }
+  }, [status, attempt])
+
+  function startUpload() {
+    setProgress(0)
+    setAttempt((a) => a + 1)
+    setStatus("uploading")
+  }
+
+  const isUploading = status === "uploading"
+  const isDone = status === "done"
+  const isError = status === "error"
+
+  const variant = isDone ? "success" : isError ? "danger" : "primary"
+
+  return (
+    <div className="flex w-80 items-center gap-4">
+      <Progress
+        key={attempt}
+        value={progress}
+        duration={DURATION_MS}
+        variant={variant}
+      />
+      <Button
+        variant={variant}
+        loading={isUploading}
+        leadingIcon={
+          isDone ? (
+            <RiCheckLine />
+          ) : isError ? (
+            <RiRefreshLine />
+          ) : (
+            <RiUploadCloud2Line />
+          )
+        }
+        onClick={startUpload}
+        className="w-32 shrink-0"
+      >
+        {isDone
+          ? "Done"
+          : isError
+            ? "Retry"
+            : isUploading
+              ? "Uploading"
+              : "Upload"}
+      </Button>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view progress` or MCP `get_item_examples_from_registries` with "progress-demo" / "progress-example".
+
+## When to use
+Determinate progress against a known total: uploads, multi-step flows, download bars, and compact dashboard stat rings (type="circle"). Do not use it when duration or total is unknown; use Spinner for indeterminate loading. For a passive status or count that does not track completion, use Badge or Status Badge.
+
+## Gotchas
+- Single self-closing component built on plain divs, not Radix: there is no Root/Indicator subcomponent and `children` is type-omitted, so the shadcn pattern `<Progress><ProgressIndicator /></Progress>` will not compile. Render labels or percentage text outside the component.
+- `type="line"` is `w-full` and stretches to fill its parent; always wrap it in a width-constrained container. `type="circle"` sets width/height via inline style from `size`, so className width utilities cannot resize the ring.
+- Every `value` change animates the line width. To restart a fill from 0 (e.g. a retry), remount with a `key` and set the target value on the next frame, as progress-upload does; resetting value in place animates the bar backward first.
+
+```tsx
+<Progress key={attempt} value={progress} duration={2000} variant={isError ? "danger" : "primary"} />
+```
+
+- The root carries `role="progressbar"` and aria-valuemin/max/now automatically but has no accessible name; pass `aria-label` yourself (div props pass through).
+- The circle is pure CSS (conic-gradient arc + radial mask), no SVG, so there are no stroke props. The arc paints with `currentColor`; a `text-*` class on the component recolors it (the inline-styled indicator cannot be themed via `data-slot` CSS).
+- `inverse*` variants render in white/static-white tones for dark surfaces; the examples place them on a `bg-strongest` canvas.

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

@@ -0,0 +1,133 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/radio-group.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/radio-group.md -->
+
+# radio-group
+
+Radix radio group wrapped in a Field; cascades variant and size to Radio items, placement left or right
+
+Install: `npx @create-ui/cli add radio-group`
+
+## Import
+
+```tsx
+import { RadioGroup } from "@/components/ui/radio-group"
+```
+
+Also exported: `radioGroupVariants`
+
+## RadioGroup props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| danger` | `primary` |
+| size | `xs \| sm \| md` | `md` |
+| placement | `left \| right` (right only sets flex-row-reverse on the single Field row; in a stacked flex-col layout add flex-row-reverse to each per-option wrapper div instead) | `left` |
+| disabled | `boolean` (Styles the inner Field only; it is NOT forwarded to the Radix root, so also set disabled on each Radio to actually block interaction) | - |
+| invalid | `boolean` (Forwarded to the inner Field; variant='danger' does not set it for you - pass both together for a full error state) | - |
+| fieldClassName | `string` (Layout lives here: fieldClassName='flex-col items-stretch gap-4' is the stacked-list recipe; className only styles the outer Radix root) | - |
+
+Extends `React.ComponentProps<typeof RadioGroupPrimitive.Root>`.
+
+## Examples
+
+From `radio-group-demo`:
+
+```tsx
+import { FieldContent } from "@/components/ui/field"
+import { Label, LabelDescription, LabelMain } from "@/components/ui/label"
+import { Radio } from "@/components/ui/radio"
+import { RadioGroup } from "@/components/ui/radio-group"
+
+const options = [
+  { value: "free", title: "Free", description: "For personal projects." },
+  {
+    value: "pro",
+    title: "Pro",
+    description: "For freelancers and small teams.",
+  },
+  {
+    value: "team",
+    title: "Team",
+    description: "For larger teams with shared workspaces.",
+  },
+]
+
+export default function RadioGroupDemo() {
+  return (
+    <RadioGroup
+      defaultValue="pro"
+      className="w-[340px]"
+      fieldClassName="flex-col items-stretch gap-4"
+    >
+      {options.map((option) => (
+        <div key={option.value} className="flex items-start gap-2">
+          <Radio id={`plan-${option.value}`} value={option.value} />
+          <FieldContent>
+            <LabelMain>
+              <Label htmlFor={`plan-${option.value}`}>{option.title}</Label>
+              <LabelDescription>{option.description}</LabelDescription>
+            </LabelMain>
+          </FieldContent>
+        </div>
+      ))}
+    </RadioGroup>
+  )
+}
+```
+
+From `radio-group-controlled`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import { FieldContent } from "@/components/ui/field"
+import { Label, LabelMain } from "@/components/ui/label"
+import { Radio } from "@/components/ui/radio"
+import { RadioGroup } from "@/components/ui/radio-group"
+
+const options = ["light", "dark", "system"] as const
+
+export default function RadioGroupControlled() {
+  const [value, setValue] = React.useState<(typeof options)[number]>("system")
+
+  return (
+    <div className="flex flex-col gap-3">
+      <RadioGroup
+        value={value}
+        onValueChange={(next) => setValue(next as (typeof options)[number])}
+        className="w-[280px]"
+        fieldClassName="flex-col items-stretch gap-3"
+      >
+        {options.map((option) => (
+          <div key={option} className="flex items-start gap-2">
+            <Radio id={`theme-${option}`} value={option} />
+            <FieldContent>
+              <LabelMain>
+                <Label htmlFor={`theme-${option}`}>
+                  {option.charAt(0).toUpperCase() + option.slice(1)}
+                </Label>
+              </LabelMain>
+            </FieldContent>
+          </div>
+        ))}
+      </RadioGroup>
+      <p className="text-placeholder text-ui-control-sm">
+        Selected: <span className="text-body font-medium">{value}</span>
+      </p>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view radio-group` or MCP `get_item_examples_from_registries` with "radio-group-demo" / "radio-group-example".
+
+## When to use
+Single-select group where all options are visible at once (plan picker, theme, sort order). For multi-select use CheckboxGroup; for long collapsible lists use Select; for a lone on/off use Switch or Checkbox.
+## Gotchas
+- There is no `RadioGroupItem` (shadcn divergence): the item is the separate `Radio` component, and each option is composed manually as a wrapper div with `Radio` plus `FieldContent > LabelMain > Label / LabelDescription` (see radio-group-demo).
+- The component renders ONE `Field` wrapping all children, not a Field per option; `Label`/`LabelDescription` sizing and disabled/invalid styling all cascade from that single Field context.
+- `variant` and `size` cascade to every child `Radio` via `RadioContext`; an explicit prop on a `Radio` wins (`variant ?? ctx ?? default`). Radio's `success`/`inverse` variants cannot be set at group level - pass them per `Radio`.
+- `variant="danger"` recolors every descendant `[data-slot=field-footer]` to `text-error-base`, including per-option footers nested in `FieldContent`.
+- The Radix root sets `orientation="horizontal"` and `display: flex`; a vertical list comes purely from `fieldClassName="flex-col items-stretch ..."`, not from any orientation or layout prop.
+- Group `disabled` never reaches the Radix root, so radios stay interactive unless each `Radio` also gets `disabled` (the disabled demos in radio-group-example set both).

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

@@ -0,0 +1,79 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/radio.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/radio.md -->
+
+# radio
+
+Single radio item for use inside RadioGroup; five variants and xs/sm/md sizes inherit from group context
+
+Install: `npx @create-ui/cli add radio`
+
+## Import
+
+```tsx
+import { Radio } from "@/components/ui/radio"
+```
+
+Also exported: `RadioContext`, `radioVariants`, `radioIndicatorVariants`
+
+## Radio props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| danger \| success \| inverse` (Own prop beats RadioGroup context; the only way to get success or inverse inside a group, since RadioGroup's own variant prop offers only primary/neutral/danger) | `primary` |
+| size | `xs \| sm \| md` (Resolved as own prop ?? RadioGroup context ?? md; the CVA defaultVariants sm is dead code because a resolved value is always passed) | `md` |
+
+Extends `React.ComponentProps<typeof RadioGroupPrimitive.Item>`.
+
+## Examples
+
+From `radio-demo`:
+
+```tsx
+import { Radio } from "@/components/ui/radio"
+import { RadioGroup } from "@/components/ui/radio-group"
+
+export default function RadioDemo() {
+  return (
+    <RadioGroup defaultValue="a">
+      <Radio value="a" aria-label="Option A" />
+      <Radio value="b" aria-label="Option B" />
+    </RadioGroup>
+  )
+}
+```
+
+From `radio-in-group`:
+
+```tsx
+import { Radio } from "@/components/ui/radio"
+import { RadioGroup } from "@/components/ui/radio-group"
+
+export default function RadioInGroup() {
+  return (
+    <div className="flex flex-col gap-6">
+      <RadioGroup variant="neutral" size="md" defaultValue="b">
+        <Radio value="a" aria-label="Option A" />
+        <Radio value="b" aria-label="Option B" />
+        <Radio value="c" aria-label="Option C" />
+      </RadioGroup>
+      <p className="text-placeholder text-ui-control-sm">
+        Children inherit <code>variant</code> and <code>size</code> from the
+        group via context — pass them on the group, not each child.
+      </p>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view radio` or MCP `get_item_examples_from_registries` with "radio-demo" / "radio-example".
+
+## When to use
+One item in a mutually-exclusive set of a few always-visible options, always rendered inside `RadioGroup` (it is a Radix RadioGroup.Item and cannot toggle on its own). For long option lists use `Select`; for a binary on/off setting use `Switch`; for standalone or multi-select choices use `Checkbox` / `CheckboxGroup`.
+
+## Gotchas
+- `Radio` and `RadioGroup` are separate registry items with separate import paths (`@/components/ui/radio` and `@/components/ui/radio-group`). There is no `RadioGroupItem` export; a shadcn-style `import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"` fails.
+- `Radio` renders its indicator dot internally and ignores children. Never nest a `RadioGroupPrimitive.Indicator`, a circle icon, or any content inside it.
+- Styling cascades from the group: `RadioGroup` publishes `variant`/`size` through `RadioContext`, so set them once on the group, not per child. A per-Radio prop overrides the context when one item must differ.
+- `RadioGroup` wraps its children in a horizontal `Field`, so labeled rows use `FieldLabel htmlFor` next to the radio (or `aria-label` when there is no visible label, as in `radio-demo`).
+- `RadioGroup`'s `invalid` and `disabled` props are passed only to the `Field` wrapper, never to the Radix root or the items: `invalid` colors the field footer but does not set `aria-invalid`, and `disabled` styles labels (cursor, pointer-events) while the radios stay interactive. The red outline needs `aria-invalid` on the `Radio` itself, and disabling needs `disabled` on each `Radio`.
+- `variant="danger"` only colors the checked/focus state; it does not mark the field invalid. The error outline comes solely from the item's `aria-invalid` attribute, on any variant.
+- `inverse` is built for dark surfaces: unchecked border and checked dot use light tokens, and focus-visible fills the control with static-black. `radio-example` shows it on a `bg-strongest` panel; on a light surface it is near-invisible.