Tailwind v4 + Shadcn UI

Overview

The Tailwind v4 + Shadcn UI skill provides a production-tested setup pattern for Tailwind CSS v4 with shadcn/ui components. This skill implements the new CSS-first architecture using @theme inline patterns and prevents 8 documented errors that commonly occur during migration and setup.

Production-Tested: This skill is battle-tested in production at WordPress Auditor

What This Skill Does

The skill guides AI agents through the complete Tailwind v4 + shadcn/ui setup:

Four-Step Architecture - CSS variables → Tailwind mapping → base styles → automatic dark mode
Prevents 8 Errors - Documented solutions for common setup failures
Dark Mode Setup - Complete ThemeProvider and toggle implementation
Migration Guide - v3 → v4 migration with community-tested patterns
OKLCH Color Space - Modern color system with automatic fallbacks
Built-in Features - Container queries, line-clamp (no plugins needed)

Location in TailStack Packages

The Tailwind v4 + Shadcn skill is available in the React package:

# Agent skill files
packages/react/.agent/skills/tailwind-v4-shadcn/
packages/react/.claude/skills/tailwind-v4-shadcn/
packages/react/.cursor/skills/tailwind-v4-shadcn/
packages/react/.opencode/skills/tailwind-v4-shadcn/

Skill Structure

Skill Contents

Each skill directory contains:

SKILL.md - Complete setup guide (666 lines)
templates/ - Production-ready file templates
- index.css - Complete CSS with color variables
- components.json - shadcn/ui v4 configuration
- vite.config.ts - Vite + Tailwind plugin setup
- theme-provider.tsx - Dark mode provider
- utils.ts - cn() utility function
references/ - Deep dive documentation
- architecture.md - Four-step pattern explanation
- dark-mode.md - Complete dark mode guide
- common-gotchas.md - Troubleshooting
- migration-guide.md - v3 → v4 migration
commands/ - Setup automation
- setup.md - Installation commands

The Four-Step Architecture

Critical: You must follow all four steps in order. Skipping any step will break your theme.

Step 1: Define CSS Variables at Root

Define color variables at the root level (NOT inside @layer base).

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

:root {
  --background: hsl(0 0% 100%);      /* hsl() wrapper required */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
}

Step 2: Map Variables to Tailwind Utilities

Use @theme inline to generate utility classes.

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

Without this step, utilities like bg-background won’t exist.

Step 3: Apply Base Styles

Reference variables directly in base styles.

@layer base {
  body {
    background-color: var(--background);  /* NO hsl() wrapper */
    color: var(--foreground);
  }
}

Never double-wrap: hsl(var(--background)) is incorrect

Step 4: Result - Automatic Dark Mode

Your components now automatically switch themes.

<div className="bg-background text-foreground">
  {/* No dark: variants needed */}
</div>

Common Errors Prevented

This skill prevents 8 documented errors:

Error #1: tw-animate-css Import Error

Error: “Cannot find module ‘tailwindcss-animate’”Solution:

# ✅ Correct for v4
pnpm add -D tw-animate-css

# ❌ Wrong (v3 only)
npm install tailwindcss-animate

Add to src/index.css:

@import "tailwindcss";
@import "tw-animate-css";

Error #2: Colors Not Working

Error: bg-primary doesn’t apply stylesCause: Missing @theme inline mappingSolution: Add the @theme inline block (Step 2 of the architecture)

Error #3: Dark Mode Not Switching

Error: Theme stays light or darkCause: Missing ThemeProviderSolution: Use the template from templates/theme-provider.tsx and wrap your app

Error #4: Duplicate @layer base

Error: “Duplicate @layer base” in consoleCause: shadcn init adds @layer base - don’t add anotherSolution: Use single @layer base block for all base styles

Error #5: Build Fails with tailwind.config.ts

Error: “Unexpected config file”Cause: v4 doesn’t use tailwind.config.ts (v3 legacy)Solution:

rm tailwind.config.ts

All configuration happens in CSS using @theme directive.

Error #6: @theme inline Breaks Multi-Theme

