# Frontend Guide: Overview

## Назначение

Этот guide определяет правила, по которым должны строиться новые frontend-экраны, shared-компоненты и рефакторинг существующего UI.

При конфликте между текущим состоянием кода и этим guide приоритет у guide. Если часть системы ещё не приведена к target state, это legacy-состояние, а не альтернативная норма.

## Границы

Guide покрывает:

- визуальную систему frontend
- layout-принципы
- shared UI primitives
- геометрию
- card и form patterns
- modal и dropdown contracts

Guide не покрывает:

- API-дизайн
- state management конкретной фичи
- domain-логику
- отдельные feature-спеки

## Карта frontend-проекта

### `frontend/src/app`

Роль:

- маршруты Next.js App Router
- page-level composition
- orchestration экранов

Правила:

- страницы собирают UI из shared и feature-компонентов
- страницы не должны становиться вторым слоем дизайн-системы
- повторяемый паттерн должен подниматься в `components`
- если в странице уже живут toolbar/filters, expandable rows, detail modal и preview modal, это сигнал к разрезанию на feature-компоненты

### `frontend/src/components`

Роль:

- shared UI primitives
- reusable feature-компоненты
- списки, панели, dropdowns, modals, detail blocks

Правила:

- всё, что задаёт повторяемую визуальную механику, должно жить здесь
- shared-компонент должен использовать проектный visual contract, а не изобретать новый
- если похожий primitive уже есть, его нужно расширять, а не создавать параллельный

### `frontend/src/hooks`

Роль:

- orchestration логики
- загрузка данных
- derived state

Правила:

- hook не кодирует дизайн-систему
- hook может возвращать данные для UI, но не должен становиться хранилищем визуальных классов
- page-specific orchestration вроде router-sync, deep-link открытия detail modal и menu dismiss logic допустимо выносить в feature hook, если page-level файл начинает разрастаться
- derived actions уровня feature, например `clearFilters` или готовая выборка `pendingDecisionRequests`, лучше держать рядом с feature hook, а не собирать заново в page-level JSX

### `frontend/src/lib`

Роль:

- API clients
- adapters
- shared helpers

Правила:

- этот слой не должен зависеть от page-level UI
- UI-специфичные преобразования нужно держать ближе к feature-компоненту

### `frontend/src/types`

Роль:

- типы API
- shared domain contracts

Правила:

- типы описывают данные, а не визуальное оформление
- UI-значимые семантические флаги должны приходить как явные поля, а не вычисляться по role-based эвристикам в нескольких местах

## Текущее состояние системы

Система уже имеет foundation layer, но он не доведён до конца.

Сильные стороны:

- единая палитра
- surface hierarchy
- `app-*` action и state primitives
- общая идея shared shell

Основные проблемы:

- разные радиусы у однотипных элементов
- дрейф карточек по визуальному весу
- разный dropdown affordance у похожих полей
- локальные ad-hoc решения в feature-страницах
- расхождение по типу экранов: часть страниц живёт как рабочие модули системы, часть как showcase/profile/dashboard из другого продукта

Следствие:

- карточки и геометрию можно и нужно нормализовать системно
- формы нужно оценивать уже после этого, индивидуально по UX-паттернам

## Экранные жанры

Перед рефакторингом нужно определить не только набор компонентов, но и жанр экрана.

Базовые типы в этом проекте:

- operational workspace: плотные рабочие страницы со status/actions/list/detail flow
- profile-like page: hero + секции + персональные или справочные блоки
- dashboard/feed: обзорные экраны с несколькими контентными зонами
- auth/legal flow: изолированные страницы вне основного app-shell сценария

Правило:

- рефакторинг должен приводить все жанры к одной продуктовой системе
- но не должен насильно превращать один жанр в другой
- удачный operational screen нельзя без причины перепридумывать как showcase-layout
- удачный profile-screen нельзя механически уплотнять до вида request list только ради единообразия