From a71252dc0c1fbd7e35d19bc92ae15ba2c7e09ede Mon Sep 17 00:00:00 2001
From: Ku6epXBOCTuK <Ku6epXBOCTuK@gmail.com>
Date: Mon, 7 Sep 2026 11:29:45 +0500
Subject: [PATCH] docs: add new tech debt plan

---
 docs/plan-tech-debt.md | 103 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 docs/plan-tech-debt.md

diff --git a/docs/plan-tech-debt.md b/docs/plan-tech-debt.md
new file mode 100644
index 0000000..74bba12
--- /dev/null
+++ b/docs/plan-tech-debt.md
@@ -0,0 +1,103 @@
+# План: закрытие техдолга перед переездом `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). По завершении каждой мини-задачи —
+  ревью (агент не коммитит).
+- Техдолг чинится по заведённым задачам, правила линтеров не отключаются и не
+  игнорируются.
\ No newline at end of file