Chris-Maskey/tailwind-v4-configuration

Tailwind CSS v4 Configuration

A complete guide to configuring Tailwind CSS v4 with its new CSS-first approach, unified toolchain, and modern feature set.

When to Use This Skill

• Installing Tailwind v4 for the first time in a new project
• Migrating from Tailwind v3 to v4 (breaking changes and setup differences)
• Setting up build tools: Vite, PostCSS, or standalone CLI
• Customizing themes using the @theme directive
• Configuring content paths and template detection
• Adding plugins or creating custom utilities
• Configuring dark mode, prefixes, or other global options
• Troubleshooting v4 configuration issues

Key v4 Changes Overview

| Aspect | v3 | v4 | | ------------------ | --------------------------------- | ----------------------------------------------- | | Configuration | tailwind.config.js (JavaScript) | @theme block in CSS | | Import | Three @tailwind directives | Single @import "tailwindcss" | | Content paths | Explicit content array | Automatic detection (respects .gitignore) | | Build pipeline | Requires PostCSS + plugins | Integrated Lightning CSS (all-in-one) | | Performance | Fast | 10x faster (Oxide engine) | | Colors | hex, rgb, hsl | Native oklch() + modern color spaces | | Variants | outline-none removed outline | outline-hidden + proper outline-none | | Shadows | shadow-sm (smallest) | shadow-xs (smallest), shadow-md (default) | | Border radius | rounded-sm (smallest) | rounded-xs (smallest), rounded-md (default) |

Core Concepts

CSS-First Configuration

All configuration now lives in your CSS file using the @theme directive:

@import "tailwindcss";

@theme {
  --color-brand-primary: oklch(0.65 0.24 354.31);
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 1920px;
}

Automatic Content Detection

v4 automatically discovers templates - no configuration needed for most projects.

Key Utility Changes

• shadow-sm (v3) → shadow-xs (v4)
• rounded-sm (v3) → rounded-xs (v4)
• bg-gradient-to-r (v3) → bg-linear-to-r (v4)

Progressive Disclosure

This skill provides detailed examples through context files. Load them when needed:

| Context File | When to Load | | ----------------------------------------------- | -------------------------------------------------- | | context/setup-examples.md | Setting up installation, CSS config, custom utils | | context/migration-guide.md | Migrating from v3 to v4 | | context/framework-examples.md | Setting up Next.js, React, Vue, SvelteKit | | context/advanced-config.md | Multi-stylesheets, theming, animations |

Best Practices

✅ DO

• Use @import "tailwindcss" with a single import
• Define theme tokens in @theme block
• Leverage automatic content detection
• Use CSS variables with @theme for dynamic theming
• Use @utility for custom utilities (not @apply for components)
• Use @custom-variant for reusable variant logic
• Test the automated upgrade tool before manual migration

❌ DON'T

• Create a tailwind.config.js file (use CSS @theme instead)
• Use @tailwind base/components/utilities separately
• Configure content paths unless you have a specific need
• Forget to update breaking utility changes (shadow, blur, radius)
• Use opacity utilities like bg-opacity-50 (use /50 instead)
• Ignore browser compatibility (v4 targets modern browsers)
• Try to load legacy autoprefixer or postcss-import

Browser Compatibility

Tailwind CSS v4 targets modern browsers:

• Chrome/Edge: 111+
• Firefox: 128+
• Safari: 16.4+

Quick Decision Guide

Need to install Tailwind v4?
├─ New project? → Use Vite plugin (recommended)
├─ Existing project? → Use PostCSS plugin
└─ Static site? → Use CLI

Migrating from v3?
└─ Run: npx @tailwindcss/upgrade

Need custom utilities?
└─ Use @utility directive in CSS

Need framework setup?
└─ See context/framework-examples.md

References

• Tailwind CSS v4 Documentation
• Tailwind CSS v4 Upgrade Guide
• Automatic Upgrade Tool