Cursor rules for Tailwind CSS v4 (CSS-first config, v4 class names)
A free Cursor rule (.mdc) for Tailwind CSS v4: @import "tailwindcss" and @theme instead of tailwind.config.js, the renamed v4 utilities, @utility and @custom-variant, and complete class names so nothing gets purged.
- Install
.cursor/rules/tailwind.mdc- Last tested
- Cursor / Tailwind CSS 4.3 docs · 2026-11-12
Tailwind CSS v4.0 shipped in January 2025, but coding agents still write a lot of v3: @tailwind directives, a new tailwind.config.js, bg-opacity-50, flex-grow, and shadow-sm where the design meant the old small shadow. Most of it still looks plausible, so it slips through review. This rule steers Cursor's agent to v4. It's an Apply to Specific Files rule (globs cover CSS, TSX, JSX, HTML, Vue, Svelte and Astro files, alwaysApply is false), so it attaches whenever styling is in play.
Every item follows Tailwind's own docs, checked on November 12, 2026, when the latest release was v4.3.5: the v3-to-v4 upgrade guide (removed and renamed utilities, currentColor borders and rings, parentheses for CSS variables in arbitrary values, the ! suffix, left-to-right variant stacking, hover only on hover-capable devices), the theme variables page (@theme, @theme inline, :root for variables that shouldn't create utilities), functions and directives (@utility, @custom-variant, @reference, @plugin, and theme() marked deprecated) and the class detection page (Tailwind reads files as plain text, so classes must be written out in full).
Fill in the [bracketed] version, stylesheet path, build integration and build command. If you still load a JavaScript config with @config, keep that line and the rule will leave it alone. Using GitHub Copilot as well? Our free Copilot Tailwind v4 instructions carry the same rules in Copilot's format, and the post on stopping agents from writing Tailwind v3 shows where the rule goes in Claude Code and Codex. The paid Next.js 16 pack adds 12 scoped rules for the rest of the stack.
tailwind.mdc---
description: Tailwind CSS v4 conventions: CSS-first config with @import "tailwindcss" and @theme, renamed v4 utilities, @utility and @custom-variant instead of @layer hacks, complete class names only. Use when writing Tailwind classes or editing the Tailwind stylesheet.
globs: **/*.css, **/*.tsx, **/*.jsx, **/*.html, **/*.vue, **/*.svelte, **/*.astro
alwaysApply: false
---
# Tailwind CSS v4
This project uses Tailwind CSS [4.x]. Main stylesheet: `[src/app/globals.css]`. If something here disagrees with the installed version or tailwindcss.com/docs, the docs win. Don't write Tailwind v3 syntax, and never invent a utility, variant or directive; check the docs or the existing code first.
## Setup (don't regress it)
- Tailwind is loaded with `@import "tailwindcss";` in the main stylesheet. Never add `@tailwind base; @tailwind components; @tailwind utilities;`.
- There is no `tailwind.config.js`. Don't create one. If the project already loads one with `@config`, leave it alone and ask before migrating it.
- Build integration: `[@tailwindcss/postcss | @tailwindcss/vite | @tailwindcss/cli]`. Don't add `postcss-import` or `autoprefixer`; v4 handles imports and vendor prefixes itself.
- Plugins load in CSS: `@plugin "@tailwindcss/typography";`. Don't add Sass, Less or Stylus; v4 isn't designed to work with them.
## Theme and design tokens
- Design tokens live in `@theme { ... }` in the main stylesheet, as CSS variables in the right namespace: `--color-brand-500`, `--font-display`, `--breakpoint-3xl`, `--radius-card`. Each one creates utilities (`bg-brand-500`, `font-display`, `3xl:`).
- Use `:root` only for plain CSS variables that shouldn't create utilities. Use `@theme inline` when a token references another variable (`--font-sans: var(--font-inter);`).
- Reuse existing tokens before adding new ones. Never hard-code a hex value when a token exists.
- In custom CSS, read tokens as variables (`var(--color-brand-500)`, `--spacing(4)`, `--alpha(var(--color-black) / 50%)`). `theme()` is deprecated; don't use it in new code.
## Write v4 class names, not v3 ones
- Opacity: `bg-black/50`, `text-black/50`, `border-black/50`. The `*-opacity-*` utilities are gone.
- Renamed: `shadow-xs` (was `shadow-sm`), `shadow-sm` (was `shadow`), the same shift for `rounded`, `blur`, `backdrop-blur` and `drop-shadow`; `outline-hidden` (was `outline-none`); `ring-3` for the old 3px `ring`; `shrink-*` and `grow-*`; `text-ellipsis`; gradients are `bg-linear-to-r`.
- `border-*`, `divide-*` and `ring` default to `currentColor`: always add a color (`border border-gray-200`).
- CSS variables in arbitrary values use parentheses: `bg-(--brand-color)`, not `bg-[--brand-color]`. Spaces in arbitrary values are underscores: `grid-cols-[max-content_auto]`.
- Important goes at the end: `flex!`. Stacked variants read left to right: `*:first:pt-0`.
- `hover:` only applies on devices that can hover. Never make hover the only way to reach something.
- Prefer `flex` or `grid` with `gap-*` over `space-x-*` and `space-y-*`.
## Custom CSS
- New utilities: `@utility tab-4 { tab-size: 4; }`. Don't define classes inside `@layer utilities` or `@layer components` and expect variants to work on them.
- Custom variants: `@custom-variant theme-midnight (&:where([data-theme="midnight"] *));`. Class-based dark mode: `@custom-variant dark (&:where(.dark, .dark *));`.
- The container utility has no `center` or `padding` options. Customize it with `@utility container { ... }`.
- In CSS modules or Vue, Svelte and Astro `<style>` blocks, add `@reference "[path/to/globals.css]";` before using `@apply` or `@variant`.
- Prefer utilities in markup. Use `@apply` only to style third-party markup you can't put classes on.
## Class detection
- Tailwind scans files as plain text. Always write complete class names: map props to full strings (`{ red: "bg-red-600 hover:bg-red-500" }`), never build them (`` `bg-${color}-600` ``).
- Classes used only in a dependency, or in a git-ignored path: register it with `@source "../node_modules/[package]";`. Safelist with `@source inline("...")`, not a config `safelist`.
## Verify
- Run `[pnpm build]` after styling changes, check the page in the browser, and report what you ran. Don't claim a style works because the class name looks right.
- Upgrading from v3: suggest `npx @tailwindcss/upgrade` (Node.js 20+) on a new branch rather than renaming classes by hand.
12 scoped Cursor rules, AGENTS.md and CLAUDE.md for Next.js 16.4 with Cache Components. This free entry is one file; the pack is the full multi-file set.