Переменные оформления

Версия набора токенов — 0.6.0. Всего переменных 189. Настроек школы всего 2; публичных имён, на которые можно опираться, — 83; производных от --brand — 9.

Справочник собирается из самого tokens.css при каждой сборке: если переменная есть здесь, она есть в продукте, и наоборот — разойтись им не из чего.

Как этим пользоваться #

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

Минимальная настройка школы — одна строка:

:root { --brand: #C2185B; }

Из --brand выводятся акцент, наведение, нажатие, бледная подложка, рамка, цвет ссылки и кольцо фокуса — отдельно для светлой и тёмной темы. Поэтому малиновая школа остаётся малиновой и в тёмной теме, а не превращается в бурую.

Куда это писать — в разделе Темы школы.

Три вещи, которые с переменными делают #

Классы отвечают не на вопрос «можно ли технически» — CSS не запретишь, — а на вопрос что мы обещаем.

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

Настройки школы #

Их 2, и в большинстве случаев дальше читать не нужно: фирменный цвет и шрифт закрывают то, ради чего вообще лезут в CSS.

Было / стало:

:root { --brand: #C2185B; }   /* было синее, стало малиновое — везде */
:root { --font-sans-brand: "PT Sans"; }

Где это видно:

• --brand — Кнопки главного действия, ссылки, выделенный пункт меню, прогресс, кольцо фокуса.
• --font-sans-brand — Весь интерфейс.

Публичные переменные #

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

Цвета: фоны, границы, текст #

Было / стало:

:root { --bg-canvas: #FFFFFF; }   /* было серым, стало белым: интерфейс «плоский» */
:root { --bg-surface: #FFFDF7; }  /* карточки чуть тёплого оттенка */
:root { --border: transparent; }  /* было в рамках, стало без рамок */
:root { --text-primary: #000000; }

Где это видно:

• --bg-canvas — Подложка всех экранов кабинета и админки.
• --bg-surface — Карточка курса, таблица, боковая панель, модальное окно.
• --bg-surface-muted — Заголовочная строка таблиц, полоса вкладок, блок кода.
• --bg-inverse — Всплывающая подсказка, панель управления видео.
• --bg-media — Плеер урока, обложка курса до загрузки.
• --border — Карточки, таблицы, поля, вкладки.
• --border-strong — Поля ввода, флажки, переключатели, выпадающие списки.
• --text-primary — Названия курсов и уроков, заголовки разделов, суммы.
• --text-body — Содержимое урока, описание курса, текст в диалогах.
• --text-secondary — Дата заказа, счётчик уроков, подпись под полем.
• --text-muted — Подсказки в полях, «ничего не найдено», сноски.
• --skeleton — Список курсов и таблицы в первые доли секунды после открытия.
• --overlay — Любое диалоговое окно, нижний лист на телефоне.

Шрифты и размеры текста #

Было / стало:

:root { --font-sans-brand: "PT Sans"; }
:root { --fs-body: 17px; }   /* было 15 — стало крупнее во всей школе */

Где это видно:

• --font-sans — Весь интерфейс.
• --font-mono — Блоки кода в уроке, ключи API в настройках.
• --fs-body — Тело урока, описания, диалоги.
• --lh-relaxed — Содержимое урока.

Отступы, скругления, размеры, тени, переходы #

Было / стало:

:root { --space-4: 12px; }   /* было просторно — стало плотнее по всей школе */
:root { --radius-control: 0; }   /* острые углы вместо скруглённых */
:root { --radius-card: 0; }
[data-lms="rail"] { width: 200px; }   /* якорь; см. раздел «Якоря» */
:root { --shadow-card: none; }   /* было с тенью — стало плоско */

Где это видно:

• --space-4 — Поля внутри карточек и диалогов.
• --radius-control — Все кнопки и поля ввода.
• --radius-card — Карточка курса, карточка заказа, панель.
• --size-panel — Панель фильтров, панель сведений о заказе.
• --size-nav-rail — Левое меню админки.
• --size-readable — Тело урока, длинные страницы документации.
• --shadow-card — Карточки курсов, панели.

Кольцо фокуса #

Где это видно:

• --focus-width — Любой элемент, на который встал фокус.

Производные от бренда: переопределять на свой риск #

Считаются из --brand сами, отдельно для светлой и тёмной темы. Переопределить каждую можно — это явный выбор, и мы его не запрещаем. Но связь с --brand при этом рвётся: тёмная тема перестаёт пересчитываться от него, и обе темы дальше на вас.

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

Где это видно:

• --accent — Заливка главной кнопки, активный пункт меню, заполненная часть прогресса.

Цвета состояний: отдаём, но не рекомендуем #

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

Пороги попадания: не рекомендуем, и тема проверяется #

44 пикселя — размер пальца, а не вкус: уменьшение ломает не вид, а возможность нажать. Здесь одних слов мало, поэтому тема, уменьшающая область нажатия ниже порога, даёт предупреждение на экране темы — тем же механизмом, что проверка контраста.

Доступность мы проверяем, вкус — нет.

Внутренние #

Их 69: примитивы палитры --p-*, номера слоёв, безопасные отступы телефона, метрики оболочки редактора. Мы меняем их свободно и без предупреждения. Опираться на них нельзя — правило, написанное по внутренней переменной, однажды перестанет применяться, молча и при обновлении.

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

Чего здесь ещё нет #

Деление утверждено, но ещё не закреплено в коде. Классы приняты 8 августа; по 02-architecture/customization.md §2 признак должен стоять в самом tokens.css — префиксом или разметкой блоков. Пока префикс --p- есть только у примитивов, признак живёт рядом с описаниями. Обязательство «не переименовывать публичную переменную», записанное в чужом файле, не переживёт рефакторинга: переименуют — переменная просто исчезнет из справочника, и никто не заметит.

Не у всех переменных есть «где видно» и пример «было / стало». customization.md §6 требует и то и другое у каждой записи: голый список имён бесполезен — за ним всё равно лезут в инспектор браузера. Чего не хватает по именам — в reports/tokens-gaps.md репозитория документации.