Tailwind CSS v4 CSS-First Configuration & Modern Theme Directives

Tailwind CSS v4 fully deprecates JavaScript configuration files (tailwind.config.js/ts) in favor of the CSS-first @theme directive and native CSS custom properties. Frontend codebases must declare theme variables, custom fonts, container breakpoints, and color palettes using standard @theme blocks and CSS color-mix() functional notation. Mixing legacy JS configuration patterns or obsolete opacity-suffix workarounds breaks CSS compilation and tree-shaking invariants in Oxide-based pipelines.

--- description: Tailwind CSS v4 CSS-First Configuration & Modern Theme Directives - Tailwind CSS v4 fully deprecates JavaScript configuration files (tailwind.config.js/ts) in favor of the CSS-first @theme directive and native CSS custom properties. Frontend codebases must declare theme variables, custom fonts, container breakpoints, and color palettes using standard @theme blocks and CSS color-mix() functional notation. Mixing legacy JS configuration patterns or obsolete opacity-suffix workarounds breaks CSS compilation and tree-shaking invariants in Oxide-based pipelines. globs: src/**/*.{css,pcss,postcss,ts,tsx,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tailwind-v4-css-first-theme-guardrail" --- # Tailwind CSS v4 CSS-First Configuration & Modern Theme Directives > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Retaining tailwind.config.js and Using Legacy CSS-in-JS Utility Hacks in Tailwind v4 ## System Constraints You are a Principal Frontend Architect enforcing Tailwind CSS v4 CSS-First Theme Directives. Strictly reject tailwind.config.js/ts, purge obsolete PostCSS plugin configurations, mandate CSS @theme directives with proper CSS variable mappings, enforce native color-mix() over custom opacity hacks, and maintain type-safe design token consumption in application templates. ## Strict Guidelines - Engineers MUST NOT create or maintain 'tailwind.config.js', 'tailwind.config.ts', or 'tailwind.config.cjs' files; all configuration MUST reside in the primary CSS entrypoint via '@theme' blocks. - Engineers MUST replace legacy utility imports ('@tailwind base; @tailwind components; @tailwind utilities;') with the single unified '@import "tailwindcss";' directive. - Engineers MUST define custom design tokens inside '@theme' using canonical token naming prefixes (e.g., '--color-*', '--font-*', '--breakpoint-*', '--spacing-*'). - Engineers MUST use modern CSS 'color-mix()' or standard slash opacity syntax ('bg-brand/50') resolving to CSS custom properties rather than RGB channel tuple variables (e.g., '--primary: 255 0 0'). - Components MUST NOT use arbitrary value brackets for design tokens that exist within the CSS '@theme' scope (use 'bg-brand' instead of 'bg-[var(--brand)]'). - Engineers MUST use '@theme inline' when overriding or dynamically extending variable maps that depend on external runtime CSS properties without generating duplicate static utility sets. - Custom plugins MUST be authored using standard CSS features via '@utility' directives rather than legacy JavaScript 'plugin()' helper functions. ## Bad vs Good Implementations ### Migration from Legacy tailwind.config.js to Tailwind v4 @theme Directives #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Tailwind v4 deprecates '@tailwind' directives and JavaScript config files. Breaking colors into RGB component tuples to work around legacy opacity injection undermines CSS color-mix() and modern color-space handling (Oklch, Display-P3). ```css /* Legacy Tailwind v3 setup with obsolete imports and reliance on JS config */ @tailwind base; @tailwind components; @tailwind utilities; :root { /* Bad: Anti-pattern channel tuples for legacy opacity workarounds */ --color-primary-rgb: 99, 102, 241; --color-surface-rgb: 15, 23, 42; } .custom-card { background-color: rgba(var(--color-surface-rgb), 0.8); } ``` #### Production Standard (Correct) > **Standard**: Adheres to Tailwind v4 CSS-first paradigm by importing 'tailwindcss', defining design tokens inside '@theme' with high-gamut Oklch color definitions, and declaring custom component behaviors via '@utility' directives. ```css /* Tailwind v4 CSS-First Entrypoint (e.g., src/index.css) */ @import "tailwindcss"; @theme { --color-brand-primary: oklch(0.62 0.24 264.4); --color-brand-accent: oklch(0.85 0.16 84.4); --color-surface-elevated: oklch(0.21 0.03 264.4); --font-display: 'Inter Variable', -apple-system, sans-serif; --breakpoint-3xl: 120rem; } @utility custom-card { background-color: color-mix(in oklch, var(--color-surface-elevated) 80%, transparent); border: 1px solid color-mix(in oklch, var(--color-brand-primary) 20%, transparent); } ``` ### Consuming Design Tokens and Dynamic Opacity in React Components #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Arbitrary variable brackets bypass compile-time token validation and prevent the Tailwind v4 compiler from applying native color modifier transformations and optimized utility mapping. ```tsx import React from 'react'; // Bad: Bypassing Tailwind v4 theme engine with raw arbitrary CSS variables export const BannerBadge = ({ label }: { label: string }) => { return ( <span className="bg-[var(--color-brand-primary)] text-[color:var(--color-surface-elevated)] p-[12px] opacity-[0.9]"> {label} </span> ); }; ``` #### Production Standard (Correct) > **Standard**: Standard classes ('bg-brand-primary/90', 'text-surface-elevated') tap directly into the '@theme' tokens defined in CSS. The v4 compiler automatically synthesizes modern color-mix operations for the '/90' opacity modifier. ```tsx import React from 'react'; // Good: Consuming CSS-first defined tokens with standard utility classes and opacity modifiers export const BannerBadge = ({ label }: { label: string }) => { return ( <span className="bg-brand-primary/90 text-surface-elevated p-3 font-display rounded-md shadow-sm"> {label} </span> ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tailwind CSS v4 CSS-First Configuration & Modern Theme Directives

Tailwind CSS v4 CSS-First Configuration & Modern Theme Directives defines an industrial-grade behavioral standard for frontend engineering. Tailwind CSS v4 fully deprecates JavaScript configuration files (tailwind.config.js/ts) in favor of the CSS-first @theme directive and native CSS custom properties. Frontend codebases must declare theme variables, custom fonts, container breakpoints, and color palettes using standard @theme blocks and CSS color-mix() functional notation. Mixing legacy JS configuration patterns or obsolete opacity-suffix workarounds breaks CSS compilation and tree-shaking invariants in Oxide-based pipelines. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Retaining tailwind.config.js and Using Legacy CSS-in-JS Utility Hacks in Tailwind v4 Without an explicit system instruction file, developers spend hours debugging silent failures.

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
AI Hallucination & Deprecation Drift	Retaining tailwind.config.js and Using Legacy CSS-in-JS Utility Hacks in Tailwind v4	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

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:

Engineers MUST NOT create or maintain 'tailwind.config.js', 'tailwind.config.ts', or 'tailwind.config.cjs' files

Engineers MUST NOT create or maintain 'tailwind.config.js', 'tailwind.config.ts', or 'tailwind.config.cjs' files; all configuration MUST reside in the primary CSS entrypoint via '@theme' blocks.

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.