Figma: zmienne i tryby (modes) w design systemie — jak ogarnąć dark mode i brandy bez duplikacji

1. Dlaczego zmienne i modes w Figma eliminują duplikację w design systemie

Największy problem przy utrzymywaniu dark mode, wielu brandów albo wariantów dostępności w jednym design systemie to mnożenie tych samych komponentów: osobne przyciski dla light i dark, osobne biblioteki dla każdego brandu, kolejne „kopie” stylów kolorów. To szybko prowadzi do rozjazdów (ktoś poprawił jeden wariant, ale zapomniał o pozostałych), trudniejszych przeglądów zmian i kosztownego utrzymania.

Zmienne (variables) i tryby (modes) w Figma zmieniają ten model: zamiast duplikować komponenty lub style, przechowujesz decyzje wizualne w postaci wartości, które mogą się przełączać zależnie od kontekstu. Komponent pozostaje jeden, a jego wygląd potrafi „podmienić się” dzięki temu, że odwołuje się do zmiennych, a nie do ręcznie ustawionych kolorów czy wartości.

W praktyce działa to jak rozdzielenie dwóch warstw:

• Warstwa komponentów — struktura, układ, stany i zachowania komponentu (to, co nie powinno się mnożyć).
• Warstwa decyzji wizualnych — kolory, tła, obramowania, wartości odstępów czy inne parametry, które mogą się różnić między trybami (to, co ma się przełączać).

Tryby są tu kluczowe, bo pozwalają jednemu zestawowi zmiennych mieć wiele zestawów wartości. Dzięki temu możesz utrzymać spójne nazwy i logikę tokenów, a jednocześnie zmieniać wygląd UI w zależności od potrzeby: light/dark, różne brandy, a nawet warianty typu high contrast. Bez kopiowania komponentów i bez utrzymywania równoległych wersji bibliotek.

To podejście redukuje duplikację na kilku poziomach:

• Jedno źródło prawdy dla wartości — aktualizujesz zmienną, a nie dziesiątki stylów i instancji rozsianych po plikach.
• Mniej „odchyleń” — skoro komponenty korzystają z tej samej puli zmiennych, trudniej o sytuację, gdzie jeden przycisk w dark mode ma inny odcień niż reszta.
• Szybsze iteracje — zmiana brandu lub korekta kontrastu to często podmiana wartości w trybie, a nie przebudowa komponentów.
• Łatwiejsze skalowanie — dodanie kolejnego brandu lub trybu nie wymaga produkowania kopii całego systemu, tylko dołożenia kolejnego zestawu wartości.

Warto też odróżnić role, jakie pełnią w Figma style i zmienne. Style były historycznie dobrym narzędziem do porządkowania kolorów i tekstu, ale przy wielu wariantach szybko pojawia się presja na duplikację (osobne style dla light i dark, osobne dla brandów). Zmienne i tryby są z założenia stworzone do tego, by te warianty obsłużyć w jednym modelu: ta sama zmienna, inne wartości w zależności od trybu.

Efekt końcowy jest prosty: zamiast pytać „który zestaw komponentów mam wstawić: light czy dark?”, przełączasz tryb i ten sam system UI dopasowuje się automatycznie. Mniej kopii, mniej niespójności, więcej kontroli.

Model tokenów: jak organizować kolory, typografię i spacing w zmiennych

Żeby zmienne i tryby działały bez chaosu, potrzebujesz prostego modelu tokenów. Token to nazwana decyzja projektowa zapisana jako zmienna (np. kolor tła, odstęp, rozmiar tekstu), którą potem przypinasz do komponentów. Kluczowe jest rozdzielenie tego, co oznacza token w interfejsie (rola), od tego, jaką ma wartość w danym wariancie (np. jasny/ciemny, różne brandy). Dzięki temu nie budujesz osobnych zestawów komponentów, tylko przełączasz wartości tokenów.

Ten wpis powstał w odpowiedzi na zagadnienia, które regularnie pojawiają się na szkoleniach prowadzonych przez Cognity.

1) Dwie warstwy tokenów: bazowe i semantyczne

Najbardziej praktyczne podejście to dwie warstwy:

• Tokeny bazowe (primitive) — surowe wartości: konkretne kolory, skale typograficzne, kroki spacingu. To „materiał”, z którego budujesz UI.
• Tokeny semantyczne (alias/role) — nazwy opisujące zastosowanie w interfejsie: tło powierzchni, tekst główny, obramowanie, stan błędu, odstęp między elementami w komponencie. To „znaczenie” i język dla całego systemu.

W praktyce komponenty powinny odwoływać się głównie do tokenów semantycznych, bo one są stabilne nawet wtedy, gdy zmieniają się wartości bazowe (np. rebranding) lub dochodzi nowy tryb (np. dark mode).

2) Kolory: od palety do ról interfejsu

W kolorach łatwo wpaść w pułapkę nazw typu „blue-500” używanych bezpośrednio w komponentach. To przyspiesza start, ale utrudnia spójne zmiany. Lepiej traktować paletę jako warstwę bazową, a dopiero role jako warstwę semantyczną.

