Design-järjestelmän rakentaminen kolmen hengen tiimillä

Kun olette kolmen hengen tiimi, joka hoitaa kymmeniä asiakasprojekteja samanaikaisesti, epäjohdonmukaisuus tulee kalleimmaksi ongelmaksi. Huomasimme saman kuvion toistuvan verkkosivujen suunnittelussa GRADAXissa: painike oli tyylitelty eri tavalla etusivulla, eri tavalla hinnoittelusivulla ja kolmannella tavalla sisällä. Jokainen poikkeama maksoi aikaa QA:ssa, toi esiin visuaalisia virheitä ja horjutti sitä siistiä tuntua, jota asiakkaamme odottivat. Jotain täytyi muuttua.

Päätös panostaa suunnittelujärjestelmään ei syntynyt kunnianhimosta tai trendien perässä juoksemisesta. Se syntyi kivusta. Käytimme noin 30 prosenttia jokaisesta uudesta projektista komponenttien uudelleenluomiseen, jotka olivat jo jossain muodossa olemassa koodipohjassamme. Suunnittelujärjestelmän avulla voisimme kirjata päätöksemme kerran ja käyttää niitä uudelleen kaikkialla, muuttaen toistuvan työn kilpailueduksi.

Mutta kirjallisuus design-järjestelmistä on dominoitu tarinoilla yrityksistä, joilla on omistautuneita alustatiimejä, joissa on kaksikymmentä tai enemmän insinööriä. Tarvimme pragmaattisen lähestymistavan, jonka kolmen hengen tiimi pystyy rakentamaan, ylläpitämään ja todellisuudessa käyttämään pysäyttämättä ominaisuustyötä. Seuraavassa on kehys, johon päädyimme kuukausien iteroinnin jälkeen.

Jokainen design-järjestelmäopas kertoo aloittavasi tokeneista, ja siihen on hyvä syy. Design-tokenit ovat atomisia arvoja, värejä, välilyöntejä, typografiaskaaloja, reunojen säteitä, joista kaikki muu on rakennettu. Ne ovat minkä tahansa koheesiivisen brändidentiteetin perusta, varmistaen visuaalisen johdonmukaisuuden kaikissa kosketuspisteissä. Määrittelimme omat CSS-mukavuusominaisuuksina yhdessä tiedostossa, sidottuna semanttisiin nimiin kuten --color-primary, --color-muted-foreground ja --radius-lg. Tämä tarkoitti, että mikä tahansa komponentti, joka viittasi näihin tokeneihin, mukautuisi automaattisesti, kun muutamme taustalla olevia arvoja.

Pienen tiimin avain insight on pitää token-setti armottoman pieni. Aloitimme vähemmän kuin neljäkymmentä tokenia, jotka kattivat värin, välilyönnit, typografian ja varjot. Suuret organisaatiot saattavat tarvita satoja, mutta löysimme, että kompakti joukko pakotti johdonmukaisuuden sen sijaan, että mahdollistaisi tuhansia hienovaraisia variaatioita. Kun kehittäjä hakee välilyöntiarvoa ja hänellä on vain kahdeksan vaihtoehtoa, hän luonnollisesti osuu oikeaan.

Vastasimme myös nimeämiskäytäntöön varhain, semanttinen kuvailevan sijaan. Sen sijaan että --blue-600 tai --spacing-16, käytimme --color-primary ja --space-md. Tämä irrotti tarkoituksen implementaatiosta ja teki tulevista uudelleensuunnitteluista triviaaleja. Kun asiakas halusi siirtyä sinisestä violettiin, muutamme kuusi riviä token-tiedostossa ja koko järjestelmä päivittyi.

Tokenien ollessa paikalla, käänsimme huomion komponentteihin. Omaksimme shadcn/ui:n perustaksemme, joka antoi meille kauniisti viimeistellyt, saavutettavat primitiivit, jotka on rakennettu Radix UI:n varaan. Sen sijaan että rakentaisimme kaiken alusta asti, laajensimme näitä primitiivejä tokenikerroksellemme ja projektikohtaisilla varianteilla. Esimerkiksi Button peri shadcnin saavutettavuuden ja näppäimistöhallinnan käyttäen samalla token-ajettua väripalettia ja välilyöntiä.