Issue: Dark mode doesn’t switch when using custom variantsCause: @theme inline bakes VALUES at build timeSolution: Use @theme (without inline) for multi-theme setups:

@theme {
  --color-text-primary: var(--color-slate-900);
}

@layer theme {
  [data-mode="dark"] {
    --color-text-primary: var(--color-white);
  }
}

Error #7: @apply Breaking (v4 Change)

Error: Cannot apply unknown utility classCause: v4 doesn’t support @apply with @layer base/componentsMigration:

/* ❌ v3 pattern */
@layer components {
  .custom-button {
    @apply px-4 py-2 bg-blue-500;
  }
}

/* ✅ v4 pattern */
@utility custom-button {
  @apply px-4 py-2 bg-blue-500;
}

Error #8: @layer base Styles Not Applying

Issue: Base styles seem ignoredCause: v4 uses native CSS layers - if not ordered, utilities override baseSolution: Define layer order explicitly or don’t use @layer base

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/base.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

Quick Setup Guide

Install Dependencies

pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node tw-animate-css
pnpm dlx shadcn@latest init

Configure Vite

// 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') } }
})

Update components.json

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

Delete Legacy Config

rm tailwind.config.ts  # v4 doesn't use this

Follow Four-Step Architecture

Implement all four steps as documented above in your src/index.css

Dark Mode Implementation

// src/components/theme-provider.tsx
import { createContext, useContext, useEffect, useState } from 'react'

type Theme = 'dark' | 'light' | 'system'

type ThemeProviderProps = {
  children: React.ReactNode
  defaultTheme?: Theme
  storageKey?: string
}

const ThemeProviderContext = createContext<ThemeProviderState | undefined>(undefined)

export function ThemeProvider({
  children,
  defaultTheme = 'system',
  storageKey = 'vite-ui-theme',
  ...props
}: ThemeProviderProps) {
  const [theme, setTheme] = useState<Theme>(
    () => (localStorage.getItem(storageKey) as Theme) || defaultTheme
  )

  useEffect(() => {
    const root = window.document.documentElement
    root.classList.remove('light', 'dark')

    if (theme === 'system') {
      const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
        ? 'dark'
        : 'light'
      root.classList.add(systemTheme)
      return
    }

    root.classList.add(theme)
  }, [theme])

  const value = {
    theme,
    setTheme: (theme: Theme) => {
      localStorage.setItem(storageKey, theme)
      setTheme(theme)
    },
  }

  return (
    <ThemeProviderContext.Provider {...props} value={value}>
      {children}
    </ThemeProviderContext.Provider>
  )
}

What’s New in Tailwind v4

OKLCH Color Space

Perceptually uniform colors

Better gradients (no muddy middle)
Wider color gamut
Automatic sRGB fallbacks
93.1% browser support

@theme {
  --color-brand: oklch(0.7 0.15 250);
}

Built-in Features

No plugins needed

Container queries built-in
Line clamp built-in
Typography plugin available
Forms plugin available

<div className="@container">
  <div className="@md:text-lg">Responsive</div>
</div>

Container Queries (Built-in)

<div className="@container">
  <div className="@md:text-lg @lg:grid-cols-2">
    Content responds to container width, not viewport
  </div>
</div>

Line Clamp (Built-in)

<p className="line-clamp-3">Truncate to 3 lines with ellipsis...</p>
<p className="line-clamp-[8]">Arbitrary values supported</p>
<p className="line-clamp-(--teaser-lines)">CSS variable support</p>

Migration from v3

Key Changes

Delete tailwind.config.ts
Move theme to CSS with @theme inline
Replace tailwindcss-animate with tw-animate-css
Update plugins: require() → @plugin
Use Vite plugin instead of PostCSS (recommended)

Automated migration tool often fails - Manual migration recommended

Default Element Styles Removed

Tailwind v4 takes a minimal approach - headings, lists, buttons lose default styles. Solution 1: Typography plugin

pnpm add -D @tailwindcss/typography

@import "tailwindcss";
@plugin "@tailwindcss/typography";

<article className="prose dark:prose-invert">
  {/* All elements styled automatically */}
</article>

Solution 2: Custom base styles

