Архитектура токенов для нескольких тем и брендов

Тема изменяет цветовой режим одного и того же бренда — например, добавляет светлую и тёмную версии одного продукта. Бренд — это другая визуальная идентичность: одни и те же компоненты дизайн-системы отображаются с разными цветами, типографикой и отступами для разных продуктов или клиентов. В обоих случаях используется одна архитектура токенов, но на разных уровнях абстракции.

Примитивные токены — это полная палитра исходных значений, доступных системе. В неё входят все оттенки цветов (color-blue-50–color-blue-900), все единицы отступов и все размеры шрифта. Примитивные токены никогда не используются непосредственно в компонентах — на них ссылаются только семантические токены. Палитра определяется один раз и используется всеми темами и брендами.

Семантические токены выражают назначение: color-background-page, color-text-primary, color-action-primary. Каждый семантический токен ссылается на значение примитивного токена, подходящее для текущей темы. Компоненты создаются исключительно на основе семантических токенов. Именно на этом уровне происходит темизация.

В светлой теме color-background-page ссылается на color-white, color-text-primary — на color-gray-900, а color-action-primary — на color-blue-500. Эти соответствия определяются в файле токенов для конкретной темы, который переопределяет семантический слой в светлом контексте.

В тёмной теме color-background-page ссылается на color-gray-950, color-text-primary — на color-gray-50, а color-action-primary — на color-blue-400 (этот оттенок немного светлее, чтобы обеспечить контраст на тёмном фоне). Меняются только семантические соответствия — примитивная палитра и все компоненты остаются неизменными.

Бренд A использует синий как основной цвет (color-action-primary: {color-blue-500}). Бренд B использует зелёный (color-action-primary: {color-green-500}). Компонент кнопки обращается к var(--color-action-primary) и совершенно не знает, какой бренд активен. Переопределения для брендов изменяют только соответствия семантических токенов, но не код компонентов.

Пользовательские свойства CSS делают переключение темы во время выполнения простым. Сохраните текущую тему в атрибуте данных: document.documentElement.setAttribute('data-theme', 'dark'). Правила CSS переопределяют семантические токены внутри [data-theme="dark"]. Браузер сразу разрешает все ссылки var() в новые значения — повторного рендеринга с помощью JS не требуется.

Если разные бренды предоставляются как отдельные развёртывания, используйте темизацию во время сборки: создавайте отдельные файлы токенов CSS для каждого бренда с помощью Style Dictionary и загружайте нужный CSS бренда при запуске приложения. Такой подход подходит, когда бренд определяется во время развёртывания — например, для разных доменов, поддоменов или white-label-экземпляров, — а не во время взаимодействия с пользователем.

Система с несколькими брендами и темами требует двумерной матрицы: бренд A, светлая тема; бренд A, тёмная тема; бренд B, светлая тема; бренд B, тёмная тема. Пользовательские свойства CSS элегантно обрабатывают такую структуру с помощью вложенных селекторов: [data-brand="a"][data-theme="dark"] переопределяет семантические токены для конкретного сочетания. Четыре сочетания — это четыре блока CSS, а не четыре кодовые базы.

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

Управление определяет, кто может добавлять или изменять токены и какой процесс проверки требуется. Для примитивных токенов требуется одобрение команды дизайна. Семантические токены требуют проверки командами дизайна и разработки. Токенами компонентов может управлять владелец компонента. При отсутствии такого управления появляются дублирующиеся токены, и гарантия «единственного источника истины» перестаёт работать.

Почему компоненты должны ссылаться на семантические токены, а не на примитивные?

Темы изменяют цветовые режимы внутри бренда, а бренды представляют собой разные визуальные идентичности. Примитивные токены образуют исходную палитру, семантические токены передают смысл и позволяют менять тему. Компоненты используют только семантические токены. Тёмный режим и переопределения бренда изменяют только сопоставления семантических токенов — компоненты остаются неизменными. Темы, изменяемые во время выполнения, используют пользовательские свойства CSS с селекторами [data-theme]; брендинг во время сборки создаёт отдельный CSS для каждого бренда. Управление токенами и версионирование поддерживают согласованность системы по мере её развития.