tailwind-v4-core

Tailwind CSS v4 Rules

You are working with Tailwind CSS v4, not v3. v4 is a ground-up rewrite with breaking changes. Your training data likely contains mostly v3 patterns. Follow these rules exactly.

Import Syntax

Always use the single import:

@import "tailwindcss";

Never use the old v3 directives:

/* WRONG - v3 syntax, does not work in v4 */
@tailwind base;
@tailwind components;
@tailwind utilities;

Configuration is CSS-First

Define design tokens with @theme, not tailwind.config.js:

@import "tailwindcss";

@theme {
  --color-brand: #ff6a00;
  --color-surface: #0a0a0a;
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;
}

Only use @config "../../tailwind.config.js" when migrating a legacy project that still needs the JS config. For new projects, never create a tailwind.config.js.

Build Tool Setup

Prefer the Vite plugin (zero-config):

// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
  plugins: [tailwindcss()],
});

PostCSS alternative (only if not using Vite):

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Never add autoprefixer or postcss-import - Tailwind v4 handles both internally.

Content Detection

v4 automatically detects template files by scanning everything not in .gitignore. No content array needed.

To include paths outside the project (e.g., a UI library in node_modules):

@source "../node_modules/@acmecorp/ui-lib";

To exclude paths:

@source not "../src/legacy";

Important Modifier Position

The ! important modifier goes at the end of the class, not the beginning:

<!-- CORRECT v4 -->
<div class="p-4!"></div>

<!-- WRONG v3 -->
<div class="!p-4"></div>

Arbitrary CSS Variable Syntax

Use parentheses, not square brackets, for CSS variable references:

<!-- CORRECT v4 -->
<div class="bg-(--brand-color)"></div>

<!-- WRONG v3 -->
<div class="bg-[--brand-color]"></div>