Description

After upgrading from Tailwind CSS v3 to v4 using npx @tailwindcss/upgrade@latest, gradient buttons stopped working. The buttons rendered with a plain background instead of the gradient.

Root Cause

The codemod replaces the old @tailwind base/components/utilities directives with a single @import 'tailwindcss'. This single import causes the preflight rule:

button { background-image: none }

to land as unlayered CSS — meaning it sits outside any @layer and therefore has higher precedence than Tailwind's layered bg-linear-to-* utilities. The gradient gets silently overridden.

Steps to Reproduce

1. Start with a working v3 project that uses gradient classes on <button> elements (e.g. bg-linear-to-r from-green-500 to-green-700 — formerly bg-gradient-to-r).
2. Run npx @tailwindcss/upgrade@latest.
3. The codemod produces this in your CSS file:

   @import 'tailwindcss';

4. Open the app — gradient buttons now render as plain/unstyled.

Fix

Replace the single @import 'tailwindcss' with split imports that give you explicit layer control, and wrap all your own global styles in @layer base:

/* Instead of: @import 'tailwindcss'; */

@layer theme, base, utilities;
@import 'tailwindcss/theme' layer(theme);
@import 'tailwindcss/preflight' layer(base);
@import 'tailwindcss/utilities';

@theme {
  /* your custom tokens */
}

@layer base {
  /* your own global styles — must be layered so Tailwind utilities win */
  * {
    box-sizing: border-box;
  }
}

This ensures button { background-image: none } from preflight stays inside @layer base, and your bg-linear-to-* utilities in @layer utilities correctly take precedence.

Related side effect: space-x-* utilities stop working

If you have a global reset like * { margin: 0; padding: 0 } in your CSS outside any layer, it will silently break space-x-* and similar utilities. Tailwind v4 uses :where() selectors (specificity 0) for those utilities, so any unlayered * rule wins. The @layer base wrapper fixes this too.

Environment

• Tailwind CSS: v4.2.4 (upgraded from v3.4.18)
• Next.js: 16.2.4 (Pages Router)
• @tailwindcss/postcss: 4.2.4
• Node: 22.x / macOS

Suggestion

It would be great if the upgrade codemod could emit the split import form by default, or at least add a comment warning about the unlayered preflight behavior when gradient utilities or space-x-* are detected in the project.