Токены цвета в макетах: уровни и правила применения

Источник: ds-docs/reference/guidelines/color-token-usage.md

Как цветовые токены работают в реальном макете: три вида токенов, четыре семантические категории, уровни наложения фона (bg-surface → bg-layer-01 → bg-layer-02) и сборка токенов внутри компонента.

Значения токенов — color-light-mode и color-dark-mode. Правила оформления самих компонентов — component-authoring-rules. Связано: README, ds-internal/AUDIT.md.

Раздел состоит из 5 слайдов (Slider 1 … 4, 6) в файле «Цех Астры».

1. Три вида токенов (`Slider 1`)

Цитаты из макета:


Primitive tokens	«Эти токены представляют базовые единицы дизайна, такие как цвета, шрифты, размеры или интервалы. Они обычно являются „фундаментальными строительными блоками“, используемыми для создания более сложных токенов или компонентов.»
Semantic tokens	«Семантические токены отображают смысловые или логические значения на основании контекста использования.»
Component-specific tokens	«Это токены, которые определены для конкретных компонентов интерфейса.»

Цепочка подстановки на примере `Text Input`

Разобран один цвет по всей цепочке, слева направо:

Value	Primitive token	Semantic token	Component-specific token
`#F6F7F8` 100 %	`gray-100`	`bg-layer-02`	`bg-form`

Второй пример на List Item / Secondary — bg-list-secondary как component-specific токен.

Правило чтения: в макете дизайнер и разработчик работают с правым концом цепочки — component-specific, если он есть у компонента, иначе semantic. Примитив (gray-100) — внутренняя реализация семантики, напрямую в макет не ставится.

