Migrate from Tailwind CSS v3 to v4

[dougaitken]

Summary

Tailwind CSS v4 is a ground-up rewrite of the framework, released January 2025. It replaces the JavaScript-based configuration system with a CSS-first approach, uses a new high-performance engine built on Lightning CSS, and leverages modern CSS features (@property, color-mix()).

v3 will eventually stop receiving updates, so we need to migrate at some point. This issue tracks the effort.

Why This Isn't a Quick Upgrade

Our project uses Tailwind in an unconventional way — as a design token processor under the CUBE CSS methodology, not as a traditional utility-class framework. This makes several of the breaking changes particularly impactful for us.

Project-Specific Challenges

1. Design token pipeline — tailwind.config.js imports JSON token files and processes them through tokensToTailwind() and clampGenerator(). These would need to be converted to CSS @theme variables or the JS config retained via @config
2. Custom plugins — Two inline plugins emit CSS custom properties (:root vars) and custom utility classes (flow-space-*, region-space-*, gutter-*). These need rewriting as @utility directives or kept via @plugin
3. corePlugins disabled — We disable preflight, textOpacity, backgroundOpacity, and borderOpacity. The corePlugins option is removed in v4 with no direct equivalent
4. PostCSS dependencies — Currently uses postcss-import, postcss-import-ext-glob, postcss-js, and autoprefixer, all of which get replaced by a single @tailwindcss/postcss plugin

General Breaking Changes to Be Aware Of

• JS config → CSS @theme — tailwind.config.js no longer auto-detected
• PostCSS simplification — tailwindcss + postcss-import + autoprefixer replaced by @tailwindcss/postcss
• Renamed utilities — shadow/blur/rounded scales shifted (e.g. shadow-sm → shadow-xs), !flex → flex!
• Opacity utilities removed — replaced by modifier syntax (bg-blue-500/50)
• Default value changes — border color now currentColor, ring width now 1px
• Requires modern browsers — Safari 16.4+, Chrome 111+, Firefox 128+
• No Sass/Less/Stylus support — Tailwind is the preprocessor now

Suggested Approach

1. Create a feature branch
2. Run npx @tailwindcss/upgrade to see what it handles automatically
3. Keep the JS config via @config initially for the token pipeline
4. Gradually migrate to pure CSS @theme definitions (v4 auto-exposes all theme values as CSS variables, which may eliminate much of our custom plugin code)
5. Audit and update any renamed utility classes in templates
6. Remove obsolete PostCSS dependencies
7. Thorough visual regression testing across the site

References

• Official Upgrade Guide
• Tailwind CSS v4.0 Announcement