# План: переезд на новый дизайн (refs)

> Статус: план к выполнению.
>
> Источники: `refs/` — Next/React-референс (правда по пикселям), `refs-html/` —
> статические HTML-снимки для быстрого просмотра в браузере.

## 1. Что происходит

В `refs/` лежит новый визуальный язык проекта: «чертёжный» техно-стиль —
сетка на фоне, IBM Plex Sans/Mono, моно-микролейблы в верхнем регистре,
острые углы 4px, панели с 1px-бордером, акценты синий/циан/амбер, зелёные
статус-точки. Референс написан на Next 16 + Tailwind v4, но **переезд
дизайновый, а не фреймворковый**: SvelteKit в `web/` остаётся, переносится
только дизайн-слой (токены → примитивы → UI-kit → страницы).

Чего не делаем: не тащим Tailwind и React в проект. Токены из
`refs/app/globals.css` переносятся в наш vanilla-CSS слой почти один в один,
классы референса (`step-card`, `setting-group`, …) воспроизводятся как наши
глобальные утилиты и стили компонентов.

## 2. Токены (фундамент)

Маппинг старых токенов `web/src/app.css` → новые из референса:

| Старый         | Новый          | Light     | Dark                     |
| -------------- | -------------- | --------- | ------------------------ |
| `--bg`         | `--background` | `#eef1f4` | `#11171d`                |
| `--surface`    | `--panel`      | `#f8fafb` | `#182129`                |
| `--text`       | `--foreground` | `#17212b` | `#e8eef2`                |
| `--text-muted` | `--muted`      | `#6d7883` | `#91a0ac`                |
| `--border`     | `--line`       | `#cbd3da` | `#33414c`                |
| `--accent`     | `--blue`       | `#1769d2` | `#54a2ff`                |
| —              | `--cyan`       | `#00a8c7` | `#00a8c7`                |
| —              | `--amber`      | `#bd7411` | `#bd7411`                |
| —              | `--success`    | `#25a96a` | `#25a96a` (статус-точки) |
| `--danger`     | без изменений  | `#e5484d` | `#ff7479`                |

Прочее:

- Радиусы: вместо `--radius-s/m` один `--radius: 4px`. Скруглённая мягкость
  старой темы уходит.
- Шрифты: `IBM Plex Sans` + `IBM Plex Mono`, self-host через `@fontsource`
  (проект offline-first, CDN нельзя). Mono — рабочий шрифт для лейблов,
  метаданных, цифр; Sans — для заголовков и текста.
- Фон-сетка приложения (32px blueprint-grid) и шахматка канвасов —
  отдельные утилиты `.app-shell`, `.checker-canvas`, не токены.
- Тёмная тема остаётся на `[data-theme='dark']` (инлайн-скрипт в `app.html`
  уже есть); класс `.dark-mode` из референса не переносим.
- На переходный период старые имена живут как алиасы
  (`--bg: var(--background)` …), чтобы существующие компоненты не ломались
  до этапа D. В конце алиасы удаляются.

## 3. Базовые примитивы дизайн-системы

Повторяющиеся паттерны референса выносим в глобальные классы `app.css`
(по одному определению, без копипасты между компонентами):

- `.mono-label` — микро-лейбл: mono 10px, uppercase, letter-spacing .1em,
  цвет muted; модификаторы `.mono-label--accent` (синие eyebrow/version).
- `.status-dot` / `.status-line` — точка `--success` + подпись
  («AUTO PIPELINE», «LIVE PREVIEW»).
- `.panel` — панель: фон `--panel`, бордер `--line`; композиция
  `.panel-heading` (label + strong + правый слот) / `.setting-group` /
  `.settings-footer` с разделителями.
- `.checker-canvas` — рабочая поверхность превью: тёмная подложка +
  шахматка; размеры через контейнер.
- `.meta-row` — пары «CAPTION значение» (dimensions/format/size,
  result-meta).
- `.segmented` — сегмент-переключатель (общий для языка, типа градиента,
  пресетов).

## 4. Минимальный UI-kit (`src/lib/components/ui/`)

API компонентов сохраняем, меняем внутренности. Новые компоненты — только
те, для которых нет аналога:

| Компонент                                     | Статус    | Что меняется                                                                                            |
| --------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `Button.svelte`                               | рестайл   | варианты `primary` (синий solid) / `secondary` (outline) / `ghost` + `icon`-режим; busy-логика остаётся |
| `Field.svelte`                                | рестайл   | обёртка в стиле `.setting-group`: mono-label + output справа                                            |
| `SliderField`                                 | рестайл   | range + `<output>` значения, опциональная строка подсказок («strict edges … more removal»)              |
| `ColorField`                                  | рестайл   | swatch + hex-input + нативный color-picker в одном поле                                                 |
| `TextField` / `SelectField` / `CheckboxField` | рестайл   | чекбокс → switch-toggle 32×18 как в рефе                                                                |
| `SegmentedControl.svelte`                     | **новый** | RU/EN, Linear/Radial, пресеты прозрачности                                                              |
| `Badge.svelte`                                | **новый** | тег типа шага (BACKGROUND/TRANSFORM/STYLE), чип «✓ AUTO»                                                |
| `MetaList.svelte`                             | **новый** | `.meta-row` для DIMENSIONS/FORMAT/SIZE                                                                  |
| `EmptyState.svelte`                           | рестайл   | под новый стиль панелей                                                                                 |

