Tailwind CSS v4 Modern Theme & Pure CSS Standard

--- description: Tailwind CSS v4 Modern Theme & Pure CSS Standard - Guardrails for Tailwind CSS v4: use @import 'tailwindcss', @theme directive in CSS, native cascade layers, and pure CSS variables instead of tailwind.config.js. globs: **/*.css, src/**/*.{tsx,html} alwaysApply: false author: "Adam Wathan & Tailwind Community (@adamwathan)" contributor_url: "https://github.com/adamwathan" verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tailwind-v4" --- # Tailwind CSS v4 Modern Theme & Pure CSS Standard > **Severity**: HIGH | **Category**: frontend > **Anti-Pattern Warning**: AI attempts to generate a legacy tailwind.config.js, uses deprecated @apply syntax, or confuses v3 arbitrary values. ## System Constraints You are a modern frontend styling expert for Tailwind CSS v4. Do NOT generate tailwind.config.js or tailwind.config.ts. In Tailwind v4, configuration belongs directly in CSS using the @theme directive. Never generate deprecated utility classes. ## Strict Guidelines - In Tailwind v4, use @import 'tailwindcss'; as the single entrypoint in CSS. - Configure custom colors, fonts, and breakpoints directly inside the @theme block in CSS, not in a JS config file. - Avoid over-relying on @apply; favor semantic utility classes in markup or native CSS variables. - Ensure color palette values map to semantic CSS custom properties for effortless dark mode switching. ## Bad vs Good Implementations ### Tailwind v4 CSS-First Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Tailwind v4 replaces @tailwind directives with a single @import 'tailwindcss' and moves config into @theme blocks. ```css /* DEPRECATED: Tailwind v3 Directives */ @tailwind base; @tailwind components; @tailwind utilities; /* And hallucinating a separate tailwind.config.js file with module.exports */ ``` #### Production Standard (Correct) > **Standard**: Uses modern Tailwind CSS v4 syntax with pure CSS variables and the native @theme declaration. ```css /* Modern Tailwind CSS v4 */ @import "tailwindcss"; @theme { --color-brand-primary: #0284c7; --color-brand-surface: #f8fafc; --font-display: "Inter", system-ui, sans-serif; --radius-card: 0.5rem; } :root { --background: var(--color-brand-surface); --foreground: #0f172a; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tailwind CSS v4 Modern Theme & Pure CSS Standard

Tailwind CSS v4 is a ground-up rebuild centered around native CSS cascading variables, CSS lightning engine compilation, and zero-configuration setups. The traditional `tailwind.config.js` or `tailwind.config.ts` configuration file is obsolete; all design tokens, theme scales, and custom plugins are defined directly in CSS via `@theme` directives and modern `@import "tailwindcss";`.

Framework Paradigm Shift & Drift MechanicsLLMs have memorized the v2 and v3 configuration schema (`module.exports = { theme: { extend: {} } }`). When asked to customize colors or fonts in a Tailwind v4 project, AI models frequently generate a duplicate `tailwind.config.js` file that is ignored by v4 Vite and PostCSS plugins, leaving developers confused as to why styles are not applying.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
Ghost tailwind.config.js Generation	AI outputs a JavaScript configuration file instead of CSS @theme directives	High	Configurations are ignored by Tailwind v4's modern CSS compiler, breaking custom design systems. Declare custom design tokens directly in `src/app/globals.css` using the `@theme { ... }` block.
Deprecated PostCSS / @apply Syntax	AI writes `@tailwind base; @tailwind components; @tailwind utilities;`	Medium	Fails compilation in Tailwind v4 and creates build errors with modern bundlers like Turbopack. Replace legacy triple-directive with single `@import "tailwindcss";` at stylesheet root.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

In Tailwind v4, use @import 'tailwindcss'

In Tailwind v4, use @import 'tailwindcss'; as the single entrypoint in CSS.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Configure custom colors, fonts, and breakpoints directly inside the @theme block in CSS, not in a JS config file.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Avoid over-relying on @apply

Avoid over-relying on @apply; favor semantic utility classes in markup or native CSS variables.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Ensure color palette values map to semantic CSS custom properties for effortless dark mode switching.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Where do I configure custom colors in Tailwind CSS v4?

In Tailwind v4, configure tokens directly inside your primary CSS file using `@theme`: `@theme { --color-brand-primary: #0284c7; }`. This automatically generates `bg-brand-primary` and `text-brand-primary` utilities.

Q:Why does Tailwind v4 not use tailwind.config.js?

Tailwind v4 is powered by Oxide, a high-performance Rust engine that parses CSS natively. Removing the JavaScript configuration file allows instant hot-reloading and seamless interoperability with CSS custom properties.