Cum construiești un design system când sunteți o echipă de trei

Când sunteți o echipă de trei persoane care gestionează simultan zeci de proiecte de client, inconsecvența devine cea mai costisitoare problemă a dumneavoastră. Am observat același tipar repetându-se în proiectele noastre de design de site la GRADAX: un buton stilizat într-un fel pe pagina principală, altfel pe pagina de prețuri și într-un al treilea fel în dashboard. Fiecare abatere ne costa timp în QA, introducea erori vizuale și eroda senzația de finisaj pe care clienții noștri o așteptau. Ceva trebuia să se schimbe.

Decizia de a investi într-un design system nu a fost determinată de ambiție sau de urmarea tendințelor. A fost determinată de durere. Cheltuiam aproximativ 30% din fiecare proiect nou recreând componente care existau deja într-o formă sau alta în altă parte a codului nostru. Un design system ne-ar permite să ne codificăm deciziile o dată și să le reutilizăm peste tot, transformând munca repetitivă într-un avantaj competitiv.

Dar literatura despre sistemele de design este dominată de povești de la companii cu echipe dedicate de platformă de douăzeci sau mai mulți ingineri. Aveam nevoie de o abordare pragmatică pe care o echipă de trei persoane să o poată construi, întreține și folosi efectiv fără a opri lucrul la funcționalități. În continuare este cadrul la care am ajuns după luni de iterare.

Fiecare tutorial de design system îți spune să începi cu tokenuri, și pe bună dreptate. Tokenurile de design sunt valorile atomice, culori, spațiere, scale tipografice, raze de bordură, din care se construiește tot restul. Ele sunt fundamentul oricărei identități de brand coerente, asigurând consistența vizuală în fiecare punct de contact. Noi le-am definit ca proprietăți personalizate CSS într-un singur fișier, mapate la nume semantice precum --color-primary, --color-muted-foreground și --radius-lg. Asta a însemnat că orice componentă care referea aceste tokenuri se adapta automat când schimbam valorile de bază.

Concluzia cheie pentru o echipă mică este să mențină setul de tokenuri extrem de restrâns. Am început cu mai puțin de patruzeci de tokenuri care acoperă culoare, spațiere, tipografie și umbre. Marile organizații pot avea nevoie de sute, dar am descoperit că un set compact forțează consecvența în loc să permită o mie de variații subtile. Când un dezvoltator caută o valoare de spațiere și are doar opt opțiuni, ajunge în mod natural la cea corectă.

De asemenea, am stabilit devreme o convenție de denumire, semantică în loc de descriptivă. În loc de --blue-600 sau --spacing-16, am folosit --color-primary și --space-md. Asta a decuplat intenția de implementare și a făcut redesignurile viitoare triviale. Când un client a vrut să treacă de la albastru la violet, am schimbat șase linii în fișierul de tokeni și întregul sistem s-a actualizat.

Cu tokenurile puse la punct, ne-am îndreptat atenția către componente. Am adoptat shadcn/ui ca fundație, ceea ce ne-a oferit primitive frumos realizate și accesibile, construite pe Radix UI. În loc să construim totul de la zero, am extins aceste primitive cu stratul nostru de tokenuri și variante specifice proiectului. Un Button, de exemplu, a moștenit accesibilitatea și gestionarea tastaturii din shadcn, folosind în același timp paleta de culori și spațierea bazate pe tokenurile noastre.

Arhitectura noastră de componente urmează o ierarhie strictă. La bază stau primitivele UI, butoane, câmpuri de introducere, insigne, tooltipuri, care nu au logică de business și acceptă stilizare prin props și combinarea className prin utilitarul cn(). Deasupra lor stau componentele compuse, bare de căutare, bare de instrumente pentru tabele de date, carduri statistice, care combină mai multe primitive în modele reutilizabile. În vârf stau secțiunile la nivel de pagină, specifice unei singure vizualizări și colocatate lângă pagina care le folosește.

Acest model cu trei niveluri previne cele mai frecvente două eșecuri ale sistemelor de design: componente prea abstracte pentru a fi utile și componente prea specifice pentru a fi reutilizabile. Când un dezvoltator trebuie să construiască o funcționalitate nouă, o asamblează din nivelul intermediar. Când nivelul intermediar nu are ce îi trebuie, o compune din primitive și, dacă se dovedește reutilizabilă, o promovează.

Documentația este locul unde majoritatea sistemelor de design ale echipelor mici ajung să moară. Echipa construiește componente frumoase, dar nu notează niciodată cum să le folosească, așa că noii contribuitori (sau autorii originali trei luni mai târziu) reinventează tipare care există deja. Am rezolvat asta făcând documentația un produs secundar al dezvoltării, nu o sarcină separată.

