Designrendszer felépítése háromfős csapattal

Amikor háromfős csapat vagy, és egyszerre több tucat ügyfélprojektet kezelsz, a következetlenség válik a legdrágább problémáddá. Észrevettük, hogy ugyanaz a minta ismétlődik a GRADAX weboldaltervezési projektjeiben: egy gomb az egyik módon stílusozva a kezdőlapon, egy másik módon az árazási oldalon, és egy harmadik módon az irányítópulton belül. Minden eltérés időbe került a QA során, vizuális hibákat vezetett be, és aláásta azt a csiszolt érzést, amelyet ügyfeleink elvártak. Valaminek változnia kellett.

A designrendszerbe való befektetés döntését nem ambíció vagy trendkövetés vezérelte. A fájdalom vezérelte. Minden új projekt körülbelül 30%-át arra fordítottuk, hogy olyan komponenseket hozzunk létre újra, amelyek valamilyen formában már léteztek máshol a kódbázisunkban. Egy designrendszer lehetővé tenné, hogy a döntéseinket egyszer kodifikáljuk és mindenhol újrahasználjuk, az ismétlődő munkát versenyelőnnyé alakítva.

De a designrendszerekről szóló szakirodalmat olyan cégek történetei uralják, amelyeknek húsz vagy több mérnökből álló dedikált platformcsapataik vannak. Szükségünk volt egy pragmatikus megközelítésre, amelyet egy háromfős csapat fel tud építeni, fenn tud tartani és ténylegesen használni tud anélkül, hogy a funkciófejlesztés leállna. Az alábbiakban azt a keretrendszert mutatjuk be, amelyre hónapoknyi iteráció után jutottunk.

Minden designrendszer-útmutató azt mondja, hogy kezdd a tokenekkel, és jó okkal. A design tokenek az atomi értékek, színek, térközök, tipográfiai skálák, saroklekerekítések, amelyekből minden más épül. Ezek képezik minden egységes márkaidentitás alapját, biztosítva a vizuális következetességet minden érintkezési ponton. A mieinket CSS egyéni tulajdonságokként definiáltuk egyetlen fájlban, szemantikus nevekre leképezve, mint a --color-primary, --color-muted-foreground és --radius-lg. Ez azt jelentette, hogy bármely komponens, amely ezekre a tokenekre hivatkozik, automatikusan alkalmazkodik, amikor megváltoztatjuk a mögöttes értékeket.

A kis csapat kulcsfontosságú felismerése, hogy a tokenkészletet könyörtelenül kicsiben tartsuk. Kevesebb mint negyven tokennel kezdtük, amelyek lefedték a színt, térközt, tipográfiát és árnyékokat. A nagy szervezeteknek több százra lehet szükségük, de úgy találtuk, hogy egy kompakt készlet a következetességet kényszeríti ki, ahelyett hogy ezer finom variációt tenne lehetővé. Amikor egy fejlesztő egy térközértékért nyúl, és csak nyolc lehetősége van, természetesen a megfelelőt választja.

Korán kialakítottunk egy elnevezési konvenciót is, a szemantikusat a leíró helyett. A --blue-600 vagy --spacing-16 helyett a --color-primary és --space-md neveket használtuk. Ez elválasztotta a szándékot a megvalósítástól, és triviálissá tette a jövőbeli újratervezéseket. Amikor egy ügyfél a kékről a lilára akart váltani, hat sort változtattunk meg a tokenfájlban, és az egész rendszer frissült.

A tokenek bevezetése után a komponensekre terelődött a figyelem. A shadcn/ui-t választottuk alapnak, amely gyönyörűen kidolgozott, akadálymentes alapvető elemeket biztosított Radix UI-ra építve. Nem mindent kezdtünk nulláról, hanem kibővítettük ezeket az alapvető elemeket a saját tokenrétegünkkel és projektspecifikus variánsokkal. Egy gomb például örökölte a shadcn akadálymentességét és billentyűzetkezelését, miközben a saját tokenalapú színpalettánkat és térközbeállításainkat használta.

Komponensarchitektúránk szigorú hierarchiát követ. Legalul az UI-alapvető elemek találhatók: gombok, bemeneti mezők, jelvények, tooltip-ek, amelyek nem tartalmaznak üzleti logikát, és stílusozásukat propokon, valamint className-összefésüléssel a cn() segédfüggvénnyel kapják. Felettük a kombinált komponensek állnak: keresősávok, adattábla-eszköztárak, statisztikai kártyák, amelyek több alapvető elemet kombinálnak újrafelhasználható mintákká. Legfelül az oldalszintű szakaszok helyezkednek el, amelyek egyetlen nézetre jellemzőek, és az őket használó oldal mellett, colocated módon találhatók.

Ez a háromszintű modell megakadályozza a két leggyakoribb designrendszer-hibát: a túl absztrakt, így használhatatlan komponenseket, és a túl specifikus, így nem újrafelhasználható komponenseket. Amikor egy fejlesztő új funkciót kell, hogy készítsen, azt a középső szint elemeiből állítja össze. Ha a középső szinten nincs meg, amire szüksége van, akkor alapvető elemekből komponálja össze, és ha bizonyulthatóan újrafelhasználható, előlépteti.

A dokumentáció az, ahol a legtöbb kiscsapatos designrendszer elhalálozik. A csapat gyönyörű komponenseket készít, de sosem írja le, hogyan kell használni őket, így az új közreműködők (vagy az eredeti szerzők három hónappal később) újra feltalálják a már létező mintákat. Ezt úgy oldottuk meg, hogy a dokumentációt a fejlesztés melléktermékévé tettük, nem külön feladattá.

