Spójne UI w aplikacjach React z użyciem tokenów projektowych i reguł

Dlaczego wygenerowane ekrany React często wyglądają niespójnie

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:

• Odstępy: padding, gapy i rytm sekcji się różnią
• Typografia: rozmiary fontów, grubości i wysokości linii nie są stałe
• Komponenty: przyciski, karty, obramowania i cienie nieznacznie się różnią
• Formularze: moment walidacji, pozycjonowanie błędów i stany disabled się różnią

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.

Tokeny projektowe prostym językiem

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ń.

Co warto tokenizować, a co zostawić elastyczne?

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.

Wybierz zestaw tokenów mały, ale kompletny

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:

• Odstępy: 4, 8, 12, 16, 24, 32
• Typografia: jeden rozmiar body, dwa rozmiary nagłówków, jedna wysokość linii dla body, jedna dla nagłówków
• Kolory: text-primary, text-muted, bg, surface, border, accent
• Radius: dwie wartości (np. 4 i 12)
• Elevacja: brak, mała, średnia (maksymalnie trzy poziomy)

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ć.

Zasady komponentów, które utrzymają spójność ekranów

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:

• Loading: zablokuj kontrolkę, pokaż spinner, zachowaj szerokość
• Disabled: obniż kontrast, ale nie usuwaj całkowicie stylów hover/focus
• Empty states: krótki komunikat plus jedna jasna akcja
• Walidacja: błędy pojawiają się pod polami i nie powodują dużych przesunięć layoutu

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.

Zasady zachowania formularzy: detale, które zwykle się rozjeżdżają

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:

• Etykiety zawsze nad polami (nie jako placeholder), znacznik required na etykiecie
• Tekst pomocniczy zawsze pod polem, ten sam rozmiar i kolor, nigdy nie używany jako błąd
• Timing walidacji: pokaż błędy po blur lub submit, czyść je przy zmianie
• Umiejscowienie błędów: jedna linia błędu bezpośrednio pod polem, wyrównana z tekstem pomocniczym
• Zachowanie fokusa: kolejność Tab podąża za wizualnym układem; Enter zatwierdza tylko w ostatnim polu lub gdy fokus jest na przycisku primary

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.

Jak wyrazić tokeny i zasady w promptcie

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.

Kompaktowy szablon promptu

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:

• „Używaj tylko powyższych tokenów; brak inline styles.”
• „Wszystkie formularze muszą używać FormRow i pokazywać błędy w ten sam sposób.”
• „Jeśli musisz dodać komponent, opieraj go na Card i istniejącej typografii.”

Jeśli używasz generatora chatowego, trzymaj spec stabilną między zapytaniami. Zmienianie jej za każdym razem niweczy sens.

Workflow, który utrzyma spójność ekranów

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:

• Potwierdź tokeny i zasady komponentów, potem zamroź je dla funkcji
• Wygeneruj ekran referencyjny i popraw spec, aż będzie dobrze
• Buduj nowe ekrany, ponownie używając komponentów, nie stylując na nowo
• Przejrzyj pod kątem spójności, potem zmieniaj reguły (tokeny/komponenty), nie pojedyncze piksele
• Zapisz spec jako wielokrotnego użytku snippet dla następnej funkcji

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.

Typowe błędy, których unikać

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:

• Używaj tej samej skali odstępów i tokenów typografii jak w istniejących ekranach; nie wymyślaj nowych wartości
• Używaj tylko zatwierdzonych komponentów i wariantów
• Uwzględnij stany loading, empty i error używając tych samych tokenów
• Określ zachowania (walidacja, kolejność fokusa, submit, disabled) tak jasno jak wygląd

Szybka lista kontrolna spójności przed akceptacją ekranu

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:

• Odstępy używają tylko wartości tokenów (brak losowych liczb)
• Typografia pasuje do skali (łącznie z wysokością linii)
• Przyciski trzymają się tych samych wariantów i rozmiarów
• Formularze używają jednego wzorca dla etykiet, pomocy i błędów
• Stany są obecne: hover, focus, disabled, loading, empty

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.

Przykład: generowanie małej funkcji React bez stylowego driftu

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:

• ProgressStepper: height=32, spacing=md, current step bold, completed steps clickable

Kolejne kroki: spraw, by spójność była domyślna

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.