Tailwind CSS v4 AI Agent Rules & Cursorrules
Guide AI agents to write modern Tailwind CSS v4 without obsolete v3 configs.
Prevent AI agents from generating deprecated Tailwind v3 config files. Enforce Tailwind CSS v4 CSS-first configuration (`@theme`), OKLCH colors, and container queries.
Configuration Workbench
Select your agent format below to preview, copy, or download the configuration file.
# Tailwind CSS v4 Cursor Rules
You are a Principal Frontend Stylist specializing in Tailwind CSS v4.
## v4 Architecture
- Do NOT generate or edit 'tailwind.config.js'. Tailwind v4 uses CSS-first configuration.
- Custom tokens belong in your CSS stylesheet inside '@theme' blocks.
- Use native CSS variables and modern color spaces (oklch).
## Class Organization
- Mobile-first: Default utility classes apply to mobile; prefix with 'md:' and 'lg:' for larger viewports.
- Maintain consistent utility ordering:
1. Display & Positioning (flex, grid, absolute, relative)
2. Sizing & Spacing (w-, h-, p-, m-)
3. Typography (text-, font-, leading-)
4. Colors & Backgrounds (bg-, text-)
5. Borders & Effects (rounded-, border-, shadow-)
6. States & Transitions (hover:, focus:, transition-, duration-)Pro-tip: Place this file directly in the root directory of your Tailwind CSS v4 & Modern UI project. AI agents like Cursor Composer, Claude Code, and GitHub Copilot will read it automatically on initialization.
Architectural Principles Enforced
When this configuration file is loaded into Cursor or Claude Code, the agent strictly enforces the following design invariants:
Do NOT create `tailwind.config.js`; configure design tokens directly in CSS using `@theme` blocks.
Use modern OKLCH color spaces for perceptual uniformity and vibrant dark modes.
Enforce mobile-first responsive design: base styles first, followed by `sm:`, `md:`, `lg:`, `xl:`.
Use Flexbox and CSS Grid semantics instead of obsolete floating layouts.
Use standard class sorting (layout -> sizing -> typography -> background -> border -> interactive).
Installation & Repository Setup
Place in project root as `.cursorrules` or `.cursor/rules/tailwind.mdc`.
Verified Agent Behavior Examples
Observe how the AI agent responds when prompted under these active rules.
Frequently Asked Questions
Why does my AI agent keep creating tailwind.config.js?
LLMs were trained on years of Tailwind v2 and v3 codebases where `tailwind.config.js` was required. Adding these rules explicitly instructs the agent that Tailwind v4 uses pure CSS configuration.