# Frontend UI Guide

Статус: нормативная карта frontend UI-системы проекта.

Этот раздел фиксирует целевое состояние интерфейса и служит точкой входа для всех решений по стилям, геометрии, карточкам, формам, модалкам и shared UI primitives. Это не одна заметка, а карта правил, по которой нужно проектировать новые экраны и проводить рефакторинг старых.

## Как читать этот раздел

Порядок чтения:

1. [01-OVERVIEW.md](01-OVERVIEW.md)  
   Что это за guide, где проходят границы и как устроен frontend по слоям.
2. [02-FOUNDATION.md](02-FOUNDATION.md)  
   Базовые токены, поверхности, action/form primitives и источники истины.
3. [03-GEOMETRY.md](03-GEOMETRY.md)  
   Целевая шкала радиусов, таксономия карточек и допустимые исключения.
4. [04-PATTERNS.md](04-PATTERNS.md)  
   Формы, dropdown-like UX, модалки, App Shell и target-pattern registry.
5. [05-MIGRATION.md](05-MIGRATION.md)  
   Что считать legacy, как двигать рефакторинг и по каким зонам идти.
6. [06-COMPONENT-INVENTORY.md](06-COMPONENT-INVENTORY.md)  
   Какие shared и feature-shared компоненты уже есть и когда какой использовать.
7. [07-DEVELOPER-WORKFLOW.md](07-DEVELOPER-WORKFLOW.md)  
   Как проектировать новый экран, форму, карточку, модалку и когда выносить код в shared.
8. [08-UI-REVIEW-CHECKLIST.md](08-UI-REVIEW-CHECKLIST.md)  
   Короткий checklist для PR review и самопроверки перед merge.

## Для чего этот guide

Guide обязателен для:

- новых экранов в `frontend/src/app`
- новых shared-компонентов в `frontend/src/components`
- переработки существующих карточек, форм, модалок и dropdown-паттернов
- code review, где нужно определить, является ли локальное UI-решение допустимым

Guide не предназначен для:

- описания API-контрактов
- описания state management конкретной фичи
- feature-specific UX-спеков

## Главная проблема системы

Сейчас frontend уже достаточно зрелый, чтобы его нормализовать системно.

Что уже в хорошем состоянии:

- палитра
- surface hierarchy
- акцентные состояния
- базовые `app-*` primitives

Что расползлось:

- геометрия
- шкала радиусов
- affordance dropdown-полей
- повторяющиеся card patterns
- разные form contracts для похожих сценариев
- визуальный жанр экранов: часть страниц выглядит как operational workspace, часть как showcase/dashboard из другого продукта

Именно поэтому этот раздел фиксирует target state заранее, даже если кодовая база ещё не полностью к нему приведена.

## Почему этот refactor вообще нужен

Цель refactor не в том, чтобы механически проставить одинаковые `rounded-*` по всему проекту.

Главная причина:

- соседние app-страницы иногда решены в разных визуальных жанрах
- из-за этого даже качественный локальный экран может выглядеть “как из другого проекта”
- если исправлять только токены, но не учитывать жанр экрана, можно легко сломать удачную страницу

Практический вывод:

- сначала нужно понять, что за экран перед нами: operational workspace, profile-like page, dashboard/feed, auth/legal flow
- потом сохранять удачный внешний контракт этого типа экрана
- и только после этого выравнивать геометрию, surfaces, controls и shared affordance

## Источники истины

Ключевые frontend primitives, на которые опирается весь guide:

- `frontend/src/app/globals.css`
- `frontend/src/components/ui/Modal.tsx`
- `frontend/src/components/shared/SearchableSelect.tsx`
- `frontend/src/components/AppShell.tsx`
- `frontend/src/components/requests/RequestComposeModal.tsx` как текущий reference для compose-like participant form

## Быстрый контракт

Если нужно принять быстрое решение без чтения всего guide:

- controls: `rounded-lg`
- secondary cards: `rounded-xl`
- primary panels и modal shells: `rounded-2xl`
- pills, avatar, search capsules: `rounded-full`
- `rounded-md` и `rounded-[...]`: legacy или редкое исключение с отдельным обоснованием
- dropdown UX с поиском, multi-select или chip-представлением должен идти через shared select-паттерн, а не через локальный ad-hoc `select`

## Навигация по рефакторингу

С этого раздела должен начинаться будущий глобальный refactor pass:

1. нормализация карточек
2. сокращение custom radii
3. выравнивание shared affordance
4. только потом индивидуальный разбор форм по паттернам

## Что уже покрыто

Этот раздел теперь выполняет две функции:

- нормативная база по visual contract
- прикладной handbook для ежедневной разработки и review

Если вопрос про то, "как должно быть", смотреть документы `01-05`.
Если вопрос про то, "как это делать в коде", смотреть документы `06-08`.