Tailwind v4 — breaking changes care te vor mușca la upgrade

Tailwind v4 e cea mai mare schimbare de la v1. 90% din cod merge neatins, dar restul de 10% te poate bloca 2 zile.

Ce se schimbă fundamental

• Nu mai există tailwind.config.js (tehnic încă merge prin compat, dar nerecomandat)
• Totul se declară în CSS cu @theme
• Clasele JIT devin native, zero build overhead
• @import "tailwindcss" înlocuiește @tailwind base; @tailwind components; @tailwind utilities;

Custom colors — noul sintax

Înainte:

module.exports = {
  theme: { extend: { colors: { brand: "#ff00ff" } } }
}

Acum în globals.css:

@theme {
  --color-brand: #ff00ff;
  --color-brand-50: #fff0ff;
}

Folosire neschimbată: bg-brand, text-brand-50.

Breaking: spacing ring/shadow

• ring-1 înainte era 3px, acum e 1px (strict la nume)
• shadow-sm → shadow-xs, shadow → shadow-sm

Fix rapid: căuți/înlocuiești în proiect.

Breaking: prefix plugin

Nu mai există prefix: "tw-" în config. Trebuie să folosești prefix direct în CSS import:

@import "tailwindcss" prefix(tw);

Apoi toate clasele devin tw-flex, tw-pt-4.

@layer în loc de plugins

Custom components în v3:

plugins: [function({ addComponents }) { ... }]

În v4:

@layer components {
  .btn-primary {
    @apply bg-brand text-white px-4 py-2 rounded-lg;
  }
}

Migrare pas cu pas

1. Backup tailwind.config.js
2. npx @tailwindcss/upgrade@latest — migrează 70% automat
3. Mută colors/spacing custom în @theme
4. Verifici vizual 5-10 pagini — cauți regresii de ring/shadow
5. Rulezi build — dacă trece, probabil ești OK

Ce NU se schimbă

• Toate utility classes de baza (flex, grid, pt-*, bg-*)
• Dark mode (încă dark:*)
• Responsive (md:*, lg:*)

Timp realist de migrare pe un proiect mediu: 4-8 ore, majoritatea pe verificări vizuale.