Дизайн-токены

Дизайн-токены — это именованные значения оформления, из которых построены все компоненты и утилиты Framework. Они позволяют менять внешний вид интерфейса целиком, не правя ни одного компонента.

Что такое дизайн-токен

Дизайн-токен — это именованное значение оформления, записанное как CSS-переменная с префиксом --sf-: --sf-primary, --sf-surface-0, --sf-space-2, --sf-focus--width.

Токен отвечает на вопрос «какое значение здесь должно стоять» одним словом вместо числа. Кнопка не знает, что её фон — #005bbe. Она знает, что её фон — «главный акцент», --sf-primary. Какой это конкретно цвет, решают тема и палитра проекта.

Токены дают три преимущества:

• Одно изменение — весь интерфейс. Изменённое значение токена меняет всё, что его использует, без правки компонентов.
• Смысл вместо числа. По имени --sf-on-error-container понятно, где цвет применяется, даже без значения.
• Темы без дублирования. Одна разметка, один набор имён; меняются только значения за именами.

Два источника значений

Во Framework есть ровно два места, где значение задаётся числом:

1. Цветовые примитивы — шаги палитры и их полупрозрачные ступени (--sf-neutral-50, --sf-primary-50--alfa-12).
2. Размерная лестница — ступени шкалы и один физический пиксель (подробно — в Базовая единица и шкала примитивов и Соразмерные ступени).

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

Литерал допустим только там, где он не является значением:

