shadcn/ui Expert

This skill provides the definitive behavior and workflow for interacting with the shadcn/ui ecosystem. shadcn/ui is a collection of beautifully-designed, accessible components and a code distribution platform built with TypeScript, Tailwind CSS, and Radix UI primitives.

Core Principles

Open Code: Components are downloaded into the project's source code (usually components/ui). They are meant to be customized, not treated as black-box dependencies.
Composition: Build complex UIs by composing simpler primitives.
Tailwind CSS: Styling is done via Tailwind CSS utility classes and CSS variables for theming.
Accessibility: Built on Radix UI, preserving ARIA labels and keyboard navigation is non-negotiable.
Iconography: Use lucide-react for all icons unless otherwise specified.

AI & MCP Tools Integration

You have access to shadcn MCP server tools. Always use these tools proactively:

Search: Use shadcn_search_items_in_registries to find components.
Examples: Use shadcn_get_item_examples_from_registries (e.g., sidebar-demo, chart-demo, data-table-demo) to understand implementation. This is critical for complex components.
Add Components: Use shadcn_get_add_command_for_items to get the CLI command.
Audit: Run shadcn_get_audit_checklist after generating code.

Workflows

1. Project Setup

Check for components.json. If missing, run npx shadcn@latest init.
For React 19 and Tailwind v4, ensure you use the @latest CLI which handles the new CSS-variable-based configuration in globals.css (instead of tailwind.config.js).

2. Adding Components

Always use the CLI: npx shadcn@latest add <component_name>.
For complex layouts, look for Blocks at ui.shadcn.com/blocks.

3. Complex Components

Sidebar: Requires SidebarProvider, Sidebar, SidebarContent, etc. Always fetch the latest example as the API is highly specific.
Charts: Built on Recharts. Use ChartConfig for theming and ChartContainer for responsive sizing.
Forms: Use react-hook-form + zod. See forms.md.

4. Theming and Dark Mode

Theming uses CSS variables in globals.css.
Use next-themes for Next.js. See dark-mode.md.

5. Creating Registries

Follow the schemas in registry.md.

Troubleshooting

1. Import Errors (`@/lib/utils`)

Ensure @/lib/utils exists and contains the cn helper.
Verify path aliases in tsconfig.json or jsconfig.json (usually "@/*": ["./*"] or "@/*": ["./src/*"]).
If using Tailwind v4, check that globals.css is correctly importing the shadcn theme variables.

2. Hydration Mismatch (Next.js)

For interactive components like Dialogs, Drawers, or Sidebars, wrap them in a client-only check if they cause hydration errors.
Ensure the ThemeProvider has suppressHydrationWarning on the <html> tag.

3. Missing Peer Dependencies

Some complex components require additional libraries (e.g., framer-motion for some animations or lucide-react for icons).
If a component fails to render, check the console for missing dependency errors and install them via npm install.

4. Tailwind Variable Issues

If colors appear as white or transparent, ensure the globals.css file contains the @layer base styles and CSS variables (e.g., --background, --primary).
In Tailwind v4, ensure you are using the correct @theme block syntax.

slog-cloud-shadcn-expert