Style Dictionary на практике: токены в CSS, SCSS и TypeScript

Style Dictionary часто берут, чтобы превратить файл с токенами в код. Это открытый инструмент сборки, и основы в нём умещаются на одном экране. Но переживёт ли результат встречу с настоящей дизайн-системой, решают детали: ссылки, режимы, единицы измерения и переименования.

В этом руководстве мы собираем CSS, SCSS и TypeScript из одного файла токенов в формате W3C DTCG с помощью Style Dictionary 5.5.5, текущего релиза. Каждый результат ниже взят из настоящей сборки небольшой светлой и тёмной темы. Есть и эксперимент: что происходит с каждым форматом, когда токен переименовывают.

Коротко

• Style Dictionary v5 читает DTCG-файлы напрямую, но формат 2025.10 пока поддерживает лишь частично (документация Style Dictionary о DTCG).
• Включите outputReferences, чтобы --bg-accent: var(--color-blue-500) осталась ссылкой, а не скопированным значением.
• Собирайте каждый режим из своего файла и дайте каждому селектор: :root для светлой темы, [data-theme="dark"] для тёмной.
• Переименование токена ломает SCSS и TypeScript на этапе сборки. В CSS оно проходит молча, поэтому оставляйте старое имя ссылкой на один релиз.

Вход: по одному DTCG-файлу на режим

Style Dictionary v5 требует Node 22 или новее (гайд по миграции на v5) и сам распознаёт формат DTCG. На входе у нас светлый и тёмный файлы в формате 2025.10. Так их выгружает из переменных Figma FISYCO, инструмент, который мы делаем. Важная часть выглядит так:

{
  "color": {
    "blue": {
      "500": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0.1451, 0.3882, 0.9216], "alpha": 1, "hex": "#2563eb" } }
    }
  },
  "bg": {
    "accent": { "$type": "color", "$value": "{color.blue.500}" }
  },
  "space": {
    "200": { "$type": "number", "$value": 8 }
  }
}

Цвета записаны в структурированной форме, которую ввёл формат 2025.10. Style Dictionary читает её начиная с версии 5.3.0. bg.accent здесь ссылка, а не hex-значение. В тёмном файле она указывает на color.blue.300.

Один конфиг на три формата

Один конфиг, три платформы. В Style Dictionary есть готовые группы трансформаций для CSS, SCSS и JavaScript. Отдельной группы для TypeScript нет, поэтому объявления типов собираются из группы js.

import StyleDictionary from "style-dictionary";

const sd = new StyleDictionary({
  source: ["tokens/design-tokens.light.tokens.json"],
  platforms: {
    css: {
      transformGroup: "css",
      buildPath: "build/",
      files: [{ destination: "tokens.css", format: "css/variables", options: { outputReferences: true } }],
    },
    scss: {
      transformGroup: "scss",
      buildPath: "build/",
      files: [{ destination: "_tokens.scss", format: "scss/variables", options: { outputReferences: true } }],
    },
    ts: {
      transformGroup: "js",
      buildPath: "build/",
      files: [
        { destination: "tokens.js", format: "javascript/es6" },
        { destination: "tokens.d.ts", format: "typescript/es6-declarations" },
      ],
    },
  },
});

await sd.buildAllPlatforms();

Установите пакет командой npm i -D style-dictionary, сохраните конфиг как build.mjs (в нём ES-модули и await на верхнем уровне) и запустите node build.mjs. В buildPath нужен слэш в конце. На каждый записанный файл сборка печатает одну строку.

Что получается на выходе

Токены в CSS, то есть кастомные свойства, со ссылкой на месте:

:root {
  --color-blue-500: #2563eb;
  --space-200: 8;
  --bg-accent: var(--color-blue-500);
}

Переменные SCSS, ссылка тоже сохранена:

$color-blue-500: #2563eb;
$space-200: 8;
$bg-accent: $color-blue-500;

И TypeScript: значения в tokens.js, типы в tokens.d.ts, имена в PascalCase:

export const ColorBlue500: string;
export const BgAccent: string;
export const Space200: number;

Первым делом проверьте опцию outputReferences. Без неё --bg-accent превращается в застывшую копию #2563eb. Тема, которая переопределяет --color-blue-500, до неё не дотянется, а файлы режимов ниже не смогут ссылаться на палитру. С этой опцией связь из макета доходит до стилей. В JavaScript значения разрешаются в любом случае: BgAccent равен "#2563eb".

Числам нужны единицы