Co warto przewidzieć w tokenach semantycznych kolorów:

• Powierzchnie (tło aplikacji, karty, elementy podniesione, overlay).
• Tekst (główny, drugorzędny, odwrotny na ciemnym tle, link).
• Obramowania i separatory (domyślne, subtelne, na fokus/akcent).
• Akcje i stany (primary, secondary, disabled; hover/pressed; success/warning/error/info).

Istotne: role powinny być opisane językiem interfejsu, a nie nazwą barwy. Dzięki temu ten sam „tekst główny” może być prawie czarny w trybie jasnym i prawie biały w trybie ciemnym — bez zmiany komponentów.

3) Typografia: zmienne dla skali i ról tekstu

Typografia w tokenach to nie tylko font family. Żeby dobrze skalować system, warto myśleć o typografii jako o zestawie decyzji, które powtarzają się w wielu miejscach:

• Rodziny fontów (np. dla tekstu i dla nagłówków, jeśli są różne).
• Rozmiary w ramach skali (kroki, które wykorzystasz w stylach tekstu).
• Grubości (regular/medium/bold jako decyzje, nie przypadkowe liczby).
• Interlinia i tracking jako elementy czytelności i rytmu.

Podobnie jak w kolorach, przydaje się warstwa semantyczna: role typu „body”, „caption”, „heading” opisują przeznaczenie. Nie chodzi o to, by tworzyć dziesiątki unikalnych wariantów, tylko kilka stabilnych ról, które pokryją większość UI.

4) Spacing: skala odstępów jako fundament spójności

Spacing najlepiej działa jako prosta skala (kroki), zamiast ręcznych wartości ustawianych „na oko”. Tokeny spacingu w zmiennych pomagają utrzymać rytm i proporcje w całym produkcie.

Co organizować jako tokeny:

• Odstępy bazowe (kroki skali używane w paddingach, gapach, marginesach).
• Odstępy semantyczne dla powtarzalnych sytuacji (np. padding w kontrolkach, odstęp między ikoną a tekstem, przerwy między sekcjami formularza).

Ważna zasada: jeśli coś jest powtarzalnym wzorcem w komponentach, zasługuje na nazwany token semantyczny. Dzięki temu później łatwiej dostroić gęstość interfejsu (np. wariant compact/comfortable) bez ręcznych poprawek w setkach miejsc.

5) Jak utrzymać model tokenów prosty i skalowalny

• Preferuj semantykę nad wyglądem: komponenty wiąż z rolami, nie z surową paletą czy przypadkowymi wartościami.
• Minimalizuj liczbę ról: dodawaj token semantyczny dopiero, gdy różnica ma znaczenie produktowe, a nie tylko estetyczne.
• Stosuj spójny zakres: te same kategorie ról w kolorach, typografii i spacingu ułatwiają myślenie o systemie.
• Unikaj „jednorazówek”: jeśli token ma być użyty tylko w jednym miejscu, często lepiej przeprojektować komponent lub ujednolicić decyzję.

Taki model tokenów tworzy solidną bazę pod dalszą pracę: zmienne przechowują decyzje, a tryby zmieniają ich wartości bez rozszczepiania bibliotek i bez duplikowania komponentów.

3. Definiowanie modes: dark/light, brand A/B oraz inne warianty (np. high contrast)

Modes w zmiennych Figma to zestawy wartości przypisane do tych samych tokenów. Zamiast tworzyć osobne style i duplikować komponenty, utrzymujesz jedną strukturę tokenów (np. color.bg, color.text), a przełączasz tylko wartości w zależności od kontekstu: motywu (light/dark), marki (brand A/B), dostępności (high contrast) czy platformy.

Co jest “mode”, a co nim nie jest?

• Mode = wariant wartości tokenów (np. inne wartości dla color.bg w dark vs light).
• Nie mode = jednorazowa decyzja na poziomie komponentu (np. inny padding w jednym wariancie komponentu) — to zwykle wariant komponentu, nie tryb tokenów.
• Nie mode = “stan” (hover/pressed/disabled). Stany najczęściej wynikają z osobnych tokenów (np. color.button.bg.hover) niż z przełączania całego trybu.

Najczęstsze typy modes i ich zastosowania

Jak podejść do projektowania zestawu modes (bez nadmiaru)

• Zacznij od osi, które realnie musisz przełączać: zwykle pierwsza jest Theme (light/dark), dopiero potem Brand.
• Unikaj mnożenia trybów: każdy dodatkowy mode zwiększa liczbę kombinacji do przetestowania (np. 2 theme × 2 brand × 2 contrast = 8).
• Oddziel „bazę” od „akcentów”: light/dark często dotyka całej palety neutralnej, a brand głównie kolorów akcentowych i elementów identyfikacji.
• Ustal, które tokeny są wrażliwe na mode: np. tokeny semantyczne (color.bg, color.text) prawie zawsze; część dekoracyjnych może pozostać stała.

Praktyczny przykład: jedna nazwa tokenu, różne wartości

