Токены в Figma: настрой один раз — и никогда не правь цвета вручную

Откройте любой Figma-файл годовалой давности. Посчитайте, сколько там оттенков серого. Семь? Двенадцать? А теперь сравните с тем, что описано в гайдлайнах — там их три.

Это не лень дизайнеров. Это нормальное поведение системы, в которой цвета живут как hex-значения, а не как переменные. Каждый новый макет добавляет «почти такой же синий», «чуть темнее на hover», «фон формы — нужен другой». Через полгода в библиотеке стилей бардак, в продакшене три разных primary, а смена бренд-цвета превращается в проект на спринт.

Токены решают это раз и навсегда — если настроены правильно. Если настроены наспех, они добавляют слой абстракции и больше ничего. Разница между «работает» и «формальность ради галочки» — в архитектуре и дисциплине, а не в самом факте использования Variables.

---

## Что такое токен и чем он не является

Дизайн-токен — это именованная переменная, в которой хранится решение, а не значение. color.background.surface — это решение «фон поверхности». То, что внутри сейчас лежит #FFFFFF, — деталь реализации. Завтра это может быть #FAFAFA, и ни один макет не придётся открывать вручную.

Чем токен не является:

• Это не «стиль в Figma с понятным названием». Стиль — статичная привязка к значению, токен — переменная, которую можно перепривязать.
• Это не способ «навести порядок в палитре». Порядок — следствие, не цель. Цель — единый источник правды между дизайном и кодом.
• Это не задача на один день. Минимально рабочая система токенов настраивается за пару дней, нормальная — за пару недель итераций.

### Признаки, что токены вам действительно нужны

• В команде больше одного дизайнера, и кто-то уже спрашивал «а какой именно серый брать для разделителя».
• Готовится редизайн, ребрендинг или поддержка тёмной темы.
• Разработчики тянут цвета из макетов глазами, а не из переменных кода.
• Маркетинг просит «такой же продукт, но в фирменном цвете партнёра» — и вы знаете, что это две недели работы.

Если хотя бы два пункта — пора. Если ни одного — возможно, вам пока хватит стилей, и это нормально.

---

## Три слоя токенов: почему один уровень — это ловушка

Самая частая ошибка — назвать переменные blue-500, blue-600, gray-100 и считать, что это система. Это не система, это переименованная палитра. При смене бренда вы снова правите всё руками: компонент кнопки до сих пор знает, что он blue-500.

Рабочая архитектура — три слоя.

### Primitive (или Core)

Сырые значения. blue-500 = #2D7FF9, gray-900 = #111315, space-4 = 4px. На этом уровне нет смысла, только цвет и число. Компоненты сюда не смотрят никогда.

### Semantic (или Alias)

Решения. color.action.primary = blue-500, color.text.default = gray-900, color.border.subtle = gray-200. Здесь живёт смысл: «кнопка действия», «основной текст», «слабая граница». Компоненты смотрят сюда и только сюда.

### Component (опционально)

Узкоспециализированные токены: button.primary.background, card.shadow. Нужны, если у компонента есть собственные исключения, которые не вписываются в семантический слой. Если у вас 200 компонентных токенов — вы что-то делаете не так, скорее всего семантика недоопределена.

Почему именно три, а не один. Когда меняется бренд, вы трогаете primitive. Когда меняется логика интерфейса («давайте предупреждения будут не жёлтыми, а оранжевыми») — трогаете semantic. Компоненты не двигаются вообще. Это и есть «настроил один раз».

### Анти-паттерны на старте

• Называть semantic-токены по цвету: color.blue.primary. Через год бренд станет зелёным, а имя останется.
• Пропустить primitive и сразу делать semantic поверх hex. Любая перекраска — снова руками.
• Делать compоnent-токены для всего подряд «на будущее». Чем больше слоёв, тем выше цена изменения.
• Заводить отдельный токен под каждый уникальный оттенок из макета, вместо того чтобы сначала спросить «а он точно должен отличаться?».

## Рабочий процесс: как токены вписываются в день дизайнера

Токены живут не в документации, а в момент, когда ты тянешь компонент на холст. Если ради «правильного» цвета нужно открыть Notion и искать имя — система не взлетит. Поэтому весь смысл настройки — сделать так, чтобы семантическое имя было ближе и удобнее, чем hex из палитры.

### От пустого файла до первого экрана

