Дизайн-токены: реализация и управление
Неизменяемые релизы с семантическим версионированием для пакетов дизайн-токенов с разрешением алиасов, проверками совместимости и безопасным для отката распространением, чтобы потребители никогда не привязывались к неподтверждённым черновым наборам токенов на разных поверхностях.
Статус пакета: пакет с AI-поддержкой для справки. Статическая проверка пакета пройдена; сценарии реализации ещё не выполнены, требуется экспертная проверка перед стабильным использованием.
Решение
Публиковать дизайн-токены как неизменяемые пакеты с семантическим версионированием в едином реестре, предоставлять только проверенные алиасы, такие как stable и previous-stable, и требовать проверки совместимости перед изменением любого алиаса. Потребители могут фиксировать точную версию или сознательно следовать алиасу; черновые наборы токенов никогда не публикуются в производственные алиасы.
Область применения
- Нумерация версий, требования к журналу изменений, карты алиасов и неизменяемость публикаций для пакетов токенов.
- Распространение между поверхностями для веб- и нативных потребителей, использующих общий реестр.
- Откат указателей алиасов в пределах ограниченного окна оператора после неудачного релиза.
- Жизненный цикл устаревания для переименованных или удалённых токенов.
Вне этого блока
- Создание семантики токенов, цветовая наука или правила стилизации компонентов.
- Механика переключения тем во время выполнения (см. блок контракта темы тёмного режима).
- Общая администрация реестра пакетов, не связанная с дизайн-токенами.
Контракт
- Опубликованный релиз токенов версии
X.Y.Zявляется неизменяемым; повторная публикация той же версии с другим содержимым отклоняется. - Ломающее переименование или удаление токенов требует увеличения мажорной версии; минорные и патч-релизы должны оставаться обратно совместимыми для всех непомеченных как устаревшие публичных алиасов.
- Производственные алиасы (
stable,previous-stable) ссылаются только на релизы, прошедшие проверки совместимости профиля; черновые или локальные сборки не могут удовлетворять алиас. - Потребители, фиксирующие точную версию, продолжают разрешать эту версию после перенаправления алиаса, если явно не обновятся.
- Устаревшие токены остаются доступными в течение настроенного льготного периода и вызывают предупреждение во время сборки или в CI перед жёсткой ошибкой.
- Откат перенаправляет
stableнаprevious-stable(или на именованную безопасную версию) в пределах окна отката профиля и фиксирует исполнителя, причину и затронутый дайджест. - Метрики внедрения показывают, какие поверхности используют какую версию токенов, чтобы наблюдать расхождение между поверхностями в одном интервале отчётности.
Руководство по реализации
- Храните токены в формате, который ваша цепочка инструментов может сравнивать (JSON, Style Dictionary или экспорт CSS custom properties) и прикрепляйте манифест релиза, аналогичный
token-release.yaml. - Запускайте визуальные или контрастные проверки на представительных экранах перед продвижением алиаса; блокируйте публикацию, если необходимые токены отсутствуют в экспорте.
- Рассматривайте обновления алиасов как изменения инфраструктуры: требуйте одобрения двумя лицами или автоматического канареечного теста на промежуточном потребителе перед перенаправлением
stable. - Документируйте поддерживаемые комбинации версий, если веб и нативные релизы выходят с разной периодичностью.
Обработка сбоев и меры предосторожности
- Если публикация прошла успешно, но последующие проверки не прошли, оставьте алиасы без изменений и отметьте релиз как
withdrawn, а не удаляйте неизменяемый артефакт. - Если откат вызывается вне окна, требуется явный запрос с пометкой break-glass и сохранение обеих версий до подтверждения миграции потребителями.
- Если потребитель запрашивает withdrawn-версию, возвращайте артефакт с заметным заголовком об устаревании, а не молча заменяйте токены.
- Если задержка репликации реестра вызывает смешанные версии в разных регионах, приостановите перемещение алиасов до тех пор, пока все реплики не будут обслуживать один и тот же дайджест.
Проверка и эксплуатация
- Отслеживайте события перенаправления алиасов, количество откатов, ссылки на устаревшие токены в CI и коэффициент внедрения версий по поверхностям.
- Оповещайте, если какая-либо производственная поверхность остаётся на версии старше минимального окна поддержки дольше порога профиля.
- Ежеквартально репетируйте откат на промежуточном алиасе, чтобы проверить корректность манифестов и поведения фиксации версий потребителями.
Предположения по внедрению
- Имена и числовые значения в
example.yamlиtoken-release.yaml— это профиль внедрения, а не универсальные значения по умолчанию. - Команда внедрения владеет учётными данными реестра, инструментами визуального сравнения и определением ломающих изменений для своей схемы токенов.