Tailwind CSS Cursor Rules Template

The first rule — utilities in markup, no separate CSS files, no @apply — is the load-bearing one. Tailwind's core trade is that styles live next to the elements they affect, so deleting markup deletes its styles and the compiler can prune everything unused. Every escape hatch Cursor takes breaks that trade: an inline style silently wins every specificity fight against utilities and ignores your theme, a hand-written class in a CSS file survives after its markup is gone, and an @apply block is a CSS class wearing a utility costume — it recreates the naming, indirection, and dead-code problems Tailwind exists to remove.

A human developer takes these escape hatches occasionally and remembers where. Cursor takes them constantly and remembers nothing — each generation is a fresh decision, so without a rule the codebase drifts toward a random mix of the two systems. Stating the boundary once in a rules file means every generated component lands on the same side of it. The rule still leaves room for genuinely global CSS (resets, font-face, keyframes) via @layer, which the performance section covers.

AI-generated Tailwind produces long class strings, and the reflex — Cursor's included — is to "clean them up" into an @apply abstraction the third time they appear. The rules point that reflex somewhere better: repetition gets extracted into a component, and variation within a component gets modeled with class-variance-authority. A CVA definition gives a button its base classes plus named intent and size variants in one typed structure, which is exactly the shape Cursor reproduces reliably — ask it for a destructive variant and it extends the variant map instead of forking a near-duplicate class string somewhere else in the tree.

The corollary is that duplication below that threshold is fine. Two cards sharing "rounded-lg border p-4" do not need an abstraction, and the rules explicitly prefer repeating utilities over inventing one. Premature extraction is worse with an AI in the loop than without, because Cursor will dutifully thread props through whatever abstraction exists rather than questioning it. For conditional styling, the clsx/cn() rule matters for a subtle reason: cn() resolves conflicts when classes merge (the later px-6 actually beats the earlier px-4), whereas naive string concatenation ships both and leaves the winner to stylesheet order.

Tailwind does not parse your code — it scans files for strings that look like class names and generates CSS only for what it finds. That makes one habit fatal: dynamically built class names. When Cursor writes `text-${color}-500`, no complete class name ever appears in the source, the compiler generates nothing, and the element renders unstyled — with no error at build time or runtime. It is the most common Tailwind bug in AI-generated code because template literals are exactly how a model "helpfully" generalizes repeated code.

The rules attack this from three sides: never construct class names dynamically (map props to complete strings instead — a lookup object or a CVA variant both work), keep content paths in your config accurate so the scanner sees every file that holds classes, and treat safelist as a last resort for names that truly arrive at runtime, such as from a CMS. If Cursor reaches for safelist during ordinary component work, that is the signal it is routing around the real rule.

The theming rules exist because Cursor, asked for "a slightly darker blue", will happily write bg-[#1e40af] — a one-off arbitrary value that no design-token change will ever reach. The rules push every recurring color, spacing step, and font into the theme as named tokens on a numeric scale (primary-50 through primary-950), extending Tailwind's defaults rather than overriding them so the standard utilities keep working. Once tokens exist, Cursor uses them: it completes bg-primary-600 like any built-in utility. Arbitrary values stay legal for genuine one-offs, which is the right ratio.

Where those tokens live depends on your Tailwind version. In v3 they go in the extend section of tailwind.config.ts; Tailwind 4 moved to CSS-first configuration, where tokens are declared as CSS variables in an @theme block in your stylesheet. The principle the rules encode — one named source of truth, extended not replaced, with CSS custom properties for values that change at runtime — is identical in both, so tell Cursor which version you run and it will write to the right file.

The same discipline applies to variant prefixes. The rules fix a single direction — base styles are mobile, sm:/md:/lg: only add up — because the one thing worse than either convention is Cursor alternating between mobile-first and desktop-first across components, which it will do if half your existing code leans each way. Dark mode follows suit: every dark: override sits beside the utility it modifies, in the same class list, rather than in a stylesheet Cursor cannot see when it edits the markup.