gh-hopeoverture-worldbuilding-app-skills-plugins-tailwind-shadcn-ui-setup/skills/tailwind-shadcn-ui-setup/references/tailwind-v4-migration.md

Tailwind CSS v4 Migration Guide

Overview

Tailwind CSS v4 introduces significant changes to configuration and usage patterns. This document outlines the differences and provides migration guidance.

Current Status (as of January 2025)

• Tailwind CSS v3.x: Stable, widely adopted
• Tailwind CSS v4: In development, alpha/beta releases available
• Recommendation: Use v3 with forward-compatible patterns for production projects

Key Differences: v3 vs v4

Configuration Format

v3 (Current)

// tailwind.config.ts
import type { Config } from 'tailwindcss'

export default {
  darkMode: 'class',
  content: ['./app/**/*.{ts,tsx}'],
  theme: {
    extend: {
      colors: { /* ... */ }
    }
  },
  plugins: []
} satisfies Config

v4 (Future)

/* @config directive in CSS */
@config "./tailwind.config.js";

@theme {
  --color-brand: #3b82f6;
  --font-sans: system-ui, sans-serif;
}

CSS Variables & Tokens

v3 Pattern (Forward-Compatible)

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
}

// tailwind.config.ts
colors: {
  background: 'hsl(var(--background))',
  foreground: 'hsl(var(--foreground))'
}

v4 Expected Pattern

@theme {
  --color-background: oklch(100% 0 0);
  --color-foreground: oklch(20% 0.02 270);
}

Plugin System

v3: JavaScript-based plugins in config file v4: CSS-based plugins with @plugin directive

Migration Strategy

Phase 1: v3 with Forward-Compatible Patterns (Current)

Use CSS variables extensively:

• Define semantic tokens (--primary, --background, etc.)
• Use HSL/OKLCH color space for easier manipulation
• Structure CSS variables to match expected v4 patterns

Phase 2: v4 Alpha/Beta Testing (When Available)

Test v4 alphas in non-production projects:

npm install tailwindcss@next

Update configuration:

• Move color tokens to @theme directive
• Convert plugins to CSS-based format
• Test build performance and output

Phase 3: v4 Stable Migration (Future)

When v4 is stable:

1. Update package: npm install tailwindcss@latest
2. Migrate config format (may have migration tool)
3. Test thoroughly across all components
4. Update documentation

Recommended Patterns for This Skill

Use CSS Custom Properties

[OK] Good (Forward-Compatible)

:root {
  --radius: 0.5rem;
  --primary: 222.2 47.4% 11.2%;
}

.card {
  border-radius: var(--radius);
  background: hsl(var(--primary));
}

[ERROR] Avoid (Hard-Coded)

.card {
  border-radius: 0.5rem;
  background: #1e293b;
}

Semantic Color Naming

Use semantic names that describe purpose, not appearance:

• [OK] --primary, --destructive, --muted
• [ERROR] --blue-500, --red-600, --gray-200

HSL Color Space

Use HSL (or OKLCH when v4 is available) for better color manipulation:

/* HSL: Hue Saturation Lightness */
--primary: 222.2 47.4% 11.2%;

/* Usage in CSS */
background: hsl(var(--primary));
background: hsl(var(--primary) / 0.8); /* With alpha */

Checking for v4 Availability

# Check installed version
npm list tailwindcss

# Check latest available version
npm view tailwindcss versions --json

# Install specific version
npm install tailwindcss@4.0.0  # When available

V4-Specific Features to Watch For

CSS-First Configuration

• @theme directive for token definition
• @plugin for extending functionality
• Native CSS nesting support

Improved Color System

• OKLCH color space support
• Better color mixing
• Improved dark mode handling

Performance Improvements

• Faster build times
• Smaller CSS output
• Better JIT performance

New Utilities

• Container queries (better support)
• Cascade layers
• View transitions

Resources

• Tailwind CSS Docs: https://tailwindcss.com/docs
• V4 Alpha Docs: https://tailwindcss.com/docs/v4-alpha
• GitHub Discussions: https://github.com/tailwindlabs/tailwindcss/discussions
• Upgrade Guide: https://tailwindcss.com/docs/upgrade-guide (when v4 is stable)

Notes for Skill Usage

When this skill runs:

1. Check Tailwind version: npm view tailwindcss version
2. If v4 stable is available: Use v4 configuration patterns
3. If v4 is not available: Use v3 with forward-compatible CSS variables
4. Add comments in generated files indicating v4 migration points:

   // TODO: When upgrading to Tailwind v4, move these tokens to @theme directive
   

This approach ensures the skill produces production-ready code today while being ready for v4 when it arrives.