Дизайн-токены: что это и как их структурировать

Коротко: что такое дизайн-токены

Дизайн-токен — это имя для значения дизайна: color.text.primary вместо #1F2937, space.4 вместо 16px. Токены хранятся в одном источнике правды и превращаются в переменные Figma, CSS-переменные, ресурсы iOS и Android.

Зачем это нужно:

• Единообразие. Дизайнер и разработчик используют одни и те же имена.
• Темизация. Светлая и тёмная тема — это разные значения одних и тех же семантических токенов.
• Управляемые изменения. Новый оттенок бренда меняется в одном месте и расходится по всему продукту.

Три слоя токенов

Ключевой принцип: интерфейс ссылается на семантику, а не на примитивы. Если кнопка напрямую использует blue.600, то в тёмной теме или при ребрендинге её придётся искать и менять вручную.

Компонентный слой не обязателен. Он полезен в больших системах, где одному компоненту нужно отличаться от общей семантики. В небольших продуктах часто хватает двух слоёв.

Как называть токены

Хорошее имя читается как путь от общего к частному. Распространённая схема:

{категория}.{свойство}.{роль}.{вариант}.{состояние}

color.bg.surface
color.bg.surface.raised
color.text.secondary
color.border.danger
button.primary.bg.hover
space.inset.md
radius.control

Правила, которые избавляют от хаоса:

• Называйте по назначению, а не по виду. color.text.danger, а не color.red-text. Красный может стать бордовым, а назначение останется.
• Единый порядок сегментов во всей системе.
• Предсказуемые шкалы. Для размеров — sm/md/lg или числовая шкала, но не смесь.
• Состояния в конце: hover, pressed, disabled, focus.
• Никаких значений в имени. space.16 ломается, когда значение меняется на 20.

Формат и пример

Удобно хранить токены в JSON. Распространённая конвенция — формат W3C Design Tokens Community Group, где у токена есть $value и $type, а ссылки записываются в фигурных скобках:

{
  "color": {
    "blue": {
      "400": { "$type": "color", "$value": "#60A5FA" },
      "600": { "$type": "color", "$value": "#2563EB" }
    },
    "action": {
      "primary": { "$type": "color", "$value": "{color.blue.600}" }
    }
  }
}

После сборки это превращается, например, в CSS-переменные с темами:

:root {
  --color-blue-400: #60a5fa;
  --color-blue-600: #2563eb;
  --color-action-primary: var(--color-blue-600);
}

[data-theme="dark"] {
  --color-action-primary: var(--color-blue-400);
}

Компоненты используют только --color-action-primary, а тема переключается одним атрибутом.

Синхронизация между Figma и кодом

Типовая цепочка:

1. В Figma токены живут как Variables: коллекция примитивов, коллекция семантики с режимами (modes) для светлой и тёмной темы. Семантические переменные ссылаются на примитивы через алиасы.
2. Экспорт в JSON — через плагин (например, Tokens Studio) или API Figma, в зависимости от вашего тарифа и процесса.
3. Репозиторий хранит JSON как источник правды. Изменения проходят через pull request, как код.
4. Сборка — инструмент вроде Style Dictionary превращает JSON в CSS-переменные, конфигурацию Tailwind, ресурсы для iOS и Android.
5. CI проверяет, что сборка проходит и в коде нет «сырых» значений цветов вне токенов.

Главное решение — где источник правды. Если правят в Figma, код получает экспорт. Если в репозитории — Figma синхронизируется из него. Двустороннее ручное редактирование почти всегда приводит к расхождениям.

Частые ошибки

• Использование примитивов прямо в компонентах.
• Сотни семантических токенов «на всякий случай», которые никто не применяет.
• Разные имена одного и того же в Figma и в коде.
• Тёмная тема как отдельный набор примитивов вместо новых значений семантики.
• Отсутствие документации: какой токен для чего.