1# shadcn/ui Integration Skill
2 
3## Install
4 
5```bash
6npx skills add google-labs-code/stitch-skills --skill shadcn-ui --global
7```
8 
9## What It Does
10 
11This skill provides expert guidance for integrating shadcn/ui components into your React applications. It helps you discover, install, customize, and optimize shadcn/ui components while following best practices.
12 
13## Example Prompts
14 
15```text
16Help me set up shadcn/ui in my Next.js project
17 
18Add a data table component with sorting and filtering to my app
19 
20Show me how to customize the button component with a new variant
21 
22Create a login form using shadcn/ui components with validation
23 
24Build a dashboard layout with sidebar navigation using shadcn/ui blocks
25```
26 
27## What is shadcn/ui?
28 
29shadcn/ui is a collection of beautifully designed, accessible, and customizable components built with:
30- **Radix UI or Base UI**: Unstyled, accessible component primitives
31- **Tailwind CSS**: Utility-first styling framework
32- **TypeScript**: Full type safety
33 
34**Key Difference**: Unlike traditional component libraries, shadcn/ui copies components directly into your project. This gives you:
35- Full control over the code
36- No version lock-in
37- Complete customization freedom
38- Zero runtime overhead
39 
40## Skill Structure
41 
42```text
43skills/shadcn-ui/
44├── SKILL.md              — Core instructions & workflow
45├── README.md             — This file
46├── examples/             — Example implementations
47│   ├── form-pattern.tsx       — Form with validation
48│   ├── data-table.tsx         — Advanced table with sorting
49│   └── auth-layout.tsx        — Authentication flow
50├── resources/            — Reference documentation
51│   ├── setup-guide.md         — Project initialization
52│   ├── component-catalog.md   — Component reference
53│   ├── customization-guide.md — Theming patterns
54│   └── migration-guide.md     — Migration from other libraries
55└── scripts/              — Utility scripts
56    └── verify-setup.sh        — Validate project configuration
57```
58 
59## How It Works
60 
61When activated, the agent follows this workflow:
62 
63### 1. **Discovery & Planning**
64- Lists available components using shadcn MCP tools
65- Identifies required dependencies
66- Plans component composition strategy
67 
68### 2. **Setup & Configuration**
69- Verifies or initializes `components.json`
70- Checks Tailwind CSS configuration
71- Validates import aliases and paths
72 
73### 3. **Component Integration**
74- Retrieves component source code
75- Installs via CLI or manual integration
76- Handles dependency installation
77 
78### 4. **Customization**
79- Applies theme customization
80- Creates component variants
81- Extends components with custom logic
82 
83### 5. **Quality Assurance**
84- Validates TypeScript types
85- Checks accessibility compliance
86- Verifies responsive behavior
87 
88## Prerequisites
89 
90Your project should have:
91- **React 18+**
92- **Tailwind CSS 3.0+**
93- **TypeScript** (recommended)
94- **Node.js 18+**
95 
96## Quick Start
97 
98### For New Projects
99 
100```bash
101# Create Next.js project with shadcn/ui
102npx create-next-app@latest my-app
103cd my-app
104npx shadcn@latest init
105 
106# Add components
107npx shadcn@latest add button
108npx shadcn@latest add card
109```
110 
111### For Existing Projects
112 
113```bash
114# Initialize shadcn/ui
115npx shadcn@latest init
116 
117# Configure when prompted:
118# - Choose style (default/new-york)
119# - Select base color
120# - Configure CSS variables
121# - Set import aliases
122 
123# Add your first component
124npx shadcn@latest add button
125```
126 
127## Available Components
128 
129shadcn/ui provides 50+ components including:
130 
131**Layout**: Accordion, Card, Separator, Tabs, Collapsible  
132**Forms**: Button, Input, Label, Checkbox, Radio Group, Select, Textarea  
133**Data Display**: Table, Badge, Avatar, Progress, Skeleton  
134**Overlays**: Dialog, Sheet, Popover, Tooltip, Dropdown Menu  
135**Navigation**: Navigation Menu, Tabs, Breadcrumb, Pagination  
136**Feedback**: Alert, Alert Dialog, Toast, Command  
137 
138Plus complete **Blocks** like:
139- Authentication forms
140- Dashboard layouts
141- Calendar interfaces
142- Sidebar navigation
143- E-commerce components
144 
145## Customization Approach
146 
147### Theme-Level Customization
148Modify CSS variables in `globals.css`:
149```css
150:root {
151  --primary: 221.2 83.2% 53.3%;
152  --secondary: 210 40% 96.1%;
153  /* ... */
154}
155```
156 
157### Component-Level Customization
158Components use `class-variance-authority` for variants:
159```typescript
160const buttonVariants = cva(
161  "base-classes",
162  {
163    variants: {
164      variant: { default: "...", destructive: "..." },
165      size: { default: "...", sm: "..." },
166    }
167  }
168)
169```
170 
171### Composition
172Create higher-level components:
173```typescript
174// Compose existing components
175export function FeatureCard({ title, description, icon }) {
176  return (
177    <Card>
178      <CardHeader>
179        {icon}
180        <CardTitle>{title}</CardTitle>
181      </CardHeader>
182      <CardContent>
183        <p>{description}</p>
184      </CardContent>
185    </Card>
186  )
187}
188```
189 
190## Integration with MCP Tools
191 
192This skill leverages shadcn MCP server capabilities:
193 
194- `list_components` - Browse component catalog
195- `get_component` - Retrieve component source
196- `get_component_metadata` - View props and dependencies
197- `get_component_demo` - See usage examples
198- `list_blocks` - Browse UI blocks
199- `get_block` - Retrieve block source with all files
200- `search_items_in_registries` - Find components in custom registries
201 
202## Best Practices
203 
2041. **Keep `ui/` pure**: Don't modify components in `components/ui/` directly
2052. **Compose, don't fork**: Create wrapper components instead of editing originals
2063. **Use the CLI**: Let `shadcn add` handle dependencies and updates
2074. **Maintain consistency**: Use the `cn()` utility for all class merging
2085. **Respect accessibility**: Preserve ARIA attributes and keyboard handlers
2096. **Test responsiveness**: shadcn components are responsive by default—keep it that way
210 
211## Troubleshooting
212 
213### "Module not found" errors
214Check your `tsconfig.json` includes path aliases:
215```json
216{
217  "compilerOptions": {
218    "paths": {
219      "@/*": ["./src/*"]
220    }
221  }
222}
223```
224 
225### Styles not applying
226- Import `globals.css` in your root layout
227- Verify Tailwind config includes component paths
228- Check CSS variable definitions match component expectations
229 
230### TypeScript errors
231- Ensure all Radix UI peer dependencies are installed
232- Run `npm install` after adding components via CLI
233- Check that React types are up to date
234 
235## Further Reading
236 
237- [Official Documentation](https://ui.shadcn.com)
238- [Component Source](https://github.com/shadcn-ui/ui)
239- [Radix UI Docs](https://www.radix-ui.com)
240- [Tailwind CSS Docs](https://tailwindcss.com)
241 
242## Contributing
243 
244Contributions to improve this skill are welcome! See the root [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
245 
246## License
247 
248See [LICENSE](../../LICENSE) in the repository root.
249