UI Design Guidelines — MANDATORY

Обязательное требование для всех новых или измененных элементов UI в этом приложении (страницы Blazor, диалоги, компоненты). Это источник истины, на который ссылается CLAUDE.md. Если правило вас блокирует, остановитесь и спросите — не отправляйте UI, который его нарушает. Основано на plans/ui-overhaul.md.

1. Mobile-first, always

• Создавайте для телефона 360–430px в первую очередь, затем расширяйте для большего размера с помощью min-width медиа-запросов / свойств точек разрыва MudBlazor. Никогда не начинайте с рабочего стола с переопределениями max-width.
• Нет горизонтального скроллирования при любой ширине 320–1920px. Если содержимое шире области просмотра, это ошибка.
• Цели касания ≥ 44px (var(--app-touch-target)). Текстовые поля ввода ≥ 16px шрифт (предотвращает масштабирование iOS при фокусе).
• Учитывайте вырезы: используйте env(safe-area-inset-*); область просмотра уже устанавливает viewport-fit=cover.
• Соблюдайте prefers-reduced-motion — никакая важная информация не должна передаваться только анимацией.

2. Design tokens — no hard-coded values

• Все цвета/радиусы/интервалы берутся из дизайн-токенов: тема MudBlazor (Web/Components/Theme.cs) + CSS пользовательские свойства, выдаваемые Web/Branding/BrandingCss.cs (var(--app-primary), --app-surface, --app-border, --app-text*, --app-radius, …).
• Никогда не кодируйте цвет в формате hex, радиус или строку бренда в компоненте или CSS-правиле. Используйте токен. Токены поступают из белолейбл BrandingOptions, поэтому палитра продавца должна беспрепятственно попасть в ваш UI.
• Новое значение, влияющее на бренд → добавьте токен + поле брендинга; не встраивайте его.

3. Responsive layout & data

• Таблицы сворачиваются в карточки на телефонах. Каждый MudTable устанавливает Breakpoint="Breakpoint.Sm" и каждый MudTd имеет DataLabel. Нет сырой широкой таблицы на мобильном. (Шаблон: Components/Pages/Nodes.razor.)
• Сетки: MudItem xs="12" sm="6" md="4" — во всю ширину на телефоне, несколько столбцов на больших экранах.
• Формы одного столбца на мобильных; большие цели касания; inputmode/autocomplete на входах; числовой/десятичный inputmode для денег/процентов.
• Правильные элементы управления для структурированного ввода — никогда не используйте сырое текстовое поле для чисел или списков. Собирайте числа, деньги, проценты, даты, перечисления и любые многозначные данные с правильным элементом управления (MudNumericField, MudDatePicker, MudSelect, редактируемый список добавления/удаления строк типизированных полей или таблица), каждое поле индивидуально проверено. Единое свободное текстовое поле MudTextField, в которое пользователь должен ввести запятую/пробел/новую строку разделённый блоб — который вы затем разбираете — запрещено: это подвержено ошибкам, непроверенно и враждебно на телефоне. Никто не хочет вводить блоб. Ввод с несколькими значениями — это редактируемый список типизированных строк (добавить / удалить), или загружается из существующих данных домена (например, запустите проверку прямо с завершенного обратного теста вместо повторного ввода его чисел). Простой MudTextField только для подлинного свободного текста — имена, примечания, поиск, описания.
• Предоставьте загрузку, пустое и ошибочное состояния на каждом списке/деталях — подходящие для мобильного.
• Мобильная нижняя навигация (Components/Layout/BottomNav.razor) является основной навигацией телефона; ящик с группировкой — это полное меню. Добавьте туда высокопроизводительные пункты назначения; держите это ≤5 элементов.

4. Dialogs (create/edit)

• Все действия добавления/создания/редактирования/новых используют диалог MudBlazor (IDialogService.ShowAsync<TDialog>), никогда встроенную форму страницы. Диалоги находятся в Web/Components/Dialogs/, предоставляют [Parameter]s, возвращают вложенную public sealed record …Result(...). Действия строк списка (начало/остановка/удаление) остаются встроенными как кнопки значков.
• На телефонах диалоги должны быть полноэкранными / полной ширины и с учетом клавиатуры.

5. Inline help — every control

• Каждый неочевидный параметр, выбор, переключатель или действие получает <HelpTip Text="…" /> (Components/HelpTip.razor) — наведение на рабочий стол, касание на мобильном. Получите текст из docs/, чтобы руководство оставалось синхронизированным с поведением; обновите оба в одном коммите.

6. White-label

• Имя продукта, логотип, описание, поддержка/компания, цвета, favicon — все берутся из BrandingOptions. Ссылайтесь на них (IBrandingThemeProvider / IOptionsMonitor<AppOptions>), никогда не используйте буквальное "cMind" или цвет бренда. Манифест PWA, значки, цвет темы и герой входа — все с брендингом.

7. PWA

• Приложение установочное. Держите конечную точку манифеста (/manifest.webmanifest) с брендингом, значки присутствуют (192/512/маскируемое + apple-touch), сервис-воркер только app-shell (никогда не касаясь схемы Blazor/_framework/hubs), и офлайн страница работает. Новый статический маршрут → сохраняйте scope манифеста.
• Blazor Server требует живую схему SignalR → устанавливаемое + app-shell, а не полный офлайн. Не обещайте офлайн интерактивность.

8. Accessibility

• Метки на входах, aria-* на пользовательских элементах управления, видимый фокус, логический порядок фокусировки. Так как тема белолейбл, проверьте контраст против активной темы, а не фиксированной палитры.

9. E2E — no UI ships untested (blocking)

Каждое изменение, ориентированное на пользователя, отправляется Playwright E2E в tests/E2ETests, управляется как реальный пользователь, на эмуляции мобильного устройства плюс рабочий стол:

• Новый маршрут → добавьте его в PageSmokeTests и MobileLayoutTests (отображается, нижняя навигация, нет ошибок в пользовательском интерфейсе).
• Преобразуйте таблицу/страницу → добавьте ее маршрут в мобильный без переполнения набор.
• Новый поток → реалистичное мобильное путешествие (создание/редактирование/сохранение в оба конца) и нежелательный путь (неправильный ввод, пустой список, доступ запрещен по роли).
• Новый совет → подтвердите, что он открывается при касании (HelpTipTests паттерн).
• Используйте AppFixture.NewAuthedMobilePageAsync / NewAnonymousMobilePageAsync (эмуляция устройства).
• dotnet test зелено перед "готово". Эмулированный WebKit ≠ мобильный Safari — шлюз реального устройства — это отдельный этап выпуска.

10. Definition of done (UI)

• Mobile-first; нет горизонтального переполнения 320–1920px; цели касания ≥44px.
• Только дизайн-токены — ноль жестко закодированных цветов/радиусов/строк брендов.
• Таблицы → карточки на телефоне (DataLabel + Breakpoint.Sm); состояния загрузки/пусто/ошибка присутствуют.
• Структурированный ввод использует правильные проверенные элементы управления (числовой/дата/выбор/редактируемая строка списка) — нет сырого текстового поля, в которое пользователь вводит разделённый число/значение блоб.
• Создание/редактирование через диалог; полноэкранно на мобильном.
• Каждый элемент управления имеет HelpTip, полученный из документов.
• White-label + PWA соблюдаются.
• Добавлены E2E мобильного + рабочего стола (дым, без переполнения, путешествие, нежелательный путь); dotnet test зелено.
• Rider get_file_problems + dotnet format analyzers чисто на измененных файлах.