| name | shadcn |
| description | Build UI with shadcn/ui — find, install, compose, and customize components using the correct CLI and patterns. Use when adding or styling frontend components, building forms/dashboards, theming, or working with components.json and the shadcn registry/MCP. |
shadcn/ui
shadcn/ui components are copied into your project (not a dependency) and
composed from primitives. Always discover the real component API before
generating code — don't guess prop names.
When to use
- Adding or composing UI components, forms, dialogs, tables, dashboards.
- Theming (CSS variables, dark mode, radius, colors) or adding from a registry.
- Reviewing frontend work that uses shadcn/ui.
Get the live, project-aware skill (recommended)
The official skill reads your project and injects accurate context. Install it
and enable the shadcn MCP so the assistant uses real component data:
npx skills add shadcn/ui
When present, it activates on a components.json and runs shadcn info --json
to learn your framework, Tailwind version, aliases, base library (radix or
base), icon library, and installed components. Prefer this over memory.
CLI workflow
Use the CLI (npx shadcn@latest …) — never hand-copy component source:
npx shadcn@latest init
npx shadcn@latest search <query>
npx shadcn@latest view <name>
npx shadcn@latest docs <name>
npx shadcn@latest add <name>
npx shadcn@latest info --json
npx shadcn@latest diff
Discover with search/view/docs (or the MCP tools) before writing code,
so you use the correct, version-specific API on the first try.
Composition rules
- Compose from shadcn primitives instead of raw HTML where one exists.
- Forms: use
Field/FieldGroup (and the form primitives) for layout and
labelling, not ad-hoc divs.
- Option sets:
ToggleGroup/RadioGroup rather than hand-rolled buttons.
- Respect the base library's API (
radix vs base) — they differ; check first.
- Keep generated component files editable in your repo; customize there.
Theming
- Style via the CSS variables shadcn generates (semantic tokens like
bg-background, text-foreground, border, ring) — avoid hard-coded hex.
- Colors use OKLCH; respect the Tailwind version (v3 vs v4) the project uses.
- Dark mode through the
.dark class / theme tokens, not duplicated styles.
- Adjust radius/colors via the theme variables, not per-component overrides.
For the deeper patterns — next-themes dark-mode setup, the v3-HSL vs
v4-OKLCH/@theme token plumbing, multi-theme, and adding cva variants — read
references/theming.md. For the token architecture behind it, see the
design-tokens skill.
Accessibility
Radix primitives give you keyboard nav, focus traps, and ARIA wiring for free —
compose them rather than hand-rolling that logic. You still owe labels for
icon-only triggers, wired-up form errors, an intact focus ring, and live
regions for your own async updates. See references/accessibility.md for the
per-component breakdown; ux-quality covers the general (non-shadcn) rules.
Reference files
Open these for depth (progressive disclosure — they don't load until needed):
references/theming.md — dark mode (next-themes), the v3/v4 token systems,
color customization, multi-theme, and cva variant customization.references/accessibility.md — what each Radix primitive handles vs. the
gaps you must fill (labels, form errors, focus ring, live regions).
Checklist
- Component API confirmed via
view/docs/MCP before coding.
- Components installed with
add (deps resolved), not pasted by hand.
- Semantic color tokens used; no stray hex values.
- Forms/option-sets use the proper shadcn composition primitives.
- Theming/dark-mode and a11y handled per the reference files when non-trivial.
Learn more
