Tailwind CSS v4 Windsurf Cascade Rules

Production-grade architectural rulebook for Tailwind CSS v4. Engineered to eliminate LLM hallucinations, enforce strict deterministic conventions, and prevent architectural drift across Cursor IDE, Claude Code CLI, and autonomous multi-agent pipelines.

Target Path

.windsurf/rules/tailwind-v4.md

Execution Scope

Project Context

Specification Format

Markdown / Config

AI Tool Support

Universal AI Assistants

02 / DRIFT ANALYSIS & VALUE PROPOSITION

Failure Patterns Prevented for Tailwind CSS v4

Without This Rule (Default LLM Behavior)Vulnerable

Tailwind CSS v4 is an entirely new CSS-first engine that completely replaces javascript-based `tailwind.config.js` with native `@theme` directives in CSS. Outdated LLMs continually hallucinate obsolete tailwind.config.js configurations.

Hallucination Symptoms

Invokes deprecated or removed APIs from older model training weights
Generates conflicting configuration files and invalid imports
Silently drops type-safety, boundaries, or transaction isolation

With This Rule (Guaranteed Invariants)Deterministic

Configure themes directly in globals.css using `@theme` and `@import 'tailwindcss';`.

Never generate or modify legacy `tailwind.config.js` or `tailwind.config.ts` files.

Use CSS custom properties for dynamic color palettes.

Enforce consistent utility ordering: layout -> spacing -> typography -> background -> borders -> interactivity.

03 / VERIFIED CODE PATTERNS

Code Standards: Anti-Pattern vs Verified Implementation

Discouraged Anti-Pattern

// Discouraged in v4: Obsolete tailwind.config.js
module.exports = {
  theme: {
    extend: { colors: { brand: "#f97316" } }
  }
};

Verified Production Standard

@import "tailwindcss";

@theme {
  --color-brand-primary: #f97316;
  --font-display: "Geist Sans", sans-serif;
}

04 / REPOSITORY PLACEMENT & 3-STEP TERMINAL INSTALLATION

How to Install Tailwind CSS v4 Windsurf Cascade Rules via Terminal

Step 1: Open Project Directory & Verify Target Placement

Open your terminal and navigate to your project root folder where the .windsurf/rules/tailwind-v4.md file will reside. Ensure the file is placed at the exact path below relative to your project root so the AI engine automatically loads it:

.windsurf/rules/tailwind-v4.md

Step 2: Fetch Rule File via Terminal Command

Run curl, PowerShell, or wget to stream the rule directly from the DevScratchpad raw API endpoint and write it to .windsurf/rules/tailwind-v4.md:

Terminal One-Liner Install

Run directly in your project root to stream and write this rule file with one command.

Raw API Stream

mkdir -p ".windsurf/rules" && curl -fsSL "https://www.devscratchpad.tech/api/raw/windsurf-rules/tailwind-v4" -o ".windsurf/rules/tailwind-v4.md"

Step 3: Verify and Activate with AI Agent

Launch your AI coding assistant (Universal AI Assistants). The assistant will automatically discover .windsurf/rules/tailwind-v4.md in your repository and apply the architectural guardrails, type constraints, and verification protocols during code generation.

05 / ROUTE DIRECTORY & CROSS-TOOLING

Alternative AI Formats for Tailwind CSS v4Cross-Tooling

/ai-skill-studio/cursor-rules/nextjs-15Next.js 15 Cursor Rules

→

/ai-skill-studio/cursor-rules/react-19React 19 Cursor Rules

→

Related Windsurf Cascade Rules PresetsSame Directory

Frontend

Next.js 15 App Router

→

Frontend

React 19 & Vite