Tailwind CSS 4: cum migrezi de la v3 fara sa spargi nimic

01Ce este nou in Tailwind CSS 4 si de ce conteaza

Tailwind 4 este construit peste Lightning CSS, scris in Rust. Build-urile devin de cinci pana la zece ori mai rapide, hot reload este aproape instant si suportul pentru sintaxa CSS moderna este complet. Cascade layers sunt native, ceea ce inseamna ca nu mai ai conflicte de specificitate intre componentele tale, utilitar Tailwind si stiluri legacy.

Configurarea s-a mutat din tailwind.config.js in CSS, prin directive at-theme si at-config. Tokens-urile devin variabile CSS direct expuse, ceea ce simplifica enorm theming-ul dinamic si reduce dependenta de JavaScript. Container queries sunt suportate first-class cu @container, fara plugin separat, si functioneaza identic cu standardul CSS.

Pentru proiectele firmei de IT Blackbone, beneficiul cel mai vizibil a fost reducerea timpului de build de la 4-5 secunde la sub o secunda, plus simplificarea pipeline-ului de tokens. Pentru echipele care lucreaza in monorepo cu zeci de pachete, diferenta in productivitate zilnica este semnificativa.

• →Lightning CSS engine: build-uri 5-10x mai rapide
• →Cascade layers native: zero conflicte de specificitate
• →Container queries fara plugin separat
• →Configurare in CSS prin at-theme si at-config
• →Variabile CSS expuse direct pentru toate tokens-urile

02Inventar inainte de migrare: ce ai in v3

Inainte sa atingi vreun fisier, fa un inventar onest. Listeaza toate plugin-urile Tailwind custom, toate utilitatile definite cu addUtilities, toate variantele custom si toate configurarile speciale din theme.extend. Listeaza si toate locurile in care folosesti @apply intensiv sau @layer pentru a injecta stiluri. Acestea sunt zonele cu risc.

Apoi listeaza dependentele care depind de Tailwind: shadcn este la 4-ready in versiunile recente, daisyUI a publicat versiunea v4-compatibila, headlessui functioneaza fara modificari, dar plugin-uri mai exotice pot intarzia. Verifica si compatibilitatea framework-ului: Next.js 16, Vite 6, Astro 5 sunt toate ok in 2026, dar configurarile vechi pot avea probleme.

Echipa Blackbone foloseste o foaie simpla de inventar care marcheaza fiecare dependenta cu unul din trei statusuri: ready, are PR de update, blocheaza migrarea. Daca apare un singur blocant, fie astepti, fie elimini dependenta. Migrarea fara inventar complet duce la opt ore de debugging si la commits revert urat.

03Codemod-ul oficial si limitele lui

Echipa Tailwind a livrat un codemod oficial care convertește tailwind.config.js in directive CSS, actualizeaza importurile, transforma clase deprecate si standardizeaza opacitatea valorilor de culoare. Pentru un proiect curat scris dupa convenții, codemod-ul rezolva 80-90 la suta din munca intr-o singura comanda. Diferenta o face mereu codul nestandard.

Limitele apar la plugin-uri custom care manipuleaza addUtilities cu logica complexa, la variante custom create prin matchVariant si la configurari de theme care folosesc functii JavaScript pentru generare. Codemod-ul nu intelege intentia ta in acele cazuri si lasa cod care nu compileaza. Acolo intervii manual.

Recomandarea firmei de IT Blackbone este sa rulezi codemod-ul pe o ramura noua, sa faci commit imediat dupa, sa pornesti dev server-ul si sa lucrezi incremental prin erorile aparute. Fiecare eroare rezolvata devine un commit mic, usor de revertit daca apare un regress. Strategia aceasta a redus timpul de migrare al unui proiect mare de la doua saptamani la patru zile.

04Breaking changes care chiar conteaza in practica

Cele mai vizibile breaking changes sunt la opacitate. In v3 scriai bg-blue-500/50 cu slash; in v4 sintaxa ramane dar implementarea s-a schimbat la color-mix, deci unele combinatii dau rezultate usor diferite vizual. Apoi, comportamentul default pentru ring-ul de focus este alt: latimea default a scazut de la 3px la 1px in unele componente.

Configurarea fontului si a culorilor s-a mutat in at-theme cu variabile CSS, ceea ce inseamna ca extensii custom complex din v3 trebuie rescrise. Plugin-ul typography are sintaxa noua pentru variante prose-invert, iar utilitarele de gradient au reguli mai stricte la composition. Aceste schimbari sunt mici individual, dar adunate pot produce zeci de regresii vizuale.

Pentru un proiect cu vizibilitate publica, echipa Blackbone face mereu un audit vizual cu Percy, Chromatic sau un setup propriu de visual regression. Compari screenshot-uri inainte si dupa migrare, validezi diferentele unul cate unul si patchuiesti rapid acolo unde brand-ul cere paritate exacta.

05Container queries si CSS variables in productie

Cele mai mari castiguri post-migrare nu vin din vitezele de build, ci din ce poti scrie nou. Container queries iti permit sa stilizezi componente in functie de marimea container-ului, nu doar a viewport-ului. Un card care se schimba intre layout vertical si orizontal pe baza spatiului disponibil este mult mai usor de scris in v4 decat in v3 cu plugin.

Variabilele CSS expuse direct simplifica theming-ul. Nu mai ai nevoie de un wrapper JavaScript pentru a schimba paleta in runtime. Setezi noile valori pe root sau pe un container si Tailwind le foloseste automat. Combinatia cu OKLCH color space, pe care v4 il accepta nativ, deschide usa pentru palete mai naturale si tranzitii vizuale mai placute.

Echipa Blackbone a livrat in ultimele luni produse in care container queries au inlocuit complet logica JavaScript de responsive layout. Codul este mai simplu, performanta este mai buna si comportamentul este mai natural. Pentru produse cu UI complex si layouts variabile, v4 este o upgrade strategica, nu doar tehnica.

• →Container queries first-class pentru layouts adaptive
• →OKLCH si color-mix pentru palete mai naturale
• →Variabile CSS expuse pentru theming dinamic fara JS
• →Cascade layers nativi pentru order predictibil
• →Build sub o secunda pe proiecte de marime medie

06Cum livrezi migrarea fara incidente in productie

Migrarea nu se livreaza intr-un singur PR mamut. Lucrezi pe o ramura separata, mergi cu main in mod regulat ca sa eviti conflicte si livrezi in staging dupa fiecare batch important. In staging ruleaza testele automate plus auditul vizual. Daca totul trece, livrezi in productie intr-o fereastra cu trafic redus si monitorizezi metricile pentru cateva ore.

Rollback plan este mandatory. Pastrezi tag-ul ultimei build cu v3 si te asiguri ca poti reveni in cinci minute daca apare un regress major. Pentru proiecte critice, faci canary deploy cu 10 la suta din trafic pe v4 si urmaresti core web vitals, rata de erori si feedback-ul utilizatorilor. Daca metricile sunt stabile dupa o ora, rulezi rollout-ul complet.

Firma de IT Blackbone a folosit aceasta abordare pentru toate migratiile recente si nu am avut niciun incident in productie. Combinatia intre planificare, audit vizual, deploy gradual si rollback rapid transforma o migrare riscanta intr-o operatiune predictibila si controlata.