W trybach zmieniają się wartości, ale nazwy tokenów pozostają te same. Dzięki temu komponenty nie „wiedzą”, czy są w dark czy w brand B — dostają właściwą wartość z aktywnego trybu.

color.bg.default:
  Light: #FFFFFF
  Dark:  #0B0F14

color.text.primary:
  Light: #111827
  Dark:  #E5E7EB

color.accent.primary:
  Brand A: #0EA5E9
  Brand B: #7C3AED

Łączenie trybów: theme × brand × dostępność

W praktyce często potrzebujesz więcej niż jednej osi zmiany. Kluczowe jest ustalenie, czy chcesz:

• Osobne zestawy modes dla różnych grup zmiennych (np. kolory mają theme i brand, ale spacing nie).
• Jeden wspólny wybór dla całego zestawu zmiennych (gdy wszystkie tokeny muszą reagować na te same tryby).

Najczęstszy, prosty układ to:

• Theme: Light, Dark
• Brand: A, B
• Contrast: Default, High

To daje jasną strukturę decyzji: najpierw środowisko (theme), potem identyfikacja (brand), na końcu potrzeby dostępności (contrast).

Warianty specjalne: kiedy mode ma sens

• High contrast: gdy masz obowiązek wspierać użytkowników wymagających mocniejszych sygnałów wizualnych (szczególnie focus i obramowania).
• Seasonal / kampanie: tylko jeśli to długotrwały i kontrolowany wariant; w przeciwnym razie lepsze są lokalne nadpisania w konkretnych ekranach.
• White label: gdy produkt jest wdrażany u wielu klientów — wtedy brand modes to fundament, ale wymagają ścisłej dyscypliny w tym, co jest „brandowalne”.

Dobrze zdefiniowane modes pozwalają przełączać motywy i marki bez ruszania komponentów: zmieniają się wartości tokenów, a UI pozostaje spójne i łatwe do utrzymania.

4. Mapowanie tokenów na komponenty: od decyzji projektowych do implementacji w UI

Same tokeny (zmienne) nie dają jeszcze spójnego UI — wartość pojawia się dopiero wtedy, gdy komponenty przestają „pamiętać kolory”, a zaczynają referować role (np. tło, tekst, obrys) poprzez tokeny. Mapowanie to moment, w którym decyzje projektowe stają się przewidywalnym zestawem reguł, a nie zbiorem wyjątków.

Zespół trenerski Cognity zauważa, że właśnie ten aspekt sprawia uczestnikom najwięcej trudności: poprawne „odklejenie” komponentów od konkretnych wartości i przejście na role, które działają niezależnie od trybu (mode).

Tokeny „bazowe” vs tokeny „semantyczne”: co mapujesz na komponent?

Najczęstszy błąd w design systemach to wiązanie komponentów bezpośrednio z tokenami „surowymi” (np. konkretnym odcieniem niebieskiego). Skuteczniejsze jest mapowanie na tokeny semantyczne (role), które potem mogą zmieniać wartości w zależności od mode (dark/light, brand itd.).

W praktyce mapowanie wygląda tak: komponent → właściwość wizualna → token semantyczny (lub komponentowy). Dzięki temu tryby (modes) wymieniają wartości tokenów, a komponenty pozostają bez zmian.

Jak rozbić komponent na „sloty” i stany, żeby mapowanie było skalowalne

Żeby tokeny nie stały się chaosem, komponent warto opisać przez sloty (części składowe) oraz stany (interakcje). To porządkuje mapowanie i zmniejsza liczbę wyjątków.

• Sloty: container (tło), label (tekst), icon, border/outline, focus ring, badge/indicator
• Stany: default, hover, pressed, disabled, selected, focus

Mapowanie tokenów robisz per slot i stan, np. „label/default” wskazuje na token tekstu, a „container/hover” na token tła hover.

Minimalny zestaw mapowań: zacznij od ról, nie od wszystkich wariantów

Jeśli system jest na etapie porządkowania, nie próbuj od razu tokenizować wszystkiego. Największy zwrot z inwestycji dają elementy, które najczęściej zmieniają się między trybami:

• Surface (tła i warstwy): page, card, overlay
• Text: primary, secondary, inverse, disabled
• Border: subtle, default, strong
• Interactive: bg/fg dla primary/secondary actions + stany hover/pressed/disabled
• Feedback: success/warning/error (wystarczą role, bez rozbudowy palety na start)

Przykład: mapowanie na przycisku bez „kolorów w komponencie”

