code-architecture-tailwind-v4-best-practices

Use CVA (~1KB) for components with 3+ variants needing type safety, such as buttons in a component library. Use tailwind-variants (~4KB) when you need responsive variants, multi-part slot components like cards, or composition via extend.

Tailwind v4 uses CSS-first configuration: import with `@import "tailwindcss"` and define design tokens inside an `@theme` block, such as `--color-brand-primary`. These tokens generate utilities and expose CSS variables automatically.

No, the Tailwind team discourages @apply for component styles because it hides styling decisions and breaks variant support. Use utilities directly in markup, component abstractions like CVA, or @utility only for genuinely reusable custom utilities.

Key changes include `shadow-sm` becoming `shadow-xs`, `rounded-sm` becoming `rounded-xs`, `bg-opacity-50` replaced by `bg-black/50`, and `bg-gradient-to-r` renamed to `bg-linear-to-r`. Run `npx @tailwindcss/upgrade` for automated migration.

Use native data attributes like `data-loading` and `data-disabled` on elements, then style them with variants such as `data-loading:opacity-50`. You can also define custom variants with `@custom-variant` for compound selectors.