Tailwind CSS v4 CSS-First Architecture & @theme Directive Enforcement

--- description: Tailwind CSS v4 CSS-First Architecture & @theme Directive Enforcement - Tailwind CSS v4 replaces JavaScript-based configuration (tailwind.config.js) with native CSS-first configuration via @theme blocks and CSS variables. Developers must configure tokens directly in stylesheets using standard CSS semantics and modern color functions (e.g., oklch, color-mix) rather than deprecated JavaScript configuration objects or legacy opacity hacks. globs: **/*.css, src/**/*.{ts,tsx,jsx,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tailwind-v4-css-first-theme-directives-standard" --- # Tailwind CSS v4 CSS-First Architecture & @theme Directive Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Configuring Tailwind tokens in tailwind.config.js or using legacy v3 alpha-value CSS variable interpolation hacks ## System Constraints You are a Principal Software Architect enforcing Tailwind CSS v4 CSS-first design systems. You must prevent the introduction of legacy tailwind.config.js files, obsolete @tailwind directives, and v3 variable-opacity hacks. You mandate pure @theme declarations, native CSS custom property token definitions, and modern color spaces like OKLCH. ## Strict Guidelines - Engineers MUST NOT create or maintain 'tailwind.config.js' or 'tailwind.config.ts' in Tailwind v4 codebases. - Engineers MUST replace legacy directives (@tailwind base; @tailwind components; @tailwind utilities;) with '@import "tailwindcss";'. - Engineers MUST declare custom design tokens (colors, fonts, breakpoints, shadows) inside a '@theme' or '@theme inline' CSS block using native '--*' property syntax. - Engineers MUST NOT format color tokens as raw space-separated RGB/HSL channels to facilitate opacity hacks; use fully formed color functions (such as oklch(), hsl(), or hex) where Tailwind v4's native color-mix handles alpha variants automatically. - Engineers MUST reference theme tokens via utility classes (e.g., 'bg-brand') or 'var(--brand)' in custom styles rather than attempting to import JS theme objects. - Components NEVER specify arbitrary values like 'bg-[rgb(var(--color-primary)/<alpha-value>)]'; use the idiomatic token utility with native slash syntax (e.g., 'bg-primary/50'). ## Bad vs Good Implementations ### Configuring Design Tokens in Tailwind v4 vs Legacy v3 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Tailwind v4 deprecates @tailwind directive stacks and the manual RGB-triplet alpha-hack. It no longer reads theme definitions from tailwind.config.js. ```css /* ❌ BAD: Legacy Tailwind v3 directives and RGB channel splitting for opacity support */ @tailwind base; @tailwind components; @tailwind utilities; :root { --color-primary-raw: 37 99 235; } /* Requires tailwind.config.js with complex rgba() callbacks */ ``` #### Production Standard (Correct) > **Standard**: Tailwind v4 automatically synthesizes utilities like 'bg-brand-primary' and 'text-brand-accent' from the @theme directive and derives opacity modifiers via CSS color-mix without manual channel plumbing. ```css /* ✅ GOOD: Idiomatic Tailwind v4 CSS-first token configuration */ @import "tailwindcss"; @theme { --color-brand-primary: oklch(0.55 0.22 260); --color-brand-accent: oklch(0.75 0.18 150); --font-display: 'Inter Variable', sans-serif; --breakpoint-3xl: 120rem; } /* Automatic color-mix alpha modifier: bg-brand-primary/50 just works */ ``` ### Consuming Dynamic Theming in React/TypeScript Components #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: resolveConfig and JS-based configuration files are incompatible with Tailwind v4's CSS engine. Arbitrary opacity bracket syntax bypasses v4's native color resolution. ```typescript // ❌ BAD: Attempting to resolve tokens from tailwind.config.js or manual string interpolation import resolveConfig from 'tailwindcss/resolveConfig'; import tailwindConfig from '../../tailwind.config.js'; // Broken in v4 export const Banner = () => { return ( <div className="bg-[rgb(var(--color-primary-raw)/0.8)] text-white p-4"> Legacy Dynamic Styling </div> ); }; ``` #### Production Standard (Correct) > **Standard**: The component utilizes native slash syntax for alpha modification ('bg-brand-primary/60') and the declared font family utility ('font-display'), fully compiled by the v4 CSS engine. ```typescript // ✅ GOOD: Standard class consumption utilizing v4 @theme variable generation import React from 'react'; interface BannerProps { title: string; isMuted?: boolean; } export const Banner: React.FC<BannerProps> = ({ title, isMuted = false }) => { return ( <div className={`p-4 rounded-xl text-white ${ isMuted ? 'bg-brand-primary/60' : 'bg-brand-primary' }`} > <h2 className="font-display text-lg font-semibold">{title}</h2> </div> ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tailwind CSS v4 CSS-First Architecture & @theme Directive Enforcement

Tailwind CSS v4 CSS-First Architecture & @theme Directive Enforcement defines an industrial-grade behavioral standard for frontend engineering. Tailwind CSS v4 replaces JavaScript-based configuration (tailwind.config.js) with native CSS-first configuration via @theme blocks and CSS variables. Developers must configure tokens directly in stylesheets using standard CSS semantics and modern color functions (e.g., oklch, color-mix) rather than deprecated JavaScript configuration objects or legacy opacity hacks. 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: Configuring Tailwind tokens in tailwind.config.js or using legacy v3 alpha-value CSS variable interpolation hacks 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	Configuring Tailwind tokens in tailwind.config.js or using legacy v3 alpha-value CSS variable interpolation hacks	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' or 'tailwind.config.ts' in Tailwind v4 codebases.

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.