Дизайн-токены: значения цвета и размера в одном формате

Прямой ответ

Дизайн-токен хранит значение цвета либо размера в общем формате, поэтому значение задаётся один раз и применяется во всех компонентах через переменную.

{ "color": { "text": { "primary": { "value": "#1a1a1a" } } } }

:root { --color-text-primary: #1a1a1a; }

Значение задаётся в одном месте, поэтому изменение применяется ко всем компонентам, использующим токен. О структуре системы — в статье про дизайн-систему.

Уровни значений и семантические токены

Значение разделяется на базовое и семантическое, поэтому изменение назначения не требует правки значения.

Базовое значение. Содержит конкретный цвет либо размер, поэтому значение определено однозначно.

Семантический токен. Ссылается на базовое значение и описывает назначение, поэтому изменение базового значения применяется по назначению.

Разделение уровней. Компонент использует семантический токен, поэтому подстановка другого базового значения не требует правки компонента.

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

Отдельный аспект — именование токена. Имя описывает назначение, а не значение, поэтому переименование при изменении цвета не требуется: токен с именем по цвету теряет смысл после изменения значения.

Генерация переменных и формат описания

Переменные стиля генерируются из описания токенов, поэтому формат описания определяет состав доступных переменных.

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

Формат описания. Значение и тип задаются в общем формате, поэтому переменная создаётся для каждого токена описания.

Проверка описания. Ошибка формата обнаруживается при генерации, поэтому некорректное значение не попадает в собранные переменные.

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

Применение в компонентах и замена темы

Компонент ссылается на переменную, поэтому замена набора значений изменяет внешний вид без правки компонента.

Ссылка на переменную. Компонент использует переменную вместо литерального значения, поэтому значение подставляется из набора.

Замена набора. Другой набор значений подставляется без изменения компонента, поэтому тема переключается на уровне переменных.

Область действия. Переменная задаётся для области, поэтому часть интерфейса использует другой набор значений.

Практическое следствие: компонент с литеральным значением не реагирует на замену набора, поэтому переключение темы не применяется к этому элементу.

О переключении тем — в статье про темизацию интерфейса; о требованиях к сочетанию цветов — в статье про контрастность цветов.

Проверка описания и состав токенов

Описание токенов проверяется при генерации, поэтому некорректное значение не попадает в собранные переменные.

Формат значения. Каждое значение задано в ожидаемом формате, поэтому переменная создаётся без ошибки разбора.

Полнота набора. Для каждой темы задан полный набор значений, поэтому переменная не остаётся без значения при переключении.

Дубли имени. Имя токена уникально, поэтому одно имя не переопределяет другое значение в том же наборе.

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

Практика: настройка токенов и переменных

1. Разделяйте базовое значение и семантический токен. Компонент использует назначение, а не конкретное значение.

2. Именуйте токен по назначению, а не по значению. Переименование при изменении цвета не требуется.

3. Ведите описание токенов в одном файле. Переменные генерируются из единого источника.

4. Генерируйте переменные из описания. Ручное дублирование значений не требуется.

5. Проверяйте формат описания при генерации. Некорректное значение не попадает в собранные переменные.

6. Не используйте литеральные значения в компонентах. Изменение токена применяется ко всем элементам.

7. Задавайте переменные для области действия. Часть интерфейса может использовать другой набор значений.

Рекомендации:

1. Не ссылайтесь на базовое значение из компонента. Изменение семантического токена не применяется к компоненту с базовым значением.
2. Не ведите переменные вручную параллельно с описанием. Расхождение между источниками приводит к частичному обновлению значений.
3. Проверяйте описание при каждой генерации. Ошибка формата обнаруживается до попадания значения в сборку.
4. Фиксируйте набор значений для каждой темы. Переключение темы выполняется подстановкой набора.
5. Пересматриваем состав токенов при изменении продукта. Новое назначение требует отдельного токена.

Практический сценарий: часть элементов не изменила цвет при обновлении

Контекст: значение основного текста изменилось, но часть элементов отображала прежнее значение.

1. Диагностика. Проверка показала, что переменные генерировались из описания токенов, но часть компонентов содержала литеральное значение цвета. Изменение описания применилось к переменным, поэтому компоненты со ссылкой обновились, а компоненты с литералом сохранили прежнее значение.
2. Причина. Компоненты создавались до введения токенов, поэтому значения задавались непосредственно, и перевод на переменные не был завершён.
3. Действия. (а) Составили перечень компонентов с литеральными значениями, чтобы объём правки был известен; (б) заменили литералы на ссылки на переменные, чтобы значение задавалось в описании токенов; (в) добавили проверку на отсутствие литеральных значений цвета при сборке, чтобы новый компонент не повторял ошибку; (г) разделили базовые значения и семантические токены, чтобы компонент ссылался на назначение; (д) перегенерировали переменные и убедились, что значение обновилось на всех элементах.
4. Результат. Изменение описания токена применяется ко всем элементам, поскольку компоненты ссылаются на переменные вместо литеральных значений.

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

FAQ

Что такое дизайн-токен? Значение цвета либо размера, заданное в общем формате и применяемое через переменную. Значение задаётся один раз.

Чем семантический токен отличается от базового значения? Семантический токен описывает назначение и ссылается на базовое значение. Компонент использует токен, а не значение.

Почему не вести переменные вручную? Ручное ведение параллельно с описанием приводит к расхождению: часть значений обновляется, часть остаётся прежней.

Как именовать токен? По назначению, а не по значению. Имя по цвету теряет смысл после изменения значения.

Источники: W3C Design Tokens, RFC 8259 JSON, W3C CSS Variables — ссылки в шапке.