Tailwind v4 + shadcn/ui Stack

Production-tested setup for Tailwind v4 with shadcn/ui. Prevents 8 documented errors through a mandatory four-step architecture.

WHAT

Complete Tailwind v4 + shadcn/ui configuration:

• Four-step theming architecture (mandatory)
• CSS variable-based color system
• Automatic dark mode switching
• Error prevention for 8 common mistakes
• Migration guide from v3
• Production-ready templates

WHEN

• Starting a new React/Vite project with Tailwind v4
• Migrating from Tailwind v3 to v4
• Setting up shadcn/ui with Tailwind v4
• Debugging: colors not working, dark mode broken, build failures
• Fixing @theme inline, @apply, or @layer base issues

KEYWORDS

tailwind v4, tailwindcss 4, shadcn, shadcn/ui, @theme inline, dark mode, css variables, vite, tw-animate-css, tailwind config, migration

Production verified: WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev)
Versions: [email protected], @tailwindcss/[email protected]

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install tailwind-v4-shadcn

Quick Start

# 1. Install dependencies
pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node tw-animate-css
pnpm dlx shadcn@latest init

# 2. Delete v3 config (v4 doesn't use it)
rm tailwind.config.ts

vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: { alias: { '@': path.resolve(__dirname, './src') } }
})

components.json (CRITICAL):

{
  "tailwind": {
    "config": "",
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true
  }
}

The Four-Step Architecture (MANDATORY)

Skipping steps breaks theming. Follow exactly:

Step 1: Define CSS Variables at Root

/* src/index.css */
@import "tailwindcss";
@import "tw-animate-css";

:root {
  --background: hsl(0 0% 100%);
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  --primary-foreground: hsl(210 40% 98%);
  /* ... all light mode colors with hsl() wrapper */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  --primary-foreground: hsl(222.2 47.4% 11.2%);
  /* ... all dark mode colors */
}

Critical: Define at root level (NOT inside @layer base). Use hsl() wrapper.

Step 2: Map Variables to Tailwind

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... map ALL CSS variables */
}

Why: Generates utility classes (bg-background, text-primary). Without this, utilities don't exist.

Step 3: Apply Base Styles