Формат токенов

Каждый файл tokens/*.json — это платформенно-нейтральный источник, формат которого строго задан tokens/schema.json.

Мета-свойства уровня файла

Ключи, начинающиеся с $, — это мета-свойства, которые не порождают токенов:

Свойство	Назначение
$schema	Указывает на ./schema.json (автодополнение + валидация в редакторе)
$description	Описание файла; попадает в target docs и в базовый документ
$type	** Тип по умолчанию для файла**: его наследуют листы-литералы, не объявившие собственный type
$dark	true означает, что файл является файлом переопределения тёмной темы (объявляются только ключи, требующие переопределения)
$namespace	Префикс пространства имён, определяющий глобальный точечный путь (подробнее в Пространства имён)

{
  "$schema": "./schema.json",
  "$namespace": "color",
  "$type": "color",
  "$description": "Палитра и семантические цвета",
  "primary": { "default": { "value": "#2B4C7C" } }
}

Пять полей листового токена

Поле	Обязательно	Назначение
value	Либо value, либо ref	Литеральное значение
ref	Либо value, либо ref	Полный путь к другому токену (статически разрешается и «запекается» на этапе сборки)
type	Нет	Тип токена; при отсутствии наследуется из файлового $type
description	Нет	Описание; попадает в комментарии артефактов и таблицы документации на каждой платформе
nativeOnly	Нет	true = добавлено направлением native, без соответствующего элемента в направлении web

Схема использует anyOf: [{required: [value]}, {required: [ref]}] + additionalProperties: false, гарантируя, что у каждого листа есть ровно одно из value или ref и не допуская лишних полей.

Семь типов

type / $type допускают только эти семь значений:

Тип	Форма значения	Пример
color	#RGB / #RRGGBB / #AARRGGBB / rgba(r,g,b,a)	"#2B4C7C", "rgba(61, 100, 158, 0.25)"
dimension	Только строка с единицей измерения "12px" / "50%" (assertTypedValue требует строку; чистое число допустимо только для типа number)	"40px", "50%"
number	Чистое число	400, 1000
string	Строка	"PingFang SC"
shadow	Строка тени, разделённая пробелами (x y blur [spread] color)	"0px 2px 12px 0px rgba(26, 26, 26, 0.08)"
duration	"200ms" / "0.2s" (нормализуется в миллисекунды)	"200ms"
cubicBezier	Массив из четырёх чисел	[0.4, 0, 0.2, 1]

Несоответствие типа значению (например, type: color со значением 40px) будет отклонено на этапе resolve функцией assertTypedValue; см. Система типов.

Ограничение нейтральных значений (красная линия 5)

Значения токенов допускают только нейтральное представление:

• ✅ Шестнадцатеричные цвета, rgba(), строки с единицами "12px" / "50%", чистые числа при типе number
• ❌ var(), rem, sp, dp и любые другие платформо-специфичные единицы или ссылки

Преобразование платформенных единиц лежит на шаблонах target’ов:

Платформа	Преобразование
Android	usesSp() определяет, что размер шрифта использует sp, остальное — dp
iOS	Размеры — CGFloat, длительности преобразуются в секунды ((ms/1000); анимации SwiftUI работают в секундах)
HarmonyOS	Размеры — чистые значения в vp
C	Чистые числа, единица указывается в комментарии (цвета 0xAARRGGBB, размеры в логических пикселях, длительности в миллисекундах)

Группировка и вложенность

На любом уровне можно вкладывать группы; группа также может объявить собственный $type, переопределяющий тип по умолчанию для всей группы:

"fontSize": {
  "$type": "dimension",
  "base": { "value": "14px" },
  "small": { "value": "13px" }
}

В typography.json нет файлового $type — типы объявляются через $type на уровне группы или через type у самого листа.

Флаг nativeOnly

Помечает токены, добавленные направлением native и не имеющие соответствия в направлении web (преимущественно новые мобильные размеры). Действие:

• В столбце описания dist/docs/tokens.md ставится отметка «добавлено для native»
• Семейный базовый документ по этому флагу фильтрует список «токенов, добавленных для native»
• Нативные target’ы не фильтруют такие токены и генерируют их как есть

Список файлов

Файл	$namespace	$type	Описание
color.json	color (выводится из имени файла)	color	Палитра и семантические цвета
color-dark.json	color (явно, должен совпадать с пространством светлого файла)	color	Инкрементное переопределение тёмной темы
components.json	""	dimension	Токены компонентного уровня
typography.json	typography	Нет (объявляется на уровне группы/листа)	Типографика
spacing.json	spacing	dimension	Шкала отступов
radius.json	radius	dimension	Скругления
shadow.json	shadow	shadow	Тени
motion.json	motion	Нет (объявляется на уровне группы/листа)	Длительности и easing
z-index.json	zIndex (явно)	number	Z-уровни