@layer base {
  h1 { @apply text-4xl font-bold mb-4; }
  h2 { @apply text-3xl font-bold mb-3; }
  ul { @apply list-disc pl-6 mb-4; }
}

Using with AI Agents

Claude Desktop & Claude.ai

Access Templates

Navigate to packages/react/.claude/skills/tailwind-v4-shadcn/templates/

Request Setup

Example: “Set up Tailwind v4 with shadcn/ui following the skill templates”

Reference Rules

Example: “Fix this Tailwind setup using the common-gotchas guide”

Cursor

Add to Rules

Include in .cursorrules:

When setting up Tailwind v4, follow .cursor/skills/tailwind-v4-shadcn/SKILL.md

Use Templates

Request specific templates: “Use the theme-provider template from tailwind-v4-shadcn”

OpenCode

Skill Available

Automatically loaded from packages/react/.opencode/skills/tailwind-v4-shadcn/

Request Setup

Example: “Initialize Tailwind v4 with dark mode using the skill templates”

Setup Checklist

Critical Rules

✅ Always Do

Wrap colors with hsl() in :root/.dark
Use @theme inline to map CSS variables
Set "tailwind.config": "" in components.json
Delete tailwind.config.ts
Use @tailwindcss/vite plugin

❌ Never Do

Put :root/.dark inside @layer base
Use .dark { @theme { } } pattern
Double-wrap: hsl(var(--background))
Use tailwind.config.ts for theme
Use @apply directive (deprecated)

Official Documentation

Learn More

Skills.sh: tailwind-v4-shadcn
shadcn/ui Vite Setup: Official Guide
shadcn/ui Tailwind v4: Migration Guide
Tailwind v4 Docs: Official Documentation

Vercel React Best Practices - For performance optimization
Node.js Backend Patterns - For backend setup

Version Information

Skill Version: 3.0.0
Tailwind CSS: 4.1.18 (Latest)
Production: WordPress Auditor
Last Updated: January 20, 2026
Browser Support: Chrome 111+, Firefox 113+, Safari 15.4+

Templates

Configuration

Agent Skills

Tailwind v4 + Shadcn UI

Overview

What This Skill Does

Location in TailStack Packages

Skill Structure

Skill Contents

The Four-Step Architecture

Common Errors Prevented

Quick Setup Guide

Dark Mode Implementation

What’s New in Tailwind v4

OKLCH Color Space

Built-in Features

Container Queries (Built-in)

Line Clamp (Built-in)

Migration from v3

Key Changes

Default Element Styles Removed

Using with AI Agents

Claude Desktop & Claude.ai

Cursor

OpenCode

Setup Checklist

Pre-Flight Checklist

Critical Rules

✅ Always Do

❌ Never Do

Official Documentation

Learn More

Version Information

Build docs developers (and LLMs) love

Templates

Configuration

Agent Skills

​Overview

​What This Skill Does

​Location in TailStack Packages

​Skill Structure

Skill Contents

​The Four-Step Architecture

​Common Errors Prevented

​Quick Setup Guide

​Dark Mode Implementation

​What’s New in Tailwind v4

OKLCH Color Space

Built-in Features

​Container Queries (Built-in)

​Line Clamp (Built-in)

​Migration from v3

Key Changes

​Default Element Styles Removed

​Using with AI Agents

​Claude Desktop & Claude.ai

​Cursor

​OpenCode

​Setup Checklist

Pre-Flight Checklist

​Critical Rules

✅ Always Do

❌ Never Do

​Official Documentation

Learn More

​Related Skills

​Version Information

Build docs developers (and LLMs) love

Overview

What This Skill Does

Location in TailStack Packages

Skill Structure

The Four-Step Architecture

Common Errors Prevented

Quick Setup Guide

Dark Mode Implementation

What’s New in Tailwind v4

Container Queries (Built-in)

Line Clamp (Built-in)

Migration from v3

Default Element Styles Removed

Using with AI Agents

Claude Desktop & Claude.ai

Cursor

OpenCode

Setup Checklist

Critical Rules

Official Documentation

Related Skills

Version Information