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

Токен меняют один раз в одном файле — а ломается интерфейс в пятнадцати местах кода, о которых никто не вспомнил в момент правки. Это не гипотетический сценарий: переименовали переменную, обновили оттенок бренда, «почистили» неиспользуемый на вид токен — и через день-два в беклоге появляются баг-репорты про съехавшие кнопки и несовпадающие цвета, никак не связанные на первый взгляд с тем самым коммитом.
Разница между этим и обычным рефакторингом переменной в том, что дизайн-токен редко остаётся внутри одного модуля. Если в проекте уже есть дизайн-система в коде — токены, компоненты, документация, процесс, — разберитесь сначала с ней целиком: подробный материал о дизайн-системе в коде закрывает эту базу. Здесь же — только про один конкретный риск внутри уже существующей системы токенов: что происходит, когда токен меняют без версионирования, и как выстроить процесс, чтобы это не превращалось в скрытую поломку.
Там, где процесс вокруг токенов пора формализовать, а не держать на честном слове, разумно подключить команду, которая отвечает и за дизайн-систему, и за её безопасное сопровождение в коде, — например, команду UI/UX-дизайна в YuSMP Group, которая выстраивает не только визуальный слой, но и процесс его поддержки.
Почему правка токена — не то же самое, что правка обычной переменной
Локальная переменная внутри функции — деталь реализации: её можно переименовать, изменить тип или удалить, и единственное, что нужно проверить, — не сломалась ли сама функция. Дизайн-токен устроен иначе: это значение, на которое транзитивно ссылаются десятки компонентов, страниц и, возможно, других токенов (составной токен, собранный из базовых). Переименование или удаление токена — это фактически изменение публичного API дизайн-системы, а не внутренняя деталь одного файла.
Отсюда и разный уровень осторожности. Правку приватной переменной ревьюер проверяет в контексте одной функции. Правку общего токена нужно проверять в контексте всех его потребителей — а их список редко очевиден без специального поиска, особенно если токен уже компилируется в CSS custom property.
Что ломается первым, когда токен меняют без контроля
Три сценария повторяются от проекта к проекту чаще остальных. Первый — переименование токена без алиаса на старое имя: компонент, который кто-то написал полгода назад и давно не трогал, продолжает ссылаться на старое имя и либо падает на сборке, либо — хуже — молча получает значение по умолчанию, не замеченное сразу.

