All 5 AI packs for $39 →
← All posts
Tailwind CSS · Cursor · Claude Code · GitHub Copilot · Codex · How-to

How to stop AI coding agents writing Tailwind v3 in a v4 project (Cursor, Claude Code, Copilot, Codex)

Published · Facts checked against official vendor pages on November 12, 2026 · Rankings are independent of sponsorships

Tailwind CSS v4.0 came out on January 22, 2025, and the latest release on November 12, 2026 is v4.3.5. Ask a coding agent to style a component in a v4 project, though, and you can still get v3: a fresh tailwind.config.js, @tailwind directives, bg-opacity-50. Some of that fails loudly. The harder part is the v3 class names that are still valid in v4 but now mean something different, so the build passes and the UI is quietly off. Here is what to watch for, taken from Tailwind's own upgrade guide, and where to put a short rule in Cursor, Claude Code, GitHub Copilot and Codex so the agent writes v4 from the start.

Tools in this post

The v3 habits that break a v4 project

These come straight from Tailwind's v3-to-v4 upgrade guide, which we read on November 12, 2026. The first group is the obvious kind, because the old syntax is gone:

  • Setup: v4 loads with @import "tailwindcss", not the three @tailwind directives. The PostCSS plugin moved to @tailwindcss/postcss, the CLI to @tailwindcss/cli, and postcss-import and autoprefixer are no longer needed.
  • Config: a JavaScript config is no longer detected automatically. Theme values live in CSS in an @theme block, and a legacy config only loads if you point at it with @config. The corePlugins, safelist and separator options aren't supported; safelisting uses @source inline().
  • Removed utilities: bg-opacity-*, text-opacity-*, border-opacity-* and the other opacity utilities are gone (use a modifier like bg-black/50), as are flex-grow-*, flex-shrink-* (now grow-* and shrink-*) and overflow-ellipsis (now text-ellipsis).
  • Custom CSS: classes defined in @layer utilities or @layer components no longer behave like utilities with variants. Use @utility. The container utility's center and padding options are gone too.
  • Syntax: CSS variables in arbitrary values use parentheses, bg-(--brand-color) rather than bg-[--brand-color], the important modifier moved to the end (flex!), and stacked variants now apply left to right.

The quiet ones: same class name, different result

The upgrade guide renamed the shadow, radius and blur scales so every step has a name. What was shadow-sm in v3 is shadow-xs in v4, and what was plain shadow is now shadow-sm. The same shift applies to rounded, blur, backdrop-blur and drop-shadow. An agent that writes rounded-sm from v3 habit gets a valid v4 class with a smaller radius than it meant, and nothing errors.

A few defaults changed the same way. ring is now 1px instead of 3px (use ring-3), and outline-none was renamed outline-hidden, while a new outline-none really sets outline-style: none. Borders, dividers and rings default to currentColor instead of gray-200 and blue-500, so a bare border no longer looks like it used to. The hover variant now applies only on devices whose primary input can hover, and space-y-* and divide-y-* use a different selector. None of these show up as build errors, which is why a rule that says "write v4 class names" is worth more than a linter here.

One more trap: class names built from strings

This one isn't new in v4, but agents do it constantly. Tailwind scans your files as plain text and generates CSS only for complete class names it finds. A component that builds bg-${color}-600 from a prop produces a class that never appears in the source, so it gets no CSS. Tailwind's docs say to map each prop value to a full class string instead. If you need classes from a package in node_modules, which Tailwind ignores by default, register it with @source.

Where to put the rule in each agent

