11 gru 2025·6 min
Spójne UI w aplikacjach React z użyciem tokenów projektowych i reguł
Dowiedz się, jak używać tokenów projektowych i reguł komponentów, aby generowane ekrany React miały spójne odstępy, typografię i zachowanie formularzy.
Dowiedz się, jak używać tokenów projektowych i reguł komponentów, aby generowane ekrany React miały spójne odstępy, typografię i zachowanie formularzy.
Niespójność UI zwykle objawia się w drobnych detalach, które wydają się nie na miejscu, gdy klikasz po aplikacji. Na jednej stronie padding jest obfity, inna wydaje się ściśnięta. Nagłówki skaczą między rozmiarami, przyciski zmieniają kształt i kolor, a ten sam input zachowuje się inaczej w zależności od ekranu.
Najczęściej przyczyną rozjazdu są kilka podstawowych rzeczy:
To jest powszechne, gdy ekrany są generowane na podstawie oddzielnych promptów. Każdy prompt to w praktyce świeży start, więc model wypełnia brakujące decyzje zgadując. Nawet „użyj nowoczesnego stylu” zostawia setki drobnych wyborów: 8px vs 12px gapy, 14px vs 16px tekst akapitowy, kiedy pokazywać błędy, jak wygląda przycisk primary.
Możesz ręcznie poprawić dwie lub trzy strony, ale to nie skalowalne. Gonisz jednorazowe poprawki CSS, kopiujesz style między plikami i znowu naprawiasz formularze. Reguły żyją w twojej głowie, nie w projekcie.
Wyobraź sobie, że dziś generujesz ekran logowania, a jutro ekran profilu. Jeśli jeden pokazuje błędy tylko po submit, a drugi po blur, użytkownicy to zauważą. Jeśli wysokość przycisku primary zmienia się między ekranami, aplikacja będzie sprawiać wrażenie zszytej z kawałków.
Spójność staje się domyślna, gdy każdy ekran podąża za tym samym wspólnym systemem: tokeny projektowe (odstępy, typografia, kolory) plus mały zestaw zasad dla komponentów i formularzy.
Design tokens to proste, nazwane wartości, które powtarzasz w całym UI. Zamiast prosić o „komfortowy padding” na każdym ekranie, używasz tokena takiego jak space-4. Zamiast „lekko zaokrąglony” używasz radius-md. Nazwa pozostaje stabilna, nawet jeśli później zmienisz, do czego się odwołuje.
Tokeny to zbiór decyzji, które chcesz, żeby każdy ekran dzielił. Usuwają gust i zgadywanie — a to właśnie powoduje drift, gdy generujesz lub budujesz nowe strony.
Typowe tokeny obejmują odstępy, typografię, kolory, kształt i niewielką ilość elevacji. Korzyść jest praktyczna: nagłówek zawsze używa tego samego rozmiaru, karta zawsze ma ten sam padding, a przycisk primary zachowuje ten sam kolor i promień.
Tokenizuj rzeczy, które wpływają na ogólne odczucie produktu: skala odstępów, rozmiary fontów i wysokości linii, podstawowe kolory (tekst, tło, primary, danger, border) oraz niewielki zestaw promieni narożników.
Pozostaw elastyczne wybory zależne od treści, takie jak długość copy, który ikon użyć czy czy sekcja potrzebuje dwóch czy trzech kart.
Gdy generujesz ekrany (w tym przy użyciu narzędzi typu Koder.ai), podanie małego zestawu tokenów na początku zmniejsza pole do zgadywania i sprawia, że wynik jest zauważalnie bardziej spójny.
Zestaw tokenów to po prostu krótkie menu dozwolonych wartości. Im mniejszy, tym lepiej, bo pozostawia mniej miejsca na losowe wybory, ale musi obejmować podstawy, które powodują, że ekrany wydają się niepasujące.
Zacznij od odstępów. Wybierz jedną skalę i używaj jej wszędzie do paddingu, gapów i layoutu. Zestaw typu 4, 8, 12, 16, 24, 32 pokrywa większość UI. Jeśli projekt potrzebuje 10px lub 18px, zaokrąglaj do najbliższego tokena zamiast wprowadzać nowe liczby.
Następnie zdefiniuj domyślną typografię, żeby nagłówki i tekst bazowy przestały dryfować. Nie potrzebujesz rozbudowanego systemu typograficznego — potrzebujesz jasnych, powtarzalnych kroków.
Kompaktowy zestaw, który pozostaje użyteczny bez nadmiernego rozrostu:
Dostępność też należy do systemu. Zdefiniuj styl outline dla fokusa (kolor, grubość, offset), żeby użytkownicy klawiatury mieli spójne stany fokusa. Ustal minimalny rozmiar targetu dotykowego (np. 44x44) dla urządzeń mobilnych. Ogranicz kolory tekstu do małego, zaufanego zestawu, by kontrast był przewidywalny.
Jeśli przyciski czasem wyglądają ściśnięte, często dlatego, że jeden ekran użył paddingu 10, a inny 12. Z tokenami możesz określić: „Przyciski: paddingY=8, paddingX=16, radius=12, token outline dla fokusa, min-height 44.” Gdy liczby są ustalone, generator przestaje improwizować.
Tokeny ustalają liczby. Zasady komponentów ustalają przyzwyczajenia.
Wybierz mały zestaw podstawowych komponentów i traktuj je jako jedyne bloki budujące ekrany. Trzymaj je nudne i wielokrotnego użytku: Button, Input, Select, Checkbox, Card. Możesz dodać TextArea i Modal, ale powinny podążać tym samym systemem (etykiety, odstępy, stany).
Następnie ogranicz warianty i zdefiniuj, kiedy są dozwolone. Na przykład: Button ma primary, secondary i danger. Primary to główna akcja na ekranie (zwykle jedna). Secondary to anuluj lub akcje niskiego priorytetu. Danger tylko dla destrukcyjnych akcji jak usunięcie. Jeśli wariantu nie da się uzasadnić, domyśl do secondary.
Reguły odstępów zapobiegają subtelnemu dryfowi. Zdefiniuj domyśły wewnątrz komponentów: padding Buttona, wysokość Inputa, odstęp etykieta→pole, standardowy gap między ułożonymi polami. Dodaj kilka reguł layoutu: Karty mają stały padding wewnętrzny i spójny odstęp nagłówek/treść; Modal używa tych samych kroków szerokości i wyrównania stopki.
Na koniec, ustal stany jako niepodlegające negocjacjom, bo to tutaj UI często zaczyna wyglądać losowo:
Gdy generujesz ekran z wieloma formularzami (np. „Utwórz projekt”), te reguły zapobiegają mieszanym rozmiarom przycisków, przesuwaniu pozycji etykiet czy jednorazowej „specjalnej” karcie, która pojawia się tylko na jednej stronie.
Nawet przy stabilnych wizualach, wiele skarg typu „to wydaje się nie w porządku” pochodzi z zachowania formularzy. Jeśli każdy ekran obsługuje etykiety, błędy i fokus inaczej, użytkownicy to odczują jako niespójność.
Wybierz jeden wzorzec formularza i stosuj go wszędzie: etykieta, znacznik opcjonalne/wymagane, tekst pomocniczy, potem tekst błędu. Trzymaj też spójne formułowanie (np. etykiety w sentence case, krótki tekst pomocniczy i komunikaty błędów zaczynające się od czasownika).
Reguły, które zapobiegają większości dryfów:
Zamknij rozmiary i layout, by ekrany nie „oddychały” inaczej. Określ jedną wysokość inputu, jedną wysokość przycisku i domyślną szerokość pola. Na desktopie wyrównaj pola do spójnej siatki i układaj etykiety nad inputami. Na mobile rób pola na pełną szerokość i unikaj formularzy dwukolumnowych, chyba że jest to naprawdę konieczne.
Prosty przykład: ekran „Utwórz projekt” może mieć Name, Region i Description. Nawet jeśli Region to select, traktuj go jak każde inne pole: ta sama wysokość, ta sama pozycja etykiety, ta sama linia błędu. Jeśli użytkownik poda submit z pustym Name, focus przejdzie do Name, błąd pojawi się pod nim, a layout pozostanie stabilny.
Jeśli generujesz ekrany w Koder.ai, umieść te reguły formularzy w promptcie raz i używaj ich przy kolejnych funkcjach, żeby każdy nowy formularz działał tak samo bez powtarzających się poprawek.
Traktuj swój prompt jak mały kontrakt UI. Trzymaj go krótko, konkretnie i możliwie wielokrotnego użytku, żeby każdy nowy ekran od razu trzymał te same odstępy, typografię, komponenty i zachowania.
Praktyczny wzorzec to wklejenie kompaktowej specyfikacji UI na początku żądania, a następnie opisanie ekranu prostym językiem.
UI SPEC (apply to every screen)
Tokens:
- Spacing: 4, 8, 12, 16, 24, 32
- Radius: 8
- Typography: H1 24/32, H2 18/26, Body 14/20
- Colors: text, muted, bg, primary, danger (no custom hex)
Components (must use): PageShell, Section, Card, Button, Input, Select, TextArea, FormRow, HelperText, Toast
Layout rules:
- Page padding: 24 desktop, 16 mobile
- Section spacing: 24
- Card padding: 16
- Grid: 12 cols desktop, 4 cols mobile, gap 16
Do:
- Reuse components and tokens only
- Keep labels above inputs, helper text below
Do not:
- Invent new spacing values, font sizes, or one-off CSS
- Mix different button heights or input styles
If a new component is needed:
- Extend an existing component pattern and document it in the output
- Do not create new visual styles outside tokens
Po specyfikacji dodaj kilka checków akceptacyjnych, które wykryją dryft wcześnie:
Jeśli używasz generatora chatowego, trzymaj spec stabilną między zapytaniami. Zmienianie jej za każdym razem niweczy sens.
Napisz kontrakt UI zanim wygenerujesz cokolwiek: mały zestaw tokenów (odstępy, typografia, kolory, radius, cienie) plus krótki inwentarz komponentów (Button, Input, Select, Card, Modal, Table, Toast). Jeśli jakiś token lub komponent brak, model go wymyśli i twój UI zacznie driftować.
Potem stwórz jeden ekran referencyjny, który przetestuje reguły. Strona z dużą ilością formularzy to dobry test, bo zawiera nagłówki, tekst pomocniczy, błędy walidacji, przyciski primary i secondary oraz toast sukcesu. Traktuj ten ekran jako bazę.
Stamtąd buduj nowe ekrany, komponując to, co już zdefiniowałeś. Nie proś o „świeże stylowanie”. Proś o te same Card, tę samą skalę odstępów, te same kroki typografii i ten sam wzorzec pól.
Prosty workflow:
Jeśli „Search users” ma ciaśniejsze odstępy niż referencja, nie poprawiaj ręcznie marginesów. Zaktualizuj tokeny odstępów lub regułę paddingu Card raz, a potem wygeneruj ponownie.
Jeśli pracujesz w Koder.ai, snapshots i rollback pomagają: zablokuj bazę, eksperymentuj bezpiecznie i szybko przywróć, jeśli zmiana zaczyna wprowadzać drift.
Najszybsza droga do utraty spójności to traktowanie tokenów i zasad jak sugestii. Małe wyjątki mnożą się przy kolejnych ekranach.
Jedna pułapka to zmiana skali odstępów w trakcie projektu. Wczesne ekrany używają 8, 16, 24. Nowy ekran wprowadza 10 i 18 „bo tak wygląda lepiej”. Teraz drift jest dozwolony, a stare ekrany nigdy nie zostaną zaktualizowane.
Innym źródłem rozjazdu jest pozwolenie generatorowi na wymyślanie nowych stylów komponentów. Jeśli nie powiesz „istnieją tylko te warianty przycisków”, może stworzyć nowy radius albo inny padding inputa na jednym ekranie.
Stany to kolejny częsty błąd. Loading, empty i error states często zmieniają odstępy i zachowanie. Jeśli dodajesz je na końcu, zwykle powstają pośpieszne wzorce, które nie pasują do reszty.
Uważaj też na zbyt ogólnikową specyfikację: „zrób nowoczesny z miękkimi cieniami” jest niejasne, a reguły zachowania typu „błędy pokazuj pod polem”, „disabled przyciski zachowują style fokusa” i „Enter submituje tylko w ostatnim polu” są konkretne i powtarzalne.
Jeśli chcesz lekki blok zabezpieczający do wklejenia w prompt, trzymaj go krótko:
Zanim zmergujesz wygenerowany ekran, zrób dwuminutowe sprawdzenie.
Zacznij od odstępów. Szukaj losowych wartości jak 13px lub jednorazowych marginesów dodanych „żeby się zmieściło”. Jeśli używasz tokenów, każdy gap powinien pochodzić z zatwierdzonego zestawu, łącznie z gutterami, paddingiem kart i odstępami między polami formularzy.
Następnie sprawdź typografię względem skali. Nagłówki powinny schodzić stopniowo. Tekst body nie powinien zmieniać rozmiaru między podobnymi sekcjami. Wysokość linii też ma znaczenie, zwłaszcza na gęstych ekranach jak strony ustawień.
Przejrzyj przyciski. Wariantu i rozmiary powinny trzymać się reguł: primary dla głównej akcji, secondary dla mniej ważnych działań, danger tylko gdy naprawdę usuwa. Wysokość przycisku, umiejscowienie ikony i styl etykiety powinny pasować.
Dla formularzy spójność to przede wszystkim struktura. Etykiety są w jednym miejscu, wskaźniki wymaganych pól według jednej reguły, pomoc i błędy się nie ścierają, a błędy pojawiają się w przewidywalnym miejscu.
Krótka lista kontrolna:
Na koniec zrób szybki przegląd mobilny. Zmień szerokość i potwierdź, że layout dopasowuje się bez wymyślania nowych rozmiarów fontów czy odstępów.
Wyobraź sobie prosty onboarding: trzy ekrany (Profile, Preferences, Confirm) oraz później strona Settings. Chcesz, by każdy ekran sprawiał wrażenie, że wyszedł od tego samego projektanta, nawet jeśli był generowany w oddzielnych przebiegach.
Zanim cokolwiek wygenerujesz, podaj mały zestaw tokenów i kilka reguł komponentów:
TOKENS
- spacing: xs=4, sm=8, md=12, lg=16, xl=24
- radius: sm=8, md=12
- type: body=14/20, title=20/28, label=12/16
- layout: pageMax=960, sectionGap=24, fieldGap=12
COMPONENT RULES
- Page: max width=pageMax, padding=xl, sectionGap between blocks
- Card: padding=lg, radius=md
- Field: label above, helper below, fieldGap between fields
- Button row: primary on right, gap=sm
- Errors: shown under field, same copy style, no alerts
Teraz wygeneruj „Profile” i „Preferences” osobno. Ponieważ oba ekrany muszą używać Page, Card, Field i Button row zgodnie z definicją, otrzymują te same marginesy, odstęp etykieta→pole i umiejscowienie przycisków. Krok Confirm też pasuje, nawet jeśli ma więcej tekstu tylko do odczytu.
Zachowanie formularzy to miejsce, gdzie drift często się wkrada, więc zdefiniuj je raz i używaj: submit zablokowany dopóki nie jest ważny, błędy inline tylko po blur lub submit, Enter submituje tylko na ostatnim kroku, a Back nigdy nie czyści już wpisanych wartości.
Gdy potrzebujesz nowego elementu UI, nie pozwól modelowi improwizować. Dodaj jedną regułę, a potem wygeneruj ponownie z myślą o ponownym użyciu:
Przekształć tokeny i zasady w wielokrotnego użytku spec, którego rzeczywiście będziesz używać. Jeśli jest za długi, by go wklejać, nie będzie przestrzegany.
Praktyczna specyfikacja zwykle zawiera: tabelę tokenów (odstępy, typografia, radii, kolory), krótki zestaw reguł komponentów (przyciski, inputy, karty, nagłówki), zasady zachowania formularzy (timing walidacji, błędy, disabled/loading), domyśły layoutu (padding strony, max width, odstępy sekcji) i krótką listę „nigdy tego nie rób” (losowe marginesy, ad-hoc rozmiary fontów).
Potem wypracuj jedną rutynę: najpierw aktualizuj spec, nie pojedyncze piksele.
Jeśli używasz Koder.ai (koder.ai), tryb planowania jest dobrym miejscem, by powtórzyć i potwierdzić spec przed generowaniem UI. Gdy chcesz spróbować alternatyw, snapshots i rollback pozwalają eksplorować bez utraty stabilnej bazy.
Ponieważ każde żądanie wygenerowania ekranu zaczyna się od zera. Jeśli nie podasz wspólnego systemu, generator sam dopisuje brakujące szczegóły — odstępy, rozmiary czcionek, padding przycisków, cienie i zachowanie formularzy — więc drobne różnice kumulują się między stronami.
Design tokens to nazwane, wielokrotnie używane wartości dla takich rzeczy jak odstępy, rozmiary czcionek, kolory czy promienie narożników.
Zamiast pisać „wygodny padding” używasz czegoś takiego jak space-md. Nazwa pozostaje niezmienna, a każdy ekran korzysta z tych samych decyzji, więc UI przestaje się rozjeżdżać.
Zacznij mało i obejmij tylko to, co powoduje widoczny drift:
Wklej kompaktowy blok specyfikacji UI na początku każdego zapytania i traktuj go jak kontrakt:
Potem opisujesz ekran poniżej. Klucz: utrzymuj specyfikację niezmienioną między ekranami.
Tokeny definiują liczby; zasady komponentów definiują nawyki. Przydatne reguły to:
Reguła domyślna: jeśli wariantu nie da się uzasadnić, wróć do standardowego.
Wybierz jeden wzorzec i stosuj go wszędzie:
To unika częstego problemu: jeden ekran waliduje przy blur, inny tylko przy submit.
Zdefiniuj kilka nienegocjowalnych reguł stanów:
Jeśli nie określisz stanów, każdy ekran wymyśli swoje własne wzorce.
Nie pozwól na improwizację stylów. Dodaj nowy komponent jako udokumentowane rozszerzenie istniejącego wzorca:
Jeśli nie potrafisz opisać go tokenami, zwykle jest za bardzo niestandardowy i spowoduje drift.
Stwórz jeden „referencyjny” ekran, który testuje system (dobrze sprawdza się strona z wieloma formularzami), potem używaj tej samej specyfikacji dla każdego nowego ekranu.
W Koder.ai możesz użyć planning mode, aby powtórzyć i potwierdzić spec, oraz snapshots i rollback, żeby zachować stabilną bazę przy eksperymentach.
Szybkie sprawdzenie przed akceptacją wygenerowanego ekranu:
Jeśli coś jest nie tak, zaktualizuj spec/tokny i wygeneruj ponownie — nie poprawiaj pojedynczych marginesów ręcznie.
Jeśli potrzebujesz „nowej” wartości, zaokrąglaj do najbliższego tokena zamiast wymyślać 10px lub 18px.