Shadcn Customization

The Customization Cascade

Theme Tokens (globals.css)
    ↓
Component Families (related components)
    ↓
Individual Variants (cva patterns)
    ↓
Instance Overrides (className props)

Always work top-down. Token changes cascade automatically; component changes require manual propagation to siblings.

Part 1: Theme Token System

CSS Variable Architecture (Tailwind v4)

shadcn/ui uses a layered CSS variable system. Understanding this prevents broken themes:

/* Layer 1: Raw values in :root */
:root {
  --radius: 0.625rem;
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
}

/* Layer 2: Theme mapping via @theme inline */
@theme inline {
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

/* Layer 3: Components consume mapped values */
/* Button uses: rounded-lg (--radius-lg), bg-primary, text-primary-foreground */

Complete Token Reference

Creating a Custom Theme

Step 1: Define your palette in OKLCH (better perceptual uniformity than HSL):

:root {
  /* Brand colors */
  --primary: oklch(0.65 0.25 250); /* Vibrant blue */
  --primary-foreground: oklch(0.98 0.01 250);

  /* Semantic adjustments */
  --destructive: oklch(0.55 0.22 25); /* Rich red */
  --accent: oklch(0.75 0.15 180); /* Teal accent */

  /* Surface hierarchy (maintain contrast) */
  --background: oklch(0.99 0.005 250);
  --card: oklch(1 0 0);
  --muted: oklch(0.96 0.01 250);
  --popover: oklch(1 0 0);
}

.dark {
  --primary: oklch(0.75 0.2 250); /* Lighter for dark mode */
  --primary-foreground: oklch(0.15 0.02 250);

  --background: oklch(0.13 0.02 250);
  --card: oklch(0.18 0.02 250);
  --muted: oklch(0.22 0.02 250);
  --popover: oklch(0.2 0.02 250);
}

Step 2: Adjust radius for personality:

:root {
  /* Sharp/Technical: */
  --radius: 0.25rem;
  /* Balanced: */
  --radius: 0.5rem;
  /* Soft/Friendly: */
  --radius: 0.75rem;
  /* Pill-like: */
  --radius: 1rem;
  /* Fully rounded: */
  --radius: 9999px;
}

Step 3: Extend with custom tokens:

:root {
  /* Custom semantic colors */
  --success: oklch(0.65 0.2 145);
  --success-foreground: oklch(0.98 0.02 145);
  --warning: oklch(0.8 0.18 85);
  --warning-foreground: oklch(0.25 0.05 85);
  --info: oklch(0.7 0.15 230);
  --info-foreground: oklch(0.98 0.01 230);
}

@theme inline {
  --color-success: var(--success);
  --color-success-foreground: var(--success-foreground);
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
}

Part 2: Component Family Groups

Critical Insight: Components Travel in Packs

When you modify one component's visual properties, related components become inconsistent. Here are the families you must update together:

Family 1: Overlays & Floating Surfaces

When customizing overlays, update ALL of these:

// Example: Adding consistent glass morphism to all overlays
// In each component file, update the content wrapper:

// dialog.tsx
const DialogContent = React.forwardRef<...>(({ className, ...props }, ref) => (
  <DialogPrimitive.Content
    className={cn(
      "bg-background/80 backdrop-blur-xl border-white/20",
      "shadow-2xl shadow-black/10",
      // ... rest of classes
      className
    )}
    {...props}
  />
))

// Apply same pattern to: SheetContent, PopoverContent,
// DropdownMenuContent, TooltipContent, HoverCardContent

Family 2: Form Controls

Unified form control styling:

// Create shared input styles
const inputBaseStyles = cn(
  'h-11 px-4', // Consistent sizing
  'rounded-lg', // Match radius
  'border-2 border-input', // Visible borders
  'bg-transparent', // Or bg-muted/50
  'transition-all duration-200', // Smooth states
  'focus-visible:ring-2 focus-visible:ring-ring/50',
  'focus-visible:border-primary',
  'placeholder:text-muted-foreground/60'
);

// Apply to Input, Textarea, Select trigger, etc.

Family 3: Buttons & Actions

Unified button treatment:

// button.tsx - Define comprehensive variants
const buttonVariants = cva(
  cn(
    'inline-flex items-center justify-center gap-2',
    'font-medium transition-all duration-200',
    'focus-visible:outline-none focus-visible:ring-2',
    'focus-visible:ring-ring focus-visible:ring-offset-2',
    'disabled:pointer-events-none disabled:opacity-50',
    // Add micro-interaction
    'active:scale-[0.98]'
  ),
  {
    variants: {
      variant: {
        default: cn(
          'bg-primary text-primary-foreground',
          'hover:bg-primary/90',
          'shadow-md shadow-primary/25',
          'hover:shadow-lg hover:shadow-primary/30'
        ),
        secondary: cn(
          'bg-secondary text-secondary-foreground',
          'hover:bg-secondary/80',
          'border border-border'
        ),
        outline: cn(
          'border-2 border-input bg-transparent',
          'hover:bg-accent hover:text-accent-foreground',
          'hover:border-accent'
        ),
        ghost: cn('hover:bg-accent/50 hover:text-accent-foreground'),
        destructive: cn(
          'bg-destructive text-destructive-foreground',
          'hover:bg-destructive/90',
          'shadow-md shadow-destructive/25'
        ),
        // Custom variants
        success: cn(
          'bg-success text-success-foreground',
          'hover:bg-success/90'
        ),
        link: cn('text-primary underline-offset-4', 'hover:underline'),
      },
      size: {
        default: 'h-10 px-5 py-2',
        sm: 'h-8 px-3 text-sm',
        lg: 'h-12 px-8 text-lg',
        xl: 'h-14 px-10 text-xl',
        icon: 'h-10 w-10',
        'icon-sm': 'h-8 w-8',
        'icon-lg': 'h-12 w-12',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
);

Family 4: Data Display

Family 5: Navigation

Part 3: Animation & Motion System

Default shadcn Animations (tw-animate-css)

shadcn uses tw-animate-css for enter/exit animations. Customize timing and easing globally:

/* In globals.css, after imports */
:root {
  /* Animation timing */
  --animation-duration: 200ms;
  --animation-duration-slow: 400ms;
  --animation-duration-fast: 150ms;

  /* Easing curves */
  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
  --ease-in-out-expo: cubic-bezier(0.87, 0, 0.13, 1);
  --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
}

@theme inline {
  --animate-duration: var(--animation-duration);
}

Adding Custom Animations

Approach 1: CSS Keyframes (simpler)

@keyframes slide-up-fade {
  from {
    opacity: 0;
    transform: translateY(8px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

@keyframes scale-in {
  from {
    opacity: 0;
    transform: scale(0.95);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

@keyframes shimmer {
  0% {
    background-position: -200% 0;
  }
  100% {
    background-position: 200% 0;
  }
}

/* Apply to components */
.animate-slide-up-fade {
  animation: slide-up-fade var(--animation-duration) var(--ease-out-expo);
}

Approach 2: Motion library (React, more control)

import { motion, AnimatePresence } from "framer-motion"

// Wrap Dialog content
const DialogContent = React.forwardRef<...>(({ className, children, ...props }, ref) => (
  <DialogPrimitive.Portal>
    <DialogPrimitive.Overlay asChild>
      <motion.div
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        exit={{ opacity: 0 }}
        className="fixed inset-0 z-50 bg-black/80"
      />
    </DialogPrimitive.Overlay>
    <DialogPrimitive.Content asChild ref={ref} {...props}>
      <motion.div
        initial={{ opacity: 0, scale: 0.95, y: 10 }}
        animate={{ opacity: 1, scale: 1, y: 0 }}
        exit={{ opacity: 0, scale: 0.95, y: 10 }}
        transition={{ duration: 0.2, ease: [0.16, 1, 0.3, 1] }}
        className={cn("fixed left-1/2 top-1/2 ...", className)}
      >
        {children}
      </motion.div>
    </DialogPrimitive.Content>
  </DialogPrimitive.Portal>
))

Micro-Interaction Patterns

// Button press effect
'active:scale-[0.98] transition-transform duration-100';

// Hover lift
'hover:-translate-y-0.5 hover:shadow-lg transition-all duration-200';

// Focus glow
'focus-visible:ring-4 focus-visible:ring-primary/20 transition-shadow duration-200';

// Skeleton loading
'animate-pulse bg-muted';
// Or shimmer:
'bg-gradient-to-r from-muted via-muted/50 to-muted bg-[length:200%_100%] animate-shimmer';

Part 4: Typography Integration

Adding Custom Fonts

Step 1: Import fonts (using next/font, Google Fonts, or local)

// app/layout.tsx (Next.js example)
import { Instrument_Serif, DM_Sans } from 'next/font/google';

const displayFont = Instrument_Serif({
  subsets: ['latin'],
  weight: '400',
  variable: '--font-display',
});

const bodyFont = DM_Sans({
  subsets: ['latin'],
  variable: '--font-body',
});

export default function RootLayout({ children }) {
  return (
    <html className={`${displayFont.variable} ${bodyFont.variable}`}>
      {children}
    </html>
  );
}

Step 2: Configure in CSS

@theme inline {
  --font-sans: var(--font-body), system-ui, sans-serif;
  --font-display: var(--font-display), Georgia, serif;
}

@layer base {
  body {
    font-family: var(--font-sans);
  }

  h1,
  h2,
  h3,
  h4,
  h5,
  h6 {
    font-family: var(--font-display);
  }
}

Step 3: Apply to components

// card.tsx - Use display font for titles
const CardTitle = React.forwardRef<...>(({ className, ...props }, ref) => (
  <h3
    ref={ref}
    className={cn(
      "font-display text-2xl font-semibold tracking-tight",
      className
    )}
    {...props}
  />
))

Part 5: Coherence Checklist

When making ANY customization, check these for consistency:

Radius Changes

• Button
• Input, Textarea, Select
• Card
• Dialog, Sheet, Popover
• DropdownMenu, ContextMenu
• Tooltip
• Badge, Alert
• Avatar
• Tabs (triggers)
• Toggle, Switch

Shadow Changes

• Button (especially primary)
• Card
• Dialog, Sheet
• Popover, Dropdown
• Hover states on interactive cards

Border Changes

• Input, Textarea, Select
• Card
• Table
• Separator
• All overlay components

Color Changes

When changing primary:

• Button (default variant)
• Links
• Focus rings
• Switch (checked)
• Slider (track fill)
• Progress (indicator)
• Checkbox, Radio (checked)
• Tabs (active indicator)

Animation Timing Changes

• Dialog enter/exit
• Sheet slide
• Dropdown appear
• Tooltip delay and fade
• Accordion expand/collapse
• Collapsible toggle
• Toast enter/exit

Part 6: Advanced Patterns

Pattern 1: Semantic Variants via Data Attributes

// Instead of multiple component variants, use data attributes
<Card data-variant="elevated">
<Card data-variant="outlined">
<Card data-variant="filled">

// Style with attribute selectors
const Card = React.forwardRef<...>(({ className, ...props }, ref) => (
  <div
    ref={ref}
    className={cn(
      "rounded-lg",
      // Base styles
      "data-[variant=elevated]:bg-card data-[variant=elevated]:shadow-lg",
      "data-[variant=outlined]:border-2 data-[variant=outlined]:border-border",
      "data-[variant=filled]:bg-muted",
      className
    )}
    {...props}
  />
))

Pattern 2: Compound Components with Consistent Spacing

// Use CSS custom properties for internal spacing
const Card = React.forwardRef<...>(({ className, ...props }, ref) => (
  <div
    ref={ref}
    style={{ '--card-padding': '1.5rem' } as React.CSSProperties}
    className={cn("rounded-lg border bg-card", className)}
    {...props}
  />
))

const CardHeader = ({ className, ...props }) => (
  <div
    className={cn(
      "px-[var(--card-padding)] pt-[var(--card-padding)]",
      className
    )}
    {...props}
  />
)

const CardContent = ({ className, ...props }) => (
  <div
    className={cn("px-[var(--card-padding)]", className)}
    {...props}
  />
)

const CardFooter = ({ className, ...props }) => (
  <div
    className={cn(
      "px-[var(--card-padding)] pb-[var(--card-padding)]",
      className
    )}
    {...props}
  />
)

Pattern 3: Theme-Aware Shadows

:root {
  --shadow-color: 220 3% 15%;
  --shadow-elevation-low:
    0.3px 0.5px 0.7px hsl(var(--shadow-color) / 0.1),
    0.4px 0.8px 1px -1.2px hsl(var(--shadow-color) / 0.1),
    1px 2px 2.5px -2.5px hsl(var(--shadow-color) / 0.1);
  --shadow-elevation-medium:
    0.3px 0.5px 0.7px hsl(var(--shadow-color) / 0.11),
    0.8px 1.6px 2px -0.8px hsl(var(--shadow-color) / 0.11),
    2.1px 4.1px 5.2px -1.7px hsl(var(--shadow-color) / 0.11),
    5px 10px 12.6px -2.5px hsl(var(--shadow-color) / 0.11);
}

.dark {
  --shadow-color: 220 40% 2%;
}

@theme inline {
  --shadow-sm: var(--shadow-elevation-low);
  --shadow-md: var(--shadow-elevation-medium);
}

Quick Reference

File Locations

Common Class Patterns

OKLCH Color Manipulation

/* Darken: reduce L (lightness) */
--primary: oklch(0.65 0.25 250);
--primary-hover: oklch(0.55 0.25 250);

/* Lighten: increase L */
--primary-light: oklch(0.75 0.25 250);

/* Desaturate: reduce C (chroma) */
--primary-muted: oklch(0.65 0.1 250);

/* Shift hue: change H */
--primary-complement: oklch(0.65 0.25 70); /* 250 + 180 = 430 → 70 */

Common Mistakes

Integration with frontend-design Skill

This skill pairs with frontend-design. Use that skill's aesthetic direction guidance, then implement here:

1. frontend-design → Choose aesthetic direction (brutalist, refined, playful, etc.)
2. shadcn-customization → Implement that direction systematically across all components

Example flow:

• Direction: "Refined luxury" → Subtle shadows, generous spacing, serif display font, muted palette
• Direction: "Playful startup" → Rounded corners (--radius: 1rem), vibrant primary, bouncy animations
• Direction: "Technical/Developer" → Sharp corners (--radius: 0.25rem), monospace accents, minimal color