TailwindCSS v4 Migration Guide: What Changed and How to Upgrade

I migrated this portfolio from TailwindCSS v3 to v4, and the upgrade was smoother than expected — but there are breaking changes you need to know about. Here's what I learned. The Big Shift: CSS-First Configuration The biggest change in Tailwind v4 is that configuration moves from tailwind.config.js into your CSS file using @theme . Before (v3) // tailwind.config.js module . exports = { theme : { extend : { colors : { brand : { accent : ' #C09E5A ' , black : ' #000000 ' , }, }, fontFamily : { sans : [ ' Inter ' , ' system-ui ' , ' sans-serif ' ], mono : [ ' JetBrains Mono ' , ' monospace ' ], }, }, }, plugins : [ require ( ' @tailwindcss/typography ' )], }; After (v4) /* app.css */ @import 'tailwindcss' ; @plugin '@tailwindcss/typography' ; @theme { --font-sans : 'Inter' , system-ui , sans-serif ; --font-mono : 'JetBrains Mono' , monospace ; --color-brand-accent : #C09E5A ; --color-brand-black : #000000 ; } This is a significant philosophical change. Your design tokens are now CSS cust