shadcn/ui expert

shadcn/ui Expert Skill Guide

Objective

Use shadcn/ui as a composable, copy-owned component baseline. Customise design tokens to match the product; never treat the library as a locked black box.

1) Setup and Configuration

npx shadcn@latest init

• Confirm aliases (@/components, @/lib) and Tailwind config are correct.
• Component output paths:
  • UI primitives: src/components/ui
  • Feature components: src/components/features or src/components/<domain>
• Keep components.json committed and stable across teammates.
• Add the cn merge helper in src/lib/utils.ts:

import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'
export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) }

2) Token and Theme Strategy

Override CSS variables in globals.css — this is how shadcn separates colour from component code:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --border: 214.3 31.8% 91.4%;
  --ring: 221.2 83.2% 53.3%;
  --radius: 0.5rem;
}
.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
}

Maintain one source of truth for radius, spacing, and typography rhythm.

3) Card Composition Pattern

shadcn Card is a composition — always use Card/CardHeader/CardTitle/CardContent:

import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'

function StatCard({ icon: Icon, label, value, variant = 'slate' }: {
  icon: React.ElementType
  label: string
  value: string | number
  variant?: 'slate' | 'red' | 'green'
}) {
  const colors = {
    slate: 'text-slate-600',
    red:   'text-red-500',
    green: 'text-green-600',
  }
  return (
    <Card>
      <CardContent className="pt-4">
        <div className="flex items-center gap-3">
          <Icon className={cn('h-5 w-5', colors[variant])} />
          <div>
            <p className="text-xs text-muted-foreground uppercase tracking-wide">{label}</p>
            <p className={cn('text-2xl font-semibold tabular-nums', colors[variant])}>{value}</p>
          </div>
        </div>
      </CardContent>
    </Card>
  )
}