# План: закрытие техдолга перед переездом `old/` (C17)

> Статус: план к выполнению. Ветка `feat/redesign`. Входит в гейт перед
> переездом старых файлов в `old/` (backlog №14; см. также
> `archive/plan-migrate-remaining.md` — техдолг «чинить по заведённым задачам,
> не игнорировать правилами»). Целевое состояние по завершении: `svelte-check` →
> 0 errors, `pnpm test` → зелёный, `lint:all` → без ошибок (допустим только
> задокументированный остаток), дизайн-токены → единый словарь `preview.css`.

## Состав техдолга (на 2026-09-07)

- **svelte-check error** — `ToolCard.svelte:19:36`: `resolve(normalizedHref)`
  принимает только типизированный роут, а `normalizedHref: string`. Красный
  svelte-check, висит на каждом прогоне.
- **фейл теста** — `src/lib/palette.test.ts`: `ENOENT src/app.css` (файл
  разъехался на `old.css` + `design2.css` при редизайне). Тест проверял
  контрасты палитры по токенам старого `app.css`
  (`text/surface/bg/link/ accent/danger/border`). При гейтах `pnpm test`
  красный, хотя 607 тестов проходят.
- **design-tokens в `kit/**`** — ~335 ошибок `lint:all` от локального плагина
  `eslint-plugins/design-tokens` (захардкоженные цвета/размеры/длительности/
  z-index/`color-mix()` в `<style>`-блоках svelte), плюс stylelint по CSS.
- **a11y-предупреждение** — `ColorField.svelte`.
- **пустой ruleset** — `Toggle.svelte`.

## Этапы

### Этап 1 — «зелёные» гейты (мелкие, по ~10–40 строк каждый)

1. **ToolCard** — убрать ошибку типов: либо валидировать `href` против набора
   известных маршрутов, либо явно протащить типизированный роут из каталога.
   Проверка: svelte-check 0 errors.
2. **palette.test.ts** — переписать чтение на новый словарь: тест контрастов
   гоняется по токенам `preview.css` (`:root` + `[data-theme="dark"]`, цвета
   `--color-*`/`--brand-*`). Отдельно: взять из нового дизайна, какие пары
   реально проверить (текст/фон, muted, акцент/бренд, бордер). Если часть
   проверок потеряла смысл в новом дизайне — сократить, не растягивать.
3. **a11y `ColorField` + пустой ruleset `Toggle`** — пофиксить прямо в этих
   компонентах.

Гейт этапа: `svelte-check` 0 errors, `pnpm test` зелёный.

### Этап 2 — миграция `kit/**` на design-токены (main объём)

Цель — `lint:all` без ошибок design-tokens (все примитивы/`color-mix()` уходят в
токены `preview.css`).

**Вариант А (основной): авто-фикс одноразовым скриптом.** Писать скрипт ТОЛЬКО
если он гарантированно ничего не испортит. Гарантии:

- Скрипт — одноразовый (`web/scripts/fix-design-tokens.mjs`), после прогона
  удаляется либо помечается неактуальным.
- Строгая карта замен: примитив → токен **1:1, только если значение точно
  совпадает с уже существующим токеном словаря** `preview.css` (цвет →
  `--color-*`/`--brand-*`, радиус → `--radius-*`, размер →
  `--space-*`/`--size-*`, длительность → `--duration-*`, z-index → `--z-*`).
  Никаких новых токенов скрипт не генерирует.
- Замены — только примитивы, не содержащие `var()`/`calc()`/`color-mix()`;
  исключения по правилам плагина (0, 0px, 1px, проценты, unitless) не трогаются.
  `color-mix()` → выносится в `preview.css` как производный `--color-*` токен
  (может требовать ручного решения имени).
- Скрипт обрабатывает только `src/lib/components/kit/**` и `src/preview.css`
  (scoped-пути плагина) и только `<style>`-блоки/`.css` — логику/разметку не
  меняет, только строки стилей.
- После прогона: обязательный дифф-ревью (все изменения — замена значений на
  `var(--x)`, ничего удалено/переставлено), затем полный `lint:all` +
  `svelte-check` + `pnpm test`. Если хоть что-то вне «замена примитива на токен»
  — скрипт считается проваленным, откатываем и переходим на вариант Б.

**Вариант Б (страховка): руками, пакетами по компонентам.** Если скрипт не
удался — чистим/заводим токены вручную, пакетами по компонентам (1–2 на задачу,
диф < ~500 строк). Отсутствующие токены (например `--space-2xl`/`--space-panel`,
уже дважды обходились в SchemaTextSource) добавляем в словарь `preview.css`
осознанно.

Гейт этапа: `pnpm --dir web lint:all` — только допустимый остаток
(неиспользуемые токены — варнинг), плюс регресс-прогон тестов и svelte-check.

### Этап 3 — чистота словаря `preview.css`

- Разобрать варнинги неиспользуемых токенов (check-tokens): либо использовать,
  либо удалить из словаря.
- После этапа 2 — повторный аудит токенов
  (`pnpm --dir web exec node scripts/check-tokens.mjs`): parity light/dark,
  hct-only, без мёртвых токенов.

### Этап 4 — финальные гейты (гейт переезда `old/`)

1. `pnpm --dir web exec svelte-check --tsconfig ./tsconfig.json` → 0 errors
2. `pnpm --dir web test` → зелёный
3. `pnpm --dir web exec prettier --check .` → чистый
4. `pnpm --dir web lint:all` → 0 (или только задокументированный остаток)
5. Обе ветки открываются: старый UI `/`, новый `/preview`

После зеленых гейтов — закрытие задач и переход к `backlog` №14 (переезд старых
файлов в `old/`).

## Порядок и коммиты

- Коммиты атомарные, < ~500 строк (AGENTS). По завершении каждой мини-задачи —
  ревью (агент не коммитит).
- Техдолг чинится по заведённым задачам, правила линтеров не отключаются и не
  игнорируются.