Tailwind CSS v4.x Best Practices

Covers Tailwind CSS v4.0 through v4.2.2 (latest stable as of March 2026). Always check the official docs at https://tailwindcss.com/docs for the latest.

Tailwind CSS is a utility-first CSS framework. Instead of writing custom CSS, you compose designs using utility classes directly in your markup. Tailwind v4 introduced CSS-first configuration with @theme variables, @utility for custom utilities, and @custom-variant for custom variants — replacing the old tailwind.config.js approach entirely.

Critical v4 Migration Gotchas

These are the most common mistakes when working with Tailwind v4. If you're migrating from v3 or using v4 for the first time, read the upgrade guide — but here are the top trip-ups: