Corp/docs/frontend-style-guide.md

Frontend Style Guide

Короткий проектный контракт для новых экранов и рефакторинга старых.

Базовые поверхности

• Внешний самостоятельный блок страницы: app-surface
• Внутренний блок внутри секции: app-surface-muted
• Не делать card inside card inside card, если можно обойтись одним внешним и одним внутренним уровнем.

Подписи секций

• Верхние подписи карточек и секций: app-card-caption
• Внутренние заголовки внутри блоков:
  • text-sm font-semibold text-[var(--foreground)]
• Не смешивать app-card-caption и обычный заголовок в одном уровне вложенности.

Кнопки

• Primary action:
  • app-action-primary
• Secondary action:
  • app-action-secondary
• Danger action:
  • secondary-style кнопка с red hover/focus, а не тяжелый красный прямоугольник по умолчанию
• Все add/create CTA должны выглядеть одинаково:
  • иконка Plus
  • app-action-primary
  • rounded-xl
  • одинаковая высота и плотность

Pills и бейджи

• Нейтральный chip/filter: app-pill
• Активный/select/primary state: app-pill-active или app-selected
• Статусы должны быть семантическими:
  • success: app-feedback-success
  • warning: app-feedback-warning
  • danger: app-feedback-danger
• Не использовать случайный синий только потому, что нужен акцент.

Формы

• Текстовые поля: app-input
• Select: app-select
• Поисковая строка в шапке: pill-форма
• Обычные form fields: скругленные углы, не pill
• Не смешивать разные hover/focus-паттерны на одном экране

Профильные и read-only страницы

• /profile и /users/[id]:
  • hero сверху
  • отдельные широкие секции ниже
  • не дублировать settings-редактирование карандашами в нескольких местах
• Read-only экран:
  • минимум inline editing
  • одно явное действие лучше, чем несколько карандашей по карточкам

Таймлайны

• Линия события цветная по типу события
• Точка только на текущем событии
• Текущее событие определяется по дате, а не по первой записи в списке

Контакты

• Контактные блоки строятся как список строк внутри app-surface-muted
• Не делать отдельную маленькую карточку на каждый контакт
• Иконки контактов нейтральны, если нет реальной причины для акцента

Чего избегать

• bg-white, bg-gray-*, ring-gray-*, focus:ring-sky-* в новых и перерабатываемых экранах
• Разных стилей add/save/delete между соседними страницами
• Декоративных badge без логики состояния
• Смешения old-gray-contract и app-* токенов в одном блоке