cc-crossbeam: Skill for Claude Code

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 dialog

Components 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

1. Use Variants - Never hardcode styles; always create/use component variants
2. CSS Variables - Theme with CSS variables in globals.css, not hardcoded colors
3. Composition - Build complex UIs by composing simple components
4. cn() Utility - Always use cn() from lib/utils.ts for conditional classes
5. 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