Skip to main content
Tailwind CSS v4 & Modern UIfrontendTarget: Tailwind CSS v4.x

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.

#tailwind cursorrules#tailwind css v4 cursor rules#tailwind claude md#tailwind css agent rules#cursor rules for tailwind

Configuration Workbench

Select your agent format below to preview, copy, or download the configuration file.

Cursor configuration for Tailwind CSS v4.
18 lines•0.8 KB
# 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`.

1Save `.cursorrules` to the root of your project.
2Ensure your CSS entry point imports `@import 'tailwindcss';`.

Verified Agent Behavior Examples

Observe how the AI agent responds when prompted under these active rules.

Scenario: Designing a responsive card grid
User prompt: “Create a 3-column responsive pricing card grid with dark mode.”
Agent Behavior: The agent generates a clean CSS Grid layout (`grid grid-cols-1 md:grid-cols-3 gap-6`) with dark mode classes and accessible focus states.

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.