Tokeny projektowe: architektura CTI, nazewnictwo, przykłady dla deweloperów

Efektywne zarządzanie stylami: Architektura i nazewnictwo design tokenów według metodologii CTI

Design tokeny to fundamentalny element nowoczesnych systemów designu, zapewniający płynną współpracę między projektantami a deweloperami. Umożliwiają standaryzację atrybutów wizualnych produktu, takich jak kolory, czcionki i odstępy, przekształcając surowe wartości w nazwane zmienne. Prawidłowo zaprojektowany system tokenów znacząco przyspiesza rozwój nowych interfejsów, upraszcza skalowanie i dostosowywanie, a także minimalizuje dług techniczny, eliminując potrzebę ręcznej zmiany zakodowanych na stałe wartości stylów w rozproszonych komponentach. W tym materiale szczegółowo omówimy architekturę design tokenów i specyfikę nazewnictwa według popularnej metodologii CTI, która stanowi podstawę wielu zaawansowanych systemów designu.

Wielopoziomowa abstrakcja design tokenów

Dla stworzenia elastycznego i skalowalnego systemu designu kluczowe jest podejście do abstrakcji wartości. Nowoczesne systemy wykorzystują trójwarstwowy model (Prymityw → Semantyka → Komponent), do którego dla pełności obrazu często dodaje się warstwę zerową — surowe dane. Model ten zapewnia ustrukturyzowany przepływ danych, gdzie zmiany na niższych poziomach automatycznie rozprzestrzeniają się na wyższe, gwarantując spójność i upraszczając globalne aktualizacje stylów.

