Style Dictionary: преобразование и генерация токенов

Style Dictionary, созданный Amazon, — это инструмент сборки, который принимает определения дизайн-токенов в формате JSON и преобразует их в любой целевой формат: пользовательские свойства CSS, модули JavaScript ES, переменные Sass, константы Swift для iOS, ресурсы XML для Android и любой собственный формат, который вы определите. Единый источник истины, множество выходных форматов.

Установите пакет с помощью npm install --save-dev style-dictionary. Инициализируйте структуру проекта командой npx style-dictionary init: она создаст config.json (или config.js) и каталог tokens/. Файл конфигурации сообщает Style Dictionary, где искать файлы токенов и куда записывать результаты.

Style Dictionary использует вложенную структуру JSON, в которой конечные узлы имеют свойство value. Например: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. Путь к значению (color, primary, 500) после преобразования становится именем токена, обычно в формате color-primary-500 или --color-primary-500.

Запустите npx style-dictionary build --config config.json (или style-dictionary build, если команда настроена в сценариях package.json). Style Dictionary читает все файлы токенов из настроенного источника, применяет преобразования и записывает результаты в указанные места. Ошибки в формате токенов выводятся с именем файла и путём.

В config.json определены платформы: css (создаёт файл CSS с пользовательскими свойствами), js (создаёт объект JS), scss (создаёт переменные Sass). Для каждой платформы указываются каталог вывода, имя файла, формат (шаблон) и применяемые преобразования (функции обработки имени и значения).

Style Dictionary включает встроенные преобразования: name/cti/kebab преобразует вложенный путь в color-primary-500, name/cti/camel создаёт colorPrimary500, size/rem преобразует значения в пикселях в rem, а color/hex приводит цвета к формату hex. Преобразования можно комбинировать, и они применяются по порядку.

Вы можете зарегистрировать пользовательские преобразования с помощью StyleDictionary.registerTransform(). Например, преобразование может переводить значения в пикселях в пункты iOS или добавлять префикс компании ко всем именам токенов. Пользовательские преобразования дают полный контроль над обработкой значений перед выводом.

Пользовательские форматы определяют шаблон выходного файла. StyleDictionary.registerFormat() получает словарь преобразованных токенов и возвращает строку — содержимое файла. Вы можете выводить токены в виде типов TypeScript, объекта темы React, расширения конфигурации Tailwind или любого другого формата, необходимого вашему стеку.

После сборки импортируйте вывод CSS в глобальную таблицу стилей: @import './tokens/tokens.css'. Импортируйте вывод JS в компоненты или конфигурацию Tailwind: import tokens from './tokens/tokens.js'. CSS предоставляет пользовательские свойства для темизации во время выполнения, а JS — типизированные константы для Tailwind и логики JavaScript.

Style Dictionary поддерживает ссылки на токены с использованием фигурных скобок: { "value": "{color.primary.500}" }. Так создаются псевдонимы семантических токенов: семантический токен ссылается на примитивный токен. Во время сборки Style Dictionary разрешает ссылки и выводит итоговое значение (или ссылку на переменную CSS — в зависимости от формата).

Запускайте Style Dictionary как сценарий npm prebuild, чтобы токены всегда пересоздавались перед сборкой приложения. Добавьте "prebuild": "style-dictionary build" в package.json. Это гарантирует, что любые изменения в файлах JSON токенов будут отражены в результатах CSS и JS до того, как сборка React начнёт их обрабатывать.

Для чего нужны преобразования в Style Dictionary?

Style Dictionary преобразует JSON токенов в любой выходной формат: переменные CSS, модули JS, Sass, iOS и Android. JSON токенов использует вложенные объекты с конечными узлами value. Преобразования обрабатывают имена и значения (camelCase, преобразование px в rem), а форматы определяют шаблон вывода. Ссылки на токены ({color.primary.500}) позволяют создавать семантические псевдонимы. Автоматизируйте процесс с помощью сценария prebuild, чтобы перед сборкой React токены всегда были актуальными.