Ещё раз посмотрите на --space-200: 8. У числовой переменной в Figma нет единиц, поэтому в файле она хранится как number, и в CSS попадает голое 8. Тогда padding: var(--space-200) становится невалидным. Встроенная трансформация size/px не поможет: она работает только с токенами типов dimension и font-size.

Своя трансформация решает это в несколько строк. Ограничьте её по пути, чтобы числа для прозрачности или z-index остались без единиц:

StyleDictionary.registerTransform({
  name: "size/px-from-figma",
  type: "value",
  filter: (token) => token.$type === "number" && token.path[0] === "space",
  transform: (token) => `${token.$value}px`,
});

Добавьте transforms: ["size/px-from-figma"] рядом с transformGroup в CSS-платформе, и сборка запишет --space-200: 8px.

У типографики своя особенность. CSS-трансформации сворачивают типографический токен в сокращённое свойство font: 400 16px/1.5 Inter. А межбуквенного интервала в этом сокращении нет. Style Dictionary предупреждает об этом при каждой сборке («Unknown CSS Font Shorthand properties»). Если межбуквенный интервал важен, выводите типографику отдельными свойствами через свой формат.

Светлая и тёмная тема

В Format Module 2025.10 нет режимов. Темы вынесены в отдельный Resolver Module, который Style Dictionary 5.5.5 пока не читает, поэтому каждый режим живёт в своём файле. Соберите их в цикле и дайте каждому селектор. Так выглядит тёмная тема на токенах:

for (const [mode, selector] of [["light", ":root"], ["dark", '[data-theme="dark"]']]) {
  const sd = new StyleDictionary({
    source: [`tokens/design-tokens.${mode}.tokens.json`],
    platforms: {
      css: {
        transformGroup: "css",
        buildPath: "build/",
        files: [{
          destination: `tokens.${mode}.css`,
          format: "css/variables",
          filter: (token) => ["bg", "fg"].includes(token.path[0]),
          options: { selector, outputReferences: true },
        }],
      },
    },
  });
  await sd.buildAllPlatforms();
}

В тёмном файле остаётся только то, что меняется:

[data-theme="dark"] {
  --bg-accent: var(--color-blue-300);
  --fg-default: var(--color-gray-50);
}

Фильтр не пускает палитру в файлы режимов, но теперь Style Dictionary предупреждает: «filtered out token references were found». Здесь так и задумано: --color-blue-300 лежит в базовой таблице стилей, которую вы подключаете первой. Если предупреждение появилось, а вы этого не планировали, значит, ссылка ведёт на токен, который вы не выпустили.

Эксперимент: переименовываем один токен

Токены в дизайн-системах переименовывают. Мы переименовали bg/accent в bg/brand и сохранили ID переменной в Figma, как это и происходит при переименовании в Figma. Затем заново выгрузили токены и пересобрали. Style Dictionary сделал ровно то, что ему сказали:

-  --bg-accent: var(--color-blue-500);
+  --bg-brand: var(--color-blue-500);

Потом мы подключили новую сборку к трём потребителям, и каждый из них по-прежнему использовал старое имя.

CSS не выдал ни одной ошибки. background: var(--bg-accent) теперь ссылается на несуществующее свойство, поэтому браузер считает объявление равным unset (MDN: invalid values), и фон становится прозрачным. Кнопка уходит в релиз без цвета.

Выходит, что самые шумные форматы как раз безопасные. CSS ломается молча, а запасное значение вроде var(--bg-accent, #2563eb) только прячет поломку.

Переименование становится безопасным благодаря двум привычкам:

1. Оставляйте старое имя ссылкой на один релиз. Верните в bg строку "accent": { "$type": "color", "$value": "{bg.brand}" }, и сборка запишет --bg-accent: var(--bg-brand). Старый код работает, пока вы переходите на новое имя. Для этого в DTCG 2025.10 есть и поле $deprecated, но прежде чем на него полагаться, проверьте, как с ним обращается ваша версия Style Dictionary.
2. Распознавайте переименование как переименование. Сравнение одних имён покажет одно удаление и одно добавление. ID переменной в $extensions показывает, что это тот же токен. Инструмент, который сравнивает ID, может сообщить о переименовании, и ревьюерам не придётся гадать (почему для поиска переименований ID токенов надёжнее имён).

Что это значит для вашего конвейера

Style Dictionary хорош как последний шаг: он гибко настраивается и читает стандартный формат. Но он не решает, что попадает в файл токенов и когда изменение можно безопасно выпускать. Именно из этих вопросов вырастает расхождение дизайн-системы, и отвечать на них нужно на ревью, до сборки.

Нужен DTCG-файл, чтобы начать? Рассказываем, как выгрузить переменные Figma на любом тарифе.