Второй сценарий — изменение значения, которое визуально ломает один-два компонента, но не остальные. Отступ, задуманный универсальным, на практике оказывается слишком маленьким для карточки с длинным заголовком — просто потому что раньше там стояло другое число, под которое верстали конкретно эту карточку. Третий, самый коварный, — удаление «неиспользуемого» токена. Поиск по основному коду ничего не находит, токен удаляют, а через неделю выясняется, что он использовался в забытом legacy-компоненте, который не попадает в обычные сценарии тестирования и не вызывает подозрений до прод-релиза.
Breaking vs non-breaking изменение токена — как их различать
Критерий простой и воспроизводимый: если меняется только значение токена — это non-breaking изменение, при условии что визуальный сдвиг приемлем для всех его потребителей. Если меняется имя или структура токена (например, был один токен отступа, а стал составной объект с полем для мобильной и десктопной версии), это всегда breaking-изменение для любого кода, который ссылается на старую форму.
/* non-breaking: значение изменилось, имя и структура — нет */
--color-primary-600: #2a5ea8; /* было #2a4e8f */
/* breaking: токен переименован — старое имя должно остаться алиасом */
--color-brand-primary: var(--color-primary-600); /* алиас на период миграции */
Единого стандарта описания токенов индустрия пока не навязывает — ближайший ориентир даёт рабочая группа Design Tokens Community Group при W3C, но на уровне версионирования полноценный semver на каждый токен избыточен — это оверинжиниринг, который требует инфраструктуры ради задачи, решаемой проще. Практичная замена — журнал изменений прямо в файле токенов (кто, когда и почему поменял значение) и обязательный алиас на старое имя при любом переименовании на период миграции, обычно один-два релизных цикла.
Ревью pull request, который трогает общий токен
PR, меняющий токен, который используется в десятке и более мест, заслуживает отдельного пункта в чек-листе ревью — такого же внимательного, как изменение публичного метода в API. Ревьюеру стоит проверить три вещи: список реально затронутых компонентов и страниц (поиск по имени токена или по сгенерированному CSS-классу, если токены компилируются), наличие алиаса на старое имя, если токен переименован, и снимки визуального регресс-теста, если он настроен в проекте.
Отдельная практическая деталь: сам факт того, что PR меняет файл токенов, стоит делать заметным — например, через обязательный лейбл или отдельную категорию в шаблоне PR. Если такие изменения растворяются среди обычных фич, их начинают ревьюить с тем же вниманием, что и правку локального стиля одной кнопки, — а цена ошибки здесь совсем другая.
Как ловить визуальные поломки раньше, чем их заметит пользователь
Unit-тесты проверяют логику, но не то, как компонент выглядит после изменения значения токена. Для этого нужен отдельный слой — visual regression или contract-тестирование: инструмент делает скриншот ключевых компонентов до изменения и после, сравнивает их пиксель в пиксель и показывает разницу. Это ловит именно то, что не видят функциональные тесты: компонент работает штатно, но отступ съехал на несколько пикселей или цвет сменился на соседний из палитры.
Настраивать такой слой на каждый токен в проекте избыточно — оправдано это для базовых, широко используемых токенов: основного цвета бренда, базовых отступов, радиусов скругления. Чем шире радиус использования токена, тем дороже ручная проверка всех затронутых мест и тем выше отдача от автоматического сравнения скриншотов в CI при каждом PR, трогающем файл токенов.
Как вывести токен из использования, чтобы никто не узнал об этом из бага?
Удаление токена «одним коммитом, раз он больше не нужен» — источник именно того скрытого сценария поломки, который описан выше. Безопасная последовательность выглядит иначе: сначала токен помечается как deprecated — в комментарии, в документации дизайн-системы и, если возможно, в линтере, который выдаёт предупреждение при обращении к нему. Затем он остаётся физически в коде минимум один-два релизных цикла, обычно с алиасом на новый токен, если речь идёт о замене, а не о полном выводе из использования.
Удалять токен стоит только после подтверждения, что обращений к нему за этот период не осталось — не «кажется, что не используется», а проверено поиском по проекту или отчётом линтера. Это превращает удаление из рискованной операции в формальность, которая занимает чуть больше времени, но не оставляет шанса на скрытую поломку в забытом месте кода.
Когда самодельного процесса уже не хватает
Пока в проекте есть один-два человека, которые помнят историю всех токенов, и объём свежих правок невелик, ручной дисциплины — алиасов, журнала изменений, внимательного ревью — обычно достаточно. Но когда токенов становится несколько десятков, в команду приходят новые разработчики без контекста по прошлым решениям, а дизайн-система используется сразу в нескольких продуктах, процесс, держащийся на памяти конкретных людей, неизбежно даёт сбой именно в тот момент, когда цена ошибки выше всего — в проде, а не на этапе ревью.
Это тот момент, когда стоит не продолжать латать процесс по мере возникновения проблем, а выстроить его системно — вместе с визуальным слоем дизайн-системы, который должен прожить этот процесс так же безопасно, как и код вокруг него. Если дизайн-система ещё не оформлена целиком, разумно начать с неё — материал о дизайн-системе в коде разбирает токены, компоненты, документацию и процесс как единое целое, а не только версионирование.
Частые вопросы
В чём разница между breaking и non-breaking изменением токена?
Non-breaking: меняется только значение (оттенок, число пикселей) без переименования или удаления — потребители кода не меняют свой код. Breaking: меняется имя токена, его структура или он удаляется — любой код, ссылающийся на старое имя, перестаёт собираться или получает неверное значение.
Нужен ли токенам отдельный номер версии, как у npm-пакета?
Для большинства проектов полный semver на уровне токенов избыточен; достаточно журнала изменений прямо в файле токенов и алиасов на старое имя на период миграции при переименовании.
Как проверить, где используется токен, перед тем как его менять?
Поиск по проекту (grep или ripgrep по имени переменной), а если токены скомпилированы в CSS — поиск по сгенерированному классу или custom property. В крупных проектах это дополняет линтер, который падает на использование токена, помеченного deprecated.
Что такое visual regression тестирование и когда оно оправдано для токенов?
Это автоматическое сравнение скриншотов компонента до и после изменения, пиксель в пиксель. Оправдано, когда меняется базовый токен — цвет, отступ, радиус, — использующийся в десятках мест: проверить их все вручную нереалистично.
Как без боли удалить токен, который, кажется, уже не используется?
Пометить deprecated, не удалять физически минимум один-два релизных цикла, оставить предупреждение в линтере при обращении к нему и удалить только после подтверждения нулевого числа обращений за этот период.
Кто должен согласовывать изменение общего токена — дизайнер или разработчик?
Значение — какой именно оттенок или отступ — решение дизайнера. Способ внедрения изменения: алиас, миграция, тесты — решение разработчика. PR, который меняет общий токен, разумно ревьюить обоим.



