Corp/docs/guides/frontend/README.md

Frontend UI Guide

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

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

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

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

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