Komponenttiarkitektuurimme seuraa tiukkaa hierarkiaa. Alimmalla tasolla sijaitsevat UI-primitiivit, painikkeet, syöttökentät, merkit, työkaluvihkot, joilla ei ole liiketoimintalogiikkaa ja jotka hyväksyvät tyylittelyn propsien ja className-yhdistelyn kautta cn()-hyödykkeen avulla. Niiden yläpuolella sijaitsevat koostetut komponentit, hakupalkit, datataulun työkalupalkit, stat-kortit, jotka yhdistävät useita primitiivejä uudelleenkäytettäviksi kuvioiksi. Ylin taso on sivutasoisia osioita, jotka ovat spesifejä yhdelle näkymälle ja sijoitetaan viereen sivulle, joka käyttää niitä.

Tämä kolmitasoinen malli estää kaksi yleisintä design-järjestelmän epäonnistumista: komponentit, jotka ovat liian abstrakteja ollakseen hyödyllisiä, ja komponentit, jotka ovat liian spesifejä ollakseen uudelleenkäytettäviä. Kun kehittäjän tarvitsee rakentaa uuden ominaisuuden, hän koostaa sen keskimmäisestä tasosta. Kun keskimmäinen taso ei sisällä mitä hän tarvitsee, hän koostaa sen primitiiveistä ja, jos se osoittautuu uudelleenkäytettäväksi, edistää sitä.

Dokumentointi on se paikka, jossa useimmat pienien tiimien design-järjestelmät kuolevat. Tiimi rakentaa kauniita komponentteja, mutta ei koskaan kirjoita ylös, miten niitä käytetään, joten uudet tekijät (tai alkuperäiset tekijät kolmen kuukauden päästä) keksivät uudelleen olemassa olevat mallit. Ratkaisimme tämän tekemällä dokumentoinnista kehityksen sivutuotteen erillisen tehtävän sijaan.

Jokainen komponenttitiedosto sisältää JSDoc-lohkon, joka kuvaa sen tarkoitusta, props-liittymää ja käyttöesimerkkiä. Ylläpidämme myös elävää Storybook-eksemplaria, jossa jokainen komponentti renderöidään eristyksessä sen varianttien kanssa. Tärkein sääntö on, että mikään pull request ei yhdistä ilman vastaavaa tarinaa. Tämä kuulostaa tiukalta, mutta se vie vähemmän kuin viisi minuuttia per komponentti ja säästää tunteja tulevaa hämmennystä.

Pidämme myös kevyttä päätösloogia, yksinkertaista markdown-tiedostoa, joka kirjaa, miksi teimme tiettyjä valintoja. Miksi valitsimme 0,5 rem:n perussäteeksi? Miksi ensisijainen värimme käyttää oklch:tä hex:n sijaan? Nämä muistiinpanot ovat arvokkaita, kun palaat päätöksiin kuuden kuukauden kuluttua, ja ne auttavat perehdyttämään freelancerit tai urakoitsijat, jotka liittyvät tilapäisesti.

Funktionaaliset testit kertovat, laukeaako nappi onClick-käsittelijän. Visuaaliset regressiotestit kertovat, näyttääkö se edelleen oikealta. Design-järjestelmälle jälkimmäinen on yhtä tärkeä kuin ensimmäinen. Integrioimme Playwright-ruutukaappauksien vertailun CI-pipelineemme, jotta jokainen pull request luo visuaalisen diffin vaikuttavista komponenteista.

Asennus oli yksinkertaisempi kuin odotimme. Jokainen Storybook-tarina toimii samalla visuaalisena testitapauksena. CI-jobimme käynnistää headless-selaimen, ottaa ruutukaappauksia kaikista tarinoista ja vertaa niitä sitoutettuihin perusarvoihin. Jos komponentin ulkonäkö muuttuu, jopa yhdellä pikselillä, PR merkitään tarkasteltavaksi. Tämä sai kiinni kymmeniä hienovaraisia regressioita, jotka olisivat läpäisseet huomatta, kuten reunuksen värin muuttuminen, koska joku päivitti tokenin ilman alhaista vaikutusta.

