What breaks when upgrading from Tailwind 3 to 4 (renamed utilities, shadow-sm, outline-none, border color)?

Run the official upgrade tool first

npx @tailwindcss/upgrade

It needs Node 20+, edits your CSS, config and templates, and works best on a clean git branch. Review the diff.

Key behavior changes

• Imports: @tailwind base; @tailwind components; @tailwind utilities; becomes @import "tailwindcss";.
• Config: tailwind.config.js is no longer auto-loaded; migrate to @theme or load with @config "./tailwind.config.js";.
• Renamed utilities (scale shift): shadow-sm -> shadow-xs, shadow -> shadow-sm, rounded-sm -> rounded-xs, rounded -> rounded-sm, blur-sm -> blur-xs, blur -> blur-sm, ring (3px) -> ring-3, outline-none -> outline-hidden.
• Removed opacity utilities: bg-opacity-50, text-opacity-* etc. Use the slash syntax: bg-black/50.
• Default border and divide color: was gray-200, now currentColor. Add explicit colors (border-gray-200) or restore in CSS:

@layer base {
  *, ::after, ::before, ::backdrop, ::file-selector-button {
    border-color: var(--color-gray-200, currentColor);
  }
}

• Default ring: was 3px blue-500, now 1px currentColor.
• Variant stacking order is now left to right: first:*:pt-0 instead of *:first:pt-0.
• Important modifier: write it at the end bg-red-500! (the leading ! form still works but is deprecated).
• CSS variable syntax: bg-[--brand] becomes bg-(--brand).
• hover: applies only on devices that support hover (@media (hover: hover)), so touch devices no longer get sticky hover states.
• Buttons use cursor: default like the browser (add back cursor-pointer in base CSS if you want).
• Preprocessors: Sass, Less and Stylus are not supported with v4.

Browser support

Safari 16.4+, Chrome 111+, Firefox 128+. Older targets should stay on v3.4.

Plugins

@plugin "@tailwindcss/typography"; replaces the plugins array. Check each plugin has a v4 compatible release.

Convert old CSS snippets with the CSS to Tailwind converter if you are rewriting components.