1. Открой Variables и убедись, что подключены коллекции primitive и semantic. Если нет — это проблема библиотеки, не твоя, эскалируй владельцу системы.
2. Любой прямоугольник, текст, иконка — получают цвет только через semantic. color.surface.default, color.text.muted, color.border.subtle. Никаких ручных hex, даже «временно посмотреть».
3. Не нашёл подходящего semantic-токена — это сигнал. Либо токен есть, но назван иначе (поищи), либо его не хватает (заведи задачу владельцу системы, временно используй ближайший по смыслу с комментарием в слое).
4. Перед коммитом макета пройдись по слоям и проверь, что нигде не осталось локальных стилей. В Figma это видно по индикатору переменной у свойства Fill / Stroke.

### Темы и режимы: где это окупается

Modes в Figma — это то место, где архитектура из трёх слоёв превращается в магию. Light, Dark, High contrast, бренд партнёра — всё это режимы одной semantic-коллекции, где значения ссылаются на разные primitive. Один клик — макет перекрашен целиком, без правок компонентов.

Что важно помнить:

• Modes переключают только то, что привязано к токенам. Любой ручной fill останется как был — и это будет видно в первой же демке тёмной темы.
• Режим — не место для исключений. Если в dark нужен другой radius у карточки — это уже не тема, это другой компонент.
• Не плоди режимов «на всякий случай». Light и dark — обязательны, всё остальное — когда есть реальный сценарий.

---

## Диагностика: как понять, что система живая

Токены легко превратить в формальность. Снаружи — всё через переменные, внутри — те же три primary и привычка «ну добавлю ещё один оттенок серого». Раз в пару спринтов имеет смысл прогонять короткий аудит.

### Чеклист здоровья токенов

• В semantic-слое нет имён, в которых зашит цвет (primary-blue, red-error).
• Любой primitive имеет хотя бы одну ссылку из semantic. Если ни одной — он либо мёртвый, либо используется напрямую (плохо).
• Компоненты в библиотеке не содержат сырых hex. Совсем.
• Количество семантических токенов не удваивается каждый квартал. Рост — это нормально, удвоение — симптом.
• Тёмная тема собирается переключением режима, а не отдельным файлом-копией.
• У каждого нового токена есть автор и причина появления. «Не помню, кто завёл» — красный флаг.

### Симптомы, что что-то пошло не так

• На макете два визуально одинаковых серых, но это разные токены. Значит, semantic-слой описан по реализации, а не по смыслу.
• Дизайнеры заводят personal-токены в своих файлах, потому что «в общей библиотеке нет нужного». Система отстаёт от продукта.
• Разработчики продолжают спрашивать «какой именно цвет тут имелся в виду». Значит, имена непонятны без дизайнера-переводчика.
• Смена бренд-цвета всё ещё требует правок в компонентах. Архитектура где-то сломана — почти всегда в semantic.

---

## Типичные ошибки в макетах

### Привязка к primitive напрямую

Самое частое. Берёшь кнопку, ставишь fill blue-500, потому что «это же и есть наш primary». Через полгода primary становится фиолетовым, а кнопка остаётся синей. Правило простое: компонент видит только semantic. Если очень хочется primitive — остановись и спроси, какого semantic-имени тебе не хватает.

### Токен под каждый чих

Появился новый экран с чуть другим фоном — заводится color.surface.onboarding.step2. Через год таких токенов сотни, и никто не помнит, чем surface.card.alt отличается от surface.elevated.secondary. Перед заведением нового semantic-токена задай вопрос: это действительно новое решение или вариация существующего?

### Semantic как палитра

Имена вида color.semantic.blue1, color.semantic.blue2. Формально слой есть, по сути — переименованный primitive. Semantic описывает роль: где это применяется и зачем. action.primary, text.inverse, border.focus — да. accent3 — нет.

### Игнорирование состояний

Hover, pressed, disabled, focus — это часть семантики, а не «потемнее на глаз». action.primary.hover, action.primary.disabled должны существовать как отдельные токены, иначе любой компонент начнёт хранить логику затемнения у себя.

---

## Вопросы для дизайн-ревью

Когда смотришь чужой макет (или свой через день), пройдись по списку. Это быстрее, чем разбираться через месяц.

• Все ли заливки и обводки привязаны к переменным? Видны ли индикаторы токенов в инспекторе?
• Используются ли только semantic-токены, или где-то торчит primitive?
• Есть ли токены, заведённые специально под этот макет? Если да — почему их не получилось переиспользовать?
• Переключается ли макет в dark mode без визуальных артефактов?
• Совпадают ли имена токенов с теми, что использует фронтенд? Если нет — где источник правды?

---

## Короткий итог сегмента

