Tailwind CSS

Quick Verdict

When to use it: Any React/Next.js project. Also works well in Vue, Svelte, and vanilla HTML.

When not to: Deep CSS purists on the team, legacy project with existing CSS architecture, or email HTML.

Best For

• AI-assisted development — the single most AI-friendly styling approach. The utility-to-CSS property mapping is so direct that LLMs rarely make mistakes.
• Rapid prototyping — no context switching between markup and style files
• React + Next.js — tree-shaking, RSC compatibility, first-class support
• Design systems — CSS custom properties + Tailwind tokens create a maintainable token system

Avoid If

• Your team genuinely prefers writing semantic CSS and has the discipline to maintain it
• Large legacy project with an existing CSS architecture you'd need to migrate
• Email HTML — Tailwind's build step can't run in most email clients (though a dedicated email preset exists)

Why People Choose It

Tailwind solved the CSS scaling problem by eliminating it. Instead of inventing class names, organizing stylesheets, and managing specificity, you compose utilities directly in your markup. flex items-center gap-4 is self-documenting.

But the real accelerant was AI. When developers discovered that AI tools produce near-perfect Tailwind code while struggling with CSS Modules or styled-components, adoption became inevitable. The mapping between Tailwind utilities and visual output is so direct that LLMs rarely make mistakes.

The v4 release (2025) was a milestone. CSS-native configuration with @theme replaced tailwind.config.js. Setup is now one CSS import.

Hidden Costs

Essentially zero. Tailwind is free and open source. The only "cost" is v3 → v4 migration if you're upgrading an existing project — configuration model changed significantly.

Correct vs Cargo-Culted Patterns

Wrong — @apply as default:

/* ❌ @apply exists for edge cases, not as a default pattern */
.card {
  @apply flex flex-col rounded-lg border p-4;
}

Right — utilities directly:

{/* ✅ Utilities directly in markup */}
<div className="flex flex-col rounded-lg border p-4">

Wrong — hardcoded Tailwind defaults:

{/* ❌ Hardcoded color — breaks theming, no semantic meaning */}
<div className="bg-zinc-900 text-zinc-100">

Right — semantic design tokens:

{/* ✅ Semantic token — theming and dark mode work correctly */}
<div className="bg-bg-raised text-text-primary">

Wrong — class conflicts without cn():

{/* ❌ bg-blue-500 and bg-red-500 will conflict silently */}
<button className={`bg-blue-500 ${isActive && 'bg-red-500'}`}>

Right — cn() merge utility:

{/* ✅ tailwind-merge resolves conflicts correctly */}
<button className={cn('bg-blue-500', isActive && 'bg-red-500')}>

AI Coding Notes

Tailwind is the strongest area for AI code generation in web development. Describe the visual outcome, not the classes:

• "A card with subtle border, rounded corners, elevated background, 24px padding" → generates correct classes
• "Mobile-first: single column, 2 columns at md, 3 at lg" → generates correct responsive breakpoints

If you use custom design tokens (e.g. --color-bg-raised), include them in your context — AI will use them instead of defaulting to Tailwind's built-in palette.

Common AI Mistakes

1. @apply everywhere — generates CSS files that duplicate utility class combinations. Use utilities directly.
2. Hardcoded Tailwind defaults — uses bg-zinc-900 instead of your semantic tokens. Include your token definitions in the prompt.
3. Missing cn() for conditional classes — generates string concatenation that causes class conflicts. Always use tailwind-merge.
4. v3 config in a v4 project — tailwind.config.js with content paths doesn't exist in v4. Check which version you're on.
5. Enormous className strings — readable Tailwind requires grouping: layout first, spacing, typography, colors last.

Start With / Grow Into / Avoid Until Needed

Start with Tailwind for any new React project. The learning curve is moderate (1–2 days to become productive) and pays off immediately in AI-assisted workflows.

Grow into the full token system — define your semantic color and spacing tokens in @theme {} as your design system solidifies.

Avoid until needed: @apply, Tailwind plugins, safelist — these are escape hatches for edge cases, not defaults.

Migration Implications

Migrating from Tailwind is low pain — it's just CSS classes in your markup. The classes are human-readable and can be replaced mechanically. Migrating v3 → v4 is moderate effort (configuration model changed, some class names changed).