Tailwind CSS v4 Migration: Key Changes, Pitfalls, and What the Upgrade Tool Misses

Tailwind CSS v4 is a major rewrite that replaces the JavaScript-based tailwind.config.js with a CSS-first configuration system using @theme blocks and CSS custom properties. The framework now uses Lightning CSS instead of PostCSS, delivering significantly faster build times and eliminating the need for autoprefixer. Features like container queries, 3D transforms, and dynamic spacing are now built-in, removing the dependency on separate plugins. An official upgrade tool automates much of the migration, but developers must manually address changed JS plugin APIs, theme() calls in CSS, and @apply usage in third-party components. Two production projects were successfully migrated in roughly one afternoon each, yielding leaner CSS output and faster builds.