shadcn
Skill297 starsChanged 9 months agoMITView on GitHub
Expert guide for ShadCN UI component library with Next.js. Use when working with ShadCN/UI projects including (1) Initial setup and configuration, (2) Adding and customizing components, (3) Theming and styling patterns, (4) Avoiding common mistakes like hardcoding styles instead of using variants/design tokens. Critical for maintaining consistent, reusable component patterns instead of one-off hardcoded implementations.
190 other projects use a version of this.
Adopted by
Most recently taken up by
- zxc-rv/XKeen-UItheir own version, first seen Nov 16, 2026
- shashidharbabu/rocketride-design-skillstheir own version, first seen Nov 15, 2026
- udaykumar-dhokia/mcp-flowtheir own version, first seen Nov 15, 2026
- theishandubey/dotclaudetheir own version, first seen Nov 15, 2026
- debugbundle/debugbundletheir own version, first seen Nov 15, 2026
- Fractera/web4-node-starter-kittheir own version, first seen Nov 15, 2026
Used with
Projects with it also use migrate-radix-to-base, nuqs and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
shadcn-uiSkillmigrate-radix-to-base
Migrates React projects and components from Radix UI to Base UI. Use when asked to migrate from radix, move to base-ui, convert radix primitives, or switch a shadcn project's base library. Handles single components ("migrate accordion") and whole projects.
Also in 15 projects that use this
thongdn-itSkillnuqs
nuqs (type-safe URL query state) best practices for Next.js applications. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, or Next.js routing with state.
Also in 4 projects that use this
bergsideSkillfriendly
Approachable, intuitive design with rounded elements, ample whitespace, and soft pastel color palettes.
Also in 4 projects that use this
bergsideSkillprofessional
Polished, business-ready design with modern typography, structured layouts, and a trustworthy visual identity.
Also in 4 projects that use this
SupabaseSkillreact-hook-form
Correct React Hook Form usage anywhere in the monorepo — data flow, subscriptions,
Also in 5 projects that use this
barisariburnuSkilltanstack
Expert assistance for TanStack Router, Query (v5), and Table (v8). Use when users need help with file-based routing, type-safe navigation, data loading, search params, queries, mutations, optimistic updates, infinite queries, table state management, or debugging TanStack libraries.
Also in 4 projects that use this
- +6 more from bergside
Other versions190 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 190
- shadcn-ui/ui★ 128ksame name
- coollabsio/coolify★ 66ksame name
- kriasoft/react-starter-kit★ 24ksame name
- MODSetter/SurfSense★ 17ksame name
- udecode/plate★ 17ksame name
- spree/spree★ 16ksame name
- trycompai/crm★ 12ksame name
- open-slide/open-slide★ 9.8ksame name
- 1weiho/open-slide★ 9.8ksame name
- openai/plugins★ 7.8ksame name
180 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- .claude/skills/crossbeam-ops/CLAUDE.mdCLAUDE.md
- adu-city-researchSkill
- adu-corrections-interpreterSkill
- cc-guideSkill
- crossbeam-opsSkill
- demo-city-reviewSkill
- demo-contractor-correctionsSkill
- fal-aiSkill
- frontend-designSkill
- long-running-agentSkill
- nano-bananaSkill
- product-demo-videoSkill
- react-best-practicesSkill
- skill-creatorSkill
- template-skillSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 5 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 187 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Critical Rule: Always use CSS variables and component variants for styling.
- Distinctive: line 58
Use Variants: - Never hardcode styles; always create/use component variants
- Very specific: line 61
cn() Utility: - Always use cn() from lib/utils.ts for conditional classes
- Distinctive: line 122
Search the official docs for:
- Distinctive: line 140
Always use the theming system - never hardcode colors or spacing
- Distinctive: line 142
Use composition to build complex UIs from simple pieces
“Common” is measured: kept by at least 6 in 10 of the 187 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ShadCN UI Expert Guide
Core Philosophy
ShadCN UI is NOT a traditional component library - it's a code distribution system that copies source code directly into your project at components/ui/. You own and control the code completely.
Critical Rule: Always use CSS variables and component variants for styling. NEVER hardcode styles directly in components. This maintains consistency across your design system.
⚠️ Critical: Tailwind v4 Color Issue
If colors aren't showing up in Tailwind v4, you need to wrap CSS variables with hsl():
/* ❌ WRONG - Colors won't work */
@theme inline {
--color-primary: var(--primary);
}
/* ✅ CORRECT - Wrap with hsl() */
@theme inline {
--color-primary: hsl(var(--primary));
}ShadCN stores HSL channels as raw values (28 100% 50%). Tailwind v4's @theme inline needs hsl() wrapper to recognize them as colors.
See theming-guide.md for full details.
Quick Reference
Initial Setup
npx shadcn@latest init # Interactive setup
npx shadcn@latest init -d # Use defaults (recommended)Adding Components
npx shadcn@latest add button card dialogComponents install to components/ui/[component-name].tsx
Import & Use
import { Button } from "@/components/ui/button"
<Button variant="default" size="lg">Click me</Button>Core Principles
- Use Variants - Never hardcode styles; always create/use component variants
- CSS Variables - Theme with CSS variables in
globals.css, not hardcoded colors - Composition - Build complex UIs by composing simple components
- cn() Utility - Always use
cn()fromlib/utils.tsfor conditional classes - Own Your Code - Components live in your repo; modify them as needed
Detailed Documentation
For comprehensive guides and examples, read these reference files:
- setup-guide.md - Detailed installation, configuration, and components.json setup
- component-patterns.md - Complete examples: forms with validation, data tables, dialogs, layouts
- theming-guide.md - CSS variables, dark mode, custom themes, color systems
- variant-creation.md - How to create and extend component variants properly
- common-mistakes.md - Anti-patterns to avoid with correct alternatives
Quick Anti-Patterns
❌ Wrong
// Hardcoded styling
<Button className="bg-blue-600 text-white px-8">Submit</Button>
// Arbitrary overrides
<Button className="!bg-red-500 !text-lg">Click</Button>
// Duplicated code
<button className="rounded-lg bg-primary px-4 py-2">Save</button>✅ Correct
// Use variants
<Button variant="primary" size="lg">Submit</Button>
// Create new variant in components/ui/button.tsx
variants: {
variant: {
danger: "bg-destructive text-destructive-foreground"
}
}
// Use component system
<Button>Save</Button>File Structure
project/
├── components/
│ ├── ui/ # ShadCN components (YOU OWN)
│ │ ├── button.tsx
│ │ ├── card.tsx
│ │ └── ...
│ └── custom/ # Your extensions
├── lib/
│ └── utils.ts # cn() utility
├── app/
│ └── globals.css # Theme CSS variables
└── components.json # ShadCN configWhen to Use Web Search
Search the official docs for:
- Specific component API details
- New/updated component examples
- Advanced composition patterns
- Latest features or changes
Example: shadcn ui [component-name] examples
Server vs Client Components
- Server Components (no
"use client"): Card, Badge, Typography, Separator - Client Components (has
"use client"): Dialog, Dropdown, Sheet, Form
Interactive components automatically include the directive.
Key Reminders
- Components don't auto-update; manually re-add or update them
- Always use the theming system - never hardcode colors or spacing
- Build reusable patterns with variants, not one-off implementations
- Use composition to build complex UIs from simple pieces
- Official docs: https://ui.shadcn.com
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