Minden komponensfájl tartalmaz egy JSDoc blokkot, amely leírja a célját, a props interfészét és egy használati példát. Emellett fenntartunk egy élő Storybook példányt, ahol minden komponenst izoláltan, a variánsaival együtt jelenítünk meg. A kritikus szabály, hogy egyetlen pull request sem kerül merge-re a hozzá tartozó story nélkül. Ez szigorúnak hangzik, de kevesebb mint öt percet vesz igénybe komponensenként, és órákat spórol a jövőbeli félreértésekkel.

Vezetünk továbbá egy könnyűsúlyú döntési naplót is, egy egyszerű markdown fájlt, amely rögzíti, miért hoztunk bizonyos döntéseket. Miért a 0,5 rem-t választottuk alap lekerekítésnek? Miért az oklch-t használjuk az elsődleges színünknél a hex helyett? Ezek a jegyzetek felbecsülhetetlenek, amikor hat hónappal később újra elővesszük a döntéseket, és segítenek az ideiglenesen csatlakozó szabadúszók vagy alvállalkozók bevezetésében.

A funkcionális tesztek azt mondják meg, hogy egy gomb elindítja-e az onClick kezelőjét. A vizuális regressziós tesztek pedig azt, hogy még mindig jól néz-e ki. Egy designrendszer esetében az utóbbi ugyanolyan fontos, mint az előbbi. Beépítettük a Playwright képernyőképes összehasonlításokat a CI folyamatunkba, így minden pull request vizuális diffet generál az érintett komponensekről.

A beállítás egyszerűbb volt, mint vártuk. Minden Storybook story egyben vizuális teszteset is. CI feladatunk elindít egy headless böngészőt, képernyőképeket készít minden storyról, és összehasonlítja őket a commitolt alapvonalakkal. Ha egy komponens megjelenése megváltozik, akár egyetlen pixelnyit is, a PR-t felülvizsgálatra jelöljük. Ez több tucat finom regressziót fogott el, amelyek észrevétlenül kerültek volna kiadásra, például egy szegélyszín megváltozását, mert valaki frissített egy tokent anélkül, hogy felismerte volna a tovagyűrűző hatást.

A vizuális teszteket világos és sötét módban is futtatjuk. Mivel a tokenjeink külön értékeket határoznak meg mindkét módhoz, egy világos módban jól kinéző változás teljesen tönkreteheti a sötét módot. A képernyőképek automatizálása mindkét módban kiküszöbölte a hibák egy egész kategóriáját, amelyek korábban eljutottak a produkcióba.

Hat hónap használat után, egy tucat ügyfélprojektben, a designrendszerünk negyven tokenről és tizenkét komponensről körülbelül nyolcvan tokenre és negyvenöt komponensre nőtt. A kérdés már nem az volt, hogy skálázzunk-e, hanem hogy hogyan skálázzunk anélkül, hogy elveszítenénk azt az egyszerűséget, amely a rendszert értékessé tette.

Bevezettünk egy hozzájárulási ellenőrzőlistát, amelyet minden új komponensnek teljesítenie kell, mielőtt bekerül a könyvtárba: csak meglévő tokeneket használhat, alapból akadálymentesnek kell lennie, legalább egy Storybook-ötletet (story) kell tartalmaznia, és világos és sötét módban is működnie kell. Azok a komponensek, amelyek bármelyik kritériumnak nem felelnek meg, a projektspecifikus kódbázisban maradnak, amíg meg nem szilárdulnak. Ez a kapuőrzés tartja megbízhatónak a megosztott könyvtárat.

Elkezdtük a rendszer verziózását szemantikus kiadásokkal is. A token vagy komponens propjának törő (breaking) változásai főverzió-emelésként jelennek meg, így a régebbi verzióhoz rögzített projektek nem törnek el váratlanul. Ez eleinte túlzás volt egy háromfős csapatnak, de megtérült, amikor elkezdtük megosztani a rendszert szabadúszó közreműködőkkel és dedikált fejlesztőcsapatokkal, akiknek stabilitási garanciákra volt szükségük.

A legfontosabb tanulság, hogy egy design-rendszernek nem kell hatalmasnak lennie ahhoz, hogy értékes legyen. Rendszerünk a vállalati mércéhez képest kicsi, de becsléseink szerint projektenként tíz órát spórol meg a csökkent duplikációval, a kevesebb vizuális hibával és a gyorsabb bevezetéssel. Egy projektre számlázó háromfős csapat számára ezek az órák közvetlenül a jövedelmezőségbe fordulnak át.

A második tanulság, hogy az elfogadottságra optimalizáljunk, ne a teljességre. Egy olyan design-rendszer, amelyet a csapat nem használ, rosszabb, mint ha nincs is design-rendszer, mert a konzisztencia illúzióját kelti, miközben a kódbázis alatta széttart. Minden döntésünk, a shadcn/ui alapként való választásától a Storybook-storyk kötelezővé tételéig, arra irányult, hogy a rendszer a legkisebb ellenállás útja legyen, ne pedig extra teher.

Végül tekintse saját ütemtervvel rendelkező termékként a design-rendszert, még akkor is, ha az egyetlen felhasználó a saját csapata. Részesítse előnyben azokat a komponenseket és tokeneket, amelyek a legtöbb duplikációt szüntetik meg. Kövesse nyomon, mely komponenseket használják leggyakrabban, és fektessen a minőségükbe. Egy design-rendszer soha nem készül el, de a megfelelő prioritásokkal még egy kis csapat is fenntarthat egy olyat, amely jóval a súlya felett teljesít. Ha fontolgatja, hogy design-rendszert épít a termékéhez, és útmutatásra van szüksége a kezdéshez, vegye fel a kapcsolatot csapatunkkal, végigmentünk a folyamaton, és segíthetünk elkerülni a leggyakoribb buktatókat.