code-architecture-tailwind-v4-best-practices

Use CVA when a component has 3 or more variants and you need type safety, such as in component libraries. For components with only 1-2 variants or prototypes, plain utility classes are preferred since they add zero bundle overhead.

CVA (~1KB) handles single-element variant styling with type safety, while tailwind-variants (~4KB) adds support for multi-part slot components, responsive variants, and component composition via extend. Choose tailwind-variants for complex design systems like cards or accordions.

Tailwind v4 uses CSS-first configuration through the @theme directive in your stylesheet. Define tokens like --color-brand-primary inside @theme, which generates both utility classes and CSS variables automatically after a single @import "tailwindcss" statement.

No, the Tailwind team discourages @apply for component styles because it hides styling decisions and breaks variant support. Use component abstractions like CVA instead, or the @utility directive only when a custom utility is genuinely needed.

Key changes include shadow-sm becoming shadow-xs, rounded-sm becoming rounded-xs, bg-gradient-to-r becoming bg-linear-to-r, and default border color changing from gray-200 to currentColor. Run npx @tailwindcss/upgrade for automated migration.