Dizajn sistem s kojim web i mobilna verzija ostaju usklađene

Na svaki od ovih problema naišao sam na stvarnom projektu prije nego što sam počeo praviti CDS.

1. Web i mobilna verzija se razilaze

Na jednoj platformi za sastanke pet ljudi je osam mjeseci gradilo svako na svoju stranu, a zajednički sloj komponenti nikad nije nastao. U kodu su na kraju bila tri UI frameworka i četiri biblioteke za padajuće menije. Na jednom marketplaceu dashboardi i mobilna aplikacija jesu dijelili biblioteku, ali je javni sajt otišao svojim putem.

Uobičajeni alati razilaženje čine besplatnim. Platform.select stavlja granu gdje god je zgodno, a uslovni importi dozvoljavaju svakom fajlu da se odvoji. Ni jedno ni drugo ne ostavlja trag i ništa ne javi grešku kad ih bude sve više.

Šta CDS radi: razliku između platformi spušta jedan sloj ispod mjesta poziva, pa kod koji koristi komponentu nikad ne mora provjeravati na kojoj je platformi. createTheme() pretvara token u string koji se razrješava po platformi, pa se ${theme.color.fg.default} svuda ponaša isto. Iznad tog sloja su zajednički recepti stilova koje primjenjuju obje platforme, a razlikuju se samo po okidaču: :hover na webu, pressed na nativnoj strani. Svaka boja ima jednu definiciju, pa se boje ne mogu razići.

Rezultat se vidi na ekranu za prijavu: poziv komponente identičan je bajt po bajt u sve tri aplikacije.

b768aa14a346  apps/web/app/LoginScreen.tsx        Next.js 16, RSC
b768aa14a346  apps/spa/src/routes/LoginRoute.tsx  Vite SPA
b768aa14a346  apps/mobile/App.tsx                 React Native 0.87

LoginForm.tsx je jedan fajl od 135 linija, bez native blizanca. Sastavljen je od Box, Button, Card, Input i Text, a podjela po platformama dešava se unutar tih primitiva.

Razlikuje se omotač oko forme: na webu je centrira Box, na telefonu je smještena u SafeAreaView, a i URL API-ja je drugi. Te razlike potiču od platforme i proizvoda, a dizajn sistem ne dodaje nijednu svoju.

2. Figma i kod su dva izvora istine

Na ovo sam nailazio svuda. Na white-label proizvodu sa trideset brendova tokene je iz Figme izvozio plugin. To je bilo automatizovano, ali samo u jednom smjeru, pa su tokeni lako zaostajali za dizajnom. Na većini projekata Figmu i kod povezuje samo čovjek koji kopira hex vrijednosti.

Dizajn se mijenja po svom rasporedu, a kod po svom, pa su bez mehanizma koji ih povezuje tačni u istom trenutku samo slučajno.

Šta CDS radi: dizajn tokeni dolaze iz Figme automatski, preko MCP servera, a ručni put postoji kao rezerva. Sloj tokena je paket: core zavisi od tokens, a ui od core, pa izmjena ulazi na jednom mjestu i niko je ne mora tražiti i mijenjati po cijelom kodu.

3. Konvencije zapisane u README-u prestaju se poštovati

Na marketplaceu sa devetnaest repozitorija isti helper za red poruka bio je kopiran u sedam njih, i ništa u projektu to nije sprječavalo.

Konvenciju koja je samo zapisana ništa ne provodi, pa traje samo do prve sedmice u kojoj niko nema vremena za pažljiv pregled.

Šta CDS radi: svaka invarijanta ima svoju provjeru i build pada čim se neka prekrši.

To je ~2.450 linija provjera, plus ESLint plugin sa četiri pravila.

Arhitekturu na okupu drži pravilo da pattern ne smije imati .native varijantu. Provjerava ga pattern-native u verify-conventions.ts, zbog kojeg CI pada na 11 subjekata. Zbog tog pravila ekran za prijavu je ostao zajednički, i takav će ostati i kad ja prestanem paziti.

CI pokreće isti lanac umjesto da ga ponovo implementira: pnpm verify i tri prava builda, za Next, Vite i Metro. Pravi buildovi su tu zato što je next build jedino mjesto gdje se pravilo o 'use client' stvarno provjerava, a provjera koja radi samo u skripti mogla bi proći dok pravi build pada.

4. Svaki novi proizvod počinje sloj komponenti od nule

Na to sam naišao dok sam pravio tri vlastita proizvoda. Bez zajedničke biblioteke svaki bi dobio svoja dugmad, forme i modal, a tri proizvoda bi na kraju imala tri seta bugova.

Šta CDS radi: to je paket koji već koristi moja finansijska platforma, a na njemu je napravljen i ovaj sajt.

To je kompletan set komponenti: primitivi (Box, Text, Button, Input, Switch, Slider), forme (Form, Field, Select, RadioGroup, OTPInput, PasswordField), overlayi (Modal, Popover, Menu, Drawer, Tooltip, Toast), navigacija (Link, Tabs, AppBar, TabBar, Breadcrumbs) i podaci (Table, Pagination, Accordion).

