@create-ui/cli 0.5.8 → 0.6.0

package/dist/skills/createui/reference/segmented-control.md

@@ -0,0 +1,146 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/segmented-control.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/segmented-control.md -->
+
+# segmented-control
+
+Single-select between 2-7 options with an animated sliding indicator; value/onValueChange, flat or grouped appearance
+
+Install: `npx @create-ui/cli add segmented-control`
+
+## Import
+
+```tsx
+import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmented-control"
+```
+
+Also exported: `segmentedControlVariants`, `segmentedControlItemVariants`, `segmentedControlIndicatorVariants`
+
+## SegmentedControl props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral` | `primary` |
+| shape | `rounded \| pill` | `rounded` |
+| size | `xs \| sm \| md \| lg \| xl` | `md` |
+| appearance | `flat \| grouped` (flat = independent-looking buttons, grouped = padded bg-weak container (pricing-toggle look); the active pill slides in BOTH) | `flat` |
+| value | `string` | - |
+| defaultValue | `string` | - |
+| onValueChange | `(value: string) => void` | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## SegmentedControlItem props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral` | `primary` |
+| shape | `rounded \| pill` | `rounded` |
+| size | `xs \| sm \| md \| lg \| xl` | `md` |
+| appearance | `flat \| grouped` (flat = independent-looking buttons, grouped = padded bg-weak container (pricing-toggle look); the active pill slides in BOTH) | `flat` |
+| iconOnly | `boolean` (renders children as a single centered icon (like Button); leadingIcon/trailingIcon are ignored; add aria-label (the text label is gone)) | `false` |
+| asChild | `boolean` (skips aria-pressed and type=button; disabled becomes aria-disabled + tabIndex=-1 instead of the native attribute) | `false` |
+| value | `string` | - |
+| selected | `boolean` (forces the active state without binding value on the root; the sliding indicator still moves to it) | - |
+| leadingIcon | `ReactNode` | - |
+| trailingIcon | `ReactNode` | - |
+
+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`): `SegmentedControlItem` (`leadingIcon` / `trailingIcon`). Import icons from `@create-ui/assets/icons` (Remix `Ri*`).
+
+## Examples
+
+From `segmented-control-demo`:
+
+```tsx
+import {
+  RiLayoutGridFill,
+  RiLineChartLine,
+  RiListUnordered,
+} from "@create-ui/assets/icons"
+
+import {
+  SegmentedControl,
+  SegmentedControlItem,
+} from "@/components/ui/segmented-control"
+
+export default function SegmentedControlDemo() {
+  return (
+    <SegmentedControl
+      variant="neutral"
+      appearance="grouped"
+      defaultValue="list"
+    >
+      <SegmentedControlItem value="grid" leadingIcon={<RiLayoutGridFill />}>
+        Grid
+      </SegmentedControlItem>
+      <SegmentedControlItem value="list" leadingIcon={<RiListUnordered />}>
+        List
+      </SegmentedControlItem>
+      <SegmentedControlItem value="chart" leadingIcon={<RiLineChartLine />}>
+        Chart
+      </SegmentedControlItem>
+    </SegmentedControl>
+  )
+}
+```
+
+From `segmented-control-appearance`:
+
+```tsx
+import {
+  RiInbox2Line,
+  RiSettings6Fill,
+  RiUser3Line,
+} from "@create-ui/assets/icons"
+
+import {
+  SegmentedControl,
+  SegmentedControlItem,
+} from "@/components/ui/segmented-control"
+
+export default function SegmentedControlAppearance() {
+  return (
+    <div className="flex flex-col items-start gap-4">
+      <SegmentedControl variant="neutral" appearance="flat" className="gap-2">
+        <SegmentedControlItem leadingIcon={<RiInbox2Line />}>
+          Inbox
+        </SegmentedControlItem>
+        <SegmentedControlItem selected leadingIcon={<RiUser3Line />}>
+          Mine
+        </SegmentedControlItem>
+        <SegmentedControlItem leadingIcon={<RiSettings6Fill />}>
+          Archived
+        </SegmentedControlItem>
+      </SegmentedControl>
+
+      <SegmentedControl
+        variant="neutral"
+        appearance="grouped"
+        defaultValue="week"
+      >
+        <SegmentedControlItem value="day">Day</SegmentedControlItem>
+        <SegmentedControlItem value="week">Week</SegmentedControlItem>
+        <SegmentedControlItem value="month">Month</SegmentedControlItem>
+      </SegmentedControl>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view segmented-control` or MCP `get_item_examples_from_registries` with "segmented-control-demo" / "segmented-control-example".
+
+## When to use
+
+Single-select between 2-7 mutually exclusive options that benefit from being visible at once: view mode, time range, billing period. Drive it with `value`/`onValueChange` or `defaultValue`; never hand-roll it as a row of `Button`s with manual active state. Wrong tool for: multi-select (`CheckboxGroup`), route or section navigation (`TabMenu`), lists past ~7 (`Select`), a boolean (`Switch`), or form-style radio choices (`RadioGroup`).
+
+## Gotchas
+
+- This is NOT Radix ToggleGroup: there is no `type` prop (single-select only), clicking the active item does not deselect it, and every item is its own Tab stop (`role="group"` + `aria-pressed` per button, no arrow-key roving).
+- An item without `value` never commits a selection; its `onClick` still fires, and calling `event.preventDefault()` inside `onClick` blocks the commit even when `value` is set.
+- The visible active background is a separate floating element (`data-slot="segmented-control-indicator"`) measured from the `data-state="on"` item; in `flat` appearance the selected item's own bg/shadow turn transparent once the indicator mounts. Style the indicator for active background/shadow; active text color stays on the item.
+- `flat` items sit flush with no gap; add spacing on the root yourself (`className="gap-2"`), as the appearance example does.
+- `variant`/`shape`/`size`/`appearance` cascade from the root via context; set them once on `SegmentedControl`, not per item (per-item props exist only as overrides).
+- `appearance="grouped"` adds container padding on top of the item height (xs/sm +4px, md/lg +8px, xl +16px), so a grouped control is taller than its `size` suggests: grouped xs/sm = 28/32px, md = 40px, lg = 48px, xl = 64px. Next to a `Button` in a toolbar, pair by rendered height, not by size name (e.g. grouped sm = 32px aligns with Button md).
+- `iconOnly` gives the item a FIXED square (`size-N`). Adding `flex-1` / `w-full` / `grow` via `className` makes the flex layout override that fixed width and stretch the square into a wide rectangle. For a compact icon toggle, add NO width class and let the square stand. Only stretch deliberately (e.g. a full-width 2-up mobile switcher) - and then accept it is no longer square.

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

@@ -0,0 +1,204 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/select.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/select.md -->
+
+# select
+
+Radix select for picking one option from a dropdown list; size and state inherit from Field, compact width variant
+
+Install: `npx @create-ui/cli add select`
+
+## Import
+
+```tsx
+import { Select, SelectProvider, SelectShell, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue } from "@/components/ui/select"
+```
+
+Also exported: `selectShellVariants`, `selectTriggerVariants`, `useSelectContext`
+
+## Select props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` | - |
+| variant | `default \| compact` (compact = width-fits-content (shell w-fit, trigger flex-none) for toolbars/inline pickers; NOT auto-applied inside InputGroup, pass it explicitly) | `default` |
+| loading | `boolean` (also hard-disables the whole root (disabled || loading) and swaps the chevron for a Spinner; the shell goes pointer-events-none) | `false` |
+| invalid | `boolean` | `false` |
+
+Extends `React.ComponentProps<typeof SelectPrimitive.Root>`.
+
+## SelectProvider props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` | `sm` |
+| variant | `default \| compact` (compact = width-fits-content (shell w-fit, trigger flex-none) for toolbars/inline pickers; NOT auto-applied inside InputGroup, pass it explicitly) | `default` |
+| invalid | `boolean` | `false` |
+| disabled | `boolean` | `false` |
+| loading | `boolean` (also hard-disables the whole root (disabled || loading) and swaps the chevron for a Spinner; the shell goes pointer-events-none) | `false` |
+| children | `ReactNode` | - |
+
+## SelectTrigger props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` | `sm` |
+| variant | `default \| compact` (compact = width-fits-content (shell w-fit, trigger flex-none) for toolbars/inline pickers; NOT auto-applied inside InputGroup, pass it explicitly) | `default` |
+
+Extends `React.ComponentProps<typeof SelectPrimitive.Trigger>`.
+
+## Examples
+
+From `select-demo`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+import {
+  France,
+  Germany,
+  Japan,
+  Turkey,
+  UnitedStates,
+} from "@create-ui/assets/flags"
+
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+
+const COUNTRIES = [
+  {
+    value: "de",
+    label: "Germany",
+    flag: <Germany className="size-5 shrink-0" />,
+  },
+  {
+    value: "us",
+    label: "United States",
+    flag: <UnitedStates className="size-5 shrink-0" />,
+  },
+  { value: "jp", label: "Japan", flag: <Japan className="size-5 shrink-0" /> },
+  {
+    value: "fr",
+    label: "France",
+    flag: <France className="size-5 shrink-0" />,
+  },
+  {
+    value: "tr",
+    label: "Türkiye",
+    flag: <Turkey className="size-5 shrink-0" />,
+  },
+]
+
+export default function SelectDemo() {
+  const [value, setValue] = React.useState<string | undefined>("de")
+  const selected = COUNTRIES.find((c) => c.value === value)
+
+  return (
+    <div className="w-full max-w-xs">
+      <Select size="md" value={value} onValueChange={setValue}>
+        <SelectTrigger>
+          {selected?.flag}
+          <SelectValue placeholder="Select country">
+            {selected?.label}
+          </SelectValue>
+        </SelectTrigger>
+        <SelectContent>
+          <SelectGroup>
+            <SelectItem value="de">
+              <Germany className="size-5 shrink-0" />
+              Germany
+            </SelectItem>
+            <SelectItem value="us">
+              <UnitedStates className="size-5 shrink-0" />
+              United States
+            </SelectItem>
+            <SelectItem value="jp">
+              <Japan className="size-5 shrink-0" />
+              Japan
+            </SelectItem>
+            <SelectItem value="fr">
+              <France className="size-5 shrink-0" />
+              France
+            </SelectItem>
+            <SelectItem value="tr">
+              <Turkey className="size-5 shrink-0" />
+              Türkiye
+            </SelectItem>
+          </SelectGroup>
+        </SelectContent>
+      </Select>
+    </div>
+  )
+}
+```
+
+From `select-in-input-group`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import {
+  InputGroup,
+  InputGroupControl,
+  InputGroupSlot,
+} from "@/components/ui/input-group"
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+
+export default function SelectInInputGroup() {
+  const [currency, setCurrency] = React.useState("usd")
+
+  return (
+    <div className="w-full max-w-xs">
+      <InputGroup size="md">
+        <Select variant="compact" value={currency} onValueChange={setCurrency}>
+          <SelectTrigger aria-label="Currency">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectGroup>
+              <SelectItem value="usd">USD</SelectItem>
+              <SelectItem value="eur">EUR</SelectItem>
+              <SelectItem value="jpy">JPY</SelectItem>
+              <SelectItem value="try">TRY</SelectItem>
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+        <InputGroupSlot>
+          <InputGroupControl placeholder="0.00" inputMode="decimal" />
+        </InputGroupSlot>
+      </InputGroup>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view select` or MCP `get_item_examples_from_registries` with "select-demo" / "select-example".
+
+## When to use
+Select picks one value from a short predefined list (country, currency, role, plan). Wrap it in Field for the label and the size/state cascade. Long or searchable lists are Command territory; a single boolean is Switch (settings row) or Checkbox (form); a few always-visible options are SegmentedControl.
+## Gotchas
+- SelectTrigger auto-wraps itself in SelectShell when standalone, and renders bare when it detects an InputShell (from InputGroup) or explicit SelectShell ancestor. Border, focus, and state chrome live on the shell, so overrides belong there, not on the trigger.
+- Inside InputGroup you must pass variant="compact" yourself; the default variant's trigger is flex-1 w-full and squeezes the sibling Input.
+- Size resolves explicit prop > InputGroup context > Field context > "sm"; invalid/disabled/loading on the root fall back to Field. Set them once on Field, never re-set per part.
+- The chevron (and the trailing primary check indicator on items) is auto-rendered; never append your own caret.
+- SelectItem auto-detects a leading icon: with multiple children whose first is an element, that first child becomes the leading slot and the rest becomes truncating text. Pass icon and label as plain siblings:
+```tsx
+<SelectItem value="de">
+  <Germany className="size-5 shrink-0" />
+  Germany
+</SelectItem>
+```

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

@@ -0,0 +1,99 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/separator.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/separator.md -->
+
+# separator
+
+Horizontal divider line; optional inline label or icon content aligned start, center or end
+
+Install: `npx @create-ui/cli add separator`
+
+## Import
+
+```tsx
+import { Separator } from "@/components/ui/separator"
+```
+
+## Separator props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| align | `start \| center \| end` (Labeled mode only: drops the flanking line on that side so the label sits flush. Ignored when there are no children.) | `center` |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `separator-demo`:
+
+```tsx
+import { Separator } from "@/components/ui/separator"
+
+export default function SeparatorDemo() {
+  return (
+    <div className="text-body text-ui-control-md flex w-[420px] flex-col gap-4">
+      <p>
+        Workspace settings are scoped to the current organization and apply to
+        every member.
+      </p>
+      <Separator />
+      <p>
+        Personal preferences only affect your account and follow you across
+        workspaces.
+      </p>
+    </div>
+  )
+}
+```
+
+From `separator-with-label`:
+
+```tsx
+import { Button } from "@/components/ui/button"
+import { Separator } from "@/components/ui/separator"
+
+export default function SeparatorWithLabel() {
+  return (
+    <div className="flex w-[360px] flex-col gap-4">
+      <Button variant="primary" appearance="solid">
+        Continue with email
+      </Button>
+      <Separator>OR</Separator>
+      <Button variant="neutral-solid" appearance="outline">
+        Create a free account
+      </Button>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view separator` or MCP `get_item_examples_from_registries` with "separator-demo" / "separator-example".
+
+## When to use
+Horizontal rule between related-but-distinct content, and the labeled "OR" divider
+(pass children). Do not hand-roll `<hr>` or `<div className="border-t">`. It is
+horizontal-only: for vertical dividers between adjacent controls use ButtonGroup,
+which draws its own borders between items. Inside forms prefer `FieldSeparator`
+from field.tsx, which wraps this same Separator with vertical padding and a
+background-backed centered label.
+
+## Gotchas
+- Not the Radix/shadcn separator: no `orientation`, no `decorative` prop, so the
+  shadcn habit `orientation="vertical"` is a type error. `role="separator"` is
+  hardcoded, but props spread after it, so pass `role="presentation"` to make it
+  purely decorative.
+- The line is a border, not a background bar: `h-0 border-t border-light` (shadcn
+  uses `h-px bg-border`). `bg-*` classes change nothing visible; recolor with
+  `border-*` classes.
+- `className` lands on different elements per mode. Plain: on the line itself, so
+  `className="border-strong"` recolors it directly. Labeled: on the outer flex
+  wrapper while the two lines keep internal classes, so recolor them via a
+  descendant selector:
+
+```tsx
+<Separator className="[&>span[aria-hidden]]:border-strong">OR</Separator>
+```
+
+- Any truthy `children` switches the render entirely: flex row with two flanking
+  `aria-hidden` line spans and a fixed `gap-3`.
+- The label slot styling is fixed: `text-placeholder`, `text-ui-control-md`, and
+  every nested `<svg>` is forced to `size-6`. Drop in a bare icon as children;
+  manual icon size classes are overridden.

package/dist/skills/createui/reference/social-login-button.md

@@ -0,0 +1,130 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/social-login-button.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/social-login-button.md -->
+
+# social-login-button
+
+OAuth sign-in button for 13 brands like Google, Apple and GitHub plus custom; colorful/black/white appearance, iconOnly
+
+Install: `npx @create-ui/cli add social-login-button`
+
+## Import
+
+```tsx
+import { SocialLoginButton } from "@/components/ui/social-login-button"
+```
+
+Also exported: `socialLoginButtonVariants`
+
+## SocialLoginButton props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `lg \| md` | `lg` |
+| shape | `rounded \| pill \| square` | `rounded` |
+| iconOnly | `boolean` (Removes the visible label, leaving no accessible name; always pass aria-label) | `false` |
+| appearance | `colorful \| black \| white` (Defaults to colorful (literal brand-colored background); the generated table misses this default) | - |
+| asChild | `boolean` (The slotted child's own children are REPLACED by the injected icon+label; slot an empty <a> carrying href/aria-label) | - |
+| brand | `apple \| behance \| discord \| dribbble \| facebook \| github \| gitlab \| google \| linkedin \| microsoft \| slack \| sso \| x \| custom` (Also fixes the copy: rendered text is always 'Continue with {label}'; custom wording only via brand=\"custom\" config.label, and only the brand-name part (the 'Continue with' prefix is hard-coded)) | - |
+| config | `{ icon: IconComponent label?: string color?: string }` (Only accepted with brand=\"custom\" (discriminated union). The icon gets no fill, just the appearance text color (white on colorful, theme text on black/white), so draw it with currentColor) | - |
+
+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`): `SocialLoginButton` (). Import icons from `@create-ui/assets/icons` (Remix `Ri*`).
+
+## Examples
+
+From `social-login-button-demo`:
+
+```tsx
+import { SocialLoginButton } from "@/components/ui/social-login-button"
+
+export default function SocialLoginButtonDemo() {
+  return (
+    <div className="flex w-full flex-col items-center justify-center gap-3">
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        <SocialLoginButton brand="google" appearance="white" />
+        <SocialLoginButton brand="apple" appearance="white" />
+      </div>
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        <SocialLoginButton brand="dribbble" shape="pill" />
+        <SocialLoginButton brand="x" shape="pill" />
+      </div>
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        <SocialLoginButton
+          brand="google"
+          iconOnly
+          aria-label="Continue with Google"
+        />
+        <SocialLoginButton
+          brand="apple"
+          appearance="black"
+          iconOnly
+          aria-label="Continue with Apple"
+        />
+        <SocialLoginButton
+          brand="github"
+          appearance="white"
+          iconOnly
+          aria-label="Continue with Github"
+        />
+        <SocialLoginButton
+          brand="dribbble"
+          shape="pill"
+          iconOnly
+          aria-label="Continue with Dribbble"
+        />
+        <SocialLoginButton
+          brand="x"
+          shape="pill"
+          iconOnly
+          aria-label="Continue with X"
+        />
+      </div>
+    </div>
+  )
+}
+```
+
+From `social-login-button-as-child`:
+
+```tsx
+"use client"
+
+import { SocialLoginButton } from "@/components/ui/social-login-button"
+
+export default function SocialLoginButtonAsChild() {
+  return (
+    <div className="flex flex-wrap justify-center gap-2">
+      <SocialLoginButton asChild brand="google">
+        <a href="#" aria-label="Continue with Google" />
+      </SocialLoginButton>
+      <SocialLoginButton asChild brand="apple" appearance="black">
+        <a href="#" aria-label="Continue with Apple" />
+      </SocialLoginButton>
+      <SocialLoginButton asChild brand="github" appearance="white">
+        <a href="#" aria-label="Continue with Github" />
+      </SocialLoginButton>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view social-login-button` or MCP `get_item_examples_from_registries` with "social-login-button-demo" / "social-login-button-example".
+
+## When to use
+Branded "Continue with X" buttons for OAuth/SSO sign-in and sign-up flows: preset brands plus brand="custom" with a config object. Do NOT use it for generic CTAs (use Button), app/extension store links (use AppStoreBadge), or passive brand chips (use Badge).
+
+## Gotchas
+- Children are ignored unless asChild: `<SocialLoginButton brand="google">Sign in</SocialLoginButton>` silently drops "Sign in" (children are destructured out and never rendered); the label always comes from the brand config.
+- Ignore the generated Icons section: there are NO leadingIcon/trailingIcon/icon props. The glyph is auto-picked per brand AND appearance: white glyph on colorful; under black/white appearances most brands keep their full-color glyph, and only brands with a theme-aware mono asset (apple, github, x) swap. Custom icons go through config.icon only.
+- asChild is not shadcn-Button-style Slot passthrough: the component clones the slotted child and REPLACES its children with the icon+label content:
+
+```tsx
+<SocialLoginButton asChild brand="google">
+  <a href="/auth/google" aria-label="Continue with Google" />
+</SocialLoginButton>
+```
+
+- Non-iconOnly buttons have fixed widths (w-[300px] at lg, w-[250px] at md) so provider stacks align. For full-width auth forms pass className="w-full"; cn() merges it over the CVA width.
+- appearance="colorful" pins the literal brand color and static black/white tokens, so it does NOT flip in dark mode; only the sso preset defines a dark variant. black/white appearances use semantic tokens and do flip with the theme.

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

@@ -0,0 +1,68 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/spinner.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/spinner.md -->
+
+# spinner
+
+Loading indicator with a conic-gradient arc; 12 color variants, solid/gradient appearance, spin/pulse/tick animations
+
+Install: `npx @create-ui/cli add spinner`
+
+## Import
+
+```tsx
+import { Spinner } from "@/components/ui/spinner"
+```
+
+Also exported: `spinnerVariants`
+
+## Spinner props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| info \| success \| warning \| danger \| away \| neutral \| neutral-static \| neutral-soft \| inverse \| inverse-static \| inverse-soft` | `primary` |
+| appearance | `solid \| gradient` | `gradient` |
+| cap | `sharp \| rounded` (Visual effect only with appearance=\"solid\" (rounded caps render as separate dot elements); with gradient appearance the prop only sets the data-cap attribute.) | `rounded` |
+| line | `short \| long` | `long` |
+| animation | `spin \| pulse \| tick` | `pulse` |
+| size | `xs \| sm \| md \| lg` (Also scales the arc stroke width via inline styles (1px at xs up to 2px at lg); the stroke cannot be restyled through className.) | `sm` |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `spinner-demo`:
+
+```tsx
+import { Spinner } from "@/components/ui/spinner"
+
+export default function SpinnerDemo() {
+  return <Spinner size="lg" />
+}
+```
+
+From `spinner-appearance`:
+
+```tsx
+import { Spinner } from "@/components/ui/spinner"
+
+export default function SpinnerAppearance() {
+  return (
+    <div className="flex flex-wrap items-center gap-6">
+      <Spinner appearance="gradient" animation="spin" size="lg" />
+      <Spinner appearance="solid" animation="spin" size="lg" />
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view spinner` or MCP `get_item_examples_from_registries` with "spinner-demo" / "spinner-example".
+
+## When to use
+Indeterminate in-flight work: saves, network calls, slow validation, page bootstrapping. Do NOT use it when progress is measurable (use Progress) or for a loading button (use Button's `loading` prop, which renders the Spinner, blocks interaction, and sets `aria-busy` for you - never compose `<Spinner />` + `disabled` by hand).
+
+## Gotchas
+- This is NOT the shadcn `Loader2` + `animate-spin` pattern. It is a pure-CSS `<div>` (conic-gradient + mask, zero SVG). Never reach for lucide icons or `animate-spin` utilities; render `<Spinner />`.
+- `children` is excluded at the type level (`Omit<..., "children">`). It draws its own arc; put visible copy ("Saving...") next to it, not inside it.
+- The arc and caps track `currentColor`: `variant` applies a `text-*` token class, so `className="text-emerald-500"` (merged last via `cn()`) recolors them. The solid track ring does NOT follow `currentColor` - its `bg-*` color always comes from `variant`.
+- The background track ring only renders when `appearance="solid"`; the default `gradient` has no track and its arc tail fades to transparent.
+- Sets `role="status"` and `aria-label="Loading"` automatically; pass your own `aria-label` for specific operations.
+- The exported `spinnerVariants` CVA defaults `size` to `lg`, but the `Spinner` component prop defaults to `sm`. Calling `spinnerVariants()` directly yields a different size than `<Spinner />`.