shadcn/ui Setup

Sets up shadcn/ui with the modern CSS-first Tailwind v4 setup, not the deprecated v3 approach.

Contract

Inputs:

• Project root directory (defaults to current working directory).
• Optional: theme name (zinc, slate, stone, etc.), component list, router type (app-router or pages-router).

Outputs:

• globals.css with @import "tailwindcss" and full @theme token block.
• components.json with CSS-first shadcn config.
• src/lib/utils.ts with cn() helper.
• Installed packages: class-variance-authority, clsx, tailwind-merge, lucide-react, tailwindcss, @tailwindcss/postcss.

Creates/Modifies:

• src/app/globals.css (created or overwritten).
• components.json (created or overwritten).
• src/lib/utils.ts (created).
• package.json (dependencies updated via bun add).
• postcss.config.mjs (created if absent).

External Side Effects:

• Runs bun add to install packages.
• Runs bunx shadcn@latest add for any specified components.

Confirmation Required:

• None. Running this skill applies all changes immediately. Review the component list before invoking in an existing project.

Delegates To:

• bunx shadcn@latest add for individual component installation.

Purpose

IMPORTANT: shadcn/ui CLI and AI assistants often generate Tailwind v3 configs by default. This skill ensures:

• Tailwind v4 CSS-first configuration
• Proper @theme block with shadcn color tokens
• No deprecated tailwind.config.js files
• Correct dependency versions

When to Use

• Setting up a new Next.js project with shadcn/ui
• Adding shadcn/ui to an existing project
• Migrating from shadcn + Tailwind v3 to v4
• Resetting a broken shadcn configuration

Quick Start

# Install core dependencies
bun add class-variance-authority clsx tailwind-merge lucide-react
bun add -D tailwindcss @tailwindcss/postcss

# Initialize shadcn (CSS-first, no tailwind.config)
bunx shadcn@latest init

# Install specific components
bunx shadcn@latest add button card input dialog

# Or install an essential starter set
bunx shadcn@latest add button card input label dialog dropdown-menu toast

What Gets Installed

Dependencies

See references/examples.md (§ Dependency Versions Example) for the full dependency block.

File Structure

See references/examples.md (§ Generated File Structure) for the full tree.

Tailwind v4 + shadcn CSS Configuration

The skill generates a CSS-first configuration using @import "tailwindcss" and an @theme block with all shadcn color tokens and border-radius variables.

See ${CLAUDE_SKILL_DIR}/references/shadcn-theme-tokens.md for the full token block (load when constructing the globals.css file).

Available Themes

Common Components

Install commonly used components:

# Essential set
bunx shadcn@latest add button card input label dialog dropdown-menu toast

# Form-focused
bunx shadcn@latest add form input label select checkbox radio-group switch textarea

# Dashboard
bunx shadcn@latest add card table tabs badge avatar dropdown-menu sheet sidebar

components.json Configuration

See references/examples.md (§ components.json Full Example) for the full config. The tailwind.config field stays empty because setup uses CSS-first configuration in v4.

Utils File

// src/lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Usage After Setup

Adding Components

# Using bunx (recommended with bun)
bunx shadcn@latest add button

# Multiple components
bunx shadcn@latest add card dialog dropdown-menu

Using Components

See references/examples.md (§ Using Components Example) for a sample composition.

Dark Mode Support

The CSS uses prefers-color-scheme by default. For manual toggle, see references/examples.md (§ Dark Mode — Manual Toggle Provider) for the provider component and class-based CSS override.

Troubleshooting

"tailwind.config.js created by shadcn CLI"

Delete it. The CLI sometimes generates v3 configs. Run:

rm tailwind.config.js tailwind.config.ts

Components not styled correctly

1. Check that globals.css is imported in your layout
2. Verify @import "tailwindcss" is at the top
3. Ensure @theme block contains all required variables

Type errors with components

Run:

bun add -D @types/react @types/react-dom

cn() utility not found

Create src/lib/utils.ts:

import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Validation

After setup, verify no v3 patterns were introduced:

# Should return nothing (no v3 tailwind.config files)
find . -name "tailwind.config.*" -not -path "*/node_modules/*"

# Should return nothing (no @apply directives)
grep -r "@apply" src/ --include="*.css" 2>/dev/null

# Verify the @import directive is present
grep "@import \"tailwindcss\"" src/app/globals.css