Vytvorenie dizajnového systému, keď ste tím troch ľudí

Keď ste tím troch ľudí, ktorý súčasne rieši desiatky projektov pre klientov, nekonzistencia sa stáva vaším najdrahším problémom. Všimli sme si rovnaký vzorec opakujúci sa naprieč našimi zákazkami na vývoj webových stránok v spoločnosti GRADAX: tlačidlo bolo na domovskej stránke štýlované jedným spôsobom, na stránke s cenami iným a v rámci dashboardu tretím. Každá odchýlka nás stála čas v QA, prinášala vizuálne chyby a narušovala čistý vzhľad, ktorý od nás naši klienti očakávali. Niečo sa muselo zmeniť.

Rozhodnutie investovať do dizajnového systému nebolo poháňané ambíciou ani sledovaním trendov. Bolo poháňané bolesťou. Trávili sme približne 30 % každého nového projektu opätovným vytváraním komponentov, ktoré už v nejakej podobe existovali inde v našom kóde. Dizajnový systém by nám umožnil zakódovať naše rozhodnutia raz a znovu ich použiť všade, čím by sa opakujúca sa práca zmenila na konkurenčnú výhodu.

Literatúra o dizajnových systémoch však dominujú príbehy z firiem s oddelenými platformnými tímmi dvadsiatich alebo viacerých inžinierov. Potrebovali sme pragmatický prístup, ktorý by dokázal zostaviť, udržiavať a reálne využívať aj tím troch ľudí, aniž by zastavil vývoj nových funkcií. Nasleduje rámec, na ktorý sme po mesiacoch iterácií dospeli.

Každý tutoriál dizajnových systémov vám hovorí, aby ste začali s tokenmi, a to zo dobrého dôvodu. Dizajnové tokeny sú atómové hodnoty, farby, odsadenia, škály typografie, polomer oblúkov, z ktorých je postavené všetko ostatné. Sú základom akéhokoľvek súvislého brand identity, zabezpečujúc vizuálnu konzistenciu naprieč každým bodom kontaktu. Naše sme definovali ako CSS custom properties v jednom súbore, mapované na sémantické názvy ako --color-primary, --color-muted-foreground a --radius-lg. To znamenalo, že každý komponent odkazujúci na tieto tokeny by sa automaticky prispôsobil, keď sme zmenili základné hodnoty.

Kľúčovým poznatkom pre malý tím je udržať sadu tokenov drsne malú. Začínali sme s menej ako štyridsiatimi tokenmi pokrývajúcimi farby, odsadenie, typografiu a tiene. Veľké organizácie môžu potrebovať stovky, ale my sme zistili, že kompaktná sada núti ku konzistencii namiesto toho, aby umožňovala tisíc jemných variácií. Keď vývojár siaha po hodnote pre odsadenie a má k dispozícii len osem možností, prirodzene sa rozhodne pre tú správnu.

Taktiež sme skoro zaviedli konvenciu pomenovania, sémantickú namiesto deskriptívnej. Namiesto --blue-600 alebo --spacing-16 sme používali --color-primary a --space-md. Tým sme odlúčili úmysel od implementácie a urobili budúce redesigny triviálnymi. Keď klient chcel prejsť z modrej na fialovú, zmenili sme šesť riadkov v súbore s tokenmi a celý systém sa aktualizoval.

S tokenmi na mieste sme sa obrátili na komponenty. Prijali sme shadcn/ui ako náš základ, ktorý nám poskytol krásne spracované, prístupné primitíva postavené na Radix UI. Namiesto stavby všetkého od nuly sme tieto primitíva rozšírili vrstvou tokenov a projektovo špecifickými variantmi. Napríklad Button dedikoval prístupnosť a obsluhu klávesnice od shadcn, zatiaľ čo používal našu farebnú paletu a odsadenie riadené tokenmi.

Naša architektúra komponentov sleduje prísnu hierarchiu. V spodnej časti sedia UI primitíva, tlačidlá, vstupy, badge, tipy, ktoré nemajú žiadnu biznis logiku a prijímajú štýlovanie cez props a spájanie className pomocou utility cn(). Nad nimi sedia komponované komponenty, vyhľadávacie lišty, toolbars dátových tabuliek, karty so štatistikami, ktoré kombinujú viacero primitív do opakovane použiteľných vzorov. Vrchol tvoria sekcie na úrovni stránky, ktoré sú špecifické pre jeden pohľad a sú uložené vedľa stránky, ktorá ich používa.

Tento trojstupňový model predchádza dvom najbežnejším zlyhaniam dizajnového systému: komponentom, ktoré sú príliš abstraktné na to, aby boli užitočné, a komponentom, ktoré sú príliš špecifické na to, aby boli opakovane použiteľné. Keď vývojár potrebuje vytvoriť novú funkciu, zostaví ju zo strednej vrstvy. Keď stredná vrstva nemá to, čo potrebuje, skladá ju z primitív a ak sa ukáže ako opakovane použiteľná, povýši ju.

Dokumentácia je miesto, kam väčšina dizajnových systémov malých tímov ide zomrieť. Tím vytvorí krásne komponenty, ale nikdy nezapíše, ako sa majú používať, takže noví prispievatelia (alebo pôvodní autori o tri mesiace neskôr) znova vynachádzajú vzory, ktoré už existujú. My sme tento problém vyriešili tým, že dokumentáciu robíme vedľajším produktom vývoja, nie samostatnou úlohou.

