Токены

Контракт

Компонент видит ярусы 2 и 3 — семантику и роли. Ярус 1 не видит никогда.

.my-thing {
  /* ярус 2: для чего цвет нужен */
  color: var(--text-primary);
  /* ярус 3: отступ по назначению */
  padding: var(--pad-panel);
  /* ярус 4: точка настройки самого компонента.
     У кнопки таких пять: --btn-bg и соседи */
  background: var(--btn-bg);
}

Доступность

Устройство

Сырые шаги. Между темами не меняются. Рампа непрерывна по определению: шаг, не занятый семантикой, — резерв под приложение и графики, а не мусор.

Шага 2 у статусов нет: у них закреплённые роли (1 — фон в светлой, 3 — текст в тёмной, 4 — заливка в светлой, 5 — текст в светлой, 6 — резерв под графики), и свободный шаг между 1 и 3 не понадобился ни разу. Значения светлот и разбор ролей — в цвете.

Ручка тона

Ярус 2 — семантика

Одно объявление на токен через light-dark(). Второго блока токенов не существует, поэтому и расходиться нечему.

Поверхности

Три последних — утопление контрола: умолчание кнопки, тег, запасная заливка бейджа. Чёрный поверх, а не своя ступень рампы, и это не мелочь. Ступень задаёт светлоту абсолютно и потому знает одну глубину, а контрол лежит то на странице, то на панели, то в модалке — и от каждой обязан отойти на одинаковый шаг. На приподнятой панели --surface-sunken давал провал 0.087 вместо 0.033: панель уже сама на шаг выше, и шаги складывались.

Направление зависит от того, где мы на рампе, как и у --surface-hover. В светлых темах контрол утоплен — чёрная плёнка; в тёмных приподнят — белая.

Это не отказ от провала, а единственная доступная его форма. Плёнка вычитает светлоту, а на дне рампы вычитать не из чего: страница тёмной темы — rgb(12,12,12), и даже сплошной чёрный даёт против неё 1.073 при 1.142 у светлых. Нужного перепада затемнением не существует. А у умолчания кнопки заливка — единственный признак: рамки нет и тени нет, обе снял провал.

Инвариант поэтому формулируется без слова «глубина»: поверхность контрола обязана отличаться от своей подложки на различимую ступень.

Знак плёнки меняется, порядок громкости — нет. Средняя строка служит двум работам сразу: это и наведение умолчания, и заливка покоя мягкого веса inst-btn--soft. Значит она обязана быть тише умолчания в обеих темах, иначе третья ступень лестницы звучит громче второй. Громкость здесь — модуль перепада к подложке, а не альфа: в светлых темах тише значит меньше чёрного, в тёмных — меньше белого.

Сторожат это три пары cmd/contrast: «кнопка против панели», «кнопка против страницы» и «лестница: мягкая против умолчания».

Текст

Рамки

Акцент

Статусы

Третьего токена — «заливки» между текстом и фоном — нет. Исключение одно, акцент: у него есть случай, которого нет у статусов, — заливка под белой подписью.

Тон через атрибут

data-tone ставит три переменные, компонент читает их и больше ничего о тоне не знает.

Графики

Прочее

Порядок слоёв

Ярус 3 — роли

Единственный ярус, который перенастраивает плотность, и единственная причина, по которой в компонентах нет констант. Объявлен через :where() — нулевая специфичность, приложение переопределяет без борьбы. Значения ниже — для плотности по умолчанию, остальные две — в плотности.

Высоты и отступы контролов

Отступы по назначению

--gap-section — четвёртая ступень ритма: просвет между разделами, тогда как --gap-row работает внутри раздела. Значение не назначено, а выведено: это --gap-row, поднятый на четыре ступени шкалы. Шкала устроена так, что +4 ступени дают ровно ×4 в каждой точке — 4→16, 6→24, 8→32, 12→48, 16→64, — поэтому отношение держится во всех пятнадцати сочетаниях масштаба и плотности без отдельного подбора.

Роль появилась после обмера собранных экранов. Без неё ярус упирался в 16px: самое громкое, чем можно было разделить два блока, было того же порядка, что просвет внутри блока, — и экран читался сплошным потоком. Ступени 24, 32, 48 и 64 при этом лежали в шкале без единой роли.

Глифы и жёлобы

Раскладка

Шкала

Не привязаны к теме и не перенастраиваются плотностью. Подробности — в типографике и ритме и форме.

Типографика

--measure — предельная длина строки, 68ch. Классическая норма 45–75 знаков; 68 стоит у верхнего края, потому что интерфейсные описания короткие и переносятся редко. Единица ch, а не пиксели: иначе мера разъезжается с кеглем на каждой из пяти ступеней масштаба.

Роль появилась после обмера: 68ch было вписано литералом в двух местах, а тело баннера меры не имело вовсе и на контейнере 1440px доходило до 105 знаков. Обрезается тело баннера, а не сам баннер: подложка сообщения уровня страницы идёт во всю ширину, текст на ней — нет.

Пространство и форма

Движение

Ярус 4 — компонент

Живёт не здесь, а рядом с компонентом. Правило одно: 2–3 переменные, не больше, и вариант описывается ими, а не переписыванием блока.

.my-btn--accent {
  --btn-fg: var(--accent-on);
  --btn-bg: var(--accent-solid);
}

Список переменных конкретного компонента — на его странице: например, у кнопки их пять, у таблицы — свои.

Варианты

Правила

Что брать, а что нет

API

Перечисляет генератор, читая src/tokens.css. Список не пишется руками и потому не может отстать от исходников.

Связанное

Цвет Типографика Ритм и форма Высота и поверхности Движение Плотность Иконки