Design tokens w praktyce, z konwerterem JSON na CSS na żywo
Design tokens w praktyce
Design tokens w praktyce z przykładami (JSON, CSS, Tailwind) | We.Inc
Czym są design tokens, jak zapisuje je format JSON grupy społecznościowej W3C, oraz konwerter na żywo, który zamienia JSON z tokenami na zmienne CSS i blok @theme dla Tailwind v4.
Design tokens to nazwane decyzje projektowe, takie jak color.primary czy space.md, zapisane jako dane, aby każda platforma czytała te same wartości. Format Design Tokens Community Group zapisuje je w JSON z $value i $type i pozwala jednemu tokenowi wskazywać na inny za pomocą nawiasów klamrowych. Narzędzia zamieniają potem ten JSON na zmienne CSS, motywy Tailwind lub kod aplikacji.
Poziomy tokenów używane przez większość zespołów
Poziom
Przykładowa nazwa
Przechowuje
Bazowy (prymityw)
Surową wartość: kolor, rozmiar lub czcionkę
Semantyczny (alias)
Rolę wskazującą na token bazowy
Komponentowy
Rolę ograniczoną do jednego komponentu
Większość wyjaśnień kończy się na definicji. Wklej lub edytuj poniżej JSON z tokenami w formacie grupy społecznościowej i zobacz w trakcie pisania, jakie właściwości niestandardowe CSS i motyw Tailwind v4 z niego powstają, z aliasami zamienionymi na odwołania var().
Edytuj JSON po lewej. Grupy mogą ustawić $type raz dla wszystkich tokenów w środku.
Odwołuj się do innego tokenu, ujmując jego ścieżkę z kropkami w nawiasy klamrowe, np. {color.blue-500}.
Zakładka CSS pokazuje zmienne :root, a zakładka Tailwind blok @theme.
Skopiuj wynik do swojego arkusza stylów. Najpierw popraw błędy pokazane pod edytorem.
Nazywaj tokeny semantyczne według ich zadania (text, surface, danger), a nie wyglądu (red, dark), aby rebranding zmieniał tylko poziom bazowy.
Nie używaj tokenów bazowych w komponentach. Komponenty powinny czytać nazwy semantyczne, aby tryb ciemny i motywy mogły podmieniać wartości pod spodem.
Trzymaj tokeny w jednym pliku pod kontrolą wersji i generuj z niego wynik dla każdej platformy.
Używaj zalecanego rozszerzenia .tokens lub .tokens.json, aby narzędzia rozpoznawały pliki.
Najczęściej zadawane pytania
Czym jest design token?
Design token to nazwa połączona z wartością projektową, np. color.text przechowujący prawie czarny kolor. Kod i pliki projektowe używają nazwy, więc zmiana wartości w jednym miejscu aktualizuje każdy przycisk, stronę i aplikację, która się do niej odwołuje.
Czy istnieje standardowy format design tokens?
Tak. Design Tokens Community Group przy W3C opublikowała 28 października 2025 Format Module 2025.10 jako końcowy raport grupy społecznościowej i określa go jako stabilny. To raport grupy społecznościowej, a nie Rekomendacja W3C.
Czym różnią się design tokens od zmiennych CSS?
Tokeny to dane źródłowe, niezależne od platformy. Właściwości niestandardowe CSS to jeden z możliwych wyników. Ten sam plik tokenów może też generować stałe w Swift, Androidzie czy JavaScripcie, czego same zmienne CSS Ci nie dadzą.
Jak design tokens współpracują z Tailwind CSS?
W Tailwind v4 deklarujesz zmienne motywu wewnątrz @theme, np. --color-primary. Tailwind tworzy z nich klasy użytkowe, takie jak bg-primary, i dodatkowo emituje je jako zwykłe zmienne CSS na :root, więc tokeny i klasy pozostają zsynchronizowane.
Jak zapisuje się kolory w formacie tokenów?
W formacie 2025.10 wartość koloru to obiekt z colorSpace, np. srgb, i tablicą składowych od 0 do 1, z opcjonalnym kanałem alfa. Ten konwerter przyjmuje też zwykłe ciągi znaków, więc możesz wklejać starsze pliki tokenów.
Dlaczego zespoły wprowadzają tokeny
Bez tokenów firmowy niebieski żyje jako kod hex wklejony w setki miejsc w CSS, aplikacjach mobilnych i plikach projektowych. Jego zmiana oznacza wyszukiwanie i zamianę, które zawsze jakieś miejsce pominie.
Z tokenami ten niebieski ma jedną nazwę i jedno miejsce. Projektanci i programiści mówią o color.primary, a krok budowania zapisuje wartość we własnym formacie każdej platformy.
Jak czytać format JSON
Każdy obiekt z $value to token; każdy inny obiekt to grupa. Właściwości zaczynające się od znaku dolara są zarezerwowane przez format: $value, $type, $description, $deprecated i $extensions.
Specyfikacja definiuje proste typy, takie jak color, dimension, fontFamily, fontWeight, duration, cubicBezier i number, oraz typy złożone, takie jak shadow, border, transition, typography, strokeStyle i gradient. Wymiary i czasy trwania to obiekty z wartością liczbową i jednostką.
Od tokenów do działającego motywu
Mała strona może trzymać tokeny bezpośrednio w CSS jako właściwości niestandardowe. Gdy wydajesz na więcej niż jedną platformę albo projektujesz w narzędziu eksportującym tokeny, generuj CSS z JSON, aby mieć jedno źródło.
Tryb ciemny staje się drugim zestawem wartości semantycznych. Kolory bazowe pozostają te same, a warstwa semantyczna podmienia, na który kolor bazowy wskazuje każda rola, wewnątrz media query dla ciemnego schematu lub atrybutu data.
Tokeny semantyczne z ciemnym motywem
Podmień wartości semantyczne, zostaw bazowe
Karta czyta tylko --surface i --text. Blok ciemny przypisuje tym dwóm nazwom nowe wartości, a karta dostosowuje się bez żadnej zmiany we własnych regułach.
Token złożony
Token cienia w formacie grupy społecznościowej
Tokeny złożone grupują kilka wartości. Tutaj kolor sam jest aliasem, a przesunięcia używają obiektów dimension.
Nie znaleziono tokenów. Token to obiekt z właściwością $value.
To jeszcze nie jest poprawny JSON: {message}
Konwerter JSON z tokenami na CSS
Edytuj plik tokenów, a zmienne CSS i motyw Tailwind aktualizują się w trakcie pisania. Plik startowy daje taki wynik: