Токены Figma в CSS, SCSS и TypeScript | FISYCO

Библиотека токенов превращает переменные и стили Figma в файлы в вашем репозитории: DTCG, JSON, пользовательские свойства CSS, SCSS, TypeScript и JavaScript с объявлениями типов. Здесь описаны настройки, от которых зависят эти файлы, и показано, как выглядит сгенерированный результат.

Перед началом

Figma подключена к рабочему пространству, и файл доступен через это подключение.
К проекту подключён репозиторий. См. Подключение репозитория.
Стили синхронизируются сами. Для переменных нужен тариф Figma Enterprise или плагин FISYCO, который отправляет их прямо из Figma. См. Плагин FISYCO для Figma.
Вы сопровождающий проекта либо владелец или администратор рабочего пространства.

Создайте библиотеку

Откройте проект, нажмите Добавить библиотеку, выберите Токены и нажмите Продолжить.
Общие настройки. Задайте название библиотеки и вставьте ссылку на файл Figma.
Метод синхронизации. Выберите Стили автоматически, переменные через плагин или Переменные из Figma, если ваш тариф Figma открывает API переменных.
Стили. Все группы стилей сразу отмечены. Снимите отметку с ненужных.
Переменные. Отметьте группы переменных для синхронизации. Если хватает стилей, этот шаг можно пропустить.
Генерация. Заполните поле Папка в репозитории (по умолчанию src/tokens), выберите форматы и правила имён, о которых ниже.
Нажмите Создать библиотеку.

Выберите, что синхронизировать

Библиотека синхронизирует ровно те группы, которые вы отметили. Группой считается первый сегмент имени токена: color/bg/surface относится к группе color. Группы переменных считаются внутри коллекции, группы стилей внутри типа стиля.

Пустой выбор означает «ничего», а не «всё». Новой библиотеке нужна хотя бы одна группа.

Чтобы поменять выбор позже, откройте библиотеку и нажмите Править состав. До нажатия Сохранить состав панель показывает, сколько токенов следующий pull request уберёт из репозитория. Состав без единой группы сохранить нельзя. Те же списки есть в разделе Настройки → Источник.

Отметьте группы, на которые ссылаются ваши алиасы. Алиас на токен вне библиотеки превращается в CSS в initial, а в файл DTCG не попадает.

Форматы вывода

Отметьте один или несколько форматов в поле Форматы вывода. В новой библиотеке сразу выбраны DTCG, JSON, CSS, TS и DTS.

Отметка	Файлы	Что внутри
DTCG	`design-tokens.tokens.json` или по `design-tokens.<mode>.tokens.json` на режим	формат W3C Design Tokens 2025.10, его читают Style Dictionary и импорт переменных в Figma
JSON	`tokens.json`	деревья `variables` и `styles` со значениями по режимам
CSS	`tokens.css`, а при текстовых стилях ещё `token-styles.css`	пользовательские свойства и классы текстовых стилей
SCSS	`tokens.scss`	по переменной Sass на токен и тот же блок `:root`
TS	`tokens.ts`	дерево `tokens`, `tokenValuesByPath`, `tokenPaths` и типы путей
JS	`tokens.js`	дерево `tokens`
DTS	`tokens.d.ts`	полные типы рядом с `tokens.ts`; при одном JS только объединение `TokenPath`

Последнее слово за флажком Генерировать типы .d.ts. Если он включён и выбран TS или JS, tokens.d.ts появится, даже когда DTS не отмечен. Если выключен, файла типов не будет.

Имена

Имя токена в коде собирается в три шага:

Шаблон именования собирает имя из плейсхолдеров. В нём обязателен {name}, имя токена в Figma. {collection}, {type} и {source} необязательны. По умолчанию шаблон {name}.
Результат переводится в нижний регистр, а каждая цепочка символов, кроме букв, цифр и /, заменяется дефисом. Каждый / начинает новый сегмент.
Регистр имён оформляет каждый сегмент: по умолчанию kebab-case, либо camelCase, либо snake_case. Префикс CSS-переменных ставится в начало CSS-переменной, по умолчанию это token.

Имя в Figma	Что изменено	CSS-переменная	Путь в `tokens.ts`
`color/bg/surface`	ничего	`--token-color-bg-surface`	`variables.color.bg.surface`
`Spacing/MD`	ничего	`--token-spacing-md`	`variables.spacing.md`
`border/radius large`	camelCase	`--token-border-radiusLarge`	`variables.border.radiusLarge`
`border/radius large`	snake_case	`--token-border-radius_large`	`variables.border.radius_large`
`color/bg/surface` в коллекции `Semantic`	шаблон `{collection}/{name}`	`--token-semantic-color-bg-surface`	`variables.semantic.color.bg.surface`
`color/bg/surface`	префикс `ds`	`--ds-color-bg-surface`	`variables.color.bg.surface`

Стили попадают в tokens.ts под styles., а {collection} для них пуст. Префикс действует и на переменные SCSS, и на классы текстовых стилей.

Имена переводятся в нижний регистр до того, как применяется регистр имён. Поэтому camelCase видит границы слов только на пробелах, дефисах и других разделителях: radiusLarge из Figma станет radiuslarge. Смена шаблона, регистра или префикса переименует все токены в сгенерированных файлах. Планируйте её как любое переименование в коде.

Режимы

Стратегия режимов определяет, как записываются светлый, тёмный и другие режимы. Имена режимов переводятся в kebab-case: Dark Mode превращается в dark-mode. Одноимённые режимы разных коллекций попадают в один блок или файл.

Значения внутри

tokens.css начинается с блока :root, в котором каждый токен записан со значением режима по умолчанию. Дальше идёт по блоку [data-theme="<mode>"] на каждый режим, включая режим по умолчанию:

:root
{
  --token-color-bg-surface: #FFFFFF;
  --token-color-text-primary: #111827;
  --token-spacing-md: 16px;
}

[data-theme="light"]
{
  --token-color-bg-surface: #FFFFFF;
  --token-color-text-primary: #111827;
  --token-spacing-md: 16px;
}

[data-theme="dark"]
{
  --token-color-bg-surface: #111827;
  --token-color-text-primary: #F9FAFB;
  --token-spacing-md: 16px;
}

Чтобы переключить режим, задайте data-theme на <html> или на любом элементе, тогда режим сменится только внутри него:

<html data-theme="dark">

Блоки режимов пишутся только в tokens.css. При этой стратегии в tokens.scss лежат значения по умолчанию. Коллекция с единственным режимом тоже получает блок. Пока вы не переименуете этот режим, Figma называет его Mode 1, и блок будет [data-theme="mode-1"].

Отдельные файлы

Каждый режим получает свой файл tokens.<mode>.css, а если выбран SCSS, ещё и tokens.<mode>.scss. Каждый файл режима пишет в :root, а tokens.css хранит значения по умолчанию. Для этой стратегии среди форматов нужен CSS или SCSS.

@import "./tokens/tokens.css";
@import "./tokens/tokens.dark.css" (prefers-color-scheme: dark);

DTCG и режимы

В формате DTCG режимов нет, поэтому FISYCO при любой стратегии пишет по полному файлу на режим. Токен без такого режима, например стиль, входит в каждый файл со своим значением. Если ни у одной переменной нет двух и более режимов, получится один файл design-tokens.tokens.json.

Единицы для чисел

Figma хранит числа без единиц, а padding: var(--token-spacing-md) без единицы не работает. В CSS и SCSS FISYCO берёт единицу из областей применения переменной, то есть из того, куда Figma разрешает её подставлять.

Области применения в Figma	Единица в CSS и SCSS	Пример
скругление углов, ширина и высота, отступ между элементами, обводка, эффекты, кегль, интерлиньяж, трекинг, отступ между абзацами, абзацный отступ	`px`	`--token-spacing-md: 16px;`
прозрачность	`%`, потому что Figma хранит прозрачность от 0 до 100	`--token-opacity-disabled: 40%;`
насыщенность шрифта	без единицы	`--token-font-weight-bold: 700;`
все области, области с разными единицами или области не записаны	поле Единица для чисел: px (по умолчанию) или Без единицы	`--token-size-base: 8px;`

У алиаса своей единицы нет, её несёт переменная, на которую он ссылается. В JSON, TS, JS и DTCG числа остаются просто числами.

Текстовые стили

Текстовый стиль превращается в tokens.css в переменную с сокращённой записью font, например --token-typography-heading: 700 24px/32px "Inter";. Ещё он становится классом в token-styles.css:

