План миграции дизайн-токенов

Действуй как architect design system. Спроектируй миграцию токенов ({{scope}}) на новую схему без поломок {{consumers}} consumer-приложений. Принцип: «никто не должен проснуться с красным CI из-за нашего рефактора».

1. Зафиксируй текущее состояние

1. Inventory старых токенов: grep по всем consumer-репам, сколько раз каждый используется. Топ-20 — критичны.
2. Categorisation: rename (только имя), refactor (значение), merge (два → один), split (один → два), remove (отказ).
3. Карта старое → новое в одном JSON/YAML — это будет источник правды для codemod, docs, deprecation warnings.

- old: --color-primary
  new: --color-accent-fg
  type: rename
  reason: "consistency with --color-accent-bg"

- old: --space-card
  new: [--space-card-x, --space-card-y]
  type: split
  reason: "horizontal/vertical padding diverged"

2. Стратегия — opt-in, не big bang

Фаза A — оба набора живут параллельно (релиз N)

1. Добавь новые токены.
2. Старые сделай aliases к новым (где возможно): --color-primary: var(--color-accent-fg);
3. Никаких сломов. Все consumer'ы продолжают работать без изменений.
4. Релиз — minor bump. В changelog: «New tokens available, old preserved».

Фаза B — codemod + opt-in (релиз N+1)

1. Codemod: jscodeshift / postcss-plugin / regex для случаев, где замена механическая.
   • Покрывает CSS files, CSS-in-JS, Tailwind config, plain strings.
   • Запусти на своём monorepo как dogfood — найди edge cases.
   • Документируй, что codemod НЕ покрывает (динамические имена, computed strings).
2. Opt-in flag для строгого режима: design-system.config.js → strict: true → старые токены кидают type error / build warning.
3. Deprecation warnings: @deprecated JSDoc + runtime warn (один раз на токен).
4. Релиз — minor bump.

Фаза C — deprecation window (между N+1 и N+M)

• Окно: 6 месяцев / 2 минорных релиза / следующий major — выбери одно и зафиксируй.
• Метрика: weekly grep usage старых токенов в consumer-репах. Цель → 0.
• Каждые 2 недели — напоминание в Slack/Discord, апдейт «N% мигрировали».
• Pair'ы с командами, которые не успевают (Office Hours).

Фаза D — удаление (релиз N+M, major bump)

1. Удали старые токены.
2. Codemod оставь ещё на один минор — для опоздавших и LTS-веток.
3. Changelog: «BREAKING: tokens removed, see migration guide».
4. Не релизь N+M пока хотя бы один топ-10 consumer не мигрировал.

3. Codemod — что покрывает, что нет

Для непокрытых — список в migration guide с примером ручной замены.

4. Коммуникация

• ADR до начала работ: проблема, решение, альтернативы.
• Migration guide — одна страница, обновляется по мере находок.
• Slack/Discord:
  • Анонс фазы A.
  • Анонс codemod + краткий how-to.
  • Weekly progress в дни деплоя.
  • Final call за 2 недели до удаления.
• DM-owners топ-10 consumer'ов с миграционным гайдом.
• Office Hours еженедельно в окне миграции — для блокеров.

5. Откат

Каждая фаза должна быть откатываемой:

• Фаза A — просто revert PR.
• Фаза B — старые токены остались aliases, codemod опционален.
• Фаза C — если ≥ 20% consumer'ов не успели — продли окно, не откатывай.
• Фаза D — не релизь major пока зелёные сигналы не получены.

Формат вывода

1. ADR с обоснованием.
2. YAML-карта старое → новое.
3. PR Фазы A: новые токены + aliases.
4. Codemod + миграционный гайд.
5. Коммуникационный план с датами.
6. Метрика-дашборд: usage старых токенов по неделе.

Anti-patterns (do NOT)

• ❌ Big-bang переименование без alias-слоя — у всех красный CI в понедельник.
• ❌ Миграция без codemod, когда замена механическая — outsourcing работы пользователю.
• ❌ @deprecated без указания нового имени — пользователь читает warning и не знает что делать.
• ❌ Окно депрекации «как только сможем» — никогда не закроется, держишь два мира вечно.
• ❌ Удаление в минорном релизе — semver violation, доверие подорвано.
• ❌ Codemod, который меняет файлы без diff-preview — невозможно ревьюить.
• ❌ Миграция всех токенов разом, когда меняется только spacing — раздувает scope, риск растёт нелинейно.
• ❌ Молчаливая миграция «changelog прочитают» — гарантированно пропустят. Slack + DM + Office Hours.
• ❌ Косметический rename (--color-primary → --color-brand) без выгоды — деньги в воздух, нарушает контракт.
• ❌ Считать, что «у нас всё в Tailwind config, codemod не нужен» — в продах есть legacy CSS, плагины, runtime-вычисления.