Home › Tailwind CSS › Tailwind CSS v4 rules
Tailwind CSS v4 rules
Cursor rules for Tailwind CSS v4: CSS-first config with @theme, @utility and @custom-variant, the Vite plugin, and tokens.
CursorTailwind CSS
How to use
Save this as .cursor/rules/tailwind-v4.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.
Note: Review and test before use. Provided as is, without warranty. See Terms.
.cursor/rules/tailwind-v4.mdcDownload ---
description: Tailwind CSS v4 conventions
globs: ["**/*.{css,tsx,jsx,vue,svelte,astro,html}"]
alwaysApply: false
---
# Tailwind CSS v4
- Config is CSS-first. The main stylesheet has `@import "tailwindcss";` and design tokens in `@theme { --color-brand-500: oklch(...); --font-display: ...; }`. Don't create `tailwind.config.js` unless the project already loads one via `@config`.
- Build integration: `@tailwindcss/vite` for Vite apps, `@tailwindcss/postcss` otherwise. No `tailwindcss` PostCSS plugin from v3, and no `autoprefixer` (built in).
- Content is detected automatically; add `@source "../packages/ui";` for paths outside the project root.
- Custom utilities with `@utility name { ... }`, custom variants with `@custom-variant dark (&:where(.dark, .dark *));`. Don't use `@layer utilities` hacks for these.
- Use theme variables in CSS as `var(--color-brand-500)`; in classes as `bg-brand-500`.
- v4 renames: `shadow-xs`/`shadow-sm` (old `shadow-sm`/`shadow`), `rounded-xs`, `outline-hidden` (old `outline-none`), `ring-3` for the old default ring. Default border color is `currentColor`, so set a border color explicitly.
- Arbitrary values sparingly; repeated ones become tokens.
- Keep class lists readable: extract components (React/Vue/Svelte) instead of `@apply` everywhere. Sort with `prettier-plugin-tailwindcss` if installed.
- Dark mode and states via variants (`dark:`, `hover:`, `focus-visible:`, `aria-expanded:`, `data-[state=open]:`).
## Done when
The build succeeds and the changed UI is checked at mobile and desktop widths, in light and dark mode.