.token-style-token-typography-heading
{
  font-family: "Inter";
  font-size: 24px;
  font-weight: 700;
  line-height: 32px;
  letter-spacing: 0px;
}

Имя класса складывается из префикса, -style- и имени переменной, поэтому префикс встречается дважды. Стиль без семейства шрифта или кегля переменной font не получает: без них сокращённая запись недействительна.

Используйте токены

CSS

@import "./tokens/tokens.css";

.card {
  background: var(--token-color-bg-surface);
  color: var(--token-color-text-primary);
  padding: var(--token-spacing-md);
}

.card-title {
  font: var(--token-typography-heading);
}

SCSS

В tokens.scss на каждый токен объявлена переменная Sass, а за ними идёт тот же блок :root. Поэтому при подключении файла появляются и пользовательские свойства. Алиас и в Sass остаётся ссылкой var():

$token-color-primary: #1A66E6;
$token-color-text: var(--token-color-primary);
$token-spacing-md: 16px;

:root
{
  --token-color-primary: #1A66E6;
  --token-color-text: var(--token-color-primary);
  --token-spacing-md: 16px;
}

@use "./tokens/tokens" as *;

.card {
  padding: $token-spacing-md;
}

TypeScript

tokens.ts экспортирует дерево tokens, плоскую карту tokenValuesByPath и список tokenPaths, все as const. Значения по режимам лежат под ID режимов Figma. Алиас выглядит как { "$alias": "<ID переменной>" }.

import { tokenValuesByPath } from "./tokens/tokens";
import type { TokenPath } from "./tokens/tokens";

const spacing = tokenValuesByPath["variables.spacing.md"];
// { type: "float", valuesByMode: { "1:0": 16, "1:1": 16 } }

const path: TokenPath = "variables.spacing.mdd"; // ошибка типов: такого токена нет

DTCG

Фрагмент design-tokens.light.tokens.json. Группы повторяют сегменты имени, ссылка остаётся ссылкой, а в $extensions хранится ID переменной Figma:

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": {
        "colorSpace": "srgb",
        "components": [
          0.102,
          0.4,
          0.902
        ],
        "alpha": 1,
        "hex": "#1a66e6"
      },
      "$extensions": {
        "com.fisyco": {
          "id": "VariableID:1:2",
          "source": "variables"
        }
      }
    },
    "text": {
      "$type": "color",
      "$value": "{color.primary}",
      "$extensions": {
        "com.fisyco": {
          "id": "VariableID:1:3",
          "source": "variables"
        }
      }
    }
  }
}

В именах DTCG префикса нет. Группы записаны в том же регистре, что и CSS-переменные, поэтому Style Dictionary соберёт --color-primary там, где FISYCO пишет --token-color-primary. Текстовые стили становятся токенами typography. У строк и логических значений нет $type: таких типов в DTCG нет. Эффекты и градиенты в файл не попадают.

Структура

В поле Структура вывода по умолчанию выбрано Один файл: все файлы лежат в папке библиотеки. Вариант По слоям переносит CSS и SCSS в styles/, файлы режимов в styles/themes/ и добавляет точку входа styles.css:

@import './styles/tokens.css';
@import './styles/token-styles.css';

Файлы режимов точка входа не импортирует: каждый из них пишет в :root. Подключайте нужный файл режима отдельно.

Получите pull request

После синхронизации откройте библиотеку и нажмите Создать PR или Обновить PR, если pull request уже открыт. Чтобы не нажимать кнопку, включите Автоматически создавать PR после каждой синхронизации в разделе Настройки → Пул-реквесты.

В описании pull request посчитаны добавленные, изменённые и удалённые токены и перечислены изменения. Переименованная в Figma переменная сохраняет свой ID, поэтому приходит как переименование. Файлы, которые FISYCO доставлял раньше, но больше не пишет, удаляются в том же коммите, остальные файлы в папке он не трогает. Как проверить каждое изменение до pull request, см. Проверка изменений и pull request.

Правка одних только настроек генерации, например нового префикса, не меняет токены в Figma. С автоматическими pull request'ами следующая синхронизация всё равно её доставит: FISYCO сравнивает сгенерированные файлы с прошлой доставкой. Ручному pull request нужна синхронизация с изменениями.

Токены в CSS, SCSS и TypeScript