Izmjerio sam šta radi sideEffects: false: ulaz koji uvozi samo Box spao je sa 253.075 B na 241.309 B. Zamka je zapisana odmah pored te postavke. @cds/tokens se ne smije označiti kao false, jer se tada izbaci reset.css i raspored se raspadne bez ijedne greške. Nijedan alat u lancu tu grešku ne prijavljuje, pa bilješka stoji tamo gdje će sljedeći čovjek pogledati.

5. Naivno postavljena tema za više brendova umnožava varijante

Jedan građevinski proizvod prodaje se pod više od trideset brendova. Da svaka komponenta za svaki brend dobije zasebnu verziju, njegovih sto komponenti pretvorilo bi se u tri hiljade varijanti koje treba ažurirati.

Šta CDS radi: komponente se na boje pozivaju samo preko imena tokena. Brend se dodaje novim setom vrijednosti tokena, a nijedna komponenta se ne mijenja. Taj pristup se već dokazao na građevinskom proizvodu, a u CDS-u je dio arhitekture od prvog commita.

38 od 74 komponente ima native blizanca, što zvuči kao da se pola sistema razišlo. U stvari su blizanci gotovo svi u jednom sloju:

33 od 38 blizanaca ne uvozi nijednu drugu komponentu. To su listovi koji prevode jedan element platforme, div u View ili input u TextInput, i ne rade ništa više. Podjela je na dnu stabla, i zato ništa iznad nje ne mora znati za nju.

Blizanac je dozvoljen samo iz tri razloga, a dva od njih uopšte nisu vezana za elemente.

Drugačiji element. Ovo važi za 33 od 38 blizanaca. Promjena je mehanička i ograničena, a komponente iznad nje je ne vide.

Drugačiji događaj. Tooltip.native postoji zato što na ekranu na dodir nema hovera, pa je okidač dugi pritisak, i to namjerno bez odgode. Na webu delayShow sprječava treperenje dok kursor prelazi preko reda ikona. Dugi pritisak već pokazuje namjeru, pa bi zbog odgode tooltip samo djelovao pokvareno.

Drugačiji prozor. NativeSelect.native postoji zato što sistemski picker mora biti iznad tastature, a do zasebnog native prozora može se doći samo kroz RN Modal. Zajednički Portal predaje stablo hostu, pa bi lista ostala ispod tastature. Ta greška se vidi samo na uređaju, i to samo unutar forme.

Preostala tri blizanca uvoze tačno po jednu komponentu i ne mijenjaju sliku.

Nijedan pattern nema blizanca, i to se provjerava: zbog pattern-native u sloju provjera CI pada na 11 subjekata čim se blizanac pojavi. Modal pokazuje da i težak slučaj može ostati zajednički, s portalom, upravljanjem fokusom i mjerenjem, a LoginForm da to može i cijeli ekran.

Kad je patternu trebala podjela, ostavio sam pattern zajedničkim, izdvojio primitiv čija je jedina razlika bio element i blizanca dao tom primitivu. To se pod pritiskom desilo četiri puta, i zato to smatram principom. Među izdvojenim primitivima su PositionedLayer, DialogActionsRow i MenuSeparator.

Pregledao sam svih 75 komponenti, koliko ih je sistem tada imao, i našao 188 problema. Svi se svode na tri osnovna uzroka, a nijedan alat u lancu ih ne uhvati: typecheck, ESLint i build prolaze.

Labela na elementu bez uloge. accessibilityLabel na čvoru bez uloge ne čita nijedna platforma. Na webu aria-label na golom div ne radi ništa, jer ARIA specifikacija ne dozvoljava da generička uloga dobije ime koje zada autor. Na nativnoj strani se accessibilityLabel bez accessible nikad ni ne pročita. Ovu grešku imalo je devet komponenti, a ispravan obrazac je već postojao u istom paketu, gdje Icon svoju labelu uvijek uparuje s role="img".

Naslijeđeni prop koji nikad ne stigne do elementa. Omit<BoxProps, …> ostavlja id, a11yRole, accessibilityLabel i pointerEvents u ugovoru, ali grana koja ih ne destrukturira prosljeđuje ih u ...box, a odatle u style helper koji vraća samo $ propse. Ništa se ne buni, jer je izostavljen prop samo undefined, a to je validna vrijednost. Četiri srodne komponente povezale su tri različita podskupa tih propsa: jedna sva četiri, dvije po dva, a jedna nijedan.

Komentar koji opisuje raniju verziju sistema. Bilješka opisuje neko ograničenje, ograničenje se kasnije ukloni, a bilješka ostane. To je najpodmuklija vrsta greške, jer čitalac komentaru vjeruje i nikad ne pokuša ono što je već mjesecima moguće. Još gora varijanta je JSDoc blok pomaknut za jedan prop, pa jedan prop ima dva opisa, a njegov susjed nijedan. Taj tekst se generiše u katalog, gdje postaje javna dokumentacija.

Važnije od broja 188 je razumjeti zašto su tri alata šutila, jer od toga zavisi hoće li sljedeća greška iste vrste biti uhvaćena. Dva od tri uzroka sada pokrivaju pravila provjere, pa njihovo otkrivanje više ne zavisi od pregleda.

Da to radim ponovo, pregled bih uradio kad je sistem imao 30 komponenti, mnogo prije nego što ih je bilo 75. Ista tri uzroka postojala su i tada, a ispravka bi bila za red veličine jeftinija. Svih 188 problema je ispravljeno, a pokrivenost za aria-label i tabindex još je otvorena.