# UI Style Guide Wave 5

Статус: `approved`

## Назначение
Этот документ фиксирует общий визуальный и композиционный каркас для всех утверждённых макетов wave 5. Он нужен не как брендбук ради брендбука, а как рабочий источник истины для:
- перегенерации и расширения макетов без визуального дрейфа;
- последующей реализации frontend-экранов;
- проверки, что новые экраны выглядят как части одной системы, а не как набор разрозненных интерфейсов.

Документ опирается на утверждённые экраны `01-16` и их `screen.md`.

## Область действия
Стандарт распространяется на:
- полноэкранные основные макеты;
- вырезки активных вкладок `tab-*`;
- экранные блоки staff console, связанные с Mission Control, каталогами, доступами, инфраструктурой, биллингом и релизной автоматизацией.

Документ не фиксирует:
- пиксельно-точные значения для production frontend;
- финальный `UI kit` в коде;
- бренд-активы и маркетинговую графику.

## Базовые принципы
- Один экран решает одну операторскую задачу и не смешивает стратегический, операционный и диагностический шум.
- Смысл важнее декоративности: каждый блок должен отвечать на вопрос, откуда возьмутся его данные и какое действие из него совершается.
- Визуальная иерархия строится от важного к подробному: сводка -> рабочая область -> детализация -> аудит.
- Плавающие и фиксированные элементы не должны закрывать полезный контент.
- Если для сущности уже есть канонический список или таблица, рядом допускается только один инспектор выбранной записи, а не дублирующая панель.
- Английские термины остаются только там, где это устойчивые технические понятия: `Issue`, `PR/MR`, `run`, `job`, slot, Human gate, Risk gate, flow, stage.

## Экранный каркас

### Общий каркас
Для всех полноэкранных макетов используется единый экранный каркас:
- левая вертикальная навигация staff console;
- верхняя глобальная панель проекта, поиска и пользовательского контекста;
- основная рабочая поверхность справа;
- мягкий светлый фон без тяжёлых декоративных подложек.

### Композиция рабочей поверхности
Рабочая поверхность строится по схеме:
1. заголовок экрана и краткое пояснение;
2. верхняя полоса вкладок/фильтров/контекстного выбора;
3. сводный блок или stage/header-блок;
4. основной контент экрана;
5. инспектор или вторичная колонка только там, где она действительно нужна.

### Плотность
- Экран должен выглядеть наполненным, но не перегруженным.
- Пустые поля допустимы только если они нужны для читаемости потока, канваса или инспектора.
- Если справа остаётся пустая вертикальная зона без самостоятельной функции, блоки нужно перераспределять, а не оставлять воздух ради воздуха.

## Цветовая семантика

### Базовая палитра
- Основа интерфейса: светлый нейтральный фон.
- Поверхности: белые или очень светлые карточки с мягкой границей.
- Акцент платформы: тёплый оранжевый для главных действий и критически важного внимания.
- Холодные голубые и серо-синие тона: рабочие статусы, справочные панели, фоновые акценты.

### Семантика статусов
- Зелёный: `Готово`, `Активен`, здоровое состояние.
- Голубой/синий: нейтральное рабочее состояние, связь, навигационное действие, связанный артефакт.
- Оранжевый: нужен фокус, ожидает решения, ручное действие, gate, rollout, предупреждение среднего уровня.
- Красный/розовый: ошибка, блокер, деградация, ошибка авторизации, incident.
- Серый: вторичный текст, отключённое состояние, техническая справка, неактивная вкладка.

Статусный цвет никогда не используется без текстового пояснения.

## Типографика и терминология
- Заголовки экранов и разделов пишутся на локали, выбранной пользователем, если термин можно выразить на ней без потери смысла.
- Термины модели процесса и технические идентификаторы сохраняются на английском там, где это источник точности.
- Внутри одного блока нельзя без причины смешивать язык выбранной пользователем локали и английский.
- Подписи статусов, вкладок и действий должны быть короткими и однозначными.
- В одном экране для одной сущности используется одно устойчивое название. Нельзя в одном месте писать `approval`, а в соседнем `согласование`, если это один и тот же объект.

## Паттерны компонентов

### Сводные карточки
Сводные карточки используются в верхней части экранов для быстрого среза состояния:
- всегда содержат число или чёткий статус;
- показывают только данные, по которым можно перейти к деталям;
- не дублируют содержимое главной таблицы, а задают операторский фокус.

### Список или таблица + инспектор
Главный операционный паттерн для каталогов и системных разделов:
- слева или в центре расположен список/таблица;
- справа расположен один инспектор выбранной записи;
- инспектор показывает детали, риски, быстрые действия и краткую историю;
- если экран уже построен как мастер-деталь, второй дополнительный детальный блок не добавляется.

### Вкладки
- Вкладки применяются только для самостоятельных плоскостей данных одной сущности.
- Активная вкладка должна менять основной контент, а не только маленький блок внутри.
- Для пакета макетов хранится:
  - один полноэкранный основной макет;
  - отдельные `tab-*` изображения как вырезки прямоугольника активной вкладки и её содержимого.
- `tab-*` не должны показывать изменившееся окружение всего экрана; они фиксируют только содержимое вкладочной поверхности.

### Карточки потока и stage-блоки
- Stage-блок показывает этап, цель этапа, ожидаемый артефакт и текущее состояние.
- Follow-up логика показывается в переходе или gate-контексте, но не дублируется одновременно как отдельный артефакт этапа и как правило перехода без необходимости.
- Связи между этапами должны быть аккуратными и читаемыми; свободное хаотичное расположение узлов не используется как источник истины.