Every major agent now has a way to load instructions only for matching files, which suits Tailwind well: the rule shows up when the agent touches CSS or components and stays out of the way for API and database work.

  • Cursor: a project rule in .cursor/rules with the .mdc extension. Cursor's docs say a plain .md file there is ignored. Set globs to your styling files and alwaysApply: false, and the rule auto-attaches when a matching file is in context. Our free Tailwind v4 Cursor rule is set up that way.
  • Claude Code: a path-scoped rule in .claude/rules/ with a paths list in its frontmatter. Anthropic's memory docs say it loads when Claude reads, writes or edits a matching file, which keeps it out of CLAUDE.md, where the docs recommend staying under 200 lines. The body of our Cursor rule works as-is; swap the description and globs lines for paths entries.
  • GitHub Copilot: a NAME.instructions.md file in .github/instructions/ with an applyTo glob. GitHub's docs say that on GitHub.com these files are used by Copilot cloud agent and Copilot code review, and VS Code's docs describe the same applyTo files for agent sessions in the editor. Our free Copilot Tailwind v4 instructions add a short section telling code review to flag v3 syntax in pull requests.
  • Codex: no globs. Codex reads AGENTS.md files from the project root down to your working directory, at most one per directory, and stops adding them once they total 32 KiB by default. Put the Tailwind section in the AGENTS.md nearest your frontend code, for example in your web app's folder in a monorepo, so it doesn't use up the root file's budget. Our AGENTS.md starter is a good place to begin.

If you are still migrating from v3

Don't ask an agent to rename classes by hand across a codebase. Tailwind's guide recommends its upgrade tool, npx @tailwindcss/upgrade, which needs Node.js 20 or later and updates dependencies, moves your config into CSS and rewrites template files. Run it on a new branch, review the diff and check the UI in a browser, as the guide suggests, then add the rule so new code stays on v4. v4 targets Safari 16.4, Chrome 111 and Firefox 128; if you need older browsers, Tailwind says to stay on v3.4, which is still published as the v3-lts release on npm.

Using Next.js? v4.3.4 (November 2, 2026) added @tailwindcss/turbopack, a Turbopack loader for Tailwind in Next.js, while Tailwind's Next.js install guide still uses @tailwindcss/postcss. Either way, the build integration is one of the [bracketed] lines to fill in at the top of the rule.

Rules for the rest of your stack

Tailwind is one file. For a whole Next.js 16 app, the paid Cursor Rules: Next.js 16 pack has 12 scoped rules, and our free library added an Expo and React Native rule and a read-only security-reviewer subagent for Claude Code this week. How long should AGENTS.md, CLAUDE.md and Cursor rules be? covers the size limits in each tool, and which file each agent reads shows how to share one source of truth. Compare the agents themselves on our Cursor, Claude Code, GitHub Copilot and OpenAI Codex pages.

FAQ

Does Tailwind CSS v4 still use tailwind.config.js?
Not by default. In v4 you configure Tailwind in CSS with @import "tailwindcss" and an @theme block. JavaScript config files still work for backward compatibility, but v4 doesn't detect them automatically; you load one explicitly with @config, and the corePlugins, safelist and separator options aren't supported.
Why does shadow-sm look different after upgrading to Tailwind v4?
Tailwind v4 renamed the shadow, radius and blur scales. The v3 shadow-sm is shadow-xs in v4, and the v3 shadow is shadow-sm. The same shift applies to rounded, blur, backdrop-blur and drop-shadow, so v3 class names still compile but render a step smaller.
How do I make Cursor use Tailwind v4 syntax?
Add a project rule in .cursor/rules with the .mdc extension, set globs to your CSS and component files and alwaysApply to false, and list the v4 conventions: @import "tailwindcss", @theme tokens, the renamed utilities and @utility for custom classes. ToolTier's free Tailwind v4 Cursor rule is a ready-made version.
What replaced bg-opacity in Tailwind v4?
Opacity modifiers. Instead of bg-black bg-opacity-50, write bg-black/50. The same applies to text, border, divide, ring and placeholder opacity utilities, which were removed in v4.

Free and paid rules for your agents

Related changelog

Sources

Prices change often. Always confirm on the vendor's site before buying. See the full tier lists and the changelog.

+ Your logo here