shadcn-setup

shadcn/ui Setup

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

Authorized Scope

Act only within the user's request and existing approval; loading this skill grants no new authority. Keep report-only requests report-only, honor the caller's target, host, provider, and cost limits, ask before expanding scope, and forward these limits to delegates.

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:

• Apply only the explicitly requested setup or migration. Invocation alone grants no permission to replace existing styles or configuration.
• Confirm before overwriting files or installing components beyond that scope.

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

Theme	Description
default	shadcn default (neutral grays)
zinc	Zinc-based neutral
slate	Slate-based cool neutral
stone	Stone-based warm neutral
gray	Pure gray
neutral	True neutral
red	Red primary
rose	Rose primary
orange	Orange primary
green	Green primary
blue	Blue primary
yellow	Yellow primary
violet	Violet primary

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