0. Surowe wartości (Raw Values): Są to podstawowe, nieabstrakcyjne dane, takie jak szesnastkowe kody kolorów (#0055FF), wartości pikselowe rozmiarów (16px) lub konkretne nazwy czcionek ('Inter', sans-serif). Stanowią one punkt wyjścia, ale nie powinny być używane bezpośrednio w kodzie ani w makietach, aby uniknąć długu technicznego.

1. Tokeny prymitywne (Primitive Tokens): To pierwszy poziom abstrakcji. Tokeny prymitywne digitalizują surowe dane, nadając im sensowne, ale wciąż abstrakcyjne nazwy. Na przykład, #0055FF może stać się blue-500. Jeśli marka zdecyduje się zmienić odcień swojego firmowego niebieskiego, wystarczy zaktualizować wartość blue-500 w jednym miejscu, a zmiana ta automatycznie zastosuje się do wszystkich zależnych tokenów. Tokeny prymitywne często opisują palety kolorów, skale odstępów lub rozmiary czcionek.

2. Tokeny semantyczne (Semantic Tokens): Te tokeny opisują rolę lub przeznaczenie zasobu w interfejsie, odpowiadając na pytanie „Po co?”. Łączą one tokeny prymitywne z konkretnymi kontekstami użycia. Na przykład, blue-500 może być użyty do stworzenia color-bg-primary (główny kolor tła). Tokeny semantyczne odgrywają kluczową rolę w implementacji motywów (jasny/ciemny) i adaptacji do różnych trybów, ponieważ ten sam token semantyczny może odwoływać się do różnych prymitywów w zależności od aktywnego motywu.

3. Tokeny komponentowe (Component Tokens): Ten poziom opisuje konkretne miejsce zastosowania stylu w obrębie pojedynczego elementu lub komponentu, odpowiadając na pytanie „Gdzie?”. Tokeny komponentowe pozwalają precyzyjnie dostosować style dla konkretnych komponentów, nie wpływając na inne elementy, które mogą używać tych samych tokenów semantycznych. Służą do zarządzania wyjątkami i specyficznymi wymaganiami komponentów, zapewniając jednocześnie dziedziczenie ogólnej semantyki. Na przykład, color-button-bg-primary-hover może być unikalny dla przycisku, nawet jeśli jego bazowy token semantyczny jest używany w innych miejscach.

Metodologia CTI: Architektura nazewnictwa

CTI (Category → Type → Item) to jedna z najpopularniejszych modeli nazewnictwa design tokenów, szczególnie szeroko stosowana w połączeniu z narzędziem Style Dictionary, które spopularyzowało to podejście. Główna idea CTI polega na tym, że na pierwszym miejscu w nazwie tokenu znajduje się jego fizyczna właściwość lub kategoria, a nie komponent, do którego się odnosi. To sprawia, że system jest łatwo interpretowalny dla kompilatorów i skryptów.

Formuła nazewnictwa w CTI zazwyczaj wygląda tak: Category-Type-Item-Subitem-State.

Rozłóżmy każdy element:

• Category (Kategoria): Określa podstawową fizyczną naturę tokenu. Jest to zawsze pierwsze słowo w nazwie tokenu i wskazuje na typ danych. Przykłady: color (kolor), size (rozmiar), font (czcionka), spacing (odstęp), radius (zaokrąglenie).
• Type (Typ): Opisuje, do jakiej właściwości interfejsu użytkownika stosuje się dana kategoria. Przykłady: background (tło), text (tekst), border (ramka), icon (ikona).
• Item (Element): Wskazuje na konkretny element lub komponent interfejsu, do którego odnosi się token. Przykłady: button (przycisk), dropdown (lista rozwijana), container (kontener).
• Sub-item (Podelement / Modyfikator): Dodaje uszczegółowienie do elementu, oznaczając jego wariant lub rolę. Przykłady: primary, secondary, success, warning, danger.
• State (Stan): Opisuje interaktywny stan elementu. Przykłady: hover (po najechaniu), active (aktywny), disabled (wyłączony), focus (w fokusu).

Na przykład, token dla koloru tła głównego przycisku w stanie aktywnym będzie wyglądał jako color-background-button-primary-active.

Zalety i wady podejścia CTI

Jak każda metodologia, CTI ma swoje mocne i słabe strony, które należy wziąć pod uwagę przy projektowaniu systemu designu.

Zalety CTI:

• Optymalizacja dla kompilatorów: Ponieważ pierwsze słowo tokenu zawsze wskazuje na jego kategorię (color, size, font), skryptom-kompilatorom (np. Style Dictionary) niezwykle łatwo jest zrozumieć, z jakimi danymi pracują. Upraszcza to automatyczne generowanie zmiennych CSS, SCSS-mixinów, plików Swift i innych formatów z definicji tokenów w JSON, minimalizując potrzebę niestandardowych konfiguracji.
• Efektywny audyt i globalne zmiany: Dla front-end dewelopera, który chce sprawdzić lub zmienić wszystkie odstępy w aplikacji, wystarczy wyszukać prefiks $spacing- lub --spacing-. Pozwala to szybko uzyskać pełną listę wszystkich zmiennych odstępów, co jest wygodne do globalnego audytu lub masowych zmian.
• Standaryzacja: CTI jest domyślną architekturą dla narzędzi takich jak Style Dictionary, co sprawia, że jest dobrze udokumentowana i zrozumiała dla wielu deweloperów pracujących z systemami designu.

Wady CTI:

• Rozproszenie stylów komponentu: W nowoczesnych frameworkach komponentowych (React, Vue) komponent, na przykład przycisk, jest izolowaną jednostką. W podejściu CTI style tego przycisku są rozproszone po całym systemie designu: kolor może znajdować się w colors.json, odstępy — w spacings.json, a zaokrąglenia — w radii.json. Aby zebrać lub usunąć komponent, deweloper musi "biegać" po różnych plikach, co narusza kontekst i utrudnia pracę.
• Złożoność wyszukiwania i autouzupełniania: Deweloperowi, który tworzy przycisk, często ważniejsze jest szybkie znalezienie wszystkiego, co dotyczy button i primary, a nie prefiksów color czy background. W długich tokenach CTI te kluczowe słowa znajdują się w środku. Autouzupełnianie w IDE najpierw proponuje wiele kolorów, a trzeba wprowadzić dużą część tokenu, aby dotrzeć do potrzebnego komponentu.
• Pracochłonność refaktoryzacji komponentów: Jeśli firma zdecyduje się zmienić nazwę komponentu (np. modal na dialog), w podejściu CTI front-end deweloper będzie musiał szukać i zmieniać nazwy tokenów w wielu różnych kategoriach (kolory, cienie, z-index, odstępy). Gdyby na pierwszym miejscu znajdował się komponent (dialog-bg-color), wystarczyłoby zmienić nazwę jednego folderu lub grupy tokenów.

Tokeny semantyczne kontra komponentowe: Rozgraniczenie ról

Zrozumienie różnic między tokenami semantycznymi a komponentowymi jest kluczem do zbudowania elastycznego systemu designu. Chociaż ich formuły nazewnictwa są podobne, ich przeznaczenie diametralnie się różni.

Tokeny semantyczne odpowiadają na pytanie „Po co?”. Określają rolę lub intencję stylu. Na przykład, color-bg-primary oznacza "główny kolor tła", niezależnie od tego, gdzie zostanie użyty. Te tokeny są maksymalnie wielokrotnego użytku i służą do zapewnienia ogólnej spójności oraz wsparcia motywów. Ich formuła nazewnictwa: [kategoria]-[właściwość]-[rola]-[intensywność]-[stan].

Tokeny komponentowe odpowiadają na pytanie „Gdzie?”. Opisują style specyficzne dla konkretnego komponentu. Są używane, gdy konieczne jest odstępstwo od ogólnej semantyki lub zastosowanie unikalnego stylu do konkretnego elementu, nie wpływając na inne części systemu. W zasadzie są to zarządzane wyjątki. Ich formuła nazewnictwa: [kategoria]-[komponent]-[właściwość]-[rola]-[intensywność]-[stan]. Jak widać, w łańcuchu po prostu dodaje się [komponent].

Złota zasada: Jeśli token jest wielokrotnie używany w różnych miejscach i określa ogólne przeznaczenie, jest to token semantyczny. Jeśli wymagana jest zmiana stylu tylko dla jednego konkretnego elementu lub komponentu, jest to token komponentowy.

Szczegóły elementów nazewnictwa CTI

Dla głębszego zrozumienia nazewnictwa CTI, przyjrzyjmy się szczegółowo każdemu z jego elementów z przykładami:

• Category (Kategoria): Główny folder lub typ danych. Jest to podstawa do organizacji tokenów.

* color (kolory) – dla wszystkich wartości kolorów.

* spacing (odstępy) – dla wewnętrznych i zewnętrznych odstępów.

* radius (zaokrąglenia) – dla promieni zaokrąglenia narożników.

* shadow (cienie) – dla parametrów cieni.

* typography (typografia) – dla stylów tekstu (rozmiar, waga, interlinia).

* size (rozmiar) – dla szerokości/wysokości elementów.

* z-index (warstwy) – do zarządzania kolejnością nakładania się elementów.

* opacity (przezroczystość) – dla wartości przezroczystości.

* duration (animacja) – dla czasu trwania animacji.

• Property (Właściwość): Uszczegóławia, do której części UI odnosi się token w ramach kategorii.

* bg / surface (tło) – dla koloru tła.

* text (tekst) – dla koloru tekstu.

* border (ramka) – dla koloru ramki.

* icon (ikona) – dla koloru ikon.

* outline / ring (fokus) – dla obramowania przy fokusu.

* overlay (nakładka pod modalem) – dla koloru nakładki.

• Role (Rola / Znaczenie): Określa funkcjonalne lub emocjonalne znaczenie tokenu.

* primary / secondary / tertiary (ważność) – do oznaczania hierarchii.

* brand / accent (styl firmowy) – dla kolorów marki.

* success (sukces/zielony) – dla komunikatów o sukcesie.

* warning (ostrzeżenie/żółty) – dla ostrzeżeń.

* danger / error (błąd/czerwony) – dla błędów.

* neutral (neutralny/szary) – dla neutralnych elementów.

* inverse (dla ciemnych teł) – dla elementów, które odwracają kolor na ciemnym tle.

* static (niezmienny w motywach: white/black) – dla kolorów niezależnych od motywu.

• Prominence (Hierarchia / Intensywność): Opisuje intensywność lub widoczność elementu.

* default / main / base – punkt odniesienia, stan bazowy (często pomijany w nazwie).

* muted (przygaszony) – mniej zauważalny.

* subtle (ledwo zauważalny) – bardzo subtelny.

* intense (wzmocniony) – bardziej wyrazisty.

* on-brand (kontrastowa treść na tle marki) – dla tekstu lub ikon na kolorze marki.

• State / Modifier / Size (Stan / Modyfikator / Rozmiar): Dodatkowe uszczegółowienia.

* Stany: hover, active, focus, disabled – dla interaktywnych stanów.

* Rozmiary: sm, md, lg, xl – dla różnych rozmiarów komponentów lub elementów.

Ważna zasada dla stanu default: Jeśli token znajduje się w stanie bazowym, spokojnym, sufiks -default jest zazwyczaj pomijany. Na przykład, color-text-primary domyślnie oznacza default-stan. Inne stany dodawane są po roli, na przykład, color-text-primary-hover.

Praktyczne przykłady budowania struktury tokenów (CTI)

Dla utrwalenia zrozumienia, rozważmy kilka praktycznych przykładów budowania tokenów dla przycisków, demonstrujących przejście od surowych wartości do specyficznych tokenów komponentowych.

Przykład 1: Przycisk accent w stanie default

Załóżmy, że mamy główny przycisk z akcentującym kolorem.

• 0. Raw Value: #0055FF (surowy niebieski kolor)
• 1. Primitive Token: blue-500 (abstrakcja surowej wartości)
• 2. Semantic Token: color-bg-accent (główny akcentujący kolor tła, odwołuje się do blue-500)
• 3. Component Token: color-button-accent-bg (kolor tła akcentującego przycisku, odwołuje się do color-bg-accent)

Tutaj widzimy, jak od ogólnego (blue-500) przechodzimy do bardziej specyficznego (color-button-accent-bg). Ważne jest, że w tokenie komponentowym nie piszemy -default, ponieważ jest to domyślne.

Przykład 2: Przycisk accent w stanie hover

Teraz rozważmy, jak zmieni się nazewnictwo dla tego samego przycisku po najechaniu.

• 0. Raw Value: #0044DD (ciemniejszy niebieski)
• 1. Primitive Token: blue-600 (abstrakcja ciemniejszego niebieskiego)
• 2. Semantic Token: color-bg-accent-hover (akcentujący kolor tła po najechaniu, odwołuje się do blue-600)
• 3. Component Token: color-button-accent-bg-hover (kolor tła akcentującego przycisku po najechaniu, odwołuje się do color-bg-accent-hover)

Tutaj wyraźnie dodaje się sufiks -hover, wskazujący na interaktywny stan. Każdy poziom abstrakcji sprawia, że system designu jest bardziej elastyczny, pozwalając zmieniać odcienie na poziomie prymitywów, nie zmieniając nazw tysięcy tokenów.

Przykład 3: Przycisk secondary w stanie default

Dla drugorzędnego przycisku można użyć innej palety, na przykład z przezroczystością.

• 0. Raw Value: #0055FF z przezroczystością 10% lub rgba(0, 85, 255, 0.1)
• 1. Primitive Token: blue-transparent-100
• 2. Semantic Token: color-bg-secondary (odwołuje się do blue-transparent-100)
• 3. Component Token: color-button-secondary-bg (odwołuje się do color-bg-secondary)

Takie podejście pozwala łatwo przełączać palety dla różnych typów przycisków, używając wspólnej struktury tokenów.

Przykład 4: Tekst przycisku secondary w stanie default

Rozważmy token dla tekstu wewnątrz drugorzędnego przycisku.

• 0. Raw Value: #0055FF
• 1. Primitive Token: blue-500
• 2. Semantic Token: color-text-on-brand (kolor tekstu na tle marki, odwołuje się do blue-500). Tutaj pojawia się modyfikator on-brand, wskazujący na kontekst użycia.
• 3. Component Token: color-button-secondary-text-on-brand (kolor tekstu drugorzędnego przycisku, odwołuje się do color-text-on-brand)

Jak widać, zawsze najpierw idzie kategoria (color, spacing, typography), następnie właściwość lub komponent, za którymi podążają modyfikatory i stany. Ta zasada „od ogółu do szczegółu” zapewnia przewidywalność i łatwość nawigacji po systemie designu.

Co ważne

• Design tokeny są kluczowym elementem do tworzenia skalowalnych, spójnych i łatwych w utrzymaniu systemów designu, zapobiegając długowi technicznemu związanemu z zakodowaniem stylów na stałe.
• Wielopoziomowy model abstrakcji (Surowe wartości → Prymitywne → Semantyczne → Komponentowe tokeny) zapewnia elastyczność i zarządzalność, pozwalając wprowadzać globalne zmiany z jednego miejsca.
• Metodologia CTI (Category → Type → Item) — popularne podejście do nazewnictwa, które jest wygodne do automatycznego przetwarzania przez kompilatory, ale może utrudniać kontekstowe wyszukiwanie i refaktoryzację stylów komponentów.
• Tokeny semantyczne określają rolę i przeznaczenie stylu, zapewniając ponowne użycie i wsparcie motywów, podczas gdy tokeny komponentowe służą do precyzyjnego dostosowywania i zarządzania wyjątkami w ramach konkretnych komponentów.
• Jasne zasady nazewnictwa z wykorzystaniem kategorii, właściwości, ról, hierarchii i stanów są krytycznie ważne dla utrzymania porządku i przewidywalności w systemie designu.

— Editorial Team