Izgradnja sistema oblikovanja, ko ste ekipa treh ljudi

Ko ste ekipa treh ljudi, ki hkrati opravlja ducat projektov za stranke, nestandardnost postane vaš najdražji problem. Opazili smo isti vzorec, ki se je ponavljal pri naših projektih oblikovanja spletnih strani v GRADAX: gumb je bil na domači strani oblikovan na en način, na strani s ceniki na drug način in na tretji način znotraj nadzorne plošče. Vsako odstopanje nas je stal časa pri testiranju kakovosti (QA), uvajalo vizualne napake in erodiralo urejen videz, ki ga pričakujejo naše stranke. Nekaj se je moralo spremeniti.

Odločitev za vlaganje v oblikovalski sistem ni bila posledica ambicij ali sledenja trendom. Bila je posledica bolečine. Približno 30 odstotkov vsakega novega projekta smo porabili za poustvarjanje komponent, ki so že v neki obliki obstajale drugje v naši kodni bazi. Oblikovalski sistem bi nam omogočil, da svoje odločitve zapišemo enkrat in jih znova uporabimo povsod, s čimer bi ponavljajoče se delo spremenili v konkurenčno prednost.

Vendar pa literatura o sistemih oblikovanja dominirajo zgodbe podjetij z namenskim platformnim timom dvajset ali več inženirjev. Potrebovali smo pragmatičen pristop, ki bi ga lahko zgradila, vzdrževala in dejansko uporabljala ekipa treh ljudi, ne da bi ustavila razvoj novih funkcij. Spodaj je okvir, na katerega smo prišli po mesecih iteracij.

Vsak vadnik o sistemih oblikovanja vam svetuje, da začnete s tokeni, in to iz dobrega razloga. Dizajnerski tokeni so atomarne vrednosti, barve, presledki, tipografske lestvice, radiji robov, iz katerih je zgrajeno vse ostalo. So temelj vsake skladne blagovne identitete, ki zagotavlja vizualno doslednost na vsaki stičišču. Naše smo definirali kot CSS lastnosti v eni sami datoteki, preslikane na semantična imena, kot so --color-primary, --color-muted-foreground in --radius-lg. To pomeni, da bi vsaka komponenta, ki sklicuje te tokene, samodejno prilagodila, ko bi spremenili osnovne vrednosti.

Ključna ugotovitev za majhno ekipo je, da nabor tokenov ostane drzno majhen. Začeli smo z manj kot štiridesetimi tokeni, ki pokrivajo barve, presledke, tipografijo in sence. Velike organizacije morda potrebujejo sto, a mi smo ugotovili, da kompakten nabor prisili doslednost namesto da bi omogočil tisoč subtilnih variacij. Ko razvijalec doseže po vrednosti presledka in ima na voljo le osem možnosti, naravno izbere pravilno.

Zgodaj smo vzpostavili tudi konvencijo poimenovanja, semantično raje kot deskriptivno. Namesto --blue-600 ali --spacing-16 smo uporabili --color-primary in --space-md. To je ločilo namen od implementacije in naredilo bodoče preoblikovanja trivialna. Ko je stranka želela preiti z modre na vijolično, smo spremenili šest vrstic v datoteki tokenov in se celoten sistem posodobil.

Ko so bili tokeni na mestu, smo se obrnili k komponentam. Kot temelj smo uporabili shadcn/ui, ki nam je dal lepo oblikovane, dostopne primitive, zgrajene na Radix UI. Namesto da bi gradili vse od začetka, smo te primitive razširili z našo plastjo tokenov in specifičnimi variantami projekta. Gumb na primer je podedoval dostopnost in obdelavo tipkovnice shadcn, medtem ko je uporabljal našo paleto barv in presledke, vodene s tokeni.

Naša arhitektura komponent sledi strogi hierarhiji. Na dnu sedijo UI primitivi, gumbi, vnosi, značke, opozorilna okna, ki nimajo poslovne logike in sprejemajo stiliziranje prek lastnosti in združevanja className z utiliteto cn(). Nad njimi stojijo sestavljene komponente, iskalni stolpci, orodne vrstice podatkovnih tabel, kartice statistik, ki združujejo več primitivov v ponovno uporabljive vzorce. Na vrhu stojijo razdelki na ravni strani, ki so specifični za en pogled in so locirani poleg strani, ki jih uporablja.

Ta model s tremi nivoji preprečuje dve najpogostejši napaki sistemov oblikovanja: komponente, ki so preveč apstraktne, da bi bile uporabne, in komponente, ki so preveč specifične, da bi bile ponovno uporabljive. Ko razvijalec potrebuje zgraditi novo funkcijo, jo sestavi iz srednjega nivoja. Ko srednji nivo nima tega, kar potrebuje, jo sestavi iz primitivov in, če se izkaže za ponovno uporabno, jo napreduje.

Dokumentacija je kraj, kjer večina sistemov oblikovanja za majhne ekipe umre. Ekipa zgradi lepe komponente, a nikoli ne zapiše, kako jih uporabljati, zato novi sodelavci (ali avtorji tri mesece kasneje) znova izmislijo vzorce, ki že obstajajo. To smo rešili tako, da smo dokumentacijo naredili stranski produkt razvoja, ne pa ločene naloge.

