Миграция дизайн-токенов: разделение ролей и безопасное удаление старых имён

Дизайн-токены делают повторяющиеся решения явными: цветовую роль, шаг отступов, типографическую шкалу или значение визуального уровня можно повторно использовать в разных компонентах и на разных платформах. Сложности начинаются, когда токен ошибочен, неоднозначен или больше не подходит продукту. Одновременное переименование или замена его значения во всех местах может нарушить контраст, компоновку, документацию и код.

Безопаснее рассматривать изменение токена как миграцию. Сначала выясните, где используется прежнее решение, затем введите более понятную замену, переводите потребителей небольшими группами и выводите старое имя из эксплуатации только после проверки. Это не создание набора токенов с нуля, а сопровождение уже существующей дизайн-системы, которая должна развиваться вместе с продуктом.

Основы изложены в руководстве по дизайн-токенам (на английском) и обзоре дизайн-токенов в Pixso. Здесь речь идёт именно об объявлении токенов устаревшими, ответственных за них и доказательствах завершённой миграции.

Почему изменение токенов становится рискованным

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

Риск миграции обычно связан с четырьмя пробелами:

1. Команда не знает всех потребителей токена.
2. Замена меняет не только значение, но и смысл.
3. Дизайн и код обновляются по разным графикам.
4. Никто не определил, что означает завершение работы со старым токеном.

Решение не в том, чтобы заморозить систему. Нужно сделать зависимости и принятые решения видимыми ещё до объявления замены.

Составьте перечень токенов по ролям, а не только по именам

Начните с таблицы назначения и использования. Укажите имя токена, категорию, семантическую роль, поддерживаемые режимы, использующие его компоненты, ответственного и предполагаемое действие. Не выводите роль только из HEX-значения: два токена с одинаковым значением могут решать разные задачи, а одному токену могут понадобиться разные значения в светлой и тёмной темах.

Собирайте подтверждённые сведения, не пытаясь с первого раза довести классификацию до совершенства. Небольшой точный перечень полезнее длинного списка с предполагаемыми зависимостями. Руководство по именованию дизайн-токенов (на английском) поможет с принципами названий, но решение о миграции остаётся за командой, отвечающей за продукты, где используются токены.

Выберите переименование, алиас или замену

Эти действия решают разные задачи.

Переименование ради ясности

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

Алиас для совместимости

Алиас совместимости позволяет старому имени продолжать работать, пока его потребители переходят на замену. Назначьте ответственного именно за этот алиас и определите условие его удаления. Не смешивайте такой временный механизм с постоянной семантической ссылкой: токен text-secondary вполне может ссылаться на базовый цвет всё время существования системы. Сам факт ссылки на другой токен не делает ни один из них устаревшим.

Замена семантического решения

Меняйте семантическое решение, если одно имя объединяет несовместимые назначения. Например, text-muted используется и для читаемых подсказок в форме, и для надписей на недоступных кнопках. Разделите его на text-secondary для вспомогательной информации и text-disabled для недоступных элементов управления. Одна глобальная замена старого имени не сможет правильно выбрать обе роли: каждое использование нужно проверить отдельно.

Удаление только после исчезновения всех потребителей

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

Создайте замену, которую можно проверить

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

Вспомогательный текст должен оставаться читаемым: более светлый оттенок не даёт права игнорировать контраст. Исключение WCAG для недоступных элементов управления связано с фактическим состоянием элемента, а не с наличием слова «disabled» в имени токена. Для других категорий токенов проверьте переносы строк, отступы, видимость фокуса и поведение тем в использующем их компоненте. Значение, подходящее для отдельного образца, может не работать в реальном контексте.

Добавьте рядом с заменой примечание о миграции:

text-muted объявлен устаревшим для новых применений. Читаемый вспомогательный текст переводите на text-secondary, а надписи на недоступных элементах управления — на text-disabled. Существующие потребители должны сохранять старое значение до проверки их компонента. Ответственный за компонент фиксирует каждую миграцию и подтверждает, когда можно удалить механизм совместимости.

Точно обозначенная область применения делает примечание полезным для дизайнеров, разработчиков и ревьюеров, которые встретят старую ссылку в запросе на слияние кода.

В отдельном файле Pixso сравните одну и ту же карточку настроек до и после разделения text-muted на text-secondary и text-disabled. Не меняйте компоновку и формулировки: «Выберите дату» должно оставаться читаемой подсказкой, а «Сохранить изменения» — обозначать недоступное действие. Подпишите роль каждой надписи и проверьте два варианта компонента вместе с ответственным за реализацию. Отдельно зафиксируйте соответствие токенов в коде и после ревью опубликуйте утверждённое обновление дизайн-библиотеки.

Сравните замену стилей в Pixso →

Переводите потребителей осмысленными группами

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

Для каждой группы зафиксируйте:

• старые и новые имена токенов;
• затронутые компоненты и состояния;
• ожидаемое визуальное или смысловое изменение;
• ответственных за дизайн и код;
• скриншоты или ссылки, подтверждающие проверку;
• дату, с которой группа сможет обходиться без алиаса.

Общее дизайн-пространство помогает команде сопоставлять состояния и обсуждать решения. Материалы с примерами дизайн-систем (на английском) и о масштабировании дизайн-систем (на английском) дают более широкий контекст; запись о миграции должна оставаться конкретной и относиться к текущим компонентам.

Проверяйте смысловые и визуальные регрессии отдельно

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

Проверка смысла и поведения

• Используется ли токен только в документированной роли?
• Соответствует ли значение требованиям проекта к контрасту и состояниям?
• Согласованно ли токен ведёт себя во всех поддерживаемых темах?
• Остаются ли стабильными экспортируемые имена и соответствия для платформ?
• Отклоняется ли неподдерживаемое использование или хотя бы становится заметным при ревью?

Визуальная проверка

• Изменились ли переносы текста на ожидаемых ширинах?
• Можно ли по-прежнему различить границы, разделители и контуры фокуса?
• Сохраняется ли нужная иерархия у всплывающих слоёв и меню?
• Сохраняет ли насыщенный данными экран свою плотность и удобство беглого просмотра?
• Остаются ли согласованными мобильные и десктопные компоненты?

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

Объясняйте вывод токена из эксплуатации как изменение продукта

Дайте потребителям конкретное уведомление о миграции: прежнее имя, причину изменения, правило замены, затронутые компоненты, ответственного и релиз, в котором планируется удаление. Если файлы токенов используют спецификацию Design Tokens Format Module (на английском), свойство $deprecated позволяет отметить токен и добавить объяснение. Эти метаданные сообщают статус, но не находят потребителей и не переносят их ссылки автоматически.

Используйте понятные всей команде названия статусов:

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

Выводите старый токен из эксплуатации на основании проверок

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

Явно зафиксируйте условия завершения:

1. Ни одному поддерживаемому потребителю больше не нужно старое имя. Если остаётся исключение, сохраните для этого потребителя совместимый путь, прежде чем удалять токен из других пакетов.
2. Замена прошла смысловые и визуальные проверки во всех поддерживаемых режимах.
3. Для алиаса и примечания о миграции объявлена дата удаления.
4. Документация, примеры и автодополнение кода больше не рекомендуют старое имя.
5. Предусмотрен откат на случай, если позже обнаружится ещё один потребитель.

Удаляйте старый токен только из пакета, чьи поддерживаемые потребители уже переведены на замену. Храните вместе последнюю рабочую версию пакета, таблицу соответствий и проверенные примеры, чтобы откат восстанавливал прежний контракт. Если позднее обнаружится потребитель, восстановите совместимость, пока ответственный проверяет соответствие ролей; не подставляйте незаметно визуально похожее значение.

Ведите реестр исключений

Не все потребители могут перейти на замену в один срок. Изменения в мобильном релизе могут быть заморожены, партнёрский пакет может предоставлять публичное имя токена, а устаревшая тема — пока не поддерживать замену. Для каждого исключения укажите ответственного, затронутую область, причину и дату пересмотра. Явное временное исключение безопаснее алиаса, который команда молча оставила навсегда.

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

Завершайте миграцию на уровне потребителей

Для карточки настроек завершение означает, что подсказка и надпись недоступной кнопки используют свои документированные роли и в дизайне, и в реализации, поддерживаемые темы проверены, а ни один поддерживаемый экземпляр больше не зависит от text-muted. Все нерешённые случаи оставьте в записи о миграции. Старое имя можно убрать из пакета, когда исчезнут эти зависимости, а не тогда, когда новый токен сам по себе выглядит готовым.

Дополнительные материалы

• Design Tokens Community Group: спецификация Format Module (на английском)
• W3C: рабочая группа сообщества по дизайн-токенам (на английском)
• Material Design: обзор дизайн-токенов (на английском)