lootlog/monorepo / .agents/skills/shadcn
shadcn
VerifiedManages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".
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, orbunx --bun shadcn@latest— based on the project'spackageManager. Examples below usenpx shadcn@latestbut substitute the correct runner for the project.
Current Project Context
!`npx shadcn@latest info --json`
The JSON above contains the project config and installed components. Use npx shadcn@latest docs <component> to get documentation and example URLs for any component.
Principles
- Use existing components first. Inspect installed components and project usage. Search registries when an appropriate component is missing; consider community registries when the standard registry does not cover the request.
- Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
- Use built-in variants before custom styles.
variant="outline",size="sm", etc. - Use semantic colors.
bg-primary,text-muted-foreground— never raw values likebg-blue-500.
Critical Rules
These rules are always enforced. Each links to a file with Incorrect/Correct code pairs.
Styling & Tailwind → styling.md
classNamefor layout, not styling. Never override component colors or typography.- No
space-x-*orspace-y-*. Useflexwithgap-*. For vertical stacks,flex flex-col gap-*. - Use
size-*when width and height are equal.size-10notw-10 h-10. - Use
truncateshorthand. Notoverflow-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. - No manual
z-indexon overlay components. Dialog, Sheet, Popover, etc. handle their own stacking.
Forms & Inputs → forms.md
- Forms use
FieldGroup+Field. Never use rawdivwithspace-y-*orgrid gap-*for form layout. InputGroupusesInputGroupInput/InputGroupTextarea. Never rawInput/TextareainsideInputGroup.- Buttons inside inputs use
InputGroup+InputGroupAddon. - Option sets (2–7 choices) use
ToggleGroup. Don't loopButtonwith manual active state. FieldSet+FieldLegendfor grouping related checkboxes/radios. Don't use adivwith a heading.- Field validation uses
data-invalid+aria-invalid.data-invalidonField,aria-invalidon the control. For disabled:data-disabledonField,disabledon the control.
Component Structure → composition.md
- Items always inside their Group.
SelectItem→SelectGroup.DropdownMenuItem→DropdownMenuGroup.CommandItem→CommandGroup. - Use
asChild(radix) orrender(base) for custom triggers. Checkbasefield fromnpx shadcn@latest info. → base-vs-radix.md - Dialog, Sheet, and Drawer always need a Title.
DialogTitle,SheetTitle,DrawerTitlerequired for accessibility. UseclassName="sr-only"if visually hidden. - Use full Card composition.
CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Don't dump everything inCardContent. - Button has no
isPending/isLoading. Compose withSpinner+data-icon+disabled. TabsTriggermust be insideTabsList. Never render triggers directly inTabs.Avataralways needsAvatarFallback. For when the image fails to load.
Use Components, Not Custom Markup → 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 follows the project base. Use
toastfrom thetoastcomponent for Base UI projects. Usetoast()fromsonnerfor Radix and React Aria projects. - Use
Separatorinstead of<hr>or<div className="border-t">. - Use
Skeletonfor loading placeholders. No customanimate-pulsedivs. - Use
Badgeinstead of custom styled spans.
Icons → icons.md
- Icons in
Buttonusedata-icon.data-icon="inline-start"ordata-icon="inline-end"on the icon. - No sizing classes on icons inside components. Components handle icon sizing via CSS. No
size-4orw-4 h-4. - Pass icons as objects, not string keys.
icon={CheckIcon}, not a string lookup.
Chat & Messaging → chat.md
- Chat UI composes the chat primitives. Conversations use
MessageScroller, rows useMessage, surfaces useBubble. Never hand-rolled bubbledivs or a raw scroll container. MessageScrollerowns scroll behavior. Streaming follow, anchoring, and jump-to-latest (MessageScrollerButton) are built in. Don't write auseStickToBottom/ResizeObserverhook.- Attachments use
Attachment; system notes and dividers useMarker. NotItemcards orSeparator+ a label.
CLI
- Never decode preset codes or build preset URLs manually. Use
npx shadcn@latest preset decode <code>,preset url <code>, orpreset open <code>. For project-aware preset detection, usenpx shadcn@latest preset resolve. - Apply preset codes directly with the CLI. Use
npx shadcn@latest apply <code>for existing projects, ornpx shadcn@latest init --preset <code>when initializing.
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>Email</FieldLabel>
<Input aria-invalid />
<FieldDescription>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 | toast (Base UI), sonner (Radix/Aria), 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 |
| Chat / conversation UI | MessageScroller, Message, Bubble, Attachment, Marker |
Key Fields
The injected project context contains these key fields:
aliases→ use the actual alias prefix for imports (e.g.@/,~/), never hardcode.isRSC→ whentrue, components usinguseState,useEffect, event handlers, or browser APIs need"use client"at the top of the file. Always reference this field when advising on the directive.tailwindVersion→"v4"uses@theme inlineblocks;"v3"usestailwind.config.js.tailwindCssFile→ the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.style→ component visual treatment (e.g.nova,vega).base→ primitive library (radixorbase). Affects component APIs and available props.iconLibrary→ determines icon imports. Uselucide-reactforlucide,@tabler/icons-reactfortabler, etc. Never assumelucide-react.resolvedPaths→ exact file-system destinations for components, utils, hooks, etc.framework→ routing and file conventions (e.g. Next.js App Router vs Vite SPA).packageManager→ use this for any non-shadcn dependency installs (e.g.pnpm add date-fnsvsnpm install date-fns).preset→ resolved preset code and values for the current project. Usenpx shadcn@latest preset resolve --jsonwhen you only need preset information.
See cli.md — info command for the full field reference.
Component Docs, Examples, and Usage
Run npx shadcn@latest docs <component> to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
npx shadcn@latest docs button dialog select
For installed components, inspect local source and project usage first. Fetch documentation when adding or updating components, or when the API remains uncertain. Match guidance to the installed implementation; unavailable upstream documentation need not block an edit supported by local evidence.
Workflow
- Get project context — already injected above. Run
npx shadcn@latest infoagain if you need to refresh. - Check installed components first — before running
add, always check thecomponentslist from project context or list theresolvedPaths.uidirectory. Don't import components that haven't been added, and don't re-add ones already installed. - Find missing components — Use
npx shadcn@latest searchwhen the requested component is not already installed. - Resolve API details — Read installed source first. When adding, updating, or resolving uncertainty, run
npx shadcn@latest docs <component>to get URLs, then fetch them. Usenpx shadcn@latest viewto browse registry items you haven't installed. To preview changes to installed components, usenpx shadcn@latest add --diff. - Install or update when needed — Use
npx shadcn@latest addfor requested additions or upstream updates. Edit existing local source directly for routine fixes. When updating existing components, use--dry-runand--diffto preview changes first (see Updating Components below). - Fix imports in third-party components — After adding components from community registries (e.g.
@bundui,@magicui), check the added non-UI files for hardcoded import paths like@/components/ui/.... These won't match the project's actual aliases. Usenpx shadcn@latest infoto get the correctuialias (e.g.@workspace/ui/components) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project. - Review added components — After adding a component or block from any registry, always read the added files and verify they are correct. Check for missing sub-components (e.g.
SelectItemwithoutSelectGroup), missing imports, incorrect composition, or violations of the Critical Rules. Also replace any icon imports with the project'siconLibraryfrom the project context (e.g. if the registry item useslucide-reactbut the project useshugeicons, swap the imports and icon names accordingly). Fix all issues before moving on. - Resolve the registry from context — Honor a specified registry. Otherwise use the project configuration and existing component source; for standard shadcn components, use the standard registry when no project override applies. Ask only when the source remains ambiguous and the choice materially changes the result.
- Switching presets — Inspect the current and incoming presets before choosing overwrite, partial, merge, or skip. Follow the user's requested scope; ask only when the choice is unresolved or would discard local customizations without authorization.
- Inspect current preset:
npx shadcn@latest preset resolve. Use--jsonwhen you need structured values. - Inspect incoming preset:
npx shadcn@latest preset decode <code>. Usepreset url <code>orpreset open <code>to share or open the preset builder. - Overwrite:
npx shadcn@latest apply <code>. Overwrites detected components, fonts, and CSS variables. - Partial:
npx shadcn@latest apply <code> --only theme,font. Updates only the selected preset parts without reinstalling UI components. Supported values arethemeandfont; comma-separated combinations are allowed.iconis intentionally not supported, because icon changes may require full component reinstall and transforms. - Merge:
npx shadcn@latest init --preset <code> --force --no-reinstall, then runnpx shadcn@latest infoto list installed components, then for each installed component use--dry-runand--diffto smart merge it individually. - Skip:
npx shadcn@latest init --preset <code> --force --no-reinstall. Only updates config and CSS, leaves components as-is. - Important: Always run preset commands inside the user's project directory.
applyonly works in an existing project with acomponents.jsonfile. The CLI automatically preserves the current base (basevsradix) fromcomponents.json. If you must use a scratch/temp directory (e.g. for--dry-runcomparisons), pass--base <current-base>explicitly — preset codes do not encode the base.
- Inspect current preset:
Updating Components
When the user asks to update a component from upstream while keeping their local changes, use --dry-run and --diff to intelligently merge. NEVER fetch raw files from GitHub manually — always use the CLI.
- Run
npx shadcn@latest add <component> --dry-runto see all files that would be affected. - For each file, run
npx shadcn@latest add <component> --diff <file>to see what changed upstream vs local. - Decide per file based on the diff:
- No local changes → safe to overwrite.
- Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
- User explicitly authorizes replacing local customizations → use
--overwritewithin that scope. A generic update request calls for preserving local changes.
- Preserve local customizations unless their replacement is explicitly authorized. Reuse authorization already given for the same scope; do not ask for it again.
Quick Reference
# Create a new project.
npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite
# Create a monorepo project.
npx shadcn@latest init --name my-app --preset base-nova --monorepo
npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
# Initialize existing project.
npx shadcn@latest init --preset base-nova
npx shadcn@latest init --defaults # shortcut: --template=next --preset=nova (base style implied)
# Apply a preset to an existing project.
npx shadcn@latest apply a2r6bw
npx shadcn@latest apply a2r6bw --only theme
npx shadcn@latest apply a2r6bw --only font
npx shadcn@latest apply a2r6bw --only theme,font
# Inspect preset codes and project preset state.
npx shadcn@latest preset decode a2r6bw
npx shadcn@latest preset url a2r6bw
npx shadcn@latest preset open a2r6bw
npx shadcn@latest preset resolve
npx shadcn@latest preset resolve --json
# Add components.
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add owner/repo/item
npx shadcn@latest add --all
# Preview changes before adding/updating.
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx
npx shadcn@latest add @acme/form --view button.tsx
npx shadcn@latest add owner/repo/item --dry-run
# Search registries.
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"
npx shadcn@latest search owner/repo -q "login"
npx shadcn@latest search # all configured registries
npx shadcn@latest search @shadcn -q "menu" -t ui # filter by item type
# Get component docs and example URLs.
npx shadcn@latest docs button dialog select
# View registry item details (for items not yet installed).
npx shadcn@latest view @shadcn/button
npx shadcn@latest view owner/repo/item
Named presets: nova, vega, maia, lyra, mira, luma
Templates: next, vite, start, react-router, astro (all support --monorepo) and laravel (not supported for monorepo)
Preset codes: Version-prefixed base62 strings (e.g. a2r6bw or b0), from ui.shadcn.com.
Detailed References
- rules/forms.md — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
- rules/composition.md — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
- rules/chat.md — MessageScroller, Message, Bubble, Attachment, Marker; streaming, anchoring, jump-to-latest
- rules/icons.md — data-icon, icon sizing, passing icons as objects
- rules/styling.md — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
- rules/base-vs-radix.md — asChild vs render, Select, ToggleGroup, Slider, Accordion
- cli.md — Commands, flags, presets, templates
- registry.md — Authoring source registries,
include, item definitions, dependencies, GitHub registry rules - customization.md — Theming, CSS variables, extending components
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |