Дизайн-токены и темизация: контракт между дизайном и кодом

Три уровня — или никакой темизации

Дизайн-токен — это именованное дизайн-решение: --color-accent, а не #2563eb. Именование и делает его контрактом: код ссылается на решение, и решение может меняться без ведома кода. Зрелые системы сходятся на трёх уровнях со строго однонаправленными ссылками:

• Палитра-примитивы — сырые значения без приклеенного смысла: --blue-600: #2563eb, --gray-100, --space-4. Полный упорядоченный набор опций. Ничто в продуктовом коде не имеет права на них ссылаться.
• Семантические токены — намерение: --color-surface, --color-on-surface, --color-accent, --color-danger, --radius-interactive. Каждый отображается в примитив. Этот слой отвечает «для чего этот цвет» — и именно здесь живёт каждая тема.
• Компонентные токены — покомпонентные привязки, потребляемые стилями компонента: --button-primary-bg: var(--color-accent). Опциональны, но ценны в масштабе: дают каждому компоненту стабильный API стилизации и место для точечных переопределений.

Почему средний слой — тот, который нельзя пропустить: темы — это перепривязка намерений. Тёмная тема не говорит «сделай синий темнее» — она говорит «surface теперь почти чёрный, on-surface почти белый, accent на шаг светлее ради контраста». Если компонентные токены привязаны напрямую к примитивам — --button-bg: var(--blue-600) — выразить это утверждение негде, кроме как переобъявив каждый компонентный токен, сотни штук, на каждую тему. С семантическим слоем тема — это ~30 строк. А если продуктовый код использует примитивы напрямую — бренд вшит намертво, просто с красивыми именами: ребрендинг из Hook снова становится find-replace.

Рантайм: CSS custom properties против JS-объектов темы

Два лагеря реализации. CSS custom properties делают каскад браузера рантаймом темизации:

:root {
  --blue-600: #2563eb;            /* примитив — продукты на него не ссылаются */
  --color-accent: var(--blue-600); /* семантика — тема живёт здесь */
  --color-surface: #ffffff;
  --color-on-surface: #111827;
}
[data-theme="dark"] {
  --color-surface: #0b0f1a;       /* перепривязка намерения; примитивы нетронуты */
  --color-on-surface: #e5e7eb;
  --color-accent: var(--blue-400); /* на шаг светлее ради контраста на тёмном */
}

Переключение темы — это document.documentElement.dataset.theme = "dark": браузер пересчитывает стили, и никакого React-ререндера не происходит вовсе, потому что не изменилось никакое React-состояние. Это переживает SSR (инлайновый скрипт ставит атрибут до первой отрисовки, убивая вспышку темы), работает сквозь микрофронтенды и не-React-поверхности и не стоит ничего на компонент. Слабости реальны: значения — нетипизированные строки (лечится генерацией TypeScript-деклараций из источника токенов), а всё, что вычисляется из токена в JS, требует getComputedStyle.

JS-объекты темы — ThemeProvider, держащий { colors: { accent: ... } } и потребляемый через контекст, — дают типизированные, компонуемые значения прямо в языке. Счёт: тема связана с рантаймом — переключение меняет значение контекста, и оно обязано перерендерить каждого потребителя; в масштабе дизайн-системы это тысячи компонентов, перерисовывающихся ради цветов, которые браузер мог бы подменить в каскаде. Плюс привязка к одному фреймворку. Синтез, победивший на практике: писать токены как данные, типизировать на этапе сборки, доставлять как CSS custom properties — типизированное авторство, каскадный рантайм.

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

Дистрибуция: токены как версионируемый пакет

При более чем одном потребляющем приложении токены становятся API с потребителями — и требуют его дисциплины. Источник истины — файл данных (JSON), собираемый в платформенные выходы — CSS custom properties, TypeScript-модуль с типами, мобильные форматы — и публикуемый как версионируемый пакет, потребляемый как любая зависимость. Это включает политики, которые держат контракт доверенным:

• Политика breaking changes. Переименование токена — поломка API. Поставляйте алиасы устаревания — старое имя, реэкспортированное как ссылка на новое, с предупреждением на этапе сборки — минимум один мажор; удаляйте только на мажорном бампе, в идеале с codemod.
• Контроль дрейфа. Контракт разъедается по одному сырому hex за раз. Линтуйте: правило stylelint, запрещающее сырые цветовые литералы и px в продуктовом коде, форсируемое в CI. Токенизированное приложение из Hook уложилось в шесть дней потому что этот линт держал кодовую базу чистой; приложения с find-replace выплачивали годы незалинтованного дрейфа.
• Ревьюйте дифф токенов как дифф API. Изменённый семантический маппинг меняет каждого потребителя этого намерения; дифф мал для чтения и огромен по радиусу поражения — смена --color-accent есть визуальное изменение всего продукта, ревьюируемое в одном файле.

Слой интеропа, честно

Токены переживают любой тулчейн, поэтому формат важен. Style Dictionary — устоявшийся трансформер: один источник токенов на входе, пер-платформенные выходы на выходе (CSS, TS, iOS, Android), с кастомными трансформами. Формат W3C Design Tokens Community Group (спека design-tokens/community-group на GitHub) — ставка на интероп: JSON-формат с $value/$type/$description, спроектированный, чтобы дизайн-инструменты, трансформеры и генераторы документации обменивались токенами. Честный статус: годы в драфте, поддержка инструментами реальна, но неровна — Style Dictionary v4 его читает, крупные дизайн-инструменты следуют с разной точностью, — и миграция существующего источника токенов на него — работа. Это всё равно правильная ставка, потому что альтернатива — пер-инструментный lock-in единственного артефакта, который ваши команды дизайна и кода обязаны делить годами.