<fundamental_concept>

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. </fundamental_concept>

<component_management>

Adding Components

<cli_usage>

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. </cli_usage>

<catalog_discovery>

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) </catalog_discovery>

<custom_registries>

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" } }

</custom_registries> </component_management>

<critical_constraints>

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.

<modification_workflow>

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. </modification_workflow> </critical_constraints>

<common_tasks>

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 </common_tasks>

<architecture_notes>

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. </architecture_notes>