Vsaka datoteka komponente vključuje JSDoc blok, ki opisuje njen namen, vmesnik lastnosti (props) in primer uporabe. Vzdržujemo tudi živo instanco Storybook, kjer je vsaka komponenta upodobljena izolirano z vsemi svojimi variantami. Ključno pravilo je, da noben pull request ni združen brez ustrezne zgodbe (story). Zveni strogo, a na komponento traja manj kot pet minut in prihrani ure prihodnje zmede.

Vzdržujemo tudi lahka dnevna odločitev, preprost markdown zapisnik, ki beleži, zakaj smo sprejeli specifične izbire. Zakaj smo za osnovni radij izbrali 0.5rem? Zakaj naš primarni barvni ton uporablja oklch namesto hex? Ti zapisi so neprecenljivi, ko se po šestih mesecih vračamo k odločitvam, in pomagajo pri uvajanju freelancerjev ali pogodbenih izvajalcev, ki se pridružijo začasno.

Funkcionalni testi vam povedo, ali gumb sproži svoj onClick handler. Vizualni regresijski testi pa povejo, ali še vedno pravilno izgleda. Za sistem oblikovanja je slednje enako pomembno kot prvo. V naš CI pipeline smo integrirali primerjave posnetkov Playwright, tako da vsak pull request generira vizualno razliko (diff) prizadetih komponent.

Namestitev je bila preprostejša, kot smo pričakovali. Vsaka zgodba (story) v Storybooku hkrati služi kot vizualni testni primer. Naša CI naloga zažene brskalnik brez glave, zajame posnetke vsake zgodbe in jih primerja z shranjenimi baznimi stanji. Če se videz komponente spremeni, celo za en sam piksel, se pull request označi za pregled. To je ujelo desetine subtilnih regresij, ki bi bile sicer objavljene neopazno, kot je bila sprememba barve roba zaradi posodobitve tokena, o kateri nekdo ni vedel posledic.

Poleg tega poganjamo vizualne teste tako v svetlem kot v temnem načinu. Ker naši tokeni definirajo ločene vrednosti za vsak način, lahko sprememba, ki v svetlem načinu izgleda v redu, v temnem načinu povsem pokvari rezultat. Avtomatizirani posnetki v obeh načinih so odpravili celotno kategorijo napak, ki so prej dosegle proizvodnjo.

Po šestih mesecih uporabe na ducatih projektov strank se je naš sistem oblikovanja razvil iz štiridesetih tokenov in dvanajstih komponent na približno osemdeset tokenov in štiriinštirideset komponent. Vprašanje ni bilo več, ali skalirati, ampak kako skalirati, ne da bi izgubili preprostost, ki je sistemu prvotno dodala vrednost.

Uvedli smo seznam prispevkov, ki ga mora vsaka nova komponenta prestati, preden stopi v knjižnico: mora uporabljati samo obstoječe tokene, mora biti dostopna že ob prvem uporabu, mora vključevati vsaj eno zgodbo (story) v Storybooku in morati delovati tako v svetlem kot v temnem načinu. Komponente, ki ne izpolnjujejo katerega koli merila, ostanejo v kodi projekta do njihovega utrjevanja. Ta kontrola ohranja zaupanje v skupno knjižnico.

Začeli smo tudi verzioniranje sistema s semantičnimi izdajami. Kršitvene spremembe tokena ali lastnosti komponente se odražajo v povečanju glavne različice, tako da projekti, priklopljeni na starejšo različico, ne bodo nepričakovoma prekinili delovanja. To je bilo sprva pretiravanje za ekipo treh ljudi, a se je izplačalo, ko smo začeli deliti sistem s freelancerskimi sodelavci in ekipami za namenski razvoj, ki so potrebovale garancije stabilnosti.

Najpomembnejše spoznanje je, da sistem oblikovanja ne potrebuje ogromnih dimenzij, da bi bil dragocen. Naš sistem je po podjetniških standardih majhen, a nam prihrani ocenjenih deset ur na projekt zaradi zmanjšane podvojnosti, manj vizualnih napak in hitrejše integracije novih članov. Za ekipo treh oseb, ki obračunava po projektu, se te ure neposredno pretvorijo v dobičkonosnost.

Drugo spoznanje je optimizacija za sprejetje, ne za popolnost. Sistem oblikovanja, ki ga vaša ekipa ne uporablja, je slabši od nobenega sistema oblikovanja, ker ustvarja iluzijo doslednosti, medtem ko se baza kode razhaja. Vsaka odločitev, ki smo jo sprejeli, od izbire shadcn/ui kot osnove do obveznih zgodb (stories) v Storybooku, je bila usmerjena v to, da bi bil sistem pot najmanjšega upora, ne pa dodatno breme.

Končno, obravnavajte svoj sistem oblikovanja kot izdelek z lastnim načrtom, tudi če so edini uporabniki vaša lastna ekipa. Prednostno obravnavajte komponente in tokene, ki bodo odpravili največjo podvojnost. Spremljajte, katere komponente se uporabljajo najbolj pogosto, in vlagajte v njihovo kakovost. Sistem oblikovanja nikoli ni končan, a z ustreznimi prioritetami lahko tudi majhna ekipa vzdržuje tistega, ki preseže svoje težo. Če razmišljate o gradnji sistema oblikovanja za vaš izdelek in želite nasvet, kje začeti, stopite v stik z našo ekipo; skozi proces smo že šli in vam lahko pomagamo, da se izognete najpogostejшим pastim.