Иконки: в рефе lucide-react; берём `lucide-svelte` (те же пути, MIT) —
16–17px, stroke, приглушённый цвет.

## 5. Шелл и страницы

### 5.1 Layout (`+layout.svelte`)

- Topbar: brand-mark «EP» (синий квадрат 30px) + `easy-png-tools` + версия
  суффиксом `/ v0.x`; справа — статус «LOCAL-ONLY», icon-btn темы
  (Moon/Sun), сегмент RU|EN.
- Footer: `easy-png-tools vX` · `pipeline is local-only` · © год.
- Фон-сетка на корневом контейнере `.app-shell`.

### 5.2 `/` — воркспейс

Текущий hero + ToolSearch переезжает в рампу референса: eyebrow
«PNG PROCESSING / WORKSPACE», крупный h1 (clamp 36–64px, tracking −0.06em),
lede; поиск — строка в стиле file-chip/pipeline-head. «Открыть последний» —
кнопка secondary. Каталог `/list-tools` — сетка карточек в стиле
`image-card` (label сверху, canvas-превью).

### 5.3 `/tools/[id]` — страница инструмента

Главная перестройка. Целевая раскладка из рефа — двухпанельная:

```txt
eyebrow + tool-title (+ LIVE PREVIEW)
┌─ settings-panel ────────┐ ┌─ preview-panel ─────────┐
│ panel-heading           │ │ preview-toolbar         │
│ setting-group ×N        │ │ checker-canvas / source │
│ (Slider/Color/Toggle…)  │ │ + result comparison     │
│ settings-footer (reset) │ │ meta-row                │
└─────────────────────────┘ └─────────────────────────┘
```

- `ParamsCard`/`ParamForm` → секция настроек: поля становятся
  `.setting-group` через обновлённый `ui/*`.
- `SourceCard`/`ResultCard`/`Preview` → превью-панель: toolbar с именем
  файла и download-btn, canvas на шахматке, result-meta снизу.
- Chain-блоки (`ChainToolBlock`) — нумерованные step-cards из главной
  рефа: индекс `01`, drag-handle, Badge типа, заголовок, кнопка удаления;
  параметры этапа — те же setting-groups внутри карточки.
- Существующий `ToolStageClassic`/inline-вариант заменяются целевой
  раскладкой; stage-абстракция из plan-inline-params закрывается этим
  переездом.

### 5.4 `/demo`

Зеркало `refs-html/index.html` — витрина пайплайна, используется как
приёмочный стенд нового стиля (делается первым среди страниц).

## 6. Этапы и проверки

Каждый этап заканчивается зелёными `test`/`check`/`build` и ревью в браузере
(обе темы) против соответствующего HTML из `refs-html/`.

- **A. Фундамент** — новые токены + алиасы старых, @fontsource IBM Plex,
  утилиты §3, тёмная тема на `[data-theme]`. Критерий: приложение выглядит
  по-старому (алиасы дают прежние цвета близко к новым), тесты зелёные,
  FOUC-скрипт темы работает.
- **B. UI-kit** — компоненты §4: сначала рестайл существующих, потом новые
  (`SegmentedControl`, `Badge`, `MetaList`). Критерий: демо-страница kit'а
  или `/demo` показывает все состояния; unit-тесты форм не падают.
- **C. Шелл** — topbar/footer по §5.1, переключение темы и языка в новом
  виде. Критерий: i18n/theme тесты зелёные, разметка шапки соответствует
  рефу.
- **D. Страница инструмента** — раскладка §5.3 на `/demo`, затем на всех
  инструментах; chain-карточки. Критерий: смоук §7, скриншоты против
  `refs-html/gradient.html` и `background-remover.html`.
- **E. Главная и каталог** — §5.2. Критерий: поиск/фильтры работают,
  покрытие search-coverage/i18n тестов зелёное.
- **F. Чистка** — удаление алиасов старых токенов, неиспользуемых классов
  `app.css` (`.tool-stage`, `.pane*`…), финальный проход по брейкпоинтам
  1200/1100/800/480 из рефа. Критерий: grep по старым токенам пуст,
  build без предупреждений.

Оценка объёма: A+B — фундамент (~полдня), C+D — основная работа (~1–2 дня),
E+F — добивка (~полдня).

## 7. Смоук (после этапа D)

1. Светлая и тёмная тема: сетка фона, панели, шахматка канвасов читаются,
   контраст mono-лейблов достаточный.
2. Инструмент с параметрами (градиент): slider/color/toggle в стиле
   setting-groups, автозапуск не регрессировал.
3. Удаление фона: сравнение source/result, маска, пипетка работают на новой
   шахматке.
4. Chain из 3+ инструментов: step-cards рендерятся, удаление/сброс работают.
5. Узкий экран 800px: настройки над превью, sticky выключается как в рефе.
6. RU/EN: новые лейблы локализованы; mono-лейблы рефа либо ключи i18n,
   либо осознанно английские брендовые элементы (см. §8).

## 8. Открытые вопросы

- Mono-лейблы рефа на английском (`PROCESSING PIPELINE`). Предложение:
  завести i18n-ключи, но для техно-эстетики допустимо оставить часть
  английскими как «приборную панель». Решить на этапе A.
- Версия в топбаре/футере: брать из package.json при сборке (define) или
  захардкодить? Мелочь, решить на этапе C.
- `refs/` оставляем в репо как источник правды; при изменении дизайна —
  правки там, затем синхронизация вручную. Регенерация refs-html описана в
  его README.