### Чат и поле ввода
Для экранов командного центра и рабочих пространств используется единый паттерн диалога:
- сообщения пользователя выровнены вправо;
- сообщения системы, агента, reviewer и других ролей идут слева;
- у сообщений есть лёгкая форма облачка или явно читаемая карточка;
- активный контент в сообщении оформляется badge-кнопками, а не сырыми ссылками в тексте;
- badge для внешнего перехода имеет иконку выхода во внешнюю систему;
- badge для запуска действия имеет иконку запуска;
- поле ввода всегда встроено в нижнюю часть диалога;
- кнопка микрофона находится внутри поля ввода слева от кнопки отправки;
- кнопка отправки круглая и находится внутри правой части поля ввода.

### Badge и chip
- Badge используются для статусов, типов сущностей и быстрых переходов.
- Chip используются для компактных фильтров и атрибутов.
- Badge не должны «висеть в воздухе»: если это `APPROVED`, `Нужно решение` или `Ожидает`, должно быть ясно, к какому сообщению, артефакту или gate они относятся.

### Панели действий
- Контрастные основные действия применяются только для реально приоритетного следующего шага.
- Если действие относится к конкретному `PR/MR`, `Issue`, slot или `run`, кнопка должна быть внутри карточки этой сущности или рядом с ней.
- На уровне экрана не должно быть лишних универсальных кнопок, которые дублируют действие из контента.

## Правила данных и антишум
- Каждый блок должен опираться на реальный источник данных: платформа, provider, Kubernetes, проекция аудита или производная сводка.
- Нельзя вводить поля только потому, что они визуально украшают экран.
- Если данные уже есть в GitHub/GitLab сущности, экран должен использовать их, а не изобретать параллельную сущность без причины.
- Артефакты не должны изображать фиктивные типы файлов, если в реальности основной артефакт этапа — это `Issue` или `PR/MR`.
- Диагностика и глубокий runtime-шум выносятся на профильные экраны, а не растаскиваются по всему интерфейсу.

## Канвас и редакторы
- Канвас используется там, где нужен обзор потока, размещения или структуры.
- Все элементы управления канвасом должны быть либо встроены в верхнюю панель, либо оформлены как аккуратные плавающие блоки, не перекрывающие ноды.
- Ноды нельзя размещать хаотично; расположение должно поддерживать читаемый сценарий слева направо или сверху вниз.
- Связи не должны обрываться и не должны проходить через текст ключевых карточек.
- Если канвас не даёт ценности по сравнению с последовательным редактором, предпочтителен последовательный редактор.

## Полноэкранные макеты и вырезки вкладок
- Полноэкранный макет показывает весь экранный каркас и общий контекст раздела.
- Вырезка вкладки показывает только прямоугольник активной вкладки с её содержимым.
- Вырезки нужны для фиксации структуры вкладок без генерации отдельного «почти такого же» целого экрана.
- Окружение вокруг вырезки не меняется и не переосмысляется; меняется только контент вкладочной поверхности.

## Применение к группам экранов

### Операционные экраны
Сюда относятся `01`, `02`, `05`, `06`, `07`.
Для них обязательны:
- ясный следующий шаг;
- связка диалога и действий;
- быстрые переходы к `Issue`, `PR/MR`, `run`, `job`, slot;
- отсутствие дублирующих глобальных кнопок.

### Каталоги и настройки
Сюда относятся `04`, `08`, `09`, `10`, `12`, `13`, `14`, `15`, `16`.
Для них обязательны:
- сводные карточки сверху;
- список/таблица + инспектор;
- вкладки как разделение самостоятельных аспектов одной модели;
- короткие операционные быстрые действия в инспекторе.

### Редакторы процесса
Сюда относятся `03` и части `16`.
Для них обязательны:
- читаемая причинно-следственная структура;
- явная модель stage, role binding, gate и follow-up;
- отсутствие декоративного хаоса в расположении нод;
- возможность понять публикацию и версионирование без чтения исходных файлов.

## Карта соответствия
Этот стайл-гайд подтверждён на основе:
- [01-command-center](01-command-center/screen.md)
- [02-issue-workspace](02-issue-workspace/screen.md)
- [03-flow-editor](03-flow-editor/screen.md)
- [04-role-catalog](04-role-catalog/screen.md)
- [05-pr-workspace](05-pr-workspace/screen.md)
- [06-inbox-and-approvals](06-inbox-and-approvals/screen.md)
- [07-executions-jobs-slots](07-executions-jobs-slots/screen.md)
- [08-projects-and-repositories](08-projects-and-repositories/screen.md)
- [09-integrations-and-accounts](09-integrations-and-accounts/screen.md)
- [10-users-and-access](10-users-and-access/screen.md)
- [11-onboarding-and-empty-states](11-onboarding-and-empty-states/screen.md)
- [12-package-catalog](12-package-catalog/screen.md)
- [13-organizations-and-groups](13-organizations-and-groups/screen.md)
- [14-fleet-servers-clusters](14-fleet-servers-clusters/screen.md)
- [15-billing-and-costs](15-billing-and-costs/screen.md)
- [16-release-policy-automation](16-release-policy-automation/screen.md)

## Открытые вопросы
- Когда перейдём к frontend-реализации, потребуется отдельный `UI kit` production-уровня: tokens, states, spacing scale, icon set и правила адаптива. Для wave 5 это не блокер, но это следующий естественный слой формализации.
