Architektura tokenów dla wielu motywów i marek

Motyw zmienia tryb kolorystyczny tej samej marki (jasną i ciemną wersję tego samego produktu). Marka to odmienna tożsamość wizualna — te same komponenty systemu projektowego są renderowane z innymi kolorami, typografią i odstępami, aby obsługiwać różne produkty lub klientów. Oba rozwiązania korzystają z tej samej architektury tokenów, ale działają na różnych poziomach abstrakcji.

Tokeny prymitywne to pełna paleta surowych wartości dostępnych w systemie. Obejmuje ona każdy odcień koloru (color-blue-50 do color-blue-900), każdą jednostkę odstępów oraz każdy rozmiar czcionki. Tokenów prymitywnych nigdy nie używa się bezpośrednio w komponentach — odwołują się do nich wyłącznie tokeny semantyczne. Paletę definiuje się raz i współdzieli między wszystkimi motywami i markami.

Tokeny semantyczne wyrażają intencję: color-background-page, color-text-primary, color-action-primary. Każdy token semantyczny odwołuje się do wartości tokenu prymitywnego odpowiedniej dla bieżącego motywu. Komponenty buduje się wyłącznie w oparciu o tokeny semantyczne. To warstwa odpowiedzialna za obsługę motywów.

W jasnym motywie: color-background-page odwołuje się do color-white, color-text-primary odwołuje się do color-gray-900, a color-action-primary odwołuje się do color-blue-500. Te mapowania są definiowane w pliku tokenów właściwym dla motywu, który nadpisuje warstwę semantyczną w jasnym kontekście.

W ciemnym motywie: color-background-page odwołuje się do color-gray-950, color-text-primary odwołuje się do color-gray-50, a color-action-primary odwołuje się do color-blue-400 (nieco jaśniejszego, aby zachować kontrast na ciemnym tle). Zmieniają się tylko mapowania semantyczne — paleta prymitywna i wszystkie komponenty pozostają bez zmian.

Marka A używa niebieskiego jako koloru podstawowego (color-action-primary: {color-blue-500}). Marka B używa zielonego (color-action-primary: {color-green-500}). Komponent przycisku odczytuje var(--color-action-primary) — nie wie nic o tym, która marka jest aktywna. Nadpisania marki zmieniają wyłącznie mapowania tokenów semantycznych, nigdy kod komponentów.

Własne właściwości CSS sprawiają, że przełączanie motywu w czasie działania jest bardzo proste. Przechowuj bieżący motyw w atrybucie danych: document.documentElement.setAttribute('data-theme', 'dark'). Reguły CSS nadpisują tokeny semantyczne w obrębie selektora [data-theme="dark"]. Przeglądarka natychmiast rozwiązuje wszystkie odwołania var() do nowych wartości — ponowne renderowanie za pomocą JavaScriptu nie jest wymagane.

W przypadku różnych marek obsługiwanych w ramach oddzielnych wdrożeń zastosuj motywowanie podczas budowania: wygeneruj oddzielne pliki tokenów CSS dla każdej marki za pomocą Style Dictionary i wczytaj właściwy plik CSS marki podczas uruchamiania aplikacji. To podejście sprawdza się, gdy marka jest określana podczas wdrażania (na podstawie różnych domen, subdomen lub instancji whitelabel), a nie podczas interakcji użytkownika.

System obsługujący wiele marek i motywów wymaga macierzy dwuwymiarowej: Marka A — jasny motyw, Marka A — ciemny motyw, Marka B — jasny motyw, Marka B — ciemny motyw. Własne właściwości CSS elegancko obsługują ten przypadek za pomocą zagnieżdżonych selektorów: [data-brand="a"][data-theme="dark"] nadpisuje tokeny semantyczne dla konkretnej kombinacji. Cztery kombinacje oznaczają cztery bloki CSS, a nie cztery bazy kodu.

W miarę rozwoju systemu projektowego tokeny są dodawane, zmieniane lub usuwane. Wersjonuj tokeny w tym samym repozytorium co kod. Podczas wycofywania tokenu zachowaj starą nazwę jako alias wskazujący na nową nazwę przez jeden cykl wydania, dodaj komentarz o wycofaniu i zaktualizuj kod korzystający z tokenu. Koordynuj zmiany tokenów między zespołami projektowymi i programistycznymi za pomocą ustrukturyzowanego dziennika zmian.

Zarządzanie określa, kto może dodawać tokeny lub je zmieniać oraz jaki proces weryfikacji jest wymagany. Tokeny prymitywne wymagają zatwierdzenia zespołu projektowego. Tokeny semantyczne wymagają weryfikacji zarówno zespołu projektowego, jak i inżynieryjnego. Tokenami komponentów może zarządzać właściciel komponentu. Bez takiego zarządzania pojawiają się zduplikowane tokeny, a gwarancja jednego źródła prawdy przestaje obowiązywać.

Motywy zmieniają tryby kolorystyczne w obrębie marki, natomiast marki to różne identyfikacje wizualne. Tokeny prymitywne to surowa paleta, a tokeny semantyczne wyrażają znaczenie i umożliwiają stosowanie motywów. Komponenty używają wyłącznie tokenów semantycznych. Tryb ciemny i nadpisania marki zmieniają tylko mapowania tokenów semantycznych — komponenty pozostają bez zmian. Motywy stosowane w czasie działania wykorzystują niestandardowe właściwości CSS z selektorami [data-theme], a branding na etapie budowania generuje osobny plik CSS dla każdej marki. Zarządzanie tokenami i wersjonowanie zapewniają spójność systemu w miarę jego rozwoju.