Токены работают, когда они ближе, чем hex, и когда semantic-слой описывает смысл, а не цвет. Всё остальное — гигиена: регулярный аудит, ревью по чеклисту, готовность сказать «нет» новому токену чаще, чем «да». Дальше посмотрим, как этот процесс стыкуется с кодом и где AI-инструменты реально помогают, а где только добавляют шума.

## Токены и код: где живёт источник правды

Самый частый конфликт в команде — где «настоящие» токены: в Figma или в коде. Пока всё держится на ручной синхронизации, эти две системы расходятся в течение спринта: дизайнер переименовал surface.muted, разработчик не узнал, на проде остался старый цвет ещё месяц. Решение не в том, кто главнее, а в том, чтобы один формат был источником, а второй — потребителем.

На практике это означает экспорт из Figma Variables в JSON (через плагин или через Tokens Studio), хранение этого JSON в репозитории и сборку CSS-переменных / Tailwind-конфига / iOS- и Android-токенов через Style Dictionary или аналог. Дизайнер всё ещё работает в Figma, но коммит в репозиторий — это и есть момент, когда токен «становится настоящим».

### Что должно лежать в репозитории

• Сырой JSON с примитивами и semantic-слоем, разбитый по файлам (primitives.json, semantic.light.json, semantic.dark.json).
• Конфиг сборки и сгенерированные артефакты (CSS, JS, нативные форматы) — но генерируемое лучше класть отдельно и не править руками.
• Краткий README: как добавить токен, кто ревьюер, как прогнать сборку локально.

Если этого нет, токены живут в трёх местах сразу: Figma, голова дизайнера, чьи-то комменты в Slack.

## AI и MCP: где помогает, а где мешает

AI-инструменты вокруг Figma — Make, MCP-сервер, плагины «сгенерируй компонент по скрину» — работают хорошо ровно настолько, насколько хорошо у тебя устроены токены. Если semantic-слой чистый, MCP-сервер отдаёт модели имена вроде action.primary и surface.raised, и сгенерированный код выглядит как написанный человеком. Если в макете торчат hex'ы, на выходе получишь компонент с захардкоженным #3B82F6 — и весь смысл системы испаряется.

### Рабочий сценарий с MCP

• Подключаешь Figma MCP к своему агенту (Claude Code, Cursor — что используете).
• Просишь сгенерировать компонент по фрейму. Агент тянет имена переменных, а не пиксели.
• В сгенерированном коде проверяешь: используются ли переменные дизайн-системы или прилетели сырые значения. Если сырые — это сигнал, что в макете не привязан токен.

То есть AI-пайплайн становится ещё и детектором гигиены: всё, что плохо именовано в Figma, всплывает в diff'е PR.

### Чего делать не стоит

• Просить AI «придумать недостающие токены». Он придумает — и заведёт color.surface.softAlt2, который никому не нужен.
• Генерировать тёмную тему через AI поверх светлой. Темы — это решения о контрасте и иерархии, а не инверсия каналов.
• Доверять авто-маппингу «hex → ближайший токен» без ревью. Ближайший по цвету ≠ правильный по смыслу.

## Командные сценарии

### Новый дизайнер в команде

Хороший признак системы — человек заходит и через день уже делает экраны без вопроса «а какой тут синий». Если первые две недели уходят на «расскажи, какой токен для чего» — semantic-слой не самодостаточен. Лечится не онбордингом, а именами.

### Редизайн с ребрендингом

Меняется primary, нейтральные, акценты. Если архитектура цела, правки идут только в primitives и частично в semantic-маппинге. Компоненты не трогаются. Если пришлось лезть в компоненты — где-то в системе сырые значения, и редизайн стал отличным поводом их найти.

### Параллельная работа двух команд

Две продуктовые команды в одной библиотеке — главный стресс-тест. Договоритесь заранее: новые semantic-токены заводит только владелец дизайн-системы по запросу через issue. Иначе через месяц будет два text.subtle с разными значениями и взаимная обида.

## Как объяснить решение команде

Дизайн-системы часто проваливаются не на этапе сборки, а на этапе разговора с продактом и разработчиками. «Мы переделываем токены» звучит как «дизайнер опять что-то перекладывает». Объяснять лучше через стоимость изменений.

• Сколько занимает смена primary сейчас и сколько займёт после.
• Сколько багов «не тот серый» закрывалось за квартал.
• Сколько времени уходит на ответ «какой здесь цвет» в каждом тикете.

Цифры не обязаны быть точными — важно показать, что речь про экономию, а не про эстетику.

### Вопросы для совместного ревью с разработкой

• Имена токенов в Figma и в коде совпадают по смыслу и по написанию?
• Есть ли в коде места, где цвет всё ещё захардкожен? Почему туда не дотянулся токен?
• Что происходит, когда дизайнер добавил новый semantic-токен: как он попадает в сборку?
• Кто ревьюит PR с изменениями токенов: только фронт, только дизайн или оба?