Každý súbor komponentu obsahuje blok JSDoc s popisom jeho účelu, rozhraním propsov a príkladom použitia. Udržujeme aj živú inštanciu Storybook, kde je každý komponent renderovaný izolovane so všetkými variantami. Kľúčovým pravidlom je, že žiadny pull request sa nespláca bez zodpovedajúceho príbehu (story). Znie to prísne, no na každý komponent to zaberie menej ako päť minút a ušetrí hodiny budúcej nejistoty.

Taktiež vedieme jednoduchý záznam rozhodnutí, súbor vo formáte markdown, ktorý zaznamenáva, prečo sme urobili konkrétne voľby. Prečo sme si vybrali 0.5rem ako základný polomer? Prečo náš primárny farba používa oklch namiesto hexu? Tieto poznámky sú nenahraditeľné pri opätovnom preskúmaní rozhodnutí po šiestich mesiacoch a pomáhajú pri onboarding freelancerov alebo externistov, ktorí do tímu nastupujú dočasne.

Funkčné testy vám povedia, či tlačidlo spustí svoj onClick handler. Vizualizované regresné testy vám povedia, či stále správne vyzerá. Pri dizajnovom systéme záleží na tom druhom rovnako ako na tom prvom. Do nášho CI pipeline sme integrovali porovnávanie snímok obrazovky cez Playwright, takže každý pull request generuje vizuálny rozdiel (diff) ovplyvnených komponentov.

Nastavenie bolo jednoduchšie, než sme čakali. Každý príbeh v Storybook slúži zároveň ako vizuálny testovací prípad. Naša CI úloha spúšťa headless prehliadač, zachytáva snímky obrazovky každého príbehu a porovnáva ich so zapísanými referenčnými hodnotami. Ak sa vzhľad komponentu zmení, dokonca aj o jeden pixel, PR je označený na revíziu. Toto zachytilo desiatky jemných regresných chýb, ktoré by sa dostali do produkcie bez povšimnutia, napríklad zmena farby okraja kvôli aktualizácii tokenu, ktorou autor neprehliadol dopad na nižšie vrstvy.

Vizuálne testy tiež spúšťame v svetlom aj tmavom režime. Keďže naše tokeny definujú oddelené hodnoty pre každý režim, zmena, ktorá vyzerá dobre v svetlom režime, môže úplne rozbíť tmavý režim. Automatizované snímky obrazovky v oboch režimoch eliminovali celú kategóriu chýb, ktoré sa predtým dostávali do produkcie.

Po šiestich mesiacoch používania naprieč desiatkami clientských projektov sa náš dizajnový systém rozrástol zo štyridsiatich tokenov a dvanástich komponentov približne na osemdesiat tokenov a štyridsaťpäť komponentov. Otázkou už nebolo, či systém škálovať, ale ako ho škálovať bez straty jednoduchosti, ktorá mu dodala hodnotu od začiatku.

Zaviedli sme kontrolný zoznam príspevkov, ktorý musí splniť každý nový komponent, než sa pripojí do knižnice: musí používať iba existujúce tokeny, musí byť z výroby dostupný (accessible), musí obsahovať aspoň jeden príbeh v Storybook a musí fungovať v oboch režimoch, svetlom aj tmavom. Komponenty, ktoré nesplnia akékoľvek kritérium, zostávajú v kóde projektu až kým nie sú dostatočne overené. Táto brána udržuje dôveryhodnosť zdieľanej knižnice.

Začali sme tiež verzionovať systém pomocou semantic releases. Lomové zmeny tokenu alebo propsu komponentu sa prejavia ako zvýšenie hlavnej verzie, takže projekty viazané na staršiu verziu sa neočakávane nerozbijú. Na trojčlennom tíme to bolo na začiatku možno nadmerné, no dividendy sa vyplácali, keď sme začali systém zdieľať s freelance spolupracovníkmi a dedikovanými vývojárskymi tímami, ktorí potrebovali záruky stability.

Jedinou najdôležitejšou lekciou je, že dizajnový systém nemusí byť obrovský, aby bol cenný. Náš systém je podľa enterprise štandardov malý, no ušetrí nám odhadom desať hodín na projekt v podobe redukcie duplicity, menej vizuálnych chýb a rýchlejšieho onboardingu. Pre trojčlenný tím fakturujúci za projekt sa tieto hodiny premietnu priamo do ziskovosti.

Druhou lekciou je optimalizovať pre adopciu, nie pre kompletnosť. Dizajnový systém, ktorý váš tím nepoužíva, je horší ako žiadny dizajnový systém vôbec, pretože vytvára ilúziu konzistencie, zatiaľ čo kódová základňa sa pod tým diverguje. Každé rozhodnutie, ktoré sme urobili, od výberu shadcn/ui ako základu až po povinnosť mať príbehy v Storybook, malo za cieľ urobiť systém cestou najmenej odporu, nie ďalšou záťažou.

Nakoniec pristupujte k svojmu dizajnovému systému ako k produktu s vlastným roadmapom, aj keď jedinými používateľmi je len váš vlastný tím. Prioritizujte komponenty a tokeny, ktoré eliminujú najviac duplicity. Sledujte, ktoré komponenty sa používajú najčastejšie, a investujte do ich kvality. Dizajnový systém nie je nikdy hotový, no s správnymi prioritami dokáže malý tím udržiavať systém, ktorý sa tvári oveľa silnejšie, než je jeho veľkosť. Ak zvážate budovanie dizajnového systému pre váš produkt a potrebujete vedenie, kde začať, kontaktujte nás, prešli sme si týmto procesom a vieme vám pomôcť vyhnúť sa najbežnejším pastiam.