• внутри запасного значения var(): var(--sf-black, #000) — это имя с запасным значением, а не цвет;
• ноль — он одинаков в любой системе;
• радиус-таблетка 1000px — заведомо больше любого блока, то есть приём, а не размер.

Правило проверяет контракт token-derivation: токен с собственным цветом или длиной вне примитивов не проходит проверку.

Три уровня: примитив → роль → токен компонента

Токены выстроены в цепочку. Каждый следующий уровень ссылается на предыдущий.

Пример ниже показывает цепочку для залитой кнопки акцентного цвета:

/* Примитив: объявлен на :root */
--sf-primary-40: #005bbe;

/* Роль: объявлена на классе темы, обе стороны рядом */
--sf-primary: light-dark(var(--sf-primary-40), var(--sf-primary-80));

/* Токен компонента: стили кнопки */
.sf-button.sf-button--default.sf-button--primary {
  --sf-button--background-color: var(--sf-primary);
}

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

• примитив отвечает за цвет как таковой — его меняют, когда меняют бренд;
• роль отвечает за смысл и тему — её меняют, когда меняют правило («граница поля должна быть тише»);
• токен компонента — внутренняя проводка компонента: через него варианты и состояния меняют вид одной части. Это не поверхность настройки, и проект его не задаёт.

Правила выбора уровня:

• в интерфейсе и в своих стилях используйте роли;
• примитив напрямую — только для настройки темы или для цвета, который сознательно не должен меняться с темой;
• токены компонента в проекте не задавайте: дизайн меняется общими токенами, а глубокое изменение вида Smart-компонента — его шаблоном (см. Как менять дизайн).

Грамматика имён

Имена токенов строятся по нескольким устойчивым правилам. Зная их, имя можно прочитать, не открывая справочник.

Префикс. Все токены Framework начинаются с --sf-. Свои токены проекта называйте иначе (например, --project-…), чтобы их нельзя было спутать с токенами Framework и чтобы обновление Framework их не задело.

Одинарный дефис соединяет слова внутри имени: --sf-surface-container, --sf-on-primary-container.

Двойной дефис отделяет владельца от его свойства или вариации.

Числа в имени — ступени, а не пиксели. У цвета число — тон палитры (-40) или процент непрозрачности (--alfa-12). У размеров — ступень лестницы (--sf-space-2, --sf-radius-1\/2). Дробные ступени содержат косую черту, и при чтении её обязательно экранировать: var(--sf-space-1\/2). Без обратной косой браузер не видит ссылку и молча отбрасывает объявление.

Слова-модификаторы ролей повторяются во всех семействах цвета:

В именах примитивов прозрачности пишется alfa: --sf-primary-50--alfa-12. Нейтральная половина шкалы прозрачности называется --sf-alpha-* (см. Нейтральная половина шкалы).

Где объявлены токены

Токены ядра поставляются в файле core.css. Цветовые примитивы и роли, ступени шкал, тени и прозрачность объявлены в каскадном слое sf.base, служебные переменные области просмотра — в sf.tokens, базовые единицы размерной шкалы (--sf-px, --sf-a0 … --sf-i9) и ступени z-index — на :root вне слоя (о слоях — Каскадные слои):

• примитивы цвета — на :root, один раз, без зависимости от темы;
• цветовые роли — на классах темы .theme-light и .theme-dark (см. Темы);
• токены компонента — в стилях самого компонента, на его корневом селекторе или на части.

Важное следствие: цветовые роли существуют только внутри элемента с классом темы. В обычной работе этот класс ставит на <html> скрипт ядра (см. Как выбирается тема на странице). Если скрипт ядра отключён или не подключён, класс темы обязательно поставить в разметку самостоятельно, иначе роли не объявлены и компоненты остаются без цвета.

Перечень переменных ядра со значениями по умолчанию — в справочнике «Все переменные»; примитивы палитры, размерной лестницы и прозрачности описаны на своих страницах. Справочник собирается из собранного ядра автоматически. Точное значение любого токена выбранного выпуска читается и прямо в поставке, в distr/core/css/core.css; у адаптивных токенов настольное значение стоит там внутри медиазапроса настольной ширины.

Размеры иконок

У иконок две шкалы, и какая из них работает, зависит от того, где стоит иконка.

Лестница --sf-icon-size-* — для иконки, которая стоит сама по себе: значок статуса, маркер, декоративный элемент. Значения в ней постоянные и не зависят от ширины экрана.

Иконка внутри контрола — кнопки, поля, тега, пункта списка — берёт размер не из лестницы, а из строки: и коробка, и сам знак равны высоте строки этого контрола. Так иконка занимает ровно строку и не меняет её высоту. Пример показывает это правило у кнопки размера 1:

.sf-button.sf-button--size-1 .sf-icon {
  --sf-icon--font-size: var(--sf-text-height-1);
  --sf-icon--height: var(--sf-text-height-1);
  --sf-icon--width: var(--sf-text-height-1);
}

Разница видна не сразу: на широком экране числа ступени 1 совпадают с кеглем. Но размеры текста адаптивные (Адаптивные размеры), а лестница иконок — нет. На узком экране ступень 1 даёт текст 14 px и строку 20 px, тогда как --sf-icon-size-1 остаётся 16 px. Поэтому иконка в контроле следует за строкой: только так она уменьшается вместе с текстом.

Цвет иконки — отдельное правило (Цвет иконки: три роли).

Другие токены ядра

Кроме цвета и размеров, ядро объявляет ещё несколько семейств; их значения — в справочнике «Все переменные»:

• ширина контейнера — --sf-container-1--size-max … --sf-container-8--size-max, от 60 до 112 rem; действуют от контрольной точки lg;
• прозрачность элемента — --sf-opacity-10 … --sf-opacity-90, от 10 до 90 % с шагом 10;
• порядок слоёв — --sf-z-index--1 (-1), --sf-z-index-0 (0) и --sf-z-index-1 … --sf-z-index-9 (от 10 до 90 с шагом 10).

Ступени z-index задают относительный порядок, а не назначение. В проекте рекомендуется связать их с ролями, например --project-layer-modal: var(--sf-z-index-8).

Как пользоваться токенами в проекте

Берите роль, а не число и не примитив. Пример показывает блок заметки, оформленный только ролями:

.project-note {
  background: var(--sf-surface-container);
  color: var(--sf-on-surface);
  border: var(--sf-px) solid var(--sf-outline-variant);
}

Такая заметка правильна в обеих темах и на любой подложке без единой дополнительной строки.

Называйте свою роль своим именем, но берите значение у Framework:

:root {
  --project-card-radius: var(--sf-radius--surface);
  --project-card-gap: var(--sf-space-3);
}

Имя проекта говорит, что это за значение в вашем интерфейсе; значение остаётся согласованным с Framework и меняется вместе с ним при перенастройке.

Не изобретайте ступени. Если нужен цвет, которого нет среди ролей, сначала найдите роль по смыслу. Если нужна прозрачность — возьмите ступень шкалы (см. Прозрачность). Значение, подобранное на глаз, не проходит контракты и не объясняется именем.

Где переопределять:

• примитивы и размерные роли — на :root;
• цветовые роли — на классах темы (см. Своя тема проекта).

Всё это пишется в CSS проекта, подключённом после core.css. Правила каскадных слоёв (Каскадные слои) гарантируют, что проект сильнее Framework. Какие токены менять, чтобы изменить дизайн, — см. Как менять дизайн.

Смотрите также

• Каскадные слои — в каком каскадном слое объявлены токены;
• Все переменные — все переменные ядра со значениями по умолчанию;
• Цветовые примитивы и палитры и Цветовые роли — примитивы и роли цвета;
• Базовая единица и шкала примитивов и Соразмерные ступени — размерная лестница;
• Проверки — контракты, проверяющие токены;
• Как менять дизайн — что менять в проекте, чтобы изменить дизайн.