style: format docs markdown

2026-09-09 04:13:13 +05:00
parent 46da54140c
commit 64e35f4fdf
36 changed files with 2092 additions and 1187 deletions
@@ -2,15 +2,14 @@

 > **СТАТУС: РЕАЛИЗОВАН (2026-09-07) — устарел.** Скрипты
 > `web/scripts/audit-dom.mjs`, `audit-css.mjs`, `audit-cdp.mjs`,
-> `audit-cdp-responsive.mjs` и npm-скрипты `refs-dom-audit` /
-> `refs-css-audit` / `refs-cdp-audit` на месте; старый текстовый `audit.mjs`
-> удалён. Актуальная доводка верности и статус пунктов F — в
-> `plan-design-fix.md`.
+> `audit-cdp-responsive.mjs` и npm-скрипты `refs-dom-audit` / `refs-css-audit` /
+> `refs-cdp-audit` на месте; старый текстовый `audit.mjs` удалён. Актуальная
+> доводка верности и статус пунктов F — в `plan-design-fix.md`.

-> Статус: к выполнению. Ветка `feat/redesign`.
-> Источник правды по пикселям: `refs-html/*.html` (статический экспорт рефа).
-> Актуальный рабочий аудит сейчас — `pnpm refs-audit` (`scripts/audit.mjs`), но он
-> **сломан** (см. «Почему текущий аудит не работает») и подлежит замене.
+> Статус: к выполнению. Ветка `feat/redesign`. Источник правды по пикселям:
+> `refs-html/*.html` (статический экспорт рефа). Актуальный рабочий аудит сейчас
+> — `pnpm refs-audit` (`scripts/audit.mjs`), но он **сломан** (см. «Почему
+> текущий аудит не работает») и подлежит замене.

 ## Почему текущий аудит не работает

@@ -37,13 +36,13 @@
   Заводим их через `t()` — совпадёт с рефом (EN).
 2. **Имена классов НЕ сводим к рефу.** Матчинг делаем по **структурному пути**,
   а не по классу. Компоненты `kit/` остаются идиоматичными, Stage 0 не
-   откатываем. Требуется только эквивалентность *структуры* (теги, вложенность,
+   откатываем. Требуется только эквивалентность _структуры_ (теги, вложенность,
   порядок сиблингов, наличие узлов, текст).
 3. **Пиксельный дифф (Playwright + pixelmatch) пока НЕ делаем.** DOM+CSS-аудита
   достаточно; добавим как сеть позже, если стили что-то упустят.
 4. **Порядок прогона маршрутов:** `demo` → `list-tools` → затем 2 инструмента
-   (`tools/linear-gradient-png` ↔ `gradient.html`,
-   `tools/remove-background-png` ↔ `background-remover.html`).
+   (`tools/linear-gradient-png` ↔ `gradient.html`, `tools/remove-background-png`
+   ↔ `background-remover.html`).

 ## Принципы

@@ -106,15 +105,15 @@ Svelte-атрибутов и комментов гидрации), чтобы п
 - `moved` — тот же текст/тег, другой путь (перепутанный порядок/родитель);
 - `textMismatch` — нормализованный текст различается (в т.ч. RU vs EN).

-Класс-мисматч — **только информационно**, не блокирует (классы свои по
-решению №2). Счётчики: `added / removed / moved / textMismatch`.
+Класс-мисматч — **только информационно**, не блокирует (классы свои по решению
+№2). Счётчики: `added / removed / moved / textMismatch`.

 ### Рендеринг

 - **наше:** dev-сервер на `5179` (как сейчас в `audit.mjs`).
 - **реф:** `pathToFileURL` к `refs-html/<ref>.html` (`file://`). Реф —
-  самодостаточный (инлайн `<style>`), рендерится полностью. Шрифты для фазы A
-  не важны (сравниваем структуру/текст, не растеризацию).
+  самодостаточный (инлайн `<style>`), рендерится полностью. Шрифты для фазы A не
+  важны (сравниваем структуру/текст, не растеризацию).
 - Переиспользуем из текущего `audit.mjs`: `discoverRoutes()`, `EXCLUDE`
  (`/preview`), `DYNAMIC` (`tools/[id]` → `gradient.html` /
  `background-remover.html`), `refNameFor()`.
@@ -122,8 +121,8 @@ Svelte-атрибутов и комментов гидрации), чтобы п
 ### Шаги (на каждом маршруте)

 1. Прогнать `pnpm refs-dom-audit`, получить дельты.
-2. Поправить структуру Svelte под реф (добавить/убрать/переставить узлы,
-   вынести тексты в `t()` с EN-базой).
+2. Поправить структуру Svelte под реф (добавить/убрать/переставить узлы, вынести
+   тексты в `t()` с EN-базой).
 3. Перезапустить, пока `added/removed/moved/textMismatch` ≃ 0 (кроме `IGNORE`).

 ---
@@ -135,17 +134,17 @@ Svelte-атрибутов и комментов гидрации), чтобы п

 ### Сравниваемые свойства (computed)

-`borderRadius`, позиция/размер (`getBoundingClientRect`: x/y/w/h),
-`padding` (все стороны), `margin`, `color`, `backgroundColor`,
+`borderRadius`, позиция/размер (`getBoundingClientRect`: x/y/w/h), `padding`
+(все стороны), `margin`, `color`, `backgroundColor`,
 `borderTop/Right/Bottom/Left Width|Color`, `fontFamily`, `fontSize`,
 `fontWeight`, `letterSpacing`, `lineHeight`, `gap`, `display`, `boxShadow`.

 ### Дифф

