shadcn – Design & UI skill for AI agents

shadcn/ui

A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.

> IMPORTANT: Run all CLI commands using the project's package runner: npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest — based on the project's packageManager. Examples below use npx shadcn@latest but substitute the correct runner for the project.

When to Use

• Use when adding new components from shadcn/ui or community registries.
• Use when styling, composing, or debugging existing shadcn/ui components.
• Use when initializing a new project or switching design system presets.
• Use to retrieve component documentation, examples, and API references.

Current Project Context

Read components.json, the package manifest/lockfile and the installed component source first. If the approved CLI is available, run its info command in the intended project directory and inspect errors directly. Skill Markdown does not inject command output automatically; do not interpret the command text as project JSON or treat any CLI failure as evidence that initialization is needed.

Use the project's existing approved CLI version and package runner when available. The @latest examples download and execute a mutable npm package; establish the intended version and registry before running them.

Principles

1. Use existing components first. Use npx shadcn@latest search to check registries before writing custom UI. Check community registries too.

2. Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.

3. Use built-in variants before custom styles. variant="outline", size="sm", etc.

4. Use semantic colors. bg-primary, text-muted-foreground — never raw values like bg-blue-500.

Critical Rules

These are defaults for the documented presets; installed source, accessibility requirements and explicit user design choices take precedence. Each links to a file with Incorrect/Correct code pairs.

Styling & Tailwind → [styling.md](./rules/styling.md)

• className for layout, not styling. Never override component colors or typography.
• **No space-x-* or space-y-*.** Use flex with gap-*. For vertical stacks, flex flex-col gap-*.
• **Use size-* when width and height are equal.** size-10 not w-10 h-10.
• Use truncate shorthand. Not overflow-hidden text-ellipsis whitespace-nowrap.
• No manual dark: color overrides. Use semantic tokens (bg-background, text-muted-foreground).
• Use cn() for conditional classes. Don't write manual template literal ternaries.
• Prefer the component overlay stacking defaults; diagnose portal/stacking contexts before overriding them. Dialog, Sheet, Popover, etc. handle their own stacking.

Forms & Inputs → [forms.md](./rules/forms.md)

• Forms prefer installed FieldGroup + Field. Never use raw div with space-y-* or grid gap-* for form layout.
• InputGroup uses InputGroupInput/InputGroupTextarea. Never raw Input/Textarea inside InputGroup.
• Buttons inside inputs use InputGroup + InputGroupAddon.
• Toggle controls can use ToggleGroup; independent boolean settings use switches or checkboxes. Don't loop Button with manual active state.
• FieldSet + FieldLegend for grouping related checkboxes/radios. Don't use a div with a heading.
• Field validation uses data-invalid + aria-invalid. data-invalid on Field, aria-invalid on the control. For 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 (radix) or render (base) for custom triggers. Check base field from npx shadcn@latest info. → [base-vs-radix.md](./rules/base-vs-radix.md)
• Dialog, Sheet, and Drawer always need a Title. DialogTitle, SheetTitle, DrawerTitle required for accessibility. Use className="sr-only" if visually hidden.
• Use full Card composition. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Don't dump everything in CardContent.
• Button has no isPending/isLoading. Compose with Spinner + data-icon + disabled.
• TabsTrigger must be inside TabsList. Never render triggers directly in Tabs.
• Avatar always needs AvatarFallback. For when the image fails to load.

Use Components, Not Custom Markup → [composition.md](./rules/composition.md)

• Use existing components before custom markup. Check if a component exists before writing a styled div.
• Callouts use Alert. Don't build custom styled divs.
• Empty states use Empty. Don't build custom empty state markup.
• Toast via sonner. Use toast() from sonner.
• Use Separator instead of <hr> or <div className="border-t">.
• Use Skeleton for loading placeholders. No custom animate-pulse divs.
• Use Badge instead of custom styled spans.

Icons → [icons.md](./rules/icons.md)

• Icons in Button use data-icon. data-icon="inline-start" or data-icon="inline-end" on the icon.
• No sizing classes on icons inside components. Components handle icon sizing via CSS. No size-4 or w-4 h-4.
• Pass icons as objects, not string keys. icon={CheckIcon}, not a string lookup.

CLI

• Never decode or fetch preset codes manually. Pass them directly to npx shadcn@latest init --preset <code>.

Key Patterns

These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.

// Form layout: FieldGroup + Field, not div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validation: data-invalid on Field, aria-invalid on the control.
<Field data-invalid>
  <FieldLabel htmlFor="invalid-email">Email</FieldLabel>
  <Input id="invalid-email" aria-invalid aria-describedby="invalid-email-error" />
  <FieldDescription id="invalid-email-error">Invalid email.</FieldDescription>
</Field>

// Icons in buttons: data-icon, no sizing classes.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

// Spacing: gap-*, not space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong

// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong

// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

Component Selection

| Need | Use |

| -------------------------- | --------------------------------------------------------------------------------------------------- |

| Button/action | Button with appropriate variant |

| Form inputs | Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider |

| Toggle between 2–5 options | ToggleGroup + ToggleGroupItem |

| Data display | Table, Card, Badge, Avatar |

| Navigation | Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination |

| Overlays | Dialog (modal), Sheet (side panel), Drawer (bottom sheet), AlertDialog (confirmation) |

| Feedback | sonner (toast), Alert, Progress, Skeleton, Spinner |

| Command palette | Command inside Dialog |

| Charts | Chart (wraps Recharts) |

| Layout | Card, Separator, Resizable, ScrollArea, Accordion, Collapsible |

| Empty states | Empty |

| Menus | DropdownMenu, ContextMenu, Menubar |

| Tooltips/info | Tooltip, HoverCard, Popover |

Key Fields

The observed project context contains these key fields:

• aliases

… (full content is in the download package)