Перейти к основному содержимому

Правила цветов вложенных карточек и аккордеонов (frontend)

Документ фиксирует, какими токенами задаётся фон карточек/аккордеонов в админке pin-admin. Цель — визуальная иерархия конструкторов (схемы полей, варианты выбора, ограничения, права): поверхности чередуются по глубине вложенности (белая → серая → белая → …), чтобы вложенный блок всегда отделялся от родителя и не бывало ни белого-на-белом, ни серого-на-сером на любой вложенности.

Действует вместе с frontend-design-system-rules.md (только токены, произвольные hex в JSX запрещены).

Токены​

ТокенНазначениеЗначение (адаптивно к теме)
surface (bg-surface)Белая поверхность (верхний и нечётные уровни вложенности).Белый в светлой теме (токен HeroUI).
surface-nested (bg-surface-nested)«Сероватая» поверхность (чётные уровни вложенности).--bj-neutral-100 (на ступень «серее» родителя; в тёмной теме — на ступень светлее).

Токен --color-surface-nested объявлен в src/styles/globals.css (секция @theme inline).

Правило вложенности​

Поверхностью считается bj-card или HeroUI <Card> (рендерит data-slot="card"). Фон чередуется по глубине вложенности поверхностей: верхний уровень — белый (surface), каждая следующая вложенность — противоположная поверхность (surface-nested серый → снова surface белый → …). Глубина считается по числу предков-поверхностей; промежуточные обёртки без класса поверхности не учитываются.

Реализовано в @layer components (src/styles/globals.css) цепочками :is(...) с растущей специфичностью — более глубокая цепочка перекрывает менее глубокую:

.bj-card { background-color: var(--color-surface); }              /* верхний уровень — белый */

/* вложенность 2 — серая, 3 — белая, 4 — серая, 5 — белая, 6 — серая (цепочки :is с ростом специфичности) */
:is(.bj-card, [data-slot="card"]) :is(.bj-card, [data-slot="card"]) {
  background-color: var(--color-surface-nested);
}
:is(.bj-card, [data-slot="card"]) :is(.bj-card, [data-slot="card"]) :is(.bj-card, [data-slot="card"]) {
  background-color: var(--color-surface);
}
/* … аналогично для уровней 4, 5, 6 */

HeroUI <Card> участвует автоматически. Собственные панели и секции-аккордеоны (CollapsibleSection) подключают правило классом bj-card — цвет по вложенности определится сам. Слой components идёт до слоя utilities, поэтому карточку можно принудительно оставить белой явной утилитой bg-surface.

Как применять​

  • Не задавайте фон карточек/панелей руками (bg-surface/bg-white) — вешайте класс bj-card (или используйте HeroUI <Card>), и цвет по глубине вложенности определится сам (белый → серый → белый → …).
  • Новые составные редакторы стройте на DocumentArrayEditor/CollapsibleSection — они уже дают bj-card.
  • Для явного переопределения используйте токены surface/surface-nested (утилита перекроет @layer components) — только для осознанных исключений ниже.

Вне правила (осознанные исключения)​

Эти паттерны не подчиняются иерархии parent-white/child-grey и не трогаются:

  • Алерты/баннеры статуса (bg-danger-50, bg-warning-50, bg-success-50) — семантическая заливка, не структурная карточка.
  • Шапки таблиц (thead c bg-default-100/60) и табличные обёртки предпросмотра/сводных видов — собственный табличный паттерн (серая шапка / белые строки).
  • Виджеты-виды данных (Kanban, Pivot, Calendar, ResourceGauge) — своя визуальная логика (напр. серая колонка канбана с белыми карточками); не выравниваются под конвенцию.
  • Навигационный аккордеон в левом меню (AppLayout) — не контентный аккордеон, показывает фон сайдбар-карточки; фон не задаётся.
  • Модалки/диалоги/поповеры (Modal/Drawer/Popover) — отдельные поверхности HeroUI, не data-slot="card"; остаются своим фоном.

Пример иерархии​

FormSection (HeroUI Card, уровень 1)             → белый
└─ DocumentArrayEditor «Поля»
   └─ .bj-card «Поле 3» (уровень 2)               → сероватый
      ├─ DocumentArrayEditor «Варианты выбора»
      │  └─ .bj-card «Вариант 1» (уровень 3)      → белый
      └─ CollapsibleSection «Валидация» (уровень 3, bj-card) → белый
         └─ .bj-accordion-body
            └─ .bj-card … (уровень 4)             → сероватый

Связанные документы​