shadcn-ui

name	shadcn-ui
description	Expert guidance for integrating and building applications with shadcn/ui components, including component discovery, installation, customization, and best practices.
allowed-tools	["shadcn*:*","mcp_shadcn*","Read","Write","Bash","web_fetch"]

Repo notice (Asymmetric-al/core): This repository is Base UI only. Shared primitives come from @base-ui/react via the shadcn base-maia style in packages/ui. Ignore any Radix UI guidance below — never add radix-ui/@radix-ui/* imports or dependencies; composition uses Base UI's render prop, not asChild. See docs/ai/rules/frontend.md.

shadcn/ui Component Integration

You are a frontend engineer specialized in building applications with shadcn/ui—a collection of beautifully designed, accessible, and customizable components built with Radix UI or Base UI and Tailwind CSS. You help developers discover, integrate, and customize components following best practices.

Core Principles

shadcn/ui is not a component library—it's a collection of reusable components that you copy into your project. This gives you:

• Full ownership: Components live in your codebase, not node_modules
• Complete customization: Modify styling, behavior, and structure freely, including choosing between Radix UI or Base UI primitives
• No version lock-in: Update components selectively at your own pace
• Zero runtime overhead: No library bundle, just the code you need

Component Discovery and Installation

1. Browse Available Components

Use the shadcn MCP tools to explore the component catalog and Registry Directory:

• List all components: Use list_components to see the complete catalog
• Get component metadata: Use get_component_metadata to understand props, dependencies, and usage
• View component demos: Use get_component_demo to see implementation examples

2. Component Installation

There are two approaches to adding components:

A. Direct Installation (Recommended)

npx shadcn@latest add [component-name]

This command:

• Downloads the component source code (adapting to your config: Radix vs Base UI)
• Installs required dependencies
• Places files in components/ui/
• Updates your components.json config

B. Manual Integration

1. Use get_component to retrieve the source code
2. Create the file in components/ui/[component-name].tsx
3. Install peer dependencies manually
4. Adjust imports if needed

3. Registry and Custom Registries

If working with a custom registry (defined in components.json) or exploring the Registry Directory:

• Use get_project_registries to list available registries
• Use list_items_in_registries to see registry-specific components
• Use view_items_in_registries for detailed component information
• Use search_items_in_registries to find specific components

Project Setup

Initial Configuration

For new projects, use the create command to customize everything (style, fonts, component library):

npx shadcn@latest create

For existing projects, initialize configuration:

npx shadcn@latest init

This creates components.json with your configuration:

• style: default, new-york (classic) OR choose new visual styles like Vega, Nova, Maia, Lyra, Mira
• baseColor: slate, gray, zinc, neutral, stone
• cssVariables: true/false for CSS variable usage
• tailwind config: paths to Tailwind files
• aliases: import path shortcuts
• rsc: Use React Server Components (yes/no)
• rtl: Enable RTL support (optional)

Required Dependencies

shadcn/ui components require:

• React (18+)
• Tailwind CSS (3.0+)
• Primitives: Radix UI OR Base UI (depending on your choice)
• class-variance-authority (for variant styling)
• clsx and tailwind-merge (for class composition)

Component Architecture

File Structure

src/
├── components/
│   ├── ui/              # shadcn components
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── dialog.tsx
│   └── [custom]/        # your composed components
│       └── user-card.tsx
├── lib/
│   └── utils.ts         # cn() utility
└── app/
    └── page.tsx

The cn() Utility

All shadcn components use the cn() helper for class merging:

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

This allows you to:

• Override default styles without conflicts
• Conditionally apply classes
• Merge Tailwind classes intelligently

Customization Best Practices

1. Theme Customization

Edit your Tailwind config and CSS variables in app/globals.css:

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    /* ... more variables */
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... dark mode overrides */
  }
}

2. Component Variants

Use class-variance-authority (cva) for variant logic:

import { cva } from "class-variance-authority";

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        outline: "border border-input",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  },
);

3. Extending Components

Create wrapper components in components/ (not components/ui/):

// components/custom-button.tsx
import { Button } from "@/components/ui/button"
import { Loader2 } from "lucide-react"

export function LoadingButton({
  loading,
  children,
  ...props
}: ButtonProps & { loading?: boolean }) {
  return (
    <Button disabled={loading} {...props}>
      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
      {children}
    </Button>
  )
}

Blocks and Complex Components

shadcn/ui provides complete UI blocks (authentication forms, dashboards, etc.):

1. List available blocks: Use list_blocks with optional category filter
2. Get block source: Use get_block with the block name
3. Install blocks: Many blocks include multiple component files

Blocks are organized by category:

• calendar: Calendar interfaces
• dashboard: Dashboard layouts
• login: Authentication flows
• sidebar: Navigation sidebars
• products: E-commerce components

Accessibility

All shadcn/ui components are built on Radix UI primitives, ensuring:

• Keyboard navigation: Full keyboard support out of the box
• Screen reader support: Proper ARIA attributes
• Focus management: Logical focus flow
• Disabled states: Proper disabled and aria-disabled handling

When customizing, maintain accessibility:

• Keep ARIA attributes
• Preserve keyboard handlers
• Test with screen readers
• Maintain focus indicators

Common Patterns

Form Building

import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

// Use with react-hook-form for validation
import { useForm } from "react-hook-form";

Dialog/Modal Patterns

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

Data Display

import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table";

Troubleshooting

Import Errors

• Check components.json for correct alias configuration
• Verify tsconfig.json includes the @ path alias:

  {
    "compilerOptions": {
      "paths": {
        "@/*": ["./src/*"]
      }
    }
  }
  

Style Conflicts

• Ensure Tailwind CSS is properly configured
• Check that globals.css is imported in your root layout
• Verify CSS variable names match between components and theme

Missing Dependencies

• Run component installation via CLI to auto-install deps
• Manually check package.json for required Radix UI packages
• Use get_component_metadata to see dependency lists

Version Compatibility

• shadcn/ui v4 requires React 18+ and Next.js 13+ (if using Next.js)
• Some components require specific Radix UI versions
• Check documentation for breaking changes between versions

Validation and Quality

Before committing components:

1. Type check: Run tsc --noEmit to verify TypeScript
2. Lint: Run your linter to catch style issues
3. Test accessibility: Use tools like axe DevTools
4. Visual QA: Test in light and dark modes
5. Responsive check: Verify behavior at different breakpoints

Resources

Refer to the following resource files for detailed guidance:

• resources/setup-guide.md - Step-by-step project initialization
• resources/component-catalog.md - Complete component reference
• resources/customization-guide.md - Theming and variant patterns
• resources/migration-guide.md - Upgrading from other UI libraries

Examples

See the examples/ directory for:

• Complete component implementations
• Form patterns with validation
• Dashboard layouts
• Authentication flows
• Data table implementations