@create-ui/cli 0.1.0-beta.0 → 0.5.0

package/dist/skills/createui/rules/composition.md

@@ -0,0 +1,249 @@
+# Component Composition
+
+How Create UI components fit together. Compose primitives — never reroll a `<select>`, a custom callout, or a hand-styled loading button when a component already exists. Every component name below is in the Create UI registry; add any of them with `npx @create-ui/cli add <name>`.
+
+## Contents
+
+- Items always inside their Group component
+- Callouts use Alert
+- Empty states use the Empty component
+- Toast notifications use sonner
+- Choosing between overlay components
+- Dialog, Sheet, and Drawer always need a Title
+- Card structure
+- Button has a `loading` prop — never hand-build a spinner button
+- TabsTrigger must be inside TabsList
+- Avatar always needs AvatarFallback
+- Use existing components instead of custom markup
+
+---
+
+## Items always inside their Group component
+
+Never render menu/list items directly inside the content container — always wrap them in the matching `*Group`.
+
+**Incorrect:**
+
+```tsx
+<SelectContent>
+  <SelectItem value="apple">Apple</SelectItem>
+  <SelectItem value="banana">Banana</SelectItem>
+</SelectContent>
+```
+
+**Correct:**
+
+```tsx
+<SelectContent>
+  <SelectGroup>
+    <SelectLabel>Fruit</SelectLabel>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+
+This applies to every group-based component:
+
+| Item | Group |
+|------|-------|
+| `SelectItem`, `SelectLabel` | `SelectGroup` |
+| `DropdownMenuItem`, `DropdownMenuLabel` | `DropdownMenuGroup` |
+| `MenubarItem`, `MenubarLabel` | `MenubarGroup` |
+| `ContextMenuItem`, `ContextMenuLabel` | `ContextMenuGroup` |
+| `CommandItem` | `CommandGroup` |
+
+---
+
+## Callouts use Alert
+
+Use `Alert` for inline callouts. Set the tone with the `variant` prop (`default` or `danger`) and compose the parts — `AlertTitle`, `AlertDescription`, and `AlertAction`. Don't hand-roll a styled `<div>`.
+
+**Incorrect:**
+
+```tsx
+<div className="rounded-lg border bg-error-weak p-4">
+  <p className="font-medium">Payment failed</p>
+  <p>Update your card to continue.</p>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<Alert variant="danger">
+  <AlertTitle>Payment failed</AlertTitle>
+  <AlertDescription>Update your card to continue.</AlertDescription>
+  <AlertAction>
+    <Button variant="danger" size="sm">Update card</Button>
+  </AlertAction>
+</Alert>
+```
+
+Related callouts ship as their own components: `inline-alert` for compact, text-row callouts and `alert-banner` for full-width page-level banners. Reach for those instead of restyling `Alert` into a different shape.
+
+---
+
+## Empty states use the Empty component
+
+Don't hand-build empty/zero states. `Empty` composes a header (`EmptyHeader` → `EmptyMedia`, `EmptyTitle`, `EmptyDescription`) and a `EmptyContent` action area. Use `EmptyMedia variant="icon"` to get the boxed icon treatment.
+
+```tsx
+import { RiFolderLine } from "lucide-react" // or your project's iconLibrary
+
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <RiFolderLine />
+    </EmptyMedia>
+    <EmptyTitle>No projects yet</EmptyTitle>
+    <EmptyDescription>Get started by creating a new project.</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>Create Project</Button>
+  </EmptyContent>
+</Empty>
+```
+
+---
+
+## Toast notifications use sonner
+
+Toasts come from `sonner`. Import the `toast` function directly — don't build a custom toast component.
+
+```tsx
+import { toast } from "sonner"
+
+toast.success("Changes saved.")
+toast.error("Something went wrong.")
+toast("File deleted.", {
+  action: { label: "Undo", onClick: () => undoDelete() },
+})
+```
+
+---
+
+## Choosing between overlay components
+
+Pick the overlay that matches the interaction — they all exist in the registry.
+
+| Use case | Component |
+|----------|-----------|
+| Focused task that requires input | `Dialog` |
+| Destructive action confirmation | `AlertDialog` |
+| Side panel with details or filters | `Sheet` |
+| Mobile-first bottom panel | `Drawer` |
+| Quick info on hover | `HoverCard` |
+| Small contextual content on click | `Popover` |
+
+---
+
+## Dialog, Sheet, and Drawer always need a Title
+
+`DialogTitle`, `SheetTitle`, and `DrawerTitle` are required for accessibility — screen readers announce them. Keep one even when the design hides it visually; add `className="sr-only"` in that case.
+
+```tsx
+<DialogContent>
+  <DialogHeader>
+    <DialogTitle>Edit Profile</DialogTitle>
+    <DialogDescription>Update your profile.</DialogDescription>
+  </DialogHeader>
+  ...
+</DialogContent>
+```
+
+---
+
+## Card structure
+
+Compose `Card` from its parts — don't dump everything into `CardContent`. `CardAction` slots an action into the header row.
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Team Members</CardTitle>
+    <CardDescription>Manage your team.</CardDescription>
+    <CardAction>
+      <Button appearance="ghost" size="sm">Settings</Button>
+    </CardAction>
+  </CardHeader>
+  <CardContent>...</CardContent>
+  <CardFooter>
+    <Button>Invite</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+## Button has a `loading` prop — never hand-build a spinner button
+
+`Button` ships a real `loading` prop. It renders the `Spinner` and disables interaction for you — do not compose a `Spinner` + `disabled` button by hand.
+
+**Incorrect:**
+
+```tsx
+<Button disabled>
+  <Spinner />
+  Saving…
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button loading>Saving…</Button>
+```
+
+For icons, use the `leadingIcon` / `trailingIcon` props (or `iconOnly` for an icon-only button) — never wrap raw `<svg>` children or add sizing classes; the component sizes the icon per `size`.
+
+```tsx
+import { RiSearchLine } from "lucide-react" // or your project's iconLibrary
+
+<Button leadingIcon={<RiSearchLine />}>Search</Button>
+<Button iconOnly aria-label="Search" leadingIcon={<RiSearchLine />} />
+```
+
+Remember the Button API: `variant` is `primary | neutral-solid | neutral-light | danger | success | inverse-solid | inverse-light`, and the outlined/ghost looks come from `appearance` (`solid | outline | ghost | soft`). There is no outline or destructive `variant` value — use `appearance="outline"` for the outlined look and `variant="danger"` for destructive actions. See `rules/styling.md` for the full variant/appearance reference.
+
+---
+
+## TabsTrigger must be inside TabsList
+
+Never render `TabsTrigger` directly inside `Tabs` — always wrap the triggers in `TabsList`.
+
+```tsx
+<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">...</TabsContent>
+</Tabs>
+```
+
+---
+
+## Avatar always needs AvatarFallback
+
+Always include `AvatarFallback` so something renders when the image is missing or fails to load.
+
+```tsx
+<Avatar>
+  <AvatarImage src="/avatar.png" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+---
+
+## Use existing components instead of custom markup
+
+If a primitive already covers the job, use it — don't reach for raw elements or utility-class fakes.
+
+| Instead of | Use |
+|---|---|
+| `<hr>` or `<div className="border-t">` | `<Separator />` |
+| `<div className="animate-pulse">` with styled divs | `<Skeleton className="h-4 w-3/4" />` |
+| `<span className="rounded-full bg-green-100 …">` | `<Badge variant="success">Active</Badge>` |
+| A status dot built from a styled `<span>` | `<StatusBadge variant="success">Online</StatusBadge>` |