-Для каждого состыкованного по пути элемента — список свойств с дельтой
-(наше значение → реф). Элементы, не совпавшие по пути (остаток из фазы A),
-идут в `unmatched`. Отчёт: элемент → свойство → наше/реф. Правится одной
-строкой CSS, без брутфорса.
+Для каждого состыкованного по пути элемента — список свойств с дельтой (наше
+значение → реф). Элементы, не совпавшие по пути (остаток из фазы A), идут в
+`unmatched`. Отчёт: элемент → свойство → наше/реф. Правится одной строкой CSS,
+без брутфорса.

 ### Шаги

@@ -167,17 +166,17 @@ Svelte-атрибутов и комментов гидрации), чтобы п
   (шаги 1–5 плана list-tools). То есть фаза A/B для list-tools стартует после
   landing этих шагов.
 3. **`tools/linear-gradient-png`** (↔ `gradient.html`) и
-   **`tools/remove-background-png`** (↔ `background-remover.html`) — **последние**.
-   Известные расхождения: наши инструменты могут иметь **другие наборы
-   параметров / UI**, чем конкретные рефовые тулзы. Ожидаются структурные и
-   стилевые дельты, которые не сводятся к «подровнять паддинг». Для них —
+   **`tools/remove-background-png`** (↔ `background-remover.html`) —
+   **последние**. Известные расхождения: наши инструменты могут иметь **другие
+   наборы параметров / UI**, чем конкретные рефовые тулзы. Ожидаются структурные
+   и стилевые дельты, которые не сводятся к «подровнять паддинг». Для них —
   триаж после прогона:
   - реальный разрыв верности → фиксим;
-   - принципиальное отличие (параметр, которого нет в реф-тулзе; иной контрол)
-     → либо аккуратно приводим наш UI параметра к рефу, либо **документируем
-     как допустимое расхождение / заносим в allowlist** конфига аудита
-     (селектор + причина). «Скипы/фиксы» для инструментов оформляем явно, чтобы
-     аудит не шумел на осознанных отличиях.
+   - принципиальное отличие (параметр, которого нет в реф-тулзе; иной контрол) →
+     либо аккуратно приводим наш UI параметра к рефу, либо **документируем как
+     допустимое расхождение / заносим в allowlist** конфига аудита (селектор +
+     причина). «Скипы/фиксы» для инструментов оформляем явно, чтобы аудит не
+     шумел на осознанных отличиях.

 ---

@@ -185,25 +184,25 @@ Svelte-атрибутов и комментов гидрации), чтобы п

 - `scripts/audit-dom.mjs` — фаза A (нормализация + структурный дифф).
 - `scripts/audit-css.mjs` — фаза B (матчинг по пути + дифф стилей).
- `package.json`: `refs-dom-audit`, `refs-css-audit` (опционально
-  `refs-audit`, прогоняющий обе фазы).
- Переиспользуем из старого `audit.mjs`: `discoverRoutes`, `EXCLUDE`,
-  `DYNAMIC`, `refNameFor`, `waitFor` (fast-fail на 4xx/5xx).
+- `package.json`: `refs-dom-audit`, `refs-css-audit` (опционально `refs-audit`,
+  прогоняющий обе фазы).
+- Переиспользуем из старого `audit.mjs`: `discoverRoutes`, `EXCLUDE`, `DYNAMIC`,
+  `refNameFor`, `waitFor` (fast-fail на 4xx/5xx).
 - Отчёты: `web/audit/dom-report.{md,json}` и `web/audit/css-report.{md,json}`
  (старый `audit-report.*` заменяем).

 ## Верификация (после каждого коммита)

- `pnpm lint`, `pnpm exec svelte-check --tsconfig ./tsconfig.json`,
-  `pnpm build` — без ошибок.
- `pnpm refs-dom-audit` (фаза A) / `pnpm refs-css-audit` (фаза B) по
-  затронутому маршруту: счётчики расхождений не растут без причины.
+- `pnpm lint`, `pnpm exec svelte-check --tsconfig ./tsconfig.json`, `pnpm build`
+  — без ошибок.
+- `pnpm refs-dom-audit` (фаза A) / `pnpm refs-css-audit` (фаза B) по затронутому
+  маршруту: счётчики расхождений не растут без причины.

 ## Риски / заметки

- **Стабильность матчинга:** нужна аккуратная нормализация (сортировка
-  классов, игнор svelte-атрибутов/`data-*`, игнор whitespace-текстовых узлов,
-  игнор внутренностей SVG-иконок). Подстраивается по первым прогонам demo.
+- **Стабильность матчинга:** нужна аккуратная нормализация (сортировка классов,
+  игнор svelte-атрибутов/`data-*`, игнор whitespace-текстовых узлов, игнор
+  внутренностей SVG-иконок). Подстраивается по первым прогонам demo.
 - **Оболочка** (TopBar/footer/язык) сейчас отличается по дизайну — сводим к рефу
  в рамках полного соответствия (без IGNORE); финальная унификация компонентов —
  отдельным рефакторингом позже.