Механизм ссылок

Что такое ref

Лист может вместо value содержать ref — полный путь к другому токену:

"selected": { "ref": "color.primary.active", "description": "Цвет текста в выбранном состоянии; следует за нажатым вариантом основного цвета" }

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

Алгоритм разрешения

Встроенная функция resolveRef(path, chain) из resolve.ts:

1. Целевой путь не существует → ошибка Указанный токен не существует: <path>
2. Цель сама является ref → рекурсия по цепочке (поддерживаются цепочки любой длины)
3. Цепочка уже содержит текущий путь → ошибка Обнаружен цикл ссылок токенов: a -> b -> a
4. Достигнут литерал → возвращается { value, type }

Цепочки косвенных ссылок

"a": { "ref": "b" },
"b": { "ref": "c" },
"c": { "value": "#2B4C7C" }

a разрешается по цепочке до литерального значения c.

Обнаружение циклов

"a": { "ref": "b" },
"b": { "ref": "a" }

Во время resolve срабатывает chain.includes(path), выбрасывается Обнаружен цикл ссылок токенов: a -> b -> a, и codegen завершается с ошибкой.

Результат запекания

Результат разрешения записывается в token.value, а исходная цепочка — в refChain (ResolvedToken.refChain, например ["color.primary.active"]). В артефактах платформ остаются только литеральные значения, никаких ref:

// button.borderRadius ссылается на radius.base (2px); после запекания:
val borderRadius = 2.dp  // Скругление кнопки следует за глобальным скруглением

Тип следует за источником истины

Если ref-лист не объявил собственный type, тип берётся у цели ссылки (2-й уровень трёхуровневого приоритета; см. Система типов).

refMap

Возвращаемый resolveTokens refMap фиксирует все разрешённые отношения ссылок (path -> исходная строка ref; для тёмных ключей добавляется префикс dark:) и используется в документации и командой pnpm verify:tokens.

Практическое применение

Типичные сценарии использования ref в tokens/:

Сценарий	Пример
Компонент следует за глобальной величиной	button.borderRadius → radius.base
Состояние следует за семантическим цветом	color.selected → color.primary.active
Размер шрифта компонента следует за типографикой	button.fontSize.small → typography.fontSize.small

Любая ссылка обязана быть полным путём (пространство имён + вложенный путь); см. Пространства имён.