@create-ui/cli 0.5.8 → 0.6.0

package/dist/skills/createui/SKILL.md

@@ -1,210 +1,232 @@
 ---
 name: createui
-description: Manages Create UI components and projects — adding, searching, viewing, theming, and composing UI. Provides project context, component patterns, and Create UI semantic tokens. Use when working with the createui CLI (init/add/create/diff/view/search/migrate/mcp), a components.json file, the @createui registry, or authoring UI with Create UI tokens and themes.
-user-invocable: false
+description: Create UI component library and design system. Use whenever writing or editing ANY React/JSX UI - pages, views, components, layouts, styling - in a project that uses Create UI (has a components.json, the @createui registry, or @create-ui/* packages), and for createui CLI or MCP operations (init/add/create/diff/view/search/migrate/mcp). Provides per-component API references (reference/<component>.md), composition rules, semantic tokens, and design recipes.
+user-invocable: true
 allowed-tools: Bash(npx @create-ui/cli *), Bash(pnpm dlx @create-ui/cli *)
 ---
 
 # Create UI
 
-Create UI is a design code system: **one unified styling system + many themes**. Components are added as source code into the user's project via the `createui` CLI, and styled with Create UI's own semantic tokens.
+Create UI is a design code system: **one unified styling system + many themes**. Components are added as source code into the user's project via the `createui` CLI and styled with Create UI's own semantic tokens. It is its own system - its own CLI (`npx @create-ui/cli`), its own registry (`@createui` - the only registry, never configure another), and its own component APIs. **Do not assume shadcn/ui conventions: the APIs differ.**
+
+## Non-negotiable workflow
+
+1. **Get project context** - `npx @create-ui/cli info` (prints components.json: aliases, `rsc`, `tailwind.css` path, `iconLibrary`). Use the real aliases in imports.
+2. **Check installed components** - list the `ui` alias directory (e.g. `components/ui/`). Never import a component that hasn't been added; never re-add installed ones.
+3. **Before the FIRST use of any component, read [`reference/<component>.md`](./reference/) in this skill folder.** It is generated from the component source and is the API authority (props, variants, defaults, icon usage, canonical example). If you cannot read it, fetch real usage instead: MCP `get_item_examples_from_registries` with `"<name>-demo"`, or `npx @create-ui/cli view <name>`.
+4. **Add what's missing** - `npx @create-ui/cli add <name>`.
+5. **Compose per the invariants below.** Never hand-roll a pattern listed in "Never hand-roll".
+6. **Exercise the component API - never ship bare defaults.** Pick `variant` / `appearance` / `size` / `state` / `orientation` to fit each element's role on every build (see "Use the full component API" below). For marketing / landing / showcase, also read [`rules/design.md`](./rules/design.md) first (section recipes, spacing rhythm, anti-patterns); for any other rich UI, skim its richness checklist + anti-patterns. Build to the user's brand and request; never clone the Create UI site.
+
+## Component inventory
+
+Every item below ships in `@createui` - and nothing else does. There is **no card, table, tabs, sheet, drawer, skeleton, sidebar, dialog/modal, popover, or alert-banner component**; the only modal surface is `CommandDialog` (part of `command`). Build other layouts from semantic-token markup and these primitives - don't invent lookalikes.
+
+<!-- MAINTENANCE: if modal/popover/alert-banner ever get registered in ui/_registry.ts, update the sentence above and the matching negations in rules/composition.md and the notes files - the generator does not maintain hand-written prose. -->
+
+<!-- BEGIN GENERATED:INVENTORY -->
+
+| Item | Exports | Key props (defaults starred) |
+| --- | --- | --- |
+| accordion | Accordion, AccordionItem, AccordionTrigger, AccordionContent | appearance: ghost-default*\|ghost-underline\|ghost-rounded\|outline-rounded\|outline-sharp\|filled-rounded |
+| app-store-badge | AppStoreBadge | variant: black*\|white · appearance: filled*\|outline · iconOnly · brand (required) |
+| aspect-ratio | AspectRatio |  |
+| avatar | Avatar, AvatarImage, AvatarText, AvatarIcon, AvatarRing, AvatarBadge, +8 more | variant: {gradient\|strong\|base\|weak\|alpha}-{inverse\|neutral\|red\|green\|orange\|blue\|sky\|indigo\|fuchsia\|yellow\|stable} (55 values) · size: 2xs\|xs\|sm\|md*\|lg\|xl\|2xl · shape: circle*\|rounded · background · stroke |
+| badge | Badge | variant: primary*\|neutral\|neutral-static\|danger\|success\|warning\|info\|verified\|highlighted\|away\|inverse\|inverse-static · appearance: solid\|outline\|soft*\|ghost · size: xs\|sm*\|md · shape: rounded*\|pill · leadingIcon/trailingIcon · iconOnly · numberOnly · disabled |
+| breadcrumb | Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbSeparator | variant: primary\|neutral · appearance: solid\|outline\|ghost · size: xs\|sm\|md · shape: rounded\|pill · separator: chevron\|slash\|dot |
+| button | Button | variant: primary*\|neutral-solid\|neutral-light\|danger\|success\|inverse-solid\|inverse-light · appearance: solid*\|outline\|ghost\|soft · size: xs\|sm\|md\|lg*\|xl · shape: rounded*\|pill\|square · leadingIcon/trailingIcon · iconOnly · loading |
+| button-group | ButtonGroup, ButtonGroupItem | variant: primary*\|neutral\|soft · size: xs\|sm\|md*\|lg\|xl · shape: rounded*\|pill\|square |
+| checkbox | Checkbox | variant: primary*\|neutral\|inverse\|danger\|success\|info · size: xs\|sm*\|md · shape: rounded*\|pill\|square |
+| checkbox-group | CheckboxGroup | variant: primary*\|danger · size: xs\|sm\|md* · placement: left*\|right |
+| chip | Chip | variant: neutral*\|info\|danger\|success · appearance: outline*\|soft · size: xs\|sm\|md\|lg*\|xl · shape: pill\|rounded* · selected · disabled · dragging · closable |
+| close-button | CloseButton | variant: neutral*\|inverse · appearance: solid\|outline\|ghost*\|soft · size: xs\|sm\|md*\|lg\|xl\|2xl · shape: rounded*\|pill\|square |
+| country-flag | CountryFlag, CurrencyFlag, FlagFallback | code (required) |
+| credit-card-input | CreditCardInput | size: xs\|sm\|md · leadingIcon · invalid · disabled · loading · showLeadingIcon · showBadge · showValidationIcon |
+| date-input | DateInput | size: xs\|sm\|md · leadingIcon · invalid · disabled · loading · showLeadingIcon |
+| dropdown-menu | DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, +2 more | size: xs\|sm*\|md |
+| field | Field, FieldLabel, FieldTitle, FieldContent, FieldDescription, FieldError, +6 more | size: xs\|sm*\|md · orientation: vertical*\|horizontal\|responsive · invalid · disabled · loading |
+| info-tooltip | InfoTooltip, InfoTooltipContent, InfoTooltipProvider, InfoTooltipTrigger | variant: primary\|neutral\|inverse\|danger\|info · size: sm\|md\|lg · side: top\|bottom\|left\|right · align: start\|center\|end · showArrow |
+| inline-alert | InlineAlert, InlineAlertIcon, InlineAlertContent, InlineAlertHeading, InlineAlertTitle, InlineAlertDescription, +2 more | variant: primary*\|neutral\|danger\|success\|warning\|info\|away · appearance: solid\|soft\|outline\|default* · layout: horizontal*\|vertical |
+| input | Input, InputProvider, InputShell | size: xs\|sm*\|md |
+| input-group | InputGroup, InputGroupProvider, InputGroupShell, InputGroupSlot, InputGroupControl, InputGroupTextarea, +9 more | invalid · disabled · loading · multiline |
+| input-otp | InputOTP | variant: outline*\|filled · size: lg*\|md\|sm · shape: rounded*\|pill\|square\|underline · invalid |
+| input-stepper | InputStepper | variant: connected\|separated · size: xs\|sm\|md · value/onValueChange · defaultValue · min · max · step · invalid · disabled |
+| label | Label, LabelBlock, LabelMain, LabelIcon, LabelRequired, LabelOptional, +4 more | size: xs\|sm\|md |
+| pagination | Pagination, PaginationContent, PaginationLink, PaginationFirst, PaginationPrevious, PaginationNext, +2 more | variant: compact\|compact-grouped* · shape: rounded*\|pill |
+| phone-input | PhoneInput | size: xs\|sm\|md · invalid · disabled · loading · showHelperIcon |
+| progress | Progress | variant: primary*\|info\|success\|warning\|danger\|away\|neutral\|neutral-static\|neutral-soft\|inverse\|inverse-static\|inverse-soft · appearance: solid*\|gradient · size: xs\|sm\|md*\|lg · shape: sharp\|pill* · type: line*\|circle · value · max · duration |
+| radio | Radio | variant: primary*\|neutral\|danger\|success\|inverse · size: xs\|sm\|md* |
+| radio-group | RadioGroup | variant: primary*\|neutral\|danger · size: xs\|sm\|md* · placement: left*\|right · disabled · invalid |
+| scroll-area | ScrollArea, ScrollBar | appearance: filled*\|ghost · size: sm\|md*\|lg · orientation: vertical*\|horizontal\|both · fade |
+| segmented-control | SegmentedControl, SegmentedControlItem | variant: primary*\|neutral · appearance: flat*\|grouped · size: xs\|sm\|md*\|lg\|xl · shape: rounded*\|pill · value/onValueChange |
+| select | Select, SelectProvider, SelectShell, SelectContent, SelectGroup, SelectItem, +4 more | variant: default*\|compact · size: xs\|sm\|md · loading · invalid |
+| separator | Separator | align: start\|center*\|end |
+| social-login-button | SocialLoginButton | appearance: colorful\|black\|white · size: lg*\|md · shape: rounded*\|pill\|square · iconOnly · brand (required) · config (required) |
+| spinner | Spinner | variant: primary*\|info\|success\|warning\|danger\|away\|neutral\|neutral-static\|neutral-soft\|inverse\|inverse-static\|inverse-soft · appearance: solid\|gradient* · size: xs\|sm*\|md\|lg · cap: sharp\|rounded* · line: short\|long* · animation: spin\|pulse*\|tick |
+| status-badge | StatusBadge | variant: primary*\|danger\|success\|warning\|info\|highlighted\|away\|verified\|cyan\|lime\|neutral\|white · size: xs\|sm\|md* |
+| switch | Switch | variant: primary*\|info\|neutral\|inverse\|semantic · size: md*\|sm\|xs · shape: pill*\|rounded · thumbType: short*\|long · ioTrigger · thumbIcon |
+| switch-group | SwitchGroup | size: xs\|sm\|md* · ioTrigger · placement: left*\|right |
+| tab-menu | TabMenu, TabMenuItem | variant: vertical-button*\|vertical-line\|horizontal-line\|horizontal-button · size: sm\|md*\|lg · value/onValueChange · indicator: left\|top\|bottom |
+| text-link | TextLink | variant: primary*\|neutral\|inverse\|danger\|success\|info · size: xs\|sm\|md*\|lg · leadingIcon/trailingIcon · visited · disabled · underline |
+| textarea | Textarea | size: xs\|sm*\|md · resizable: x\|y\|both · loading |
+| toast | Toast, ToastBody, ToastIcon, ToastContent, ToastTitle, ToastDescription, +3 more | variant: primary*\|neutral\|danger\|success\|warning\|info\|away · appearance: solid*\|soft\|outline\|default |
+| tooltip | Tooltip, TooltipContent, TooltipProvider, TooltipTrigger | TooltipContent: variant: primary*\|neutral\|inverse\|danger\|info · showArrow · side: top\|bottom*\|left\|right · sideOffset |
+
+<!-- END GENERATED:INVENTORY -->
+
+> The registry also ships **hooks** (`use-mobile`, `use-credit-card-input`, `use-date-input`, `use-phone-input`) and **lib utilities** (`utils`, `country-flags`, `currency-flags`) - installed automatically as dependencies of the components that need them.
+
+## Icons
+
+**Icons go through props, never as children next to text.** The component sizes the icon per its `size` - never add `size-4` / `w-4 h-4` to an icon inside a component. Import UI icons from `@create-ui/assets/icons` (Remix `Ri*`, e.g. `RiSearchLine`) - **never `lucide-react`**. Brand / flag / payment / social marks come from `@create-ui/assets/{social,flags,payments,brands,badges,banks,crypto}`.
 
-Components are delivered as source code through a registry (registry + components-as-source). Create UI is its own system — its own CLI (`createui`), its own registry (`@createui`), and its own tokens and themes. There is no style/base split, and **`@createui` is the only registry** — never configure, suggest, or default to another one.
-
-> **IMPORTANT:** Run CLI commands with `npx @create-ui/cli <command>` (or `pnpm dlx @create-ui/cli <command>`).
-
-This skill is for **using Create UI in your app**: install components with the CLI, then compose them with the patterns and rules below.
-
-## Current Project Context
-
-Run the `info` command to read the project's config and installed components:
+```tsx
+// Correct - icon props
+<Badge variant="success" leadingIcon={<RiCheckLine />}>Verified</Badge>
+<Button appearance="outline" trailingIcon={<RiArrowRightLine />}>Docs</Button>
 
-```bash
-npx @create-ui/cli info
+// Incorrect - NEVER put the icon in children next to text
+<Badge variant="success"><RiCheckLine /> Verified</Badge>
 ```
 
-`info` prints project info plus the contents of `components.json` (config, aliases, `tailwind.css` path, `iconLibrary`). Run it before adding or editing components so imports, the icon library, and `"use client"` advice match the real project. (There is no `--json` flag.)
-
-## Principles
-
-1. **Use existing components first.** Search the registry before writing custom UI: `npx @create-ui/cli search @createui -q "toast"`.
-2. **Compose, don't reinvent.** Settings page = `TabMenu` + `FieldGroup` + `Field` controls. Checkout = `Field` + `PhoneInput` + `CreditCardInput` + `Button`.
-3. **Use built-in props before custom classes.** `variant`, `appearance`, `size`, `shape` on `Button`; `size` on `Field` — reach for these before `className`.
-4. **Use semantic tokens, never raw values.** `bg-static`, `text-body`, `bg-primary-base` — never `bg-blue-500` or hardcoded hex.
-
-## Critical Rules
-
-These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
-
-### Styling & Tailwind → [styling.md](./rules/styling.md)
-
-- **Use Create UI semantic tokens.** Surfaces `bg-static` / `bg-weak`, text `text-body` / `text-placeholder`, primary `bg-primary-base`. Never raw colors.
-- **`className` for layout, not styling.** Don't override a component's colors or typography.
-- **No `space-x-*` / `space-y-*`.** Use `flex` + `gap-*` (`flex flex-col gap-4` for vertical stacks).
-- **Use `size-*` when width equals height.** `size-10`, not `w-10 h-10`.
-- **Focus is `outline-*`, never `ring-*`.** Components use `outline-2 outline-transparent` + `focus-visible:outline-primary-700`.
-- **Semantic spacing classes only when Figma references a token.** `var(--component/sm,8px)` → `gap-component-sm`; a static `space-space-4` → `gap-4`.
-- **Use `cn()` for conditional classes.** Not manual template-literal ternaries.
-
-### Forms & Inputs → [forms.md](./rules/forms.md)
-
-- **Forms use `FieldGroup` + `Field`.** Never raw `div` + `space-y-*` for form layout.
-- **`Field` owns size; children inherit it.** Set `size` on `Field` (`xs` | `sm` | `md`); `Input`, `Select`, etc. read it via context — never downgrade a child.
-- **`InputGroup` uses `InputGroupControl` / `InputGroupTextarea`.** Never a raw `Input` / `Textarea` inside `InputGroup`.
-- **Option sets (2–7 choices) use `SegmentedControl`** (single-select via `value` / `onValueChange`). Don't loop `Button` with manual active state; multi-select belongs to `CheckboxGroup`.
-- **`FieldSet` + `FieldLegend` group related checkboxes/radios.** Not a `div` with a heading.
-- **Validation: `data-invalid` on `Field`, `aria-invalid` on the control.** Disabled: `data-disabled` on `Field`, `disabled` on the control.
-
-### Component Structure → [composition.md](./rules/composition.md)
-
-- **Items always inside their Group.** `SelectItem` → `SelectGroup`; `DropdownMenuItem` → `DropdownMenuGroup`; `CommandItem` → `CommandGroup`.
-- **Use `asChild` for custom triggers.** Polymorphism is `asChild` + Radix `Slot` — `<Button asChild><Link href="/x">Docs</Link></Button>`.
-- **`Button` HAS a real `loading` prop.** `<Button loading>Saving…</Button>` renders a Spinner and blocks interaction — don't compose your own.
-- **Use the right `Button` API.** `variant` (`primary` / `danger` / `success` / `neutral-solid` / …) + `appearance` (`solid` / `outline` / `ghost` / `soft`). There is no `variant="outline"`/`"destructive"`/`"secondary"`.
-- **`Avatar` always needs `AvatarFallback`.**
-- **Prefer components over custom markup.** Callouts → `InlineAlert`; toasts → `Toast`; dividers → `Separator`; tags → `Badge`; removable tags → `Chip`; loading → `Spinner`.
-
-### Icons → [icons.md](./rules/icons.md)
-
-- **Icons in `Button` go through props.** `leadingIcon` / `trailingIcon` (and `iconOnly` for icon-only buttons) — no `data-icon`.
-- **No sizing classes on icons inside components.** The component sets icon size via CVA — no `size-4` / `w-4 h-4`.
-- **Pass icons as components, not string keys.** `icon={CheckIcon}`, never `icon="check"`.
-- **Import icons from `@create-ui/assets/icons`** (Remix `Ri*`, e.g. `RiSearchLine`). Registry components already ship these imports — never swap them. Brand / flag / payment / social marks come from `@create-ui/assets/{social,flags,payments,brands,…}`.
-
-## Key Patterns
-
-The most common idioms that differentiate correct Create UI code. For edge cases, see the linked rule files above.
+<!-- BEGIN GENERATED:ICON-MATRIX -->
+
+| Component | leadingIcon | trailingIcon | iconOnly |
+| --- | --- | --- | --- |
+| AppStoreBadge | - | - | yes |
+| Badge | yes | yes | yes |
+| BreadcrumbItem | yes | yes | - |
+| Button | yes | yes | yes |
+| ButtonGroupItem | yes | yes | yes |
+| CreditCardInput | yes | - | - |
+| DateInput | yes | - | - |
+| SegmentedControlItem | yes | yes | yes |
+| SocialLoginButton | - | - | yes |
+| TabMenuItem | yes | yes | - |
+| TextLink | yes | yes | - |
+
+Components NOT in this table take no leadingIcon/trailingIcon props:
+
+- `Chip` takes its icon or `Avatar` as the FIRST CHILD (auto-slotted into the lead slot). No icon props.
+- `InlineAlert` and `Toast` use dedicated icon subcomponents (`InlineAlertIcon`, `ToastIcon`); `FieldHelper` and `AccordionTrigger` take an `icon` prop; `InputGroupKbd` inherits Badge's icon props.
+- Everything else: icons are not part of the component's API - put the icon next to it in your own markup.
+
+<!-- END GENERATED:ICON-MATRIX -->
+
+## Cross-cutting invariants
+
+- **Prop taxonomy**: `variant` = color intent (`primary`, `danger`, `success`, `neutral-*`, ...) · `appearance` = fill weight (`solid` / `outline` / `soft` / `ghost`) · `size` · `shape`. **There is no `variant="outline"`, `variant="secondary"`, or `variant="destructive"`** - an outline style is `appearance="outline"`, a destructive action is `variant="danger"`.
+- **`Field` owns size; children inherit it.** Set `size` (`xs` | `sm` | `md`) once on `Field`; `Input`, `Select`, `Textarea`, labels and helpers read it via context. Never re-set or downgrade size on a child.
+- **Validation**: `data-invalid` on `Field`, `aria-invalid` on the control. Disabled: `data-disabled` on `Field`, `disabled` on the control.
+- **`Button` has a real `loading` prop** - `<Button loading>Saving...</Button>`. Don't compose spinners into buttons.
+- **Use `asChild` for custom triggers/links** - `<Button asChild><Link href="/x">Docs</Link></Button>`.
+- **Items live inside their Group**: `SelectItem` → `SelectGroup` and `CommandItem` → `CommandGroup` are structural (always wrap); `DropdownMenuGroup` is semantic grouping - a lone `DropdownMenuItem` may sit directly in `DropdownMenuContent`.
+- **Semantic tokens only, never raw colors.** Surfaces `bg-static` / `bg-weak` / `bg-light`, text `text-strongest` / `text-body` / `text-placeholder` / `text-disabled` / `text-static`, borders `border-weak` / `border-light`, primary `bg-primary-base` / `text-primary-base` / `bg-primary-weakest`, status `{error,success,warning,info,away,verified,highlighted}-{base,weak,weakest}`. Never `bg-blue-500`, never hex.
+- **The theme is already chosen - never ask for or re-pick the brand color.** The project's primary and neutral colors were selected at `init` (primary: `indigo`* / `blue` / `lime` / `green` / `red` / `orange` / `yellow` / `cyan`; neutral: `gray`* / `slate` / `zinc` / `base` / `stone`) and live as tokens in the global CSS. Use `bg-primary-base` / `text-primary-base` / `border-primary-*` for any accent - they already render that choice. Do NOT ask the user "what color/theme", do NOT offer or invent a color (there is no `violet` etc. - the set above is fixed), and do NOT rewrite the theme token values in the CSS to "apply" a color. Switching the whole project's theme is `npx @create-ui/cli init --theme <name>` / `--neutral <name>` - only when the user explicitly asks for it.
+- **Focus is `outline-*`, never `ring-*`.**
+- **Spacing**: vertical stacks are `flex flex-col gap-*` (never `space-y-*`); `size-10` not `w-10 h-10`; semantic spacing classes (`gap-component-sm`) only when a Figma design references a token - otherwise standard Tailwind (`gap-4`).
+- **`className` is for layout, not restyling** - don't override a component's colors or typography; reach for `variant`/`appearance` first.
+
+## Use the full component API
+
+Every component exposes many axes - `variant`, `appearance`, `size`, `shape`, state flags, often `orientation` / `layout` / `placement`, and more - and the set differs per component. **Defaults are a baseline, not the answer**; one size and one variant everywhere reads as a wireframe. Before building with a component, read its `reference/<component>.md` prop table and deliberately use the axes that fit the design. The heuristics below show the *kind* of judgment, not a closed list - `shape` and any component-specific axis count just as much:
+
+- **`size`** tracks density / prominence: small for dense or secondary chrome, the default for standard body UI, large for the primary CTA or hero.
+- **`appearance`** tracks hierarchy: exactly one `solid` (primary) action per group, secondary `soft` / `outline`, tertiary or dismiss `ghost`.
+- **`variant`** tracks intent: `primary` for the main action, `neutral-*` for neutral chrome, semantic (`danger` / `success` / `warning` / `info`) only for real meaning - status on Badge / InlineAlert / Toast rides `variant`, never raw color.
+- **State is a prop, not markup**: reach for built-in `loading` / `invalid` (+ `aria-invalid`) / `disabled` / `selected` / `checked` / `readOnly` when context implies them.
+- **Everything else is a real choice too** - `shape`, `orientation` / `layout` (e.g. `Field orientation="horizontal"`, `InlineAlert layout="vertical"`, `TabMenu variant="horizontal-line"` vs `"vertical-button"`), `placement`, and whatever else the component's reference lists. Match it to the design; don't leave it at default out of habit.
+
+Each `reference/<component>.md` canonical example already spans its component's axes - mirror that range, don't collapse to defaults. `rules/design.md` has the per-component richness checklist and anti-patterns.
+
+## Never hand-roll
+
+| You need | Use (never raw markup) |
+| --- | --- |
+| Tabs | `TabMenu` + `TabMenuItem` + your own value-keyed panels (recipe below) |
+| Toggle between 2-7 options | `SegmentedControl` + `SegmentedControlItem` (`value`/`onValueChange`) - never a row of `Button`s with manual active state |
+| Tag / label | `Badge` (icons via `leadingIcon`/`trailingIcon`) |
+| Removable / interactive tag | `Chip` (icon or `Avatar` as FIRST CHILD, `closable`/`onClose`) |
+| Status dot | `StatusBadge` (dot only - label goes next to it) |
+| Callout / inline banner | `InlineAlert` (+`InlineAlertIcon`/`Title`/`Description`) |
+| Notification | `Toast` (+`ToastIcon`/`ToastTitle`/`ToastAction`) |
+| Avatar initials | `Avatar` + `AvatarText` (**`AvatarFallback` does not exist**) |
+| Loading state | `Spinner`, or `Button loading` |
+| Divider | `Separator` |
+| Menu | `DropdownMenu` family |
+| Command palette | `Command` (inline) / `CommandDialog` (modal) |
+
+## Recipes
+
+**Tabs with content panels** - `TabMenu` renders the tab list only; you render the panels, keyed by value:
 
 ```tsx
-import { Button } from "@/components/ui/button"
-import { Field, FieldGroup, FieldLabel, FieldDescription } from "@/components/ui/field"
-import { Input } from "@/components/ui/input"
-import { RiArrowRightLine, RiSearchLine } from "@create-ui/assets/icons"
-import Link from "next/link"
-
-// Button: appearance + icon props + loading. No variant="outline", no data-icon.
-<Button appearance="outline" leadingIcon={<RiSearchLine />}>Search</Button>
-<Button loading>Saving…</Button>
-<Button asChild appearance="ghost" trailingIcon={<RiArrowRightLine />}>
-  <Link href="/docs">Docs</Link>
-</Button>
-
-// Forms: FieldGroup + Field. Field owns size; Input inherits it.
-<FieldGroup>
-  <Field size="md">
-    <FieldLabel htmlFor="email">Email</FieldLabel>
-    <Input id="email" type="email" />
-    <FieldDescription>We'll never share it.</FieldDescription>
-  </Field>
-</FieldGroup>
-
-// Spacing: gap-component-sm only when Figma uses a token; otherwise gap-4.
-<div className="flex flex-col gap-4">…</div>
-
-// Conditional classes via cn().
-<div className={cn("rounded-lg p-4", isActive && "bg-weak")} />
+const [tab, setTab] = React.useState("overview")
+
+<TabMenu variant="horizontal-line" indicator="bottom" value={tab} onValueChange={setTab}>
+  <TabMenuItem value="overview" label="Overview" />
+  <TabMenuItem value="billing" label="Billing" leadingIcon={<RiBankCardLine />} />
+</TabMenu>
+{tab === "overview" && <OverviewPanel />}
+{tab === "billing" && <BillingPanel />}
 ```
 
-## Component Selection
-
-Every name below ships in `@createui` — and nothing else does. If a component isn't in this table (there is no card, table, tabs, sheet, drawer, skeleton, sidebar, dialog/modal, popover, or alert-banner component), build the layout from semantic-token markup and these primitives instead. The only modal surface is `CommandDialog` (part of `command`).
-
-| Need                       | Use                                                                                                    |
-| -------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Button / action            | `Button` (`variant` + `appearance`), `ButtonGroup`, `CloseButton`, `SocialLoginButton`, `AppStoreBadge` |
-| Form layout                | `Field` + `FieldGroup` (+ `FieldSet` / `FieldLegend`), `Label`                                          |
-| Form inputs                | `Input`, `Textarea`, `Select`, `Checkbox`, `Radio` / `RadioGroup`, `Switch`, `InputOTP`                 |
-| Grouped on/off controls    | `CheckboxGroup`, `SwitchGroup`                                                                          |
-| Formatted inputs           | `DateInput`, `PhoneInput`, `CreditCardInput`, `InputStepper`, `PasswordStrength`                        |
-| Toggle between 2–7 options | `SegmentedControl` + `SegmentedControlItem`                                                             |
-| Inputs with affordances    | `InputGroup` + `InputGroupAddon` / `InputGroupButton`                                                   |
-| Data display               | `Badge`, `StatusBadge` (dot), `Chip`, `Avatar`, `CountryFlag` / `CurrencyFlag` (both from the `country-flag` item), `Progress` |
-| Navigation                 | `Breadcrumb`, `Pagination`, `TabMenu`, `TextLink`                                                       |
-| Menus                      | `DropdownMenu`                                                                                          |
-| Command palette            | `Command` (inline) / `CommandDialog` (modal)                                                            |
-| Feedback                   | `Toast`, `InlineAlert` (inline callout), `Progress`, `Spinner`                                          |
-| Tooltips / info            | `Tooltip`, `InfoTooltip`                                                                                |
-| Layout                     | `Accordion`, `AspectRatio`, `ScrollArea`, `Separator`                                                   |
-
-> **Icons & assets** all come from `@create-ui/assets`: UI icons at `@create-ui/assets/icons` (Remix `Ri*`), plus `social` / `flags` / `payments` / `brands` / `badges` / `banks` / `crypto` marks (these back `CountryFlag`, `SocialLoginButton`, …). Never import from `lucide-react`. See [rules/icons.md](./rules/icons.md).
-
-> The registry also ships **hooks** (`use-mobile`, `use-credit-card-input`, `use-date-input`, `use-phone-input`) and **lib utilities** (`utils`, `country-flags`, `currency-flags`) — these appear in `search` results as `registry:hook` / `registry:lib` items and are installed automatically as dependencies of the components that need them.
-
-## Key Fields (components.json)
-
-`info` surfaces these fields — read them before writing imports or advising on directives:
-
-- **`aliases`** — the import prefixes (`components`, `utils`, `ui`, `lib`, `hooks`). Use the actual aliases (e.g. `@/components/ui`, `@/lib/utils`), never hardcode.
-- **`rsc`** — when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top.
-- **`tsx`** — whether components are emitted as `.tsx` (default `true`).
-- **`tailwind.css`** — the global CSS file where tokens are defined. Edit this file; never create a new one.
-- **`iconLibrary`** — Create UI's icon library, `createui`. Icons (and all marks) come from `@create-ui/assets`; UI icons are `@create-ui/assets/icons` (Remix `Ri*`). Never import from `lucide-react` or another package.
-- **`menuColor`** (`default` | `inverted`) / **`menuAccent`** (`subtle` | `bold`) — menu surface treatment.
+**Billing / pricing toggle** - the active pill slides between items in both appearances; `appearance="grouped"` adds the padded `bg-weak` container (the classic pricing-toggle look):
 
-**`@createui` is the only registry.** There is no `registries` field to configure — never add one or point the project at another registry.
+```tsx
+const [billing, setBilling] = React.useState("monthly")
 
-See [cli.md — `info`](./cli.md) and [customization.md](./customization.md) for the full reference.
+<SegmentedControl appearance="grouped" variant="neutral" value={billing} onValueChange={setBilling}>
+  <SegmentedControlItem value="monthly">Monthly</SegmentedControlItem>
+  <SegmentedControlItem value="yearly">Yearly</SegmentedControlItem>
+</SegmentedControl>
+```
 
-## Workflow
+**Showcase-quality switch** - bare `<Switch />` is for dense forms; showcases should exercise the richer API (see `reference/switch.md`). Labelled apply-immediately rows use `SwitchGroup`; the `Field` composition below is for submit-to-save forms:
 
-1. **Get project context** — `npx @create-ui/cli info`.
-2. **Check installed components first** — before `add`, list the `ui` alias directory (e.g. `components/ui/`); `info` prints the config and aliases but not an installed-components list. Don't import un-added components, and don't re-add installed ones.
-3. **Find components** — `npx @create-ui/cli search @createui -q "<query>"`.
-4. **Inspect before adding** — `npx @create-ui/cli view <name>` to see an item's metadata and files; `npx @create-ui/cli diff <name>` to see what changed upstream for an installed one.
-5. **Add** — `npx @create-ui/cli add <name>`.
-6. **Review added files** — read them and verify composition (e.g. `SelectItem` inside `SelectGroup`), imports, and adherence to the Critical Rules. Registry components import icons from `@create-ui/assets/icons` — keep them as-is; never rewrite them to `lucide-react` or another package.
-7. **Components come from `@createui`** — always. Never configure another registry or suggest one.
+```tsx
+<Field size="md" orientation="horizontal">
+  <FieldContent>
+    <FieldLabel htmlFor="2fa">Enforce two-factor auth</FieldLabel>
+  </FieldContent>
+  <Switch id="2fa" thumbIcon defaultChecked />
+</Field>
+<Switch variant="semantic" thumbType="long" ioTrigger aria-label="Accept" />
+```
 
-## Updating Components
+(`Field` size does not cascade to `Switch` - pair them explicitly, or use `SwitchGroup` which pairs both automatically.)
 
-To keep local edits while pulling upstream changes, use the `diff` command — **never fetch raw files manually.**
+## components.json keys
 
-1. `npx @create-ui/cli diff` — list installed components that have updates.
-2. `npx @create-ui/cli diff <name>` — show what changed upstream for that component.
-3. Decide per component: no local changes → re-add; has local changes → read the local file, study the diff, apply upstream changes while preserving your edits.
-4. `npx @create-ui/cli add <name> --overwrite` replaces files — **only with the user's explicit approval.**
+- **`aliases`** - import prefixes (`ui`, `components`, `utils`, `lib`, `hooks`). Use the project's actual aliases, never hardcode.
+- **`rsc`** - when `true`, components using state/effects/events need `"use client"`. Keep the boundary tight: isolate the interactive piece in its own file rather than hoisting the directive over a whole static section.
+- **`tailwind.css`** - the global CSS file where tokens live. Edit it; never create a new one. Never rewrite the primary/neutral theme token values here to change the brand color - that is an `init` choice (see invariants above).
+- **`iconLibrary`** - `createui` (`@create-ui/assets`). Never swap registry imports to another icon package.
+- **`menuColor`** (`default` | `inverted`) / **`menuAccent`** (`subtle` | `bold`) - menu surface treatment.
 
-## Quick Reference
+## CLI quick reference
 
 ```bash
-# Initialize an existing project (writes components.json, installs deps).
-npx @create-ui/cli init
-npx @create-ui/cli init --theme indigo --neutral gray --font-variant v1
-
-# Scaffold a new project (missing name/template/theme are prompted interactively).
-npx @create-ui/cli create my-app --template next
-npx @create-ui/cli create
-
-# Add components (items are always bare names).
-npx @create-ui/cli add button select dropdown-menu
-npx @create-ui/cli add --all
-
-# Inspect the registry (@createui is the registry argument for search/list only).
+npx @create-ui/cli init                       # existing project (writes components.json)
+npx @create-ui/cli create my-app --template next   # new project (next | start | vite)
+npx @create-ui/cli add button select          # add components (bare names)
 npx @create-ui/cli search @createui -q "toast"
-npx @create-ui/cli search @createui -l 500   # full listing — the default limit is 100, the registry has more items
-npx @create-ui/cli view button
-npx @create-ui/cli diff button
-
-# Migrate (e.g. consolidate radix imports, or switch icon library).
-npx @create-ui/cli migrate --list
-
-# Set up the MCP server for your client.
-npx @create-ui/cli mcp init --client claude
+npx @create-ui/cli view button                # item metadata + files
+npx @create-ui/cli diff button                # upstream changes for installed items
+npx @create-ui/cli mcp init --client claude   # set up the MCP server
 ```
 
-**Primary themes:** indigo (default), blue, lime, green, red, orange, yellow, cyan
-**Neutral themes:** gray (default), slate, zinc, base, stone
-**Templates:** `next`, `start`, `vite` (plus `next-monorepo` for `init`)
+`add --overwrite` replaces files - only with the user's explicit approval. To update, prefer `diff` and merge upstream changes while preserving local edits. Primary themes: indigo (default), blue, lime, green, red, orange, yellow, cyan. Neutrals: gray (default), slate, zinc, base, stone.
 
-## Detailed References
+## Detailed references
 
-- [cli.md](./cli.md) — every command and flag (init, create, add, diff, view, search, migrate, info, mcp, skill).
-- [mcp.md](./mcp.md) — the MCP server, `mcp init` clients, and the available MCP tools.
-- [customization.md](./customization.md) — theming, the `--color-*` / semantic tokens, radius, and dark mode.
-- [rules/styling.md](./rules/styling.md) — semantic tokens, `className` scope, spacing, `size-*`, `outline-*` focus, `cn()`.
-- [rules/forms.md](./rules/forms.md) — `FieldGroup`, `Field` size cascade, `InputGroup`, `SegmentedControl`, `FieldSet`, validation states.
-- [rules/composition.md](./rules/composition.md) — Groups, overlays, `TabMenu`, `Avatar`, `InlineAlert`, `Toast`, `Separator`, `Badge`, `Button` loading.
-- [rules/icons.md](./rules/icons.md) — `leadingIcon` / `trailingIcon`, icon sizing, passing icons as components.
+- [reference/](./reference/) - **per-component API (generated from source - read before first use)**.
+- [rules/design.md](./rules/design.md) - design taste: hero/CTA/footer/pricing recipes, richness checklist, anti-patterns.
+- [rules/icons.md](./rules/icons.md) - icon props per component, sizing, assets packages.
+- [rules/composition.md](./rules/composition.md) - groups, overlays, TabMenu, Avatar, InlineAlert, Toast.
+- [rules/forms.md](./rules/forms.md) - FieldGroup/Field, size cascade, InputGroup, SegmentedControl, validation.
+- [rules/styling.md](./rules/styling.md) - semantic tokens, className scope, spacing, focus.
+- [cli.md](./cli.md) - every command and flag. [mcp.md](./mcp.md) - MCP tools and workflow. [customization.md](./customization.md) - theming and tokens.
 
 ## Resources
 

package/dist/skills/createui/agents/openai.yml

@@ -1,5 +1,5 @@
 interface:
   display_name: "Create UI"
-  short_description: "Manages Create UI components — adding, searching, updating, styling, and composing UI from the @createui registry."
+  short_description: "Create UI component library: per-component API references, composition rules, semantic tokens, and design recipes for building UI with the @createui registry."
   icon_small: "./assets/createui-small.png"
   icon_large: "./assets/createui.png"