Your AI coding agent set up Tailwind the v3 way, and in v4 your styles silently stop working

You asked your AI coding agent to set up Tailwind in a fresh project. It wrote a globals.css with three @tailwind lines, added a tailwind.config.js with your colors, and everything looks standard. Then the page renders with no styling at all, or your custom colors do nothing, or the build fails on a PostCSS plugin error. The setup matches a thousand tutorials, and that is the problem.

The cause is Tailwind CSS v4 changing how you install and configure it. The agent is writing v3.

Why this happens

Most of what an agent learned about Tailwind is v3. The Tailwind v4 upgrade guide lists the changes that break that setup:

• The directives are gone. In v3 you wrote @tailwind base;, @tailwind components; and @tailwind utilities;. In v4 you use a regular CSS import: @import "tailwindcss";.
• The JavaScript config is no longer detected automatically. The guide says tailwind.config.js files are still supported for backward compatibility, but v4 does not pick them up by itself. That is why your custom colors can silently do nothing.
• The PostCSS plugin moved. In v3 the tailwindcss package was the PostCSS plugin. In v4 it lives in a separate package, @tailwindcss/postcss.
• The CLI moved too. It is now @tailwindcss/cli.

An agent that writes the v3 form into a v4 project gives you a stylesheet that Tailwind never processes.

How to tell if this is your problem

1. Check your version. Open package.json and look at the tailwindcss entry, or run npm ls tailwindcss. If it is 4 or higher, this applies.
2. Open your main CSS file. If it contains @tailwind base; style lines, that is the v3 form.
3. Open postcss.config.js (or .mjs). If tailwindcss is listed as the plugin, that is also the v3 form.
4. Look for a tailwind.config.js that holds your theme. If your CSS never mentions it, v4 is not reading it.

The fix

Replace the three directives in your CSS file with the single import from the upgrade guide:

@import "tailwindcss";

If you use Vite, the guide recommends its dedicated plugin over PostCSS:

import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
});

If you use PostCSS instead, install @tailwindcss/postcss and list that as the plugin in place of tailwindcss. The guide says that in v4 imports and vendor prefixing are handled for you, so you can remove postcss-import and autoprefixer if they are in the project.

If you have a tailwind.config.js

Either load it explicitly from your CSS, using the directive from the guide:

@config "../../tailwind.config.js";

or move your theme values into CSS. The guide’s examples use an @theme block for this:

@theme {
  --font-display: "Satoshi", "sans-serif";
  --color-avocado-100: oklch(0.99 0 0);
}

Be aware that the guide says the corePlugins, safelist and separator options are not supported in v4.0. To safelist utilities, it points to @source inline().

Watch for renamed utilities

If the page loads but things look slightly off, the agent may also be using utility names that changed. The guide lists renames such as shadow-sm to shadow-xs, shadow to shadow-sm, rounded to rounded-sm, ring to ring-3, and outline-none to outline-hidden. It also lists removed utilities: bg-opacity-* is replaced by an opacity modifier like bg-black/50, and flex-shrink-* by shrink-*.

If you need older browsers

The guide says v4.0 is designed for Safari 16.4+, Chrome 111+ and Firefox 128+, and that if you need older browsers you should stay on v3.4. In that case pin the version instead of migrating.

How to avoid this next time

Tell the agent your version before it touches the config: “This project uses Tailwind CSS v4. Use @import "tailwindcss";, the @tailwindcss/vite or @tailwindcss/postcss plugin, and no @tailwind directives.” In review, search the diff for @tailwind and for tailwindcss: inside a PostCSS config, and treat either as a sign the agent fell back to v3.