shadcn-ui
Expert guidance for integrating and building applications with shadcn/ui components, including component discovery, installation, customization, and best practices.
Install / Use
npx skills add google-labs-code/stitch-skills --skill shadcn-uiInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of shadcn-ui
shadcn-ui scores 91/100 on our quality scale, 999th of 4,700 Development & Engineering skills we index (top 22%).
Its SKILL.md is 8.9 KB long, well organised into 30 sections with 11 code examples: a thorough specification that gives an agent plenty to work with.
With 8,363 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 3 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-15 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-28. Automated pattern scan on 2026-09-28. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
shadcn-ui compared with similar skills
All 4 of these similar skills score higher than shadcn-ui; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| shadcn-ui (this skill)by google-labs-code | 91 | 8.4k | 3mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 9d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
Frequently asked questions
- How do I install shadcn-ui?
- Run
npx skills add google-labs-code/stitch-skills --skill shadcn-ui. The install tabs above show the steps for each supported agent. - Which AI agents does shadcn-ui work with?
- It is written for Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is shadcn-ui safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is shadcn-ui still maintained?
- The repository was last updated about 3 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: 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"
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_componentsto see the complete catalog - Get component metadata: Use
get_component_metadatato understand props, dependencies, and usage - View component demos: Use
get_component_demoto 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.jsonconfig
B. Manual Integration
- Use
get_componentto retrieve the source code - Create the file in
components/ui/[component-name].tsx - Install peer dependencies manually
- 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_registriesto list available registries - Use
list_items_in_registriesto see registry-specific components - Use
view_items_in_registriesfor detailed component information - Use
search_items_in_registriesto 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.):
- List available blocks: Use
list_blockswith optional category filter - Get block source: Use
get_blockwith the block name - 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.jsonfor correct alias configuration - Verify
tsconfig.jsonincludes the@path alias:{ "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }
Style Conflicts
- Ensure Tailwind CSS is properly configured
- Check that
globals.cssis 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.jsonfor required Radix UI packages - Use
get_component_metadatato 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:
- Type check: Run
tsc --noEmitto verify TypeScript - Lint: Run your linter to catch style issues
- Test accessibility: Use tools like axe DevTools
- Visual QA: Test in light and dark modes
- 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 initializationresources/component-catalog.md- Complete component referenceresources/customization-guide.md- Theming and variant patternsresources/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
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