⚠️ gray-100 не экспортируется ни в один DTCG-файл: коллекция примитивов в выгрузку не попадает (в экспорте только colors/*, components/*, state-layer-colors/*, other/*). В коде примитив недоступен как переменная — только через семантику (Q-003).

2. Четыре семантические категории (`Slider 2`)

«Токены разделены глобально на четыре категории семантики токенов: text, border (обводка), foreground (наполнитель), background (задний фон).»

Плюс отдельная ветка //additional:


`text`	Цвет текста
`border`	Обводка
`fg (foreground)`	Наполнитель (иконки, глифы)
`bg (background)`	Задний фон
`afg (additional foreground)`	Дополнительная палитра наполнителя
`abg (additional background)`	Дополнительная палитра фона

Сверка с DTCG-экспортом — категории подтверждаются структурой файла: colors/text, colors/border, colors/foreground, colors/background, colors/additional.

⚠️ afg/abg — это имена групп, а не префиксы токенов. Внутри colors/additional/afg/ лежат токены вида fg-color-lion-primary, внутри colors/additional/abg/ — bg-color-lion-primary. Токена, начинающегося на afg- или abg-, в экспорте нет ни одного. Макет подаёт их как префиксы — это вводит в заблуждение (Q-001).

Разбор компонента `Form / Text Input`

Один и тот же компонент показан дважды — в light-mode и dark-mode — с одинаковым набором токенов:


Подпись `Label`	`text-secondary`
Значение `Value`	`text-primary`
Иконка	`fg-secondary`
Фон поля	`bg-layer-02`
Обводка	`border-primary`

Правило: имена токенов не меняются между темами — меняются только их значения.

3. Уровни наложения фона (`Slider 3`, `Slider 4`)

Это ядро правил. Уровни зафиксированы Dev-аннотациями Figma (не стикерами), то есть их видит разработчик прямо в DevMode.


Фон страницы	«Основной задний фон страницы»	(корневой фон `Template`)
Уровень 1	«Первый уровень слоя, наложенного поверх, — семантических токенов `bg-surface`»	`bg-surface`
Уровень 2	«Второй уровень слоя наложения поверх — семантических токенов `bg-layer-01`, `bg-layer-inverse-01`, `bg-layer-disabled-01`»	`bg-layer-01` · `bg-layer-inverse-01` · `bg-layer-disabled-01`

Аннотация уровня 1 навешена на 4 узла одного экрана: Basic Action, Container (внутри ✱ Widget Status), Title & Description, Navigation Bar. То есть bg-surface — это фон любого блока первого уровня на странице, независимо от его роли.

Уровень 2 навешен на [Item Container] внутри кнопки — вложенный контейнер внутри блока первого уровня.

Аннотации продублированы для светлой и тёмной копии экрана (по 6 на копию, всего 12) — подтверждает правило «имена токенов одни, значения разные».

Как это проверять

Из макета: «Переключайте Local Variable color = light-mode и dark-mode для просмотра поведения токенов. Подробнее о токенах в режиме DevMode (Shift+D).»

`Slider 4` — «Пример работы слоёв `bg-layer`»

«Пример макета с использованием токенов из четырёх разных наборов слоёв: базовый слой, набор слоёв 01, набор слоёв 02.»

Практическая раскладка по 17 стикерам на двух экранах: только три значения — bg-surface, bg-layer-01, bg-layer-02. Вложенность читается так:

Фон страницы
└── bg-surface        ← блок первого уровня (карточка, виджет, Navigation Bar)
    └── bg-layer-01   ← контейнер внутри блока
        └── bg-layer-02 ← элемент внутри контейнера (поле ввода, чип)

⚠️ Формулировка «четырёх разных наборов слоёв» противоречит перечислению, где наборов три: базовый, 01, 02 (Q-002).

4. Сборка токенов внутри компонента (`Slider 6`)

«Каждый компонент имеет свою структуру токена. В каждом компоненте могут быть свой text, border, foreground, background.»

Разбор Widget Accounts And Cards HPG:


Фон кнопки	`button-primary-bg`	component-specific
Иконка на цветной кнопке	`fg-primary-on-color-light`	foreground
Фон иконки счёта	`bg-card-icon`	component-specific
Заголовок	`text-primary`	text
Подпись / сумма	`text-secondary`	text
Фон вложенного элемента	`bg-layer-01`	background
Фон элемента глубже	`bg-layer-02`	background

Правило: внутри одного компонента одновременно живут токены разных категорий; уровни bg-layer-* продолжают работать и внутри компонента, а не только на уровне страницы.

⚠️ bg-card-icon в экспорте отсутствует — есть только components/components/components-color/card-icon/bg-card-icon-default. Стикер даёт усечённое имя (Q-004).

Сводка правил

В макет ставится component-specific токен, если он есть у компонента, иначе — semantic. Примитив в макете не используется и в коде недоступен.
Категория выбирается по назначению: text → текст, border → обводка, fg → наполнитель, bg → фон.
Фон набирается уровнями: фон страницы → bg-surface (блок 1-го уровня) → bg-layer-01 (контейнер внутри) → bg-layer-02 (элемент внутри контейнера).
Инверсные и заблокированные состояния берут свой уровень 2: bg-layer-inverse-01, bg-layer-disabled-01.
Имена токенов не зависят от темы. Проверка — переключением Local Variable color между light-mode и dark-mode.
Внутри компонента категории смешиваются свободно; уровни bg-layer-* действуют и внутри.

Про Dev-аннотации Figma

Да, аннотации читаются через REST API — они приходят на самом узле полем annotations:

"annotations": [
  { "label": "Первый уровень слоя наложенного по вверх семантических токенов bg-surface",
    "properties": [ { "type": "fills" } ] }
]

Особенности, важные для конвейера:

В этом разделе 12 аннотаций на 12 узлах — все в Slider 3, все видимые.
Поле properties указывает, к какому свойству узла привязана аннотация (здесь везде fills). У 2 из 12 аннотаций properties отсутствует — привязка только к узлу.
Аннотации приходят и для узлов внутри инстансов (id вида I546:98859;12707:25081).
Аннотация — свободный текст: имена токенов в ней не связаны с реальными boundVariables узла. Сверять их нужно вручную (см. ниже).

Сверка аннотаций с `boundVariables`

boundVariables.fills на аннотированных узлах даёт консистентную картину — один и тот же VariableID на всех узлах одного уровня:


Фон страницы	`40000333:373`	2	(без имени)
Уровень 1	`40000333:399`	8	`bg-surface`
Уровень 2	`40000333:432`	2	`bg-layer-01`

Аннотации не противоречат привязкам: разные уровни — разные переменные, одинаковые уровни — одна переменная.

⚠️ Эти VariableID принадлежат библиотеке, которой нет в нашем словаре foundations/tokens/variable-ids.json (638 записей, ни одной с префиксом 40000333) — имена подтверждены только текстом аннотаций и стикеров, не словарём (Q-005).

Открытые вопросы


Q-001	`afg`/`abg` поданы как префиксы токенов, а в экспорте это имена групп; токенов на `afg-`/`abg-` нет ни одного — внутри лежат `fg-color-` / `bg-color-`	Переписать слайд: «группы `afg`/`abg`, токены `fg-color-`/`bg-color-`»	Владелец токенов
Q-002	`Slider 4` говорит «четырёх разных наборов слоёв», перечисляя три: базовый, 01, 02	Исправить число или добавить четвёртый набор	Владелец ДС
Q-003	Примитивы (`gray-100`) показаны в цепочке, но в DTCG-экспортах их нет — в коде примитив недоступен	Указать в макете, что примитив — внутренний слой, и не экспортируется	Владелец токенов
Q-004	Стикер даёт `bg-card-icon`, в экспорте — только `bg-card-icon-default`	Привести стикер к полному имени	Владелец ДС
Q-005	VariableID из этого файла (`40000333:*`) отсутствуют в `variable-ids.json` — автоматическая сверка «аннотация ↔ реальный токен» невозможна	Дособрать словарь по библиотеке цвета файла «Цех Астры»	Конвейер документации
Q-006	Уровни фона зафиксированы только Dev-аннотациями в `Slider 3`; в `Slider 4` те же правила показаны стикерами поверх растровых скриншотов (`image 2020`, `image 2021`) — при изменении токенов картинки не обновятся	Перевести `Slider 4` на живые компоненты либо пометить как снимок с датой	Владелец ДС
Q-007	В эталонных примерах используются устаревшие компоненты: `❌ List item / Default` (`Slider 1`) и 6 инстансов `Action Button/❌ Deprecated 2.0/❌ Deprecated None/…` (`Slider 3`) — включая тот, на котором висит аннотация уровня 2	Пересобрать примеры на актуальных (Stable) компонентах, см. Версии компонента	Владелец ДС
Q-008	Нумерация слайдов: `Slider 1, 2, 3, 4, 6` — `Slider 5` отсутствует, при этом порядок по координате X непрерывный	Перенумеровать или вернуть пропавший слайд	Владелец ДС
Q-009	Не описано, что делать при более трёх уровней вложенности фона (есть ли `bg-layer-03`)	Задать правило для глубокой вложенности	Владелец токенов
Q-010	Не описано, как уровни `bg-layer-*` сочетаются с `State layer` (см. component-authoring-rules) — накладывается ли слой состояния поверх уровня и каким токеном	Дать таблицу «уровень + состояние → токен»	Владелец токенов
Q-011	В аннотациях опечатки: «наложенного по вверх», «наложения по вверх» (во всех 12)	Поправить формулировку	Владелец ДС

Источник

Figma-файл «Цех Астры» mzqKIv9lKDjD3oDm5o5Egg, страница «Докум» 540:81027, Section «Пример работы токенов» 546:98744.
Слайды: Slider 1 546:98745 · Slider 2 546:98769 · Slider 3 546:98814 · Slider 4 546:99001 · Slider 6 546:98913.
Прочитано Figma REST API 2026-07-30 (968 узлов): тексты — по видимым узлам, сопоставление стикер↔элемент — по координатам, уровни фона — по полю annotations (12 аннотаций) и boundVariables.fills.
Сверка имён с DTCG: foundations/tokens/color-light-mode.tokens.json (426 токенов). Подтверждены 13 из 15 имён; расхождения — Q-003, Q-004.
Соседние разделы той же страницы, ещё не разобранные: «Color code syntax: react, flutter» 546:99026, «State Layer и Gradient» 546:106440, «Space Token» 546:98586, «Radius Token» 546:98683.

Токены цвета в макетах: уровни и правила применения

1. Три вида токенов (Slider 1)

Цепочка подстановки на примере Text Input

2. Четыре семантические категории (Slider 2)

Разбор компонента Form / Text Input

3. Уровни наложения фона (Slider 3, Slider 4)