Style Dictionary: transformowanie i generowanie tokenów

Style Dictionary, utworzone przez Amazon, to narzędzie do budowania, które pobiera definicje tokenów projektowych w formacie JSON i generuje je w dowolnym formacie docelowym: niestandardowych właściwościach CSS, modułach JavaScript ES, zmiennych Sass, stałych Swift dla systemu iOS, zasobach XML dla systemu Android oraz dowolnym zdefiniowanym przez Ciebie formacie. Jedno źródło prawdy, wiele wyników.

Zainstaluj pakiet za pomocą npm install --save-dev style-dictionary. Zainicjalizuj strukturę projektu poleceniem npx style-dictionary init, które utworzy plik config.json (lub config.js) oraz katalog tokens/. Konfiguracja informuje Style Dictionary, gdzie znajdują się pliki tokenów i gdzie zapisywać wyniki.

Style Dictionary używa zagnieżdżonej struktury JSON, w której węzły końcowe mają właściwość value. Na przykład: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. Ścieżka do wartości (color, primary, 500) staje się po transformacji nazwą tokenu, zwykle zapisywaną jako color-primary-500 lub --color-primary-500.

Uruchom npx style-dictionary build --config config.json (lub style-dictionary build, jeśli skonfigurowano je w skryptach package.json). Style Dictionary odczytuje wszystkie pliki tokenów ze skonfigurowanego źródła, stosuje transformacje i zapisuje wyniki w skonfigurowanych miejscach docelowych. Błędy w formacie tokenów są zgłaszane wraz z nazwą pliku i ścieżką.

Plik config.json definiuje platformy: css (generuje plik CSS z własnymi właściwościami), js (generuje obiekt JS), scss (generuje zmienne Sass). Każda platforma określa katalog wyjściowy, nazwę pliku, format (szablon) oraz transformacje (funkcje przetwarzające nazwę i wartość), które należy zastosować.

Style Dictionary zawiera wbudowane transformacje: name/cti/kebab przekształca zagnieżdżoną ścieżkę w color-primary-500, name/cti/camel generuje colorPrimary500, size/rem przelicza wartości pikselowe na rem, a color/hex normalizuje kolory do zapisu szesnastkowego. Transformacje można łączyć i są stosowane w określonej kolejności.

Niestandardowe transformacje można rejestrować za pomocą StyleDictionary.registerTransform(). Możesz na przykład utworzyć transformację przeliczającą wartości pikselowe na punkty iOS albo dodającą do wszystkich nazw tokenów prefiks specyficzny dla firmy. Niestandardowe transformacje zapewniają pełną kontrolę nad przetwarzaniem wartości przed wygenerowaniem wyników.

Niestandardowe formaty definiują szablon pliku wyjściowego. StyleDictionary.registerFormat() otrzymuje słownik przekształconych tokenów i zwraca ciąg znaków — zawartość pliku. Możesz generować tokeny jako typy TypeScript, obiekt motywu React, rozszerzenie konfiguracji Tailwind lub dowolny inny format wymagany przez Twój stos technologiczny.

Po zbudowaniu zaimportuj wynik CSS w globalnym arkuszu stylów: @import './tokens/tokens.css'. Zaimportuj wynik JS w komponentach lub konfiguracji Tailwind: import tokens from './tokens/tokens.js'. CSS udostępnia własne właściwości do zmiany motywu w czasie działania, a JS — stałe o określonych typach na potrzeby Tailwind i logiki JavaScript.

Style Dictionary obsługuje odwołania do tokenów za pomocą nawiasów klamrowych: { "value": "{color.primary.500}" }. Tworzy to semantyczne aliasy tokenów — token semantyczny odwołuje się do tokenu prymitywnego. Podczas budowania Style Dictionary rozwiązuje odwołania i generuje końcową wartość (lub odwołanie do zmiennej CSS, zależnie od formatu).

Uruchamiaj Style Dictionary jako skrypt npm prebuild, aby tokeny zawsze były generowane ponownie przed zbudowaniem aplikacji. Dodaj "prebuild": "style-dictionary build" do pliku package.json. Dzięki temu każda zmiana w plikach JSON tokenów zostanie uwzględniona w wynikach CSS i JS, zanim proces budowania Reacta je przetworzy.

Do czego służą transformacje w Style Dictionary?

Style Dictionary przekształca JSON tokenów w dowolny format wyjściowy: zmienne CSS, moduły JS, Sass, iOS i Android. JSON tokenów używa zagnieżdżonych obiektów z węzłami końcowymi zawierającymi value. Transformacje przetwarzają nazwy i wartości (camelCase, px-to-rem), a formaty definiują szablon wyniku. Odwołania do tokenów ({color.primary.500}) umożliwiają tworzenie semantycznych aliasów. Zautomatyzuj ten proces za pomocą skryptu prebuild, aby tokeny były zawsze aktualne przed zbudowaniem aplikacji React.