Fiecare fișier de componentă include un bloc JSDoc care descrie scopul său, interfața de props și un exemplu de utilizare. Menținem de asemenea o instanță Storybook activă unde fiecare componentă este randată izolat cu variantele sale. Regula critică este că niciun pull request nu se face merge fără story-ul corespunzător. Pare strict, dar durează mai puțin de cinci minute per componentă și economisește ore de confuzie viitoare.

De asemenea, ținem un jurnal de decizii ușor, un simplu fișier markdown care consemnează de ce am făcut anumite alegeri. De ce am ales 0.5rem ca rază de bază? De ce culoarea noastră principală folosește oklch în loc de hex? Aceste note sunt neprețuite când revenim la decizii șase luni mai târziu și îi ajută să se integreze pe freelancerii sau colaboratorii care ni se alătură temporar.

Testele funcționale vă spun dacă un buton declanșează handlerul onClick. Testele de regresie vizuală vă spun dacă arată încă bine. Pentru un sistem de design, ultimul contează la fel de mult ca primul. Am integrat comparațiile de capturi de ecran Playwright în pipeline-ul nostru CI, astfel încât fiecare pull request generează un diff vizual al componentelor afectate.

Configurarea a fost mai simplă decât ne așteptam. Fiecare poveste Storybook funcționează și ca un caz de test vizual. Jobul nostru CI lansează un browser headless, capturează capturi de ecran pentru fiecare poveste și le compară cu referințele salvate. Dacă aspectul unei componente se schimbă, chiar și cu un singur pixel, PR-ul este semnalat pentru revizuire. Acest lucru a prins zeci de regresii subtile care ar fi ajuns neobservate în producție, cum ar fi o culoare de bordură care se schimbă pentru că cineva a actualizat un token fără să realizeze impactul în aval.

De asemenea, rulăm teste vizuale atât în modul light, cât și în dark mode. Deoarece tokens-urile noastre definesc valori separate pentru fiecare mod, o modificare care arată bine în light mode poate strica complet dark mode-ul. Capturile de ecran automate în ambele moduri au eliminat o întreagă categorie de bug-uri care ajungeau în producție.

După șase luni de utilizare în peste o duzină de proiecte de client, design system-ul nostru crescuse de la patruzeci de tokens și douăsprezece componente la aproximativ optzeci de tokens și patruzeci și cinci de componente. Întrebarea nu mai era dacă să scalăm, ci cum să scalăm fără a pierde simplitatea care făcea sistemul valoros în primul rând.

Am introdus o listă de verificare pentru contribuții pe care fiecare componentă nouă trebuie să o treacă înainte de a intra în bibliotecă: trebuie să folosească doar tokenuri existente, trebuie să fie accesibilă din start, trebuie să includă cel puțin o poveste Storybook și trebuie să funcționeze atât în modul luminos, cât și în cel întunecat. Componentele care nu îndeplinesc orice criteriu rămân în baza de cod specifică proiectului până când sunt consolidate. Această filtrare menține biblioteca partajată demnă de încredere.

Am început, de asemenea, să versionăm sistemul cu lansări semantice. Modificările incompatibile la un token sau la o proprietate de componentă apar ca versiuni majore, astfel încât proiectele fixate pe o versiune mai veche nu se strică neașteptat. Acest lucru a fost exagerat pentru o echipă de trei la început, dar a dat roade pe măsură ce am început să împărtășim sistemul cu colaboratori freelanceri și echipe de dezvoltare dedicate care aveau nevoie de garanții de stabilitate.

Cea mai importantă lecție este că un design system nu trebuie să fie uriaș pentru a fi valoros. Sistemul nostru este mic după standardele enterprise, dar ne economisește aproximativ zece ore pe proiect prin duplicare redusă, mai puține erori vizuale și onboarding mai rapid. Pentru o echipă de trei persoane care facturează pe proiect, acele ore se traduc direct în profitabilitate.

A doua lecție este să optimizați pentru adoptare, nu pentru completitudine. Un design system pe care echipa dumneavoastră nu îl folosește este mai rău decât absența unui design system, pentru că creează iluzia consecvenței în timp ce baza de cod diverge dedesubt. Fiecare decizie pe care am luat-o, de la alegerea shadcn/ui ca fundament până la impunerea poveștilor Storybook, a vizat transformarea sistemului în calea de cea mai mică rezistență, nu într-o povară suplimentară.

În final, tratați design system-ul ca pe un produs cu propria foaie de parcurs, chiar dacă singurii utilizatori sunt echipa dumneavoastră. Prioritizați componentele și token-urile care vor elimina cea mai multă duplicare. Urmăriți care componente sunt folosite cel mai frecvent și investiți în calitatea lor. Un design system nu este niciodată finalizat, dar cu prioritățile corecte, chiar și o echipă mică poate întreține unul care performează mult peste așteptări. Dacă luați în considerare construirea unui design system pentru produsul dumneavoastră și doriți îndrumare despre de unde să începeți, contactați echipa noastră, am trecut prin acest proces și vă putem ajuta să evitați cele mai frecvente capcane.