Suoritamme myös visuaalisia testejä sekä vaaleassa että tummassa tilassa. Koska tokenimme määrittelevät erilliset arvot kummallekin tilalle, muutos, joka näyttää hyvältä vaaleassa tilassa, voi rikkoa tumman tilan kokonaan. Automaattiset ruutukaappaukset molemmissa tiloissa eliminoi koko luokan virheitä, jotka aiemmin pääsivät tuotantoon.

Kuuden kuukauden käytön jälkeen kahdellatoista asiakasprojektilla design-järjestelmämme oli kasvanut neljästäkymmenestä tokenista ja kymmenestäneljästä komponentista noin kahdeksankymmeneen tokeniin ja neljäkymmeneviiteen komponenttiin. Kysymys ei enää ollut siitä, pitäisikö skaalata, vaan siitä, miten skaalata menettämättä yksinkertaisuutta, joka teki järjestelmästä arvokkaan aluksi.

Otimme käyttöön osallistuslistan, jonka jokaisen uuden komponentin on läpäistävä ennen liittymistä kirjastoon: sen on käytettävä vain olemassa olevia tokenneja, sen on oltava saavutettava suoraan käyttöönotosta, sen on sisällettävä vähintään yksi Storybook-tarina ja sen on toimittava sekä vaaleassa että tummassa tilassa. Komponentit, jotka epäonnistuvat missä tahansa kriteerissä, pysyvät projektikohtaisessa koodikannassa, kunnes ne ovat vahvistuneet. Tämä portinvartijuus pitää yhteisen kirjaston luotettavana.

Aloitimme myös versioneerin järjestelmän semanttisilla julkaisuilla. Murtavat muutokset tokenissa tai komponentin propissa näkyvät suurina versionousina, joten projektit, jotka on sidottu vanhempaan versioon, eivät rikkoudumatta odottamatta. Tämä oli yliampuvaa kolmen hengen tiimille aluksi, mutta se maksoi dividendit, kun aloitimme jakamisen järjestelmän freelance-yhteistyökumppaneiden ja omistautuneiden kehitystiimien kanssa, jotka tarvitsivat vakausgarantioita.

Tärkein oppi on se, että design-järjestelmän ei tarvitse olla valtava ollakseen arvokas. Järjestelmämme on pieni yritysvaatimuksien mukaan, mutta se säästää meiltä arviolta kymmenen tuntia projektia kohti vähentyneen toiston, harvemman visuaalisen virheen ja nopeamman perehdytyksen ansiosta. Kolmen hengen tiimille, joka veloittaa projektikohtaisesti, nämä tunnit kääntyvät suoraan kannattavuudeksi.

Toinen oppi on optimoida adoptiota, ei täydellisyyttä. Design-järjestelmä, jota tiimisi ei käytä, on huonompi kuin ei design-järjestelmää lainkaan, koska se luo konsistenssin illuusion, vaikka koodikanta hajaantuu alapuolella. Jokainen tekemämme päätös, shadcn/ui:n valinnasta pohjaksi Storybook-tarinoiden pakottamiseen, oli suunnattu tekemään järjestelmästä vähiten vastustavan polun eikä ylimääräiseksi taakaksi.

Viimeiseksi käsittele design-järjestelmää tuotteena, jolla on oma tuotepolku, vaikka ainoat käyttäjät olisivat oma tiimisi. Priorisoi komponentit ja muuttujat, jotka poistavat eniten päällekkäisyyttä. Seuraa, mitkä komponentit ovat eniten käytettyjä, ja sijoita niiden laatuun. Design-järjestelmä ei ole koskaan valmis, mutta oikeilla prioriteeteilla jopa pieni tiimi voi ylläpitää sellaista, joka tekee enemmän kuin sen koko perusteella voisi olettaa. Jos harkitset design-järjestelmän rakentamista tuotteellesi ja haluat ohjeita siitä, mistä aloittaa, ota yhteyttä tiimiimme. Olemme kokeneet prosessin ja voimme auttaa sinua välttämään yleisimmät sudenkuopat.