Правила Frontend Design System

Назначение

Документ задаёт стандарты дизайн-системы frontend-приложений Pin на стеке HeroUI v3.0.5 + Tailwind CSS 4.3. Применяется ко всем SPA, включая pin-admin. Цель — единообразный визуальный язык, переиспользуемые токены, корректная инициализация тем и стилей, поддержка светлой/тёмной тем и адаптивности.

Базовый стек

Слой	Технология	Версия	Назначение
Component library	HeroUI	3.0.5	Базовые UI-примитивы (Button, Input, Modal, Table, Tabs, Tooltip и т.д.)
CSS framework	Tailwind CSS	4.3	Utility-классы для layout и композиции
Theme provider	HeroUI <HeroUIProvider>	—	Корневой провайдер темы, dark/light режим
Tailwind preset	HeroUI Tailwind plugin	—	Интеграция HeroUI токенов в Tailwind config
CSS variables	Native CSS Custom Properties	—	Финальные значения токенов
Иконки	Lucide / iconify-react	актуальная	Векторные иконки, tree-shake friendly
Шрифты	Inter (UI), JetBrains Mono (code)	—	Системный fallback допустим

Установка и инициализация

Подключение HeroUI и Tailwind preset

src/app/main.tsx
  import { HeroUIProvider } from "@heroui/react";
  import { ThemeProvider } from "./theme/ThemeProvider";
  // ...
  <HeroUIProvider locale="ru-RU">
    <ThemeProvider>
      <RouterProvider router={router} />
    </ThemeProvider>
  </HeroUIProvider>

src/shared/theme/tailwind-preset.ts
  import { heroui } from "@heroui/react";
  export const heroPreset = heroui({
    themes: {
      light: { ... },
      dark: { ... },
    },
  });

tailwind.config.ts
  import { heroPreset } from "@/shared/theme/tailwind-preset";
  export default {
    content: ["./src/**/*.{ts,tsx,html}", "./node_modules/@heroui/react/dist/**/*.{ts,tsx,js,jsx}"],
    presets: [heroPreset],
    darkMode: "class",
  };

