Tokeny w Tailwind, zmienne CSS i CSS-in-JS

Wyjście platformy CSS w Style Dictionary generuje plik z niestandardowymi właściwościami CSS: --color-primary-500: #3b82f6; --spacing-4: 16px; i tak dalej. Zmienne te są definiowane na :root, dzięki czemu są dostępne globalnie. Stanowi to podstawę wykorzystywania wszystkich tokenów w aplikacji.

Należy zaimportować wygenerowany plik tokenów CSS do globalnego arkusza stylów lub głównego komponentu layoutu: @import './tokens/tokens.css'. W Next.js należy zaimportować go w app/layout.tsx lub styles/globals.css. Po zaimportowaniu każda reguła CSS i każdy komponent w aplikacji może odwoływać się do niestandardowych właściwości.

W arkuszach stylów komponentów lub modułach CSS należy odwoływać się do zmiennych CSS: background-color: var(--color-primary-500); oraz padding: var(--spacing-4);. Jeśli wartość tokenu zmieni się w źródłowym pliku JSON, ponowne zbudowanie Style Dictionary zaktualizuje plik CSS, a wszystkie komponenty korzystające z tej zmiennej automatycznie odzwierciedlą nową wartość.

Niestandardowe właściwości CSS umożliwiają przełączanie motywów w czasie działania. W trybie ciemnym należy nadpisać wartości tokenów w selektorze motywu: [data-theme="dark"] { --color-background: #1a1a2a; --color-text: #f0f0f0; }. Ustawienie document.documentElement.setAttribute('data-theme', 'dark') natychmiast przełącza wszystkie wartości tokenów bez ponownego ładowania ani budowania aplikacji.

Należy rozszerzyć motyw Tailwind w pliku tailwind.config.js, aby używać wartości tokenów: theme: { extend: { colors: { primary: { 500: tokenOutput.color.primary[500] } } } }. Należy zaimportować wyjście JS ze Style Dictionary do konfiguracji Tailwind, aby klasy Tailwind (bg-primary-500) zawsze korzystały z autorytatywnych wartości tokenów.

Aby umożliwić przełączanie motywów w czasie działania za pomocą Tailwind, należy skonfigurować kolor tak, aby odwoływał się do zmiennej CSS: 'primary': 'rgb(var(--color-primary-rgb) / <alpha-value>)'. Wymaga to przechowywania w zmiennej CSS składowych RGB bez otoczenia funkcją rgb() (--color-primary-rgb: 59 130 246). Tailwind automatycznie obsłuży wtedy narzędzia przezroczystości.

Biblioteki CSS-in-JS korzystają z obiektu motywu w JavaScript. Należy przekazać wyjście JS ze Style Dictionary jako wartość dostawcy motywu: <ThemeProvider theme={tokens}>. Komponenty uzyskują dostęp do tokenów za pomocą const theme = useTheme() i theme.color.primary[500]. Style Dictionary generuje obiekt tokenów z typami, a dostawca motywu udostępnia go komponentom.

Wtyczka stylelint-no-hardcoded-colors oraz niestandardowe reguły ESLint mogą wymusić, aby w arkuszach stylów i plikach komponentów nie występowały zapisane na stałe wartości szesnastkowe. Jeśli programista wpisze color: #3b82f6 zamiast color: var(--color-primary-500), linter zgłosi błąd. Dzięki temu system tokenów pozostaje jedynym źródłem kolorów.

Gdy nazwy klas Tailwind są konstruowane dynamicznie na podstawie nazw tokenów w czasie działania, mechanizm purge Tailwind może usunąć te klasy, ponieważ nie występują one w kodzie źródłowym jako statyczne ciągi znaków. Należy dodać wzorce dynamicznych klas do safelist w pliku tailwind.config.js: safelist: [{ pattern: /bg-primary-/ }].

Wtyczka Figma Tokens eksportuje wartości tokenów z Figmy bezpośrednio do formatu JSON Style Dictionary. Przebieg pracy wygląda następująco: projektanci aktualizują kolory w Figma Variables, eksportują je za pomocą wtyczki, zatwierdzają zaktualizowany plik JSON, skrypt prebuild uruchamia Style Dictionary, a zaktualizowane wyjścia CSS i JS są wykorzystywane w aplikacji React. Dzięki temu projekt i kod pozostają zsynchronizowane.

Niestandardowe właściwości CSS obowiązują w elemencie, na którym zostały zdefiniowane, oraz w jego elementach potomnych. Umożliwia to nadpisywanie motywu na poziomie komponentu: komponent karty może ustawić --color-background: var(--color-surface-elevated) na swoim elemencie głównym, a wszystkie elementy potomne użyją koloru wyniesionej powierzchni bez prop drilllingu.

Style Dictionary generuje niestandardowe właściwości CSS do globalnego importu oraz obiekty JS na potrzeby integracji z Tailwind i CSS-in-JS. Zmienne CSS umożliwiają przełączanie motywów w czasie działania za pomocą nadpisań [data-theme]. Tailwind rozszerza swoją konfigurację o wartości tokenów z wyjścia JS; aby obsługiwać motywy z przezroczystością, należy skonfigurować Tailwind tak, aby odwoływał się do zmiennych CSS przechowujących składowe RGB. Reguły lintowania wymuszają używanie wyłącznie tokenów kolorów, dzięki czemu zapisane na stałe wartości nie trafiają do bazy kodu.