name	shadcn-ui
description	Must always be enabled when working with shadcn-ui.

## What is shadcn-ui?

shadcn-ui is NOT an npm package. It's a code distribution platform that copies component source code directly into your project.

Key principle: Components are added via CLI (pnpx shadcn@latest add) from a remote registry, NOT installed as dependencies.

## Adding Components ### Primary Method: CLI

# Add single component
pnpx shadcn@latest add button

# Add multiple components
pnpx shadcn@latest add button card dialog

# Add all components
pnpx shadcn@latest add --all

# Preview component before adding
pnpx shadcn@latest view button

Important: Always use the CLI to add components. Do NOT create component files manually in components/ui/ unless explicitly instructed.

### Finding Components

Official catalog: Browse components at https://ui.shadcn.com/docs/components
CLI preview: Use pnpx shadcn@latest view <component-name> to preview before adding
Search: Check the documentation site for all 60+ available components organized by category:
- Form & Input (16 components)
- Layout & Navigation (8 components)
- Overlays & Dialogs (11 components)
- Feedback & Status (7 components)
- Display & Media (10 components)

### Custom Registries (if configured)

# Add from namespaced registry
pnpx shadcn@latest add @v0/dashboard

# Add from URL
pnpx shadcn@latest add https://example.com/r/custom-component.json

Registry configuration is in components.json:

{
  "registries": {
    "@acme": "https://registry.acme.com/r/{name}.json"
  }
}

## DO NOT Edit Generated Files

NEVER directly edit files in these directories without explicit user instruction:

components/ui/ - CLI-generated component files
Any directory specified in components.json aliases

Why?: These files are managed by the CLI. Direct edits will be lost on updates.

### When Component Behavior Needs Customization

Step 1: Try usage-side control first

// ✅ Best: Control via props/className/composition at usage site
<Button className="custom-styling" onClick={customHandler} />

Step 2: If usage-side control is insufficient You MUST ask the user for permission before modifying components/ui/ files.

Required information for user approval:

Why extension is needed: Explain what cannot be achieved via props/className
Design approach: Describe how you plan to extend the component (new props, variant, internal logic change, etc.)

Example request:

The Button component needs to support an icon prop for consistent icon positioning. This cannot be achieved via className alone because it requires conditional rendering logic. I propose adding an optional icon?: React.ReactNode prop and rendering it with fixed spacing before children. May I modify components/ui/button.tsx?

Only proceed with modification after receiving explicit user approval.

## Common Tasks

Initial setup: See https://ui.shadcn.com/docs/installation
Theming/Dark mode: See https://ui.shadcn.com/docs/dark-mode
Form integration: See https://ui.shadcn.com/docs/components/form
Custom components: See https://ui.shadcn.com/docs/components-json
Monorepo setup: See https://ui.shadcn.com/docs/monorepo

For comprehensive reference when documentation is insufficient, consult: https://ui.shadcn.com/llms.txt

## Technical Details

Built with: TypeScript, Tailwind CSS, Radix UI primitives
Configuration: components.json at project root
Customization: Components are yours to own - they're copied into your codebase
Updates: Re-run pnpx shadcn@latest add <component> --overwrite to update

Remember: shadcn-ui provides the code, not the package. You maintain full control and ownership.

shadcn-ui

Install Skill

SKILL.md