Контентом сканирования обязательно покрывается node_modules/@heroui/react/dist/** — иначе production-build сбрасывает классы HeroUI.

Подключение глобальных стилей

src/app/index.css
  @import "tailwindcss";
  @plugin "@heroui/react/tailwind";

  @layer base {
    :root { color-scheme: light; }
    .dark { color-scheme: dark; }
    html, body, #root { @apply h-full bg-background text-foreground; }
    body { @apply antialiased font-sans; }
  }

@plugin директива Tailwind 4.3 заменяет старую регистрацию через preset; компоненты HeroUI автоматически получают свою тему.

Дизайн-токены

Все токены хранятся в src/shared/theme/tokens/:

shared/theme/tokens/
  colors.ts        // primary, secondary, success, warning, danger, neutral, AlertLevel (Green/Yellow/Red/Black)
  typography.ts    // text-xs..text-3xl, headings, leading, tracking
  spacing.ts       // 0/0.5/1/1.5/2/3/4/6/8/12/16/24/32/48
  radius.ts        // none/sm/md/lg/xl/full
  shadows.ts       // sm/md/lg/xl, inset
  elevations.ts    // z-index уровни: base/dropdown/sticky/overlay/modal/toast/tooltip
  motion.ts        // duration-fast/normal/slow, ease-out, ease-in

Все токены экспортируются как TypeScript константы и одновременно записываются в Tailwind preset через HeroUI themes секцию. UI-компоненты используют только токенные значения, не сырые hex/px.

Темы и ThemeProvider

Целевые темы

• light — основной режим для рабочих часов.
• dark — для длительной работы в вечернее/ночное время.
• system — следует системной настройке (default).

Контракт ThemeProvider

src/shared/theme/ThemeProvider.tsx
  - читает theme из useThemeStore (Zustand persisted)
  - синхронизирует с document.documentElement (className "dark" | "light")
  - слушает window.matchMedia("(prefers-color-scheme: dark)") если theme === "system"
  - предоставляет хук useTheme() с { theme, setTheme }

Правила

• Все цвета компонентов задаются семантическими токенами (background, foreground, primary, default, success, warning, danger), а не сырыми hex.
• Тёмная тема обязательна для всех экранов и виджетов; контрастность WCAG AA минимум.
• Анимация переключения темы 150ms ease-out через CSS-переменные.

Сетка и breakpoints

Breakpoint	Ширина	Назначение
xs	< 480px	Мобильный портрет, основной адаптив сворачивает таблицы в карточки
sm	≥ 480px	Мобильный landscape
md	≥ 768px	Планшет
lg	≥ 900px	Целевой минимум для рабочих экранов
xl	≥ 1280px	Стандартный ноутбук
2xl	≥ 1440px	Стандартный десктоп
3xl	≥ 1920px	Широкоэкранный

Целевой диапазон для разработки каталогов: 900–1400px. При этом сервис обязан работать корректно от 320px до 2560px.

Подробнее в ui-responsive-design-rules.md.

Композиция компонентов

Слой	Использование
HeroUI компонент	Базовый примитив (Button, Input, Modal, Autocomplete, …). Используется напрямую из @heroui/react; не патчится глобально через :where; кастомизация через className/classNames.
Molecule	Композиция примитивов + логика отображения (FormField, ConfirmDialog, async-селекты). Тонкие atom-обёртки над HeroUI не создаём («ui kit в нашем ui kit»).
Organism	Композиция molecules + хуки данных, но без бизнес-flow (тот живёт в widgets/features).

Цвета по бизнес-смыслу

Семантика	Светлая	Тёмная	Использование
primary	brand color	brand color	CTA, активные элементы, ссылки
success	green	green	Подтверждения, validated/published статусы, AlertLevel Green
warning	amber	amber	Подсказки, validation warnings, AlertLevel Yellow
danger	red	red	Деструктивные действия, validation errors, AlertLevel Red
critical	dark red / black	dark red	AlertLevel Black, критические события
default	neutral	neutral	Нейтральные badge, secondary buttons
background	white	dark gray	Основной фон
foreground	dark text	light text	Основной текст
divider	light gray	dark gray	Разделители

Использование Tailwind 4.3

• Использовать новый @theme блок для конфигурации тем напрямую в CSS.
• Использовать новый @plugin для HeroUI интеграции.
• Не использовать deprecated @apply в production-критичных компонентах (только в lego-обёртках).
• Tailwind directives @layer base/components/utilities сохраняют силу.
• Container queries (@container) разрешены для адаптивных карточек.
• Logical properties (ms-, me-, ps-, pe-) обязательны для будущей RTL-поддержки.

Запрещено

• Произвольные hex-цвета в JSX (bg-[#abcdef]) — только токены.
• Произвольные размеры (w-[173px]) — только токены или контентные размеры.
• Inline стили (style={{ color: ... }}) кроме случаев анимаций.
• Глобальные :root переопределения CSS-переменных HeroUI вне theme preset.
• Подключение нескольких UI-библиотек одновременно (Mantine, MUI, Chakra) — только HeroUI.

Версионирование

• HeroUI закреплён на минорной версии (^3.0.5). Major-обновление — через ADR.
• Tailwind CSS закреплён на минорной версии (^4.3.0). Major-обновление — через ADR.
• Lock-файл pnpm-lock.yaml коммитится.

Дополнительные ресурсы

• Полная документация HeroUI — .claude/docs/heroui/llms-full.txt (LLM-формат, разделы <page url="…">). Основной справочник по компонентам, props, slots, accessibility и паттернам; используйте при добавлении/изменении UI.

Обратные ссылки

Автоссылки: где используется этот документ.

• frontend-card-and-accordion-styling-rules.md (1): Правила цветов вложенных карточек и аккордеонов (frontend)
• frontend-form-field-behavior-rules.md (1): Правила Поведения Полей В Формах-Редакторах
• frontend-fsd-and-atomic-rules.md (1): Правила Frontend FSD И Atomic Design
• frontend-state-management-rules.md (1): Правила Frontend State Management
• ui-accessibility-rules.md (1): Правила UI Accessibility (A11Y)
• ui-responsive-design-rules.md (1): Правила UI Responsive Design

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

• frontend-rules.md — общие правила frontend.
• frontend-state-management-rules.md — Zustand, TanStack Query.
• frontend-fsd-and-atomic-rules.md — слои FSD и Atomic.
• ui-responsive-design-rules.md — breakpoints и адаптивность.
• ui-accessibility-rules.md — A11Y.
• frontend-form-field-behavior-rules.md — поведение, отображение и состояния полей в формах-редакторах.
• docs/04-frontends/pin-admin/01-design-system/ — токены и темы конкретного приложения.