Tailwind CSS v4 Modern Pure CSS Engine & Directive Invariants

Deprecates legacy @tailwind base/components/utilities directives and tailwind.config.js in favor of single @import 'tailwindcss' and native @theme CSS variables.

Authors:Adam Wathan, AgentRules Frontend Working Group

Version:v1.0.0

Last Ratified:2026-03-20

Linked Rule:tailwind-v4

RFC-2119 Invariant Mandates

The keywords “MUST”, “MUST NOT”, and “SHOULD” in this document are to be interpreted as described in BCP 14 / RFC 2119.

MUST NOTClause 1

CSS entrypoints in Tailwind CSS v4 projects MUST NOT contain legacy @tailwind base, @tailwind components, or @tailwind utilities directives.

Engineering Rationale:Tailwind CSS v4 features the Oxide Rust engine which replaces directive expansion with standard CSS imports.

Failure Blast Radius:Build fails with: 'Unknown at-rule @tailwind encountered during CSS compilation'.

MUSTClause 2

All Tailwind v4 projects MUST import stylesheet via '@import "tailwindcss";' at the root of their primary CSS file.

Engineering Rationale:This single import loads the modern zero-runtime CSS utility suite.

Failure Blast Radius:Missing styles and complete CSS asset omission.

SHOULDClause 3

Custom theme tokens and design system variables SHOULD be declared inside '@theme' blocks rather than legacy tailwind.config.js files.

Engineering Rationale:Tailwind v4 is 100% CSS-first, eliminating JavaScript config overhead during bundler cycles.

Failure Blast Radius:Slow build times and missed theme token inheritance.

Complete RFC Specification Document

IETF Formal Markdown Format

# RFC-007: Tailwind CSS v4 Modern Pure CSS Engine

## 1. Abstract
Tailwind CSS v4 replaces legacy directives with standard CSS imports.

## 2. Invariant Specifications (RFC-2119)
```css
/* COMPLIANT (RFC-007): */
@import "tailwindcss";

@theme {
  --color-brand-primary: #0284c7;
}
```

Community Consensus Rating

Do these behavioral constraints represent the highest engineering standard for your team?

98% Consensus