tailwind-v4-anti-patterns

Tailwind v4 Anti-Patterns

These are the patterns AI models generate most frequently when working with Tailwind v4 projects. Every one of them is wrong. If you catch yourself generating any of these, stop and correct immediately.

Anti-Pattern 1: Creating tailwind.config.js in a New Project

If starting a new Tailwind v4 project, do NOT create a tailwind.config.js or tailwind.config.ts file. Configuration lives in CSS:

/* All config goes here, in your main CSS file */
@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --font-sans: "Inter", sans-serif;
}

The only exception: migrating an existing v3 project where you explicitly need @config "../../tailwind.config.js" as a bridge.

Anti-Pattern 2: Installing Wrong Packages

Do NOT install these v3-era packages:

• tailwindcss as a PostCSS plugin directly (use @tailwindcss/postcss or @tailwindcss/vite)
• autoprefixer (handled by Tailwind v4 internally)
• postcss-import (handled by Tailwind v4 internally)

Correct v4 installation:

For Vite projects:

npm install -D tailwindcss @tailwindcss/vite

For PostCSS projects:

npm install -D tailwindcss @tailwindcss/postcss

Anti-Pattern 3: Using @tailwind Directives

/* WRONG - v3 syntax */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* CORRECT - v4 syntax */
@import "tailwindcss";

Anti-Pattern 4: Using Opacity Utilities

These classes do not exist in v4:

• bg-opacity-*
• text-opacity-*
• border-opacity-*
• divide-opacity-*
• placeholder-opacity-*
• ring-opacity-*

Always use the / modifier syntax: bg-red-500/50, text-white/80.

Anti-Pattern 5: Relying on Default Border/Ring Colors

If you write class="border" without a color, the border will be currentColor in v4 (not gray-200 as in v3). Same for ring (1px currentColor instead of 3px blue-500).

Always be explicit:

<div class="border border-gray-200"></div>
<div class="ring-3 ring-blue-500"></div>