## Короткий итог сегмента

Токены становятся настоящей системой в тот момент, когда у них появляется один источник правды и понятный путь до кода. AI и MCP усиливают то, что уже хорошо устроено, и беспощадно подсвечивают то, что устроено плохо. А разговор с командой ведётся не про красоту имён, а про стоимость изменений — это единственный язык, на котором дизайн-система звучит убедительно.

## Финальный чеклист: «у нас нормальные токены»

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

### Primitives

• Палитра primitives не растёт от макета к макету: новых оттенков не появляется месяцами.
• Имена нейтральны: blue.500, а не brand.main и не ocean.deep.
• Дубликаты с разницей в 1–2 единицы яркости вычищены.
• Ни один компонент не ссылается на primitive напрямую.

### Semantic

• У каждого токена есть смысловое имя: что это, а не как выглядит.
• Состояния (hover, pressed, disabled) описаны как отдельные токены, а не как «возьми основной и затемни».
• Текст по поверхностям проходит контраст без ручной правки в макете.
• Тёмная тема — отдельный маппинг, а не «инвертировали и поехали».

### Связь с кодом

• Имена в Figma и в коде совпадают по написанию, а не «примерно похожи».
• Есть автоматический экспорт (Tokens Studio, Style Dictionary, плагин — что угодно, но не ручной CSV).
• В коде ноль хардкодов цвета в новых компонентах. Старые помечены как долг.
• PR с изменением токенов проходит ревью и дизайна, и фронта.

### Процесс

• Понятно, кто заводит новый semantic-токен и через какой канал.
• Понятно, как и когда удаляются устаревшие.
• Изменения примитивов и семантики не катятся в одном PR.
• У библиотеки есть версия, и команды знают, на какой они сидят.

## Анти-паттерны, которые ломают всё

### «Заведём пока, потом разберёмся»

В библиотеке появляются токены color.temp.newButton, surface.figmaTestV2, text.fromLanding. Через полгода их используют в проде, удалить нельзя, переименовать страшно. Лучше неудобный отказ на ревью, чем удобный мусор в системе.

### Семантика, которая описывает внешний вид

color.lightGrayBg, text.darkBlue, border.thinGray — это не семантика, это primitives под видом семантики. При смене темы или ребрендинге такие имена врут. Имя должно отвечать на «зачем», а не на «как выглядит».

### Один токен — много смыслов

text.primary используется и для заголовков, и для кнопок, и для иконок в инпуте. Когда дизайнеру понадобится поменять цвет иконок — он не сможет, потому что заодно поедут заголовки. Если токен начинает означать «всё тёмное» — пора его расщеплять.

### Дизайнер сам себе платформа

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

### Документация как музей

Страница в Notion с описанием токенов, последний раз обновлённая «когда мы делали редизайн». Команда давно не сверяется, в макетах живёт другая правда. Документация либо синхронизируется автоматически из библиотеки, либо её честнее удалить.

## Вопросы для ревью дизайн-системы

Эти вопросы стоит задавать раз в квартал — себе, команде, и заодно разработке. Если на половину нет внятного ответа, у системы накопился долг.

• Сколько в библиотеке semantic-токенов? Если число выросло за квартал без явной причины — что именно добавили и зачем?
• Какие токены не используются ни в одном компоненте? Почему они ещё живы?
• Где в продукте остались последние хардкоды цвета и кто отвечает за их вычистку?
• Что произойдёт, если завтра поменяется primary? Сколько файлов и компонентов придётся открыть руками?
• Может ли новый дизайнер собрать экран без вопросов к старшему — только по библиотеке и принципам?
• Как тёмная тема узнаёт о новом semantic-токене: автоматически или каждый раз вручную?
• Когда в последний раз дизайн и фронт вместе смотрели на список токенов? Если давно — это не процесс, это случайность.

## Практический итог

Токены — это не модный слой поверх макета и не способ навести красоту в библиотеке. Это договорённость о том, что в продукте есть один источник правды на цвет, и любое изменение проходит через него. Primitives хранят палитру, semantic описывает смысл, код подхватывает имена один в один, а команда понимает, кто и как добавляет новое.

Сделанная один раз эта работа возвращает время на каждом редизайне, каждом новом разработчике и каждом «давайте чуть подкрутим основной». Не сделанная — превращает любую правку цвета в маленький проект на неделю. Выбор, по сути, между «настроить токены сейчас» и «настраивать цвета вручную всегда».