Zamiast ustawiać w przycisku konkretne wartości (np. #0B5FFF), przypisujesz role. W Figma oznacza to, że właściwości warstw (fill/stroke/text) wskazują na zmienne. Przycisk staje się „ramą”, a wartości przychodzą z tokenów aktywnego mode.

Analogicznie mapujesz stany: zamiast osobnych komponentów dla hover/pressed, możesz (zależnie od sposobu budowy komponentów) opisać je jako warianty i nadal podpinać pod tokeny stanów, np. color.action.primary.bg.hover. Kluczowe: komponent nie zna trybu; to tryb zmienia wartości tokenów.

Most między designem a kodem: dlaczego mapowanie musi być „czytelne dla implementacji”

Mapowanie w Figma ma sens wtedy, gdy da się je bezpośrednio przełożyć na style w UI. Nie chodzi o identyczne nazwy, ale o spójną logikę ról. W skrócie:

• Projekt mówi: „to jest tekst główny na powierzchni bazowej”.
• Token koduje tę rolę: color.text.primary na color.surface.default.
• Komponent konsumuje role: „label = text.primary”, „container = action.primary.bg”.

Jako uzupełnienie, w kodzie często kończy się to mapowaniem tokenów do zmiennych CSS lub obiektu motywu. Ważne, by utrzymać relację „rola → wartość w trybie”, np.:

/* przykład poglądowy */
:root[data-mode="light"] {
  --color-text-primary: #111;
  --color-surface-default: #fff;
}
:root[data-mode="dark"] {
  --color-text-primary: #f5f5f5;
  --color-surface-default: #111;
}

.button-primary {
  background: var(--color-action-primary-bg);
  color: var(--color-action-primary-fg);
}

Heurystyki, które zapobiegają „tokenowej inflacji”

• Preferuj role globalne (text/surface/border) nad mnożeniem tokenów per komponent — dopóki nie masz realnej potrzeby różnicowania.
• Token komponentowy twórz dopiero, gdy różne komponenty potrzebują różnych wartości dla tej samej roli (np. specjalne tło tylko dla jednego typu bannera).
• Unikaj mapowania do „primitives” w warstwach komponentów — utrudnia to dark mode i rebranding bez zmian w komponentach.
• Trzymaj stany interakcji w tej samej logice co default (hover/pressed to nadal role, nie wyjątki).

Dobrze wykonane mapowanie sprawia, że zmiana dark/light lub brandu nie wymaga kopiowania komponentów ani ręcznych poprawek — podmieniasz wartości tokenów w mode, a komponenty automatycznie renderują właściwy wygląd.

5. Testowanie komponentów i trybów: scenariusze, checklisty i szybka walidacja

Zmienne i modes upraszczają utrzymanie design systemu, ale zwiększają liczbę kombinacji do sprawdzenia: komponent × stan × tryb (np. light/dark) × brand × kontekst (np. tło, powierzchnia). Testowanie w Figma powinno więc być powtarzalne, szybkie i oparte o te same scenariusze dla wszystkich komponentów, zamiast ad-hoc „przeklikiwania”. Celem jest wykrycie problemów typowych dla tokenów: nieczytelnych kontrastów, przypadkowych fallbacków, źle przypiętych zmiennych oraz rozjazdów między trybami.

Co testujesz, gdy wchodzą tryby?

W klasycznym podejściu sprawdzasz, czy komponent wygląda dobrze w jednym zestawie kolorów. Przy zmiennych i trybach weryfikujesz dodatkowo, czy:

• Mapowanie tokenów jest konsekwentne (ten sam „sens” koloru w każdym trybie),
• Zmiany trybu nie ujawniają twardo wpisanych wartości (hard-coded),
• Stany (hover/pressed/disabled/focus) zachowują kontrast i hierarchię,
• Warstwy (surface/overlay/inverse) nie „zlewają się” w dark mode,
• Brandowanie nie psuje semantyki (np. akcent brandu nie staje się kolorem błędu).

Minimalny zestaw scenariuszy testowych (komponenty)

Zamiast próbować „przetestować wszystko”, warto przyjąć minimalny, wspólny szkielet scenariuszy. Poniżej baza, którą da się zastosować do większości elementów UI.

Checklisty: szybka kontrola jakości tokenów

Checklisty pozwalają złapać problemy wcześniej niż review wizualne. To proste „tak/nie”, które można przejść w kilka minut na komponent.

• Zmienne: Czy wszystkie kolory/typografia/spacings, które powinny reagować na tryb, są przypięte do zmiennych (a nie wpisane ręcznie)?
• Brak „dziur”: Czy w żadnym trybie nie pojawia się fallback/nieoczekiwany styl (np. tekst nagle staje się czarny na ciemnym tle)?
• Kontrast: Czy tekst, ikony i obrysy są czytelne na wszystkich docelowych powierzchniach?
• Hierarchia: Czy primary nadal jest primary, a secondary nadal jest secondary po przełączeniu trybu/brandu?
• Stany: Czy focus/disabled są jednoznaczne i spójne we wszystkich trybach?
• Spójność semantyczna: Czy kolory „sukces/ostrzeżenie/błąd/info” nie zmieniają znaczenia między brandami?
• Kompozycja: Czy komponent nie „rozsypuje się” w layoutach responsywnych po zmianie trybu (np. przez inne wartości spacingu lub fontu)?

Walidacja „na makietach”, nie tylko na komponentach

Komponent może przejść test w izolacji, a wysypać się w realnym układzie. Dlatego szybka walidacja powinna obejmować przynajmniej kilka kluczowych ekranów (lub sekcji UI) złożonych z komponentów:

• Widok z dominującą typografią (nagłówki + tekst + linki),
• Widok z dużą liczbą akcji (toolbar, listy, CTA),
• Widok z komunikatami systemowymi (alerty, toasty, błędy formularzy),
• Widok „gęsty” (tabele, listy, filtry),
• Widok z overlay (modal/popover) na różnych tłach.

To pozwala szybko wykryć problemy warstwowania, kontrastów na złożonych powierzchniach oraz sytuacje, w których tokeny działają „lokalnie”, ale nie globalnie.

Praktyka: macierz testów (co najmniej) i zasada „krytycznych ścieżek”

Żeby nie utonąć w kombinacjach, warto z góry zdefiniować macierz testów: tryby × najważniejsze komponenty × krytyczne stany. Minimum, które zwykle daje najlepszy zwrot:

• Tryby: Light + Dark (obowiązkowo), Brand warianty (jeśli istnieją),
• Komponenty: przyciski, inputy, linki, nawigacja, karty, alerty,
• Stany krytyczne: disabled i focus (najczęściej psują dostępność),
• Konteksty: surface podstawowy + elevated + akcent (jeśli używany).

Resztę można testować rotacyjnie lub przy okazji zmian w tokenach.

Szybkie techniki wykrywania problemów w Figma

• Widok porównawczy: ułóż obok siebie ten sam ekran/komponent w różnych trybach, by „różnice” były widoczne natychmiast.
• „Stress test” kontrastu: sprawdź komponent na najbardziej skrajnych powierzchniach (najciemniejszej i najjaśniejszej) dostępnych w systemie.
• Wykrywanie wartości ręcznych: selekcja warstw i szybki przegląd właściwości ujawnia elementy, które nie są podpięte pod zmienne.
• Test skali: sprawdź komponent z minimalną i maksymalną treścią (np. krótkie vs. bardzo długie etykiety), bo w dark mode często rośnie wrażliwość na „szum” wizualny.

Co raportować po teście (żeby poprawki były szybkie)

Dobry raport z walidacji trybów nie powinien być opisem „coś wygląda źle”, tylko wskazaniem, który token/zmienna lub które przypięcie jest podejrzane. Minimalny format zgłoszenia:

• Tryb: (np. Dark + Brand B),
• Kontekst: (np. karta na elevated surface),
• Komponent i stan: (np. input, focus),
• Objaw: (np. focus ring niewidoczny),
• Podejrzenie: (np. obrys używa niewłaściwej zmiennej / brak wariantu w danym trybie).

Taki opis skraca drogę od znalezienia błędu do poprawy w źródle (zmienne/tryby) i zmniejsza ryzyko „łatki” tylko w jednym komponencie.

6. Struktura bibliotek Figma: pliki, biblioteki, zależności i publikowanie zmian

Dobrze ułożona struktura plików i bibliotek w Figma decyduje o tym, czy zmienne i tryby faktycznie redukują duplikację, czy tylko przenoszą chaos w inne miejsce. Celem jest takie rozdzielenie zasobów, aby: (1) tokeny (zmienne) miały jedno źródło prawdy, (2) komponenty mogły je konsumować bez kopiowania, (3) zmiany dało się publikować kontrolowanie i przewidywalnie.

Pliki vs biblioteki: co jest czym i po co

Plik w Figma to miejsce pracy (strony, ramki, komponenty, zmienne). Biblioteka to plik (lub zestaw plików) udostępniony innym przez funkcję publikowania, tak aby elementy mogły być włączane jako zasoby (Variables/Styles/Components) w innych plikach.

Rekomendowany podział: „Tokens → Components → Product”

Najprostszy, skalowalny układ zależności to łańcuch:

• Tokens (Variables) — jeden plik/ biblioteka jako źródło prawdy dla zmiennych i ich trybów.
• Components — komponenty, które odwołują się do zmiennych z biblioteki tokenów (zamiast mieć wartości wpisane ręcznie).
• Product/Projects — pliki produktowe, które używają komponentów (i pośrednio tokenów), bez potrzeby duplikowania czegokolwiek.

Taki układ ułatwia kontrolę zmian: tokeny można aktualizować bez przepinania setek ekranów, a komponenty pozostają spójne pomiędzy produktami.

Zależności i „kierunek” importu

Kluczowa zasada: zależności powinny iść w jedną stronę. Komponenty mogą zależeć od tokenów, ale tokeny nie powinny zależeć od komponentów. Pliki produktowe zależą od komponentów (i czasem bezpośrednio od tokenów), ale biblioteki nie powinny zależeć od plików produktowych.

• Dozwolone: Product → Components → Tokens
• Unikaj: Components → Product, Tokens → Components (np. „podpinanie” tokenów pod lokalne style z komponentów)

W praktyce oznacza to m.in. że w bibliotece komponentów nie trzymasz ekranów „referencyjnych” jako źródła prawdy (mogą być jako dokumentacja, ale nie jako zależność), a w bibliotece tokenów nie „uzależniasz” się od konkretnego UI.

Warianty organizacji bibliotek: monorepo vs podział na moduły

Figma pozwala utrzymać design system w jednym dużym pliku albo rozbić go na kilka bibliotek. Wybór zależy od skali i liczby zespołów.

Biblioteki dla wielu marek i produktów: wspólny rdzeń + nakładki

Jeśli obsługujesz kilka marek lub produktów, praktyczny jest model:

• Core Tokens — wspólne zmienne (np. semantyczne) dostępne wszędzie.
• Brand Tokens — oddzielne biblioteki tokenów specyficzne dla marki (np. inny zestaw wartości w trybach), bez kopiowania komponentów.
• Core Components — komponenty zbudowane na semantyce (czyli „czytają” tokeny), możliwie neutralne wobec brandu.

Dzięki temu brandy różnią się głównie konfiguracją tokenów/trybów, a nie duplikacją całych bibliotek komponentów.

Publikowanie zmian: rytm, odpowiedzialność i higiena wersji

W design systemie publikowanie jest mechanizmem „wdrożenia” do innych plików. Żeby nie zaskakiwać konsumentów biblioteki:

• Ustal ownership: kto publikuje tokeny, kto komponenty, kto zatwierdza zmiany.
• Publikuj warstwami: najpierw tokeny, potem komponenty (unikasz sytuacji, że komponenty oczekują tokenów, których jeszcze nie ma).
• Stosuj changelog w opisie publikacji: co dodano, co zmieniono, co potencjalnie wpływa na istniejące ekrany.
• Ogranicz breaking changes: jeśli zmiana może „rozsypać” UI, planuj ją jako osobny release i komunikuj wcześniej.

Minimalny standard komunikatu przy publikacji, który pomaga utrzymać porządek:

Typ zmiany: dodanie / modyfikacja / usunięcie
Zakres: Tokens / Components / Icons
Wpływ: brak / możliwe różnice wizualne / wymagane poprawki
Instrukcja: co zrobić w plikach produktowych (jeśli dotyczy)

Włączanie bibliotek w plikach produktowych: zasada „tyle, ile trzeba”

W plikach produktowych włączaj tylko te biblioteki, które są faktycznie używane. Mniej aktywnych bibliotek to:

• mniej ryzyka pomyłki (np. użycia komponentu z niewłaściwej biblioteki),
• łatwiejsze utrzymanie zależności,
• czytelniejszy proces aktualizacji po publikacji.

Jeżeli plik ma korzystać z komponentów, zazwyczaj wystarczy podpiąć bibliotekę komponentów (która i tak opiera się na tokenach). Bezpośrednie włączanie tokenów w plikach produktowych zostaw na przypadki, gdy faktycznie pracujesz na zmiennych poza komponentami (np. tła sekcji, layouty, prototypy).

Zasady nazewnictwa i utrzymanie porządku: konwencje, governance i wersjonowanie

Zmienne i tryby w Figma potrafią radykalnie ograniczyć duplikację, ale tylko wtedy, gdy towarzyszy im konsekwentne nazewnictwo i proste zasady utrzymania. Bez nich design system szybko zamienia się w zbiór „prawie takich samych” tokenów, trybów i bibliotek, których nikt nie jest pewien. Ta sekcja porządkuje trzy filary: konwencje (jak nazywać), governance (kto i jak podejmuje decyzje) oraz wersjonowanie (jak bezpiecznie wprowadzać zmiany).

Konwencje nazewnictwa: mniej kreatywności, więcej przewidywalności

Dobre nazwy mają być przede wszystkim stabilne i odczytywalne. W praktyce najlepiej sprawdzają się nazwy opisujące intencję, a nie wygląd. Dzięki temu token nie „psuje się” semantycznie, kiedy zmienisz kolor lub dopracujesz kontrast w innym trybie.

• Nazwy semantyczne zamiast wizualnych: preferuj określenia typu „tło powierzchni”, „tekst podstawowy”, „obramowanie subtelne” zamiast „szary-200” czy „niebieski”.
• Jedna konwencja separatorów: wybierz jedną formę (np. ukośniki albo kropki) i trzymaj się jej w całej bibliotece, żeby łatwo filtrować i wyszukiwać.
• Hierarchia w nazwie: prowadź od ogółu do szczegółu (kategoria → rola → stan), aby listy zmiennych układały się logicznie.
• Stany jako sufiksy: stany interakcji i warianty (hover, pressed, disabled) powinny wynikać z nazwy w sposób powtarzalny, żeby dało się je przewidzieć bez zgadywania.
• Unikaj nazw „tymczasowych”: „new”, „test”, „final2” to szybka droga do długów. Jeśli coś jest eksperymentem, odseparuj to procesem (np. folderem roboczym), a nie produkcyjną nazwą.
• Język i liczba: ustal, czy nazwy są po polsku czy po angielsku i konsekwentnie wybieraj liczbę pojedynczą. Mieszanie języków utrudnia wyszukiwanie i onboarding.

Ważne: nazwy trybów (modes) też wymagają dyscypliny. Najczęstszy błąd to nadawanie im „marketingowych” etykiet, które nie mówią, co się faktycznie zmienia. Tryb ma być jednoznaczny: light/dark, brand A/brand B, high contrast itp.

Porządek w zmiennych: minimalny zestaw reguł, który robi różnicę

Utrzymanie ładu to nie tylko nazwy, ale też ograniczanie nadmiaru. Im mniej tokenów o podobnym znaczeniu, tym mniej pracy przy kolejnych trybach i tym mniejsze ryzyko rozjazdów.

• Jedna rola = jedna zmienna: jeśli dwie zmienne opisują to samo (np. „tekst/primary” i „tekst/default”), wybierz jedną i migruj użycia.
• Nie koduj wartości w nazwie: wartości i tak będą różne między trybami; nazwa ma opisywać przeznaczenie.
• Unikaj „wyjątków na komponent”: tokeny typu „button/primary/bg” łatwo mnożą się przy każdym nowym komponencie. Preferuj tokeny wspólne dla ról UI, a wyjątkami zarządzaj świadomie i rzadko.
• Stała struktura kategorii: kolory, typografia i odstępy powinny mieć podobną logikę grupowania, żeby system był intuicyjny.

Governance: kto może zmieniać co i dlaczego

Governance nie musi być „ciężkim procesem”. Chodzi o to, by decyzje o tokenach i trybach miały właściciela, a zmiany były przewidywalne dla całej organizacji. Najprostszy model to jasny podział odpowiedzialności i minimalny przepływ akceptacji.

• Właściciel systemu: osoba lub mały zespół odpowiedzialny za spójność nazw, porządek w zmiennych i publikowanie zmian.
• Ścieżka zgłoszeń: zdefiniuj, jak zgłasza się potrzebę nowego tokenu/trybu i jakie kryteria musi spełnić (np. brak istniejącego odpowiednika, realna potrzeba w wielu miejscach).
• Decyzje o wyjątkach: ustal, kiedy dopuszczalne są tokeny specyficzne i jak są dokumentowane, żeby „tymczasowe” rozwiązania nie zostawały na stałe.
• Regularne porządki: cykliczny przegląd duplikatów, nieużywanych zmiennych i niespójnych nazw jest tańszy niż późniejsza wielka migracja.

Dobrą praktyką jest też utrzymywanie krótkich zasad w jednym miejscu (nawet jeśli to tylko zwięzła strona w dokumentacji): co tworzymy, jak nazywamy, kto zatwierdza, jak ogłaszamy zmiany.

Wersjonowanie i komunikacja zmian: stabilność dla zespołów produktowych

Nawet najlepszy design system będzie się zmieniał. Kluczowe jest rozróżnienie zmian, które są bezpieczne, od tych, które mogą „zepsuć” istniejące widoki albo wymagają migracji. Zamiast liczyć na pamięć zespołu, wprowadź proste zasady wersjonowania i komunikacji.

• Zmiany kompatybilne: dodanie nowej zmiennej, nowego trybu albo rozszerzenie zestawu wartości zwykle nie łamie istniejących projektów — to dobry kandydat na mniejsze wydanie.
• Zmiany niekompatybilne: usunięcie zmiennej, zmiana znaczenia nazwy, masowe przemianowanie lub reorganizacja struktur wymaga planu migracji i wyraźnej informacji dla użytkowników biblioteki.
• Changelog: utrzymuj krótką listę „co się zmieniło” oraz „co trzeba zrobić” (jeśli cokolwiek). Bez tego nawet poprawa jakości może zostać odebrana jako chaos.
• Okno migracji: gdy planujesz porządki, zostaw czas na dostosowanie plików produktowych — szczególnie jeśli zmiana dotyka wielu komponentów i ekranów.

W kontekście zmiennych i trybów szczególnie ważne jest, by unikać zmian „w ciszy”: drobna korekta w nazwie albo roli tokenu potrafi mieć szeroki zasięg. Stabilność nazw to fundament; jeśli musisz je zmienić, potraktuj to jak zmianę o wysokim ryzyku i skomunikuj ją tak samo jasno jak większy refactor komponentów.

Najczęstsze pułapki, które rozwalają porządek

• Synonimy: kilka nazw dla tej samej roli UI prowadzi do duplikacji i sporów „którego użyć”.
• Tryby jako obejście: tworzenie dodatkowych trybów zamiast poprawnego modelu tokenów utrudnia rozwój i testowanie.
• Brak właściciela: jeśli „każdy może”, w praktyce nikt nie pilnuje spójności.
• Brak rytmu publikacji: nieregularne, nieopisane zmiany budują nieufność do biblioteki i skłaniają zespoły do lokalnych kopii.

Jeśli potraktujesz nazewnictwo, governance i wersjonowanie jako część design systemu (a nie „dodatki”), zmienne i modes pozostaną narzędziem upraszczającym pracę — zamiast kolejną warstwą komplikacji.

Podsumowanie: checklisty kontroli jakości i rekomendowany rytm zarządzania (baseline–aktualizacja–EVM–prognoza)

Zmienne i tryby (modes) w Figma porządkują design system, bo pozwalają oddzielić decyzje (np. znaczenie koloru, rola typografii) od realizacji (konkretne wartości dla light/dark czy różnych brandów). Dzięki temu przestajesz utrzymywać równoległe zestawy komponentów, a zamiast tego sterujesz wariantami przez spójne przełączanie trybów oraz kontrolę mapowania tokenów na UI. Końcowy efekt to mniej duplikacji, mniej regresji i prostsze utrzymanie zgodności z implementacją.

Checklisty kontroli jakości (design system i Figma)

• Spójność tokenów: każda wartość „w produkcie” ma przypisanie do zmiennej; unikasz ręcznie wpisanych kolorów, fontów i odstępów w komponentach.
• Rozdzielenie ról: tokeny są opisane semantycznie (po funkcji), a nie nazwami zależnymi od trybu; tryb zmienia wartości, nie znaczenie.
• Kompletność trybów: każdy token używany przez komponent ma wartości we wszystkich wspieranych trybach; brakujące wartości są wychwytywane przed publikacją.
• Brak „martwych” zmiennych: cyklicznie usuwasz lub archiwizujesz tokeny nieużywane, żeby nie rozmywały standardu.
• Stabilne mapowanie komponentów: komponenty odwołują się do tokenów konsekwentnie; nie ma mieszanek tokenów o podobnej funkcji w jednym miejscu.
• Kontrast i czytelność: kluczowe stany (default/hover/active/disabled/focus) są sprawdzone w każdym trybie pod kątem kontrastu i hierarchii wizualnej.
• Stany i interakcje: style focus ring, tła, obramowania i komunikaty (np. error/success) zachowują spójne reguły w dark/light i między brandami.
• Skalowalność: nowe komponenty i nowe tryby można dodać bez tworzenia osobnych „klonów” bibliotek; zmienne są pierwszym wyborem, nie obejściem.
• Kontrola zmian: każda zmiana tokenów ma opis „co i dlaczego”, jest śledzona i komunikowana do zespołów (design i dev) w jednym miejscu.
• Zgodność z implementacją: istnieje jasny punkt odniesienia, czy to, co w Figma, odpowiada temu, co w kodzie (nawet jeśli szczegóły integracji są różne).

Checklisty jakości planu prac (bez „znikających” tematów)

• Cel i zakres: zdefiniowane, jakie tryby wspierasz (np. light/dark, brandy, dostępność), a czego świadomie nie obejmujesz na tym etapie.
• Definicja „done”: ustalone kryteria ukończenia dla tokenów, komponentów i trybów (np. kompletność, kontrast, publikacja, dokumentacja zmian).
• Ryzyka: wypisane ryzyka związane z rozjazdem design–kod, zbyt dużą liczbą tokenów, oraz z szybkim przyrostem trybów.
• Zależności: wiadomo, które komponenty i obszary UI są krytyczne i w jakiej kolejności je obejmujesz, by nie blokować wdrożeń.
• Metryki: mierzysz postęp w sposób jednoznaczny (np. pokrycie komponentów tokenami, pokrycie trybów, liczba regresji po publikacji).

Rekomendowany rytm zarządzania: baseline–aktualizacja–EVM–prognoza

Żeby utrzymać porządek przy rosnącej liczbie tokenów i trybów, przydaje się stały cykl zarządczy. Nie chodzi o ciężki proces, tylko o powtarzalny rytm, który minimalizuje chaos.

• Baseline: ustalasz punkt startowy — aktualny zestaw tokenów, wspierane tryby, listę komponentów w zakresie oraz kryteria jakości. To jest Twoja „umowa” na bieżący etap.
• Aktualizacja: w stałym interwale (np. tygodniowo lub na koniec sprintu) dopinasz zmiany: nowe tokeny, korekty wartości w trybach, porządki w nieużywanych zmiennych, doprecyzowanie mapowań. Zmiany są opisane i komunikowane.
• EVM (Earned Value Management): raz na interwał porównujesz plan do rzeczywistości, ale bez rozdmuchiwania raportów. Sprawdzasz, ile „wartości” faktycznie dowieziono (np. komponenty gotowe we wszystkich trybach) względem tego, co zaplanowano, i gdzie pojawia się odchylenie czasu lub wysiłku.
• Prognoza: na podstawie odchyleń i trendu aktualizujesz przewidywania: kiedy domkniesz pokrycie kluczowych komponentów, czy tryby wymagają uproszczeń, i gdzie warto ograniczyć zakres, by utrzymać jakość.

Najważniejsze: traktuj zmienne i tryby jako narzędzie do redukcji wariantów w plikach, a nie jako sposób na ich mnożenie. Jeśli cyklicznie weryfikujesz kompletność, spójność oraz wpływ zmian na komponenty, dark mode i wielość brandów przestają być „drugą biblioteką”, a stają się kontrolowanym przełączeniem wartości w jednym, spójnym systemie.

Na zakończenie – w Cognity wierzymy, że wiedza najlepiej działa wtedy, gdy jest osadzona w codziennej pracy. Dlatego szkolimy praktycznie.

Dataverse w roli „źródła prawdy”: jak zbudować model danych, który skaluje PowerApps i raportowanie 01 maja 2026

Hardening endpointów agentów: rate limits, budżety tokenów i „circuit breaker” na dziwne sesje 29 kwietnia 2026