shadcn
Manages 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", "switch to --preset", and for building a design system or applying a DESIGN.md or brand spec to shadcn/ui.
How do I install this agent skill?
npx skills add https://github.com/laguagu/claude-code-nextjs-skills --skill shadcnIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a comprehensive framework guide and toolset for managing shadcn/ui projects. It provides safe, standard developer workflows for component installation, theming, and UI auditing using well-known services and tools.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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.
Run all CLI commands with the project's package runner, chosen from its lockfile or the
packageManagerfield inpackage.json:npx shadcn@latest,pnpm dlx shadcn@latestorbunx --bun shadcn@latest. The examples below usenpx shadcn@latest; substitute the project's runner.
For a new project, use Bun by default. Existing projects retain their configured package manager.
Current Project Context
Run shadcn@latest info --json with the project's package runner and read the
returned config and component list. Do not assume shell interpolation inside a
skill runs on every client. Use shadcn@latest docs <component> for docs resolved
to the project's base.
Principles
- Use existing components first. Use
npx shadcn@latest searchto check registries before writing custom UI. Check community registries too. - 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
Use these as defaults for this design system; preserve explicit project requirements. 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
InputGroupButtonin anInputGroupAddon. Place the addon after the input and setalign="inline-end"for a trailing button; don't use a plainButton. - 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 the installed base's composition API. Radix uses
asChild; Base UI usesrender. For React Aria, fetch the Aria component docs rather than applying either pattern automatically. Check thebasefield fromshadcn@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 the relevant Card slots. Add header, description and footer only when their content exists.
- 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. - Assistant activity uses
Trace. Reasoning, tool calls, sources and steps areTraceLines in aTrace, oneTraceper run of message parts. Behavior wraps the line:TraceCollapsible, a sheet trigger or a link. Not a hand-rolledCollapsibleor aMarker.
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 />
<FieldError>Enter a valid email address.</FieldError>
</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–7 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, Trace |
Key Fields
The info --json output has top-level project, config, preset, components and links. Key fields:
config.aliases→ use the actual alias prefix for imports (e.g.@/,~/), never hardcode.project.rsc→ 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.project.tailwindVersion→"v4"uses@theme inlineblocks;"v3"usestailwind.config.js.project.tailwindCss→ the global CSS file where custom CSS variables are defined (absolute path:config.resolvedPaths.tailwindCss). Always edit this file, never create a new one.config.style→ component visual treatment (e.g.nova,vega).config.base→ primitive library (radix,baseoraria). Affects component APIs and available props.config.iconLibrary→ determines icon imports. Uselucide-reactforlucide,@tabler/icons-reactfortabler, etc. Never assumelucide-react.config.resolvedPaths→ exact file-system destinations for components, utils, hooks, etc.project.framework/project.frameworkName→ routing and file conventions (e.g.next-appvsvite).- Package manager → not in the
infooutput. Read the lockfile or thepackageManagerfield inpackage.jsonfor 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
Before you write or change code that uses a component's props or composition you have not checked in this session, run npx shadcn@latest docs <component> and fetch the URLs. The installed file wraps a primitive whose props and composition differ between bases (radix, base, aria), so read the docs rather than guess.
Workflow
- Get project context — run
shadcn@latest info --jsonwith the project runner. - 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 components —
npx shadcn@latest search. - Get docs and examples — 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 —
npx shadcn@latest add. 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. - Choose the registry from context — use the project's configured registry or
@shadcnfor standard components. Ask when competing sources materially change the requested result. - Switching presets — Ask the user first: overwrite, partial, merge, or skip?
- 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 (base,radixoraria) 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:
Design Systems from DESIGN.md
When the user asks for a design system from a DESIGN.md (or a brand spec), with or without a preset, follow design-system.md end to end:
init --preset <code> --template <vite|next> --name <app> --no-monorepo -y. Without a preset code, pick the closest style and pass--base base --preset <style>. Thenadd --all -y.- Read the DESIGN.md frontmatter, Do's and Don'ts, and Known Gaps before editing.
- Map its tokens onto the shadcn variables in the CSS file at
project.tailwindCss. Pin the radius scale, shadows, fonts andtype-*utilities. - Restyle components by editing their
cvavariants. Change control heights together. - Build the design system page per design-system-page.md: contrast-checked color roles, type specimens, pinned state matrices, edge cases, do/don't pairs, recipes. Check coverage with
scripts/showcase-coverage.mjs. - Verify in a browser: typecheck, no console errors, loads at the top, no horizontal overflow, dark mode.
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. Use the CLI rather than fetching raw files from GitHub: it handles registry resolution, file paths and CSS diffing, and --diff shows what would replace the local changes.
- 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 says "just update everything" → use
--overwrite, but confirm first.
- Never use
--overwritewithout the user's explicit approval.
Quick Reference
# Create a new project.
npx shadcn@latest init --name my-app --base base --preset nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite
# Create a design system app (then follow design-system.md).
npx shadcn@latest init --name my-ds --preset b0 --template vite --no-monorepo -y
npx shadcn@latest init --name my-ds --base base --preset maia --template vite --no-monorepo -y
npx shadcn@latest add --all -y
# Create a monorepo project.
npx shadcn@latest init --name my-app --base base --preset nova --monorepo
npx shadcn@latest init --name my-app --base base --preset nova --template next --monorepo
# Initialize existing project.
npx shadcn@latest init --preset 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, sera, rhea (see the current preset definitions).
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, Trace; streaming, anchoring, jump-to-latest, assistant activity rows
- 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 - mcp.md — shadcn MCP server:
shadcn mcp initeditor config, MCP tools, configuring registries incomponents.json - customization.md — Theming, CSS variables, extending components
- design-system.md: DESIGN.md (with or without a preset) to a themed app: style picking, token mapping, radius, fonts, type scale, control heights, showcase traps, verification
- design-system-page.md: What goes on a design system page and how: foundations, component tiers, pinned state matrices, contrast pairs, edge cases, do/don't, recipes
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/laguagu/claude-code-nextjs-skills/shadcn">View shadcn on skillZs</a>