package/dist/skills/createui/rules/forms.md

@@ -0,0 +1,301 @@
+# Forms & Inputs
+
+## Contents
+
+- Forms use FieldGroup + Field
+- Choosing the right form control
+- InputGroup requires InputGroupControl/InputGroupTextarea
+- Buttons inside inputs use InputGroup + InputGroupButton
+- Option sets (2–7 choices) use ToggleGroup
+- Dropdowns use Select
+- FieldSet + FieldLegend for grouping related fields
+- Field validation and disabled states
+
+---
+
+## Forms use FieldGroup + Field
+
+Always lay out a form with `FieldGroup` + `Field` — never a raw `div` with `space-y-*`. `Field` owns the size, invalid, disabled and loading state for everything inside it, and the nested control reads that state automatically.
+
+**Incorrect:**
+
+```tsx
+<div className="space-y-4">
+  <div className="flex flex-col gap-2">
+    <label htmlFor="email">Email</label>
+    <input id="email" type="email" />
+  </div>
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { Field, FieldGroup, FieldLabel, FieldDescription } from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" type="email" />
+    <FieldDescription>We'll never share your address.</FieldDescription>
+  </Field>
+  <Field>
+    <FieldLabel htmlFor="password">Password</FieldLabel>
+    <Input id="password" type="password" />
+  </Field>
+</FieldGroup>
+```
+
+`Field` accepts `size` (`"xs" | "sm" | "md"`, default `"sm"`) and `orientation` (`"vertical" | "horizontal" | "responsive"`, default `"vertical"`). Size cascades top-down: set it once on `Field` and the control, label, and description inherit it — never re-set the size on each child.
+
+```tsx
+// Horizontal layout for settings rows.
+<Field orientation="horizontal">
+  <FieldLabel htmlFor="notifications">Email notifications</FieldLabel>
+  <Switch id="notifications" />
+</Field>
+```
+
+Use `FieldLabel className="sr-only"` for a visually hidden but accessible label.
+
+---
+
+## Choosing the right form control
+
+Every control below exists in the registry. Pick by intent:
+
+| Need | Use |
+|---|---|
+| Single-line text | `Input` |
+| Multi-line text | `Textarea` |
+| Dropdown of predefined options | `Select` |
+| Searchable dropdown | `Combobox` |
+| Native HTML select (no JS) | `native-select` |
+| Boolean in a settings row | `Switch` |
+| Boolean in a form | `Checkbox` |
+| One choice from a few options | `RadioGroup` |
+| One choice across 2–7 visible options | `ToggleGroup` |
+| Verification / OTP code | `InputOTP` |
+| Numeric value with step controls | `input-stepper` |
+
+---
+
+## InputGroup requires InputGroupControl/InputGroupTextarea
+
+Never put a raw `Input` or `Textarea` inside an `InputGroup`. The group manages size and state through its own context, so use `InputGroupControl` (single-line) or `InputGroupTextarea` (multi-line).
+
+**Incorrect:**
+
+```tsx
+<InputGroup>
+  <Input placeholder="Search…" />
+</InputGroup>
+```
+
+**Correct:**
+
+```tsx
+import { InputGroup, InputGroupControl } from "@/components/ui/input-group"
+
+<InputGroup>
+  <InputGroupControl placeholder="Search…" />
+</InputGroup>
+```
+
+For multi-line input inside a group, use the `multiline` prop with `InputGroupTextarea`:
+
+```tsx
+import { InputGroup, InputGroupTextarea } from "@/components/ui/input-group"
+
+<InputGroup multiline>
+  <InputGroupTextarea placeholder="Leave a comment…" rows={4} />
+</InputGroup>
+```
+
+---
+
+## Buttons inside inputs use InputGroup + InputGroupButton
+
+Never absolutely-position a `Button` over an `Input`. Compose `InputGroup` + `InputGroupButton` (or `InputGroupAddon` for non-interactive affordances). `InputGroupButton` inherits the group's size and state, so you don't set `size` on it. Pass the icon through `leadingIcon`, or use `iconOnly` for an icon-only button — never a `data-icon` attribute.
+
+**Incorrect:**
+
+```tsx
+<div className="relative">
+  <Input placeholder="Search…" className="pr-10" />
+  <Button className="absolute right-0 top-0" iconOnly aria-label="Search">
+    <RiSearchLine />
+  </Button>
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { InputGroup, InputGroupControl, InputGroupButton } from "@/components/ui/input-group"
+import { RiSearchLine } from "lucide-react"
+
+<InputGroup>
+  <InputGroupControl placeholder="Search…" />
+  <InputGroupButton iconOnly aria-label="Search" leadingIcon={<RiSearchLine />} />
+</InputGroup>
+```
+
+For a static prefix/suffix (currency, unit, helper text) use `InputGroupAddon` instead of a button:
+
+```tsx
+import { InputGroup, InputGroupControl, InputGroupAddon } from "@/components/ui/input-group"
+
+<InputGroup>
+  <InputGroupAddon>$</InputGroupAddon>
+  <InputGroupControl placeholder="0.00" inputMode="decimal" />
+  <InputGroupAddon>USD</InputGroupAddon>
+</InputGroup>
+```
+
+---
+
+## Option sets (2–7 choices) use ToggleGroup
+
+For a small set of mutually-exclusive (or multi-select) choices, use `ToggleGroup` + `ToggleGroupItem`. Don't hand-roll a row of `Button`s with manual active state. `ToggleGroup` is built on Radix, so it takes `type="single"` or `type="multiple"` and the matching value props (`value` / `defaultValue` / `onValueChange`).
+
+**Incorrect:**
+
+```tsx
+const [selected, setSelected] = useState("daily")
+
+<div className="flex gap-2">
+  {["daily", "weekly", "monthly"].map((option) => (
+    <Button
+      key={option}
+      appearance={selected === option ? "solid" : "outline"}
+      onClick={() => setSelected(option)}
+    >
+      {option}
+    </Button>
+  ))}
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
+
+<ToggleGroup type="single" defaultValue="daily">
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+  <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>
+</ToggleGroup>
+```
+
+Use `type="multiple"` (value is a string array) when more than one option can be active at once. Wrap a labelled toggle group in a `Field` and connect them with `aria-labelledby`:
+
+```tsx
+import { Field, FieldTitle } from "@/components/ui/field"
+import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
+
+<Field orientation="horizontal">
+  <FieldTitle id="theme-label">Theme</FieldTitle>
+  <ToggleGroup type="single" defaultValue="system" aria-labelledby="theme-label">
+    <ToggleGroupItem value="light">Light</ToggleGroupItem>
+    <ToggleGroupItem value="dark">Dark</ToggleGroupItem>
+    <ToggleGroupItem value="system">System</ToggleGroupItem>
+  </ToggleGroup>
+</Field>
+```
+
+---
+
+## Dropdowns use Select
+
+`Select` is composed from Radix parts: `SelectTrigger`, `SelectValue`, `SelectContent`, and `SelectItem`. There is no `items` prop — render `SelectItem` children. Inside a `Field`, the trigger inherits the field's size, invalid, and disabled state automatically, so set them on `Field`, not on each part.
+
+```tsx
+import { Field, FieldLabel } from "@/components/ui/field"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+
+<Field>
+  <FieldLabel htmlFor="role">Role</FieldLabel>
+  <Select>
+    <SelectTrigger id="role">
+      <SelectValue placeholder="Select a role" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="admin">Admin</SelectItem>
+      <SelectItem value="editor">Editor</SelectItem>
+      <SelectItem value="viewer">Viewer</SelectItem>
+    </SelectContent>
+  </Select>
+</Field>
+```
+
+`Select` accepts `size` (`"xs" | "sm" | "md"`), `invalid`, `disabled`, and `loading`. When it's not inside a `Field`, set these on the `Select` itself. For a dropdown with no JS, reach for `native-select` instead. For a searchable list, use `Combobox`.
+
+---
+
+## FieldSet + FieldLegend for grouping related fields
+
+Use `FieldSet` + `FieldLegend` to group related checkboxes, radios, or switches — not a `div` with a heading. `FieldLegend` takes `variant="legend"` (default, section-sized) or `variant="label"` (form-control-sized).
+
+```tsx
+import {
+  FieldSet,
+  FieldLegend,
+  FieldDescription,
+  FieldGroup,
+  Field,
+  FieldLabel,
+} from "@/components/ui/field"
+import { Checkbox } from "@/components/ui/checkbox"
+
+<FieldSet>
+  <FieldLegend variant="label">Notifications</FieldLegend>
+  <FieldDescription>Choose what you want to hear about.</FieldDescription>
+  <FieldGroup>
+    <Field orientation="horizontal">
+      <Checkbox id="product" />
+      <FieldLabel htmlFor="product">Product updates</FieldLabel>
+    </Field>
+    <Field orientation="horizontal">
+      <Checkbox id="security" />
+      <FieldLabel htmlFor="security">Security alerts</FieldLabel>
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+
+For a single-choice group, swap the checkboxes for a `RadioGroup` inside the same `FieldSet`.
+
+---
+
+## Field validation and disabled states
+
+`Field` exposes the state two ways: the boolean props `invalid` / `disabled` / `loading`, or the matching `data-invalid` / `data-disabled` / `data-loading` attributes. Either form drives the field styling (label, description, error). The control itself still needs `aria-invalid` / `disabled` so its own visuals and assistive tech reflect the state. Use `FieldError` to render the message.
+
+```tsx
+import { Field, FieldLabel, FieldError } from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+
+// Invalid.
+<Field invalid>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" type="email" aria-invalid />
+  <FieldError>Enter a valid email address.</FieldError>
+</Field>
+
+// Disabled.
+<Field disabled>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" type="email" disabled />
+</Field>
+```
+
+This pattern works for every control: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `native-select`, and `InputOTP`.

package/dist/skills/createui/rules/icons.md

@@ -0,0 +1,130 @@
+# Icons
+
+## Contents
+
+- [Import from the configured icon library](#import-from-the-configured-icon-library)
+- [Icons in Button use the leadingIcon / trailingIcon props](#icons-in-button-use-the-leadingicon--trailingicon-props)
+- [Icon-only buttons](#icon-only-buttons)
+- [No sizing classes on icons inside components](#no-sizing-classes-on-icons-inside-components)
+- [Pass icons as component values, not string keys](#pass-icons-as-component-values-not-string-keys)
+
+---
+
+## Import from the configured icon library
+
+**Always import icons from the project's configured `iconLibrary`.** Read the `iconLibrary` field from `createui info` (or `components.json`): `lucide` → `lucide-react`, `tabler` → `@tabler/icons-react`, etc. The resolved default is `lucide`. Never hardcode an icon package.
+
+Inside this monorepo, components import their icons from `@create-ui/assets/icons` (RemixIcon `Ri*`, e.g. `RiSearchLine`, `RiArrowRightLine`, `RiCheckLine`). In an end-user project, use whatever `iconLibrary` resolves to.
+
+---
+
+## Icons in Button use the leadingIcon / trailingIcon props
+
+`Button` accepts icons through the `leadingIcon` and `trailingIcon` props — not as children. The button sizes the icon automatically per `size` (via its CVA `[&_svg]:size-N`), so the icon never needs a sizing class. There is no `data-icon` attribute in Create UI.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="mr-2 size-4" />
+  Search
+</Button>
+
+<Button>
+  Next
+  <ArrowRightIcon className="ml-2 size-4" />
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button leadingIcon={<SearchIcon />}>Search</Button>
+
+<Button trailingIcon={<ArrowRightIcon />}>Next</Button>
+```
+
+---
+
+## Icon-only buttons
+
+For a button that shows only an icon, set `iconOnly`, pass the icon via `leadingIcon`, and always supply an `aria-label`. There is no separate icon-button component. For a close affordance, use the `close-button` component instead.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="size-4" />
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button iconOnly aria-label="Search" leadingIcon={<SearchIcon />} />
+
+<Button iconOnly aria-label="More options" appearance="ghost" leadingIcon={<MoreIcon />} />
+```
+
+---
+
+## No sizing classes on icons inside components
+
+Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons rendered inside `Button`, `DropdownMenuItem`, `Alert`, `Sidebar*`, or other Create UI components — unless the user explicitly asks for a custom icon size.
+
+**Incorrect:**
+
+```tsx
+<Button leadingIcon={<SearchIcon className="size-4" />}>Search</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon className="mr-2 size-4" />
+  Settings
+</DropdownMenuItem>
+```
+
+**Correct:**
+
+```tsx
+<Button leadingIcon={<SearchIcon />}>Search</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon />
+  Settings
+</DropdownMenuItem>
+```
+
+---
+
+## Pass icons as component values, not string keys
+
+Use `icon={CheckIcon}`, not a string key into a lookup map.
+
+**Incorrect:**
+
+```tsx
+const iconMap = {
+  check: CheckIcon,
+  alert: AlertIcon,
+}
+
+function StatusBadge({ icon }: { icon: string }) {
+  const Icon = iconMap[icon]
+  return <Icon />
+}
+
+<StatusBadge icon="check" />
+```
+
+**Correct:**
+
+```tsx
+// Import from the project's configured iconLibrary (e.g. lucide-react, @tabler/icons-react).
+import { CheckIcon } from "lucide-react"
+
+function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) {
+  return <Icon />
+}
+
+<StatusBadge icon={CheckIcon} />
+```