sfera/visual-design-rules.md

# ОБЩИЕ ПРАВИЛА ВИЗУАЛЬНОГО ДИЗАЙНА SFERA

> 📋 **Базовые принципы дизайна системы управления складами и поставками**

---

## 🎨 **1. ЦВЕТОВАЯ СИСТЕМА**

### 1.1 Основная палитра

**PRIMARY COLORS (OKLCH)**:

- **Primary**: `oklch(0.65 0.28 315)` - основной фиолетовый
- **Primary Foreground**: `oklch(0.985 0 0)` - белый текст
- **Secondary**: `oklch(0.94 0.08 315)` - светло-фиолетовый
- **Background**: `oklch(0.98 0.02 320)` - светлый фон

**GLASS SYSTEM**:

- **Base**: `bg-white/10 backdrop-blur border-white/20`
- **Cards**: `bg-white/5 backdrop-blur border-white/10`
- **Buttons**: `glass-button` / `glass-secondary`

### 1.2 Функциональные цвета

**STATUS COLORS**:

- 🟢 **Success**: `green-400/500` - завершенные операции
- 🔴 **Error**: `red-400/500` - ошибки и критичные состояния
- 🟡 **Warning**: `yellow-400/500` - предупреждения
- 🔵 **Info**: `blue-400/500` - информационные сообщения
- 🟣 **Processing**: `purple-400/500` - процессы в работе

**CABINET COLORS**:

- **Селлер**: `blue-400` - синий
- **Фулфилмент**: `purple-400` - фиолетовый
- **Поставщик**: `green-400` - зеленый
- **Логистика**: `orange-400` - оранжевый

### 1.3 Иерархическая цветовая схема

**УРОВНИ ДЕТАЛИЗАЦИИ (для фулфилмента)**:

- 🔵 **Уровень 1 (Магазины)**: уникальные цвета
  - ТехноМир: `blue-400/500`
  - Стиль и Комфорт: `pink-400/500`
  - Зелёный Дом: `emerald-400/500`
- 🟢 **Уровень 2 (Товары)**: `green-500`
- 🟠 **Уровень 3 (Варианты)**: `orange-500`

---

## 🔤 **2. ТИПОГРАФИКА**

### 2.1 Шрифты

**FAMILY**:

- **Sans**: `var(--font-geist-sans)` - основной шрифт
- **Mono**: `var(--font-geist-mono)` - код и техническая информация

### 2.2 Размеры и веса

**HEADINGS**:

- **H1**: `text-3xl font-bold text-white` - заголовки страниц
- **H2**: `text-2xl font-semibold text-white` - секции
- **H3**: `text-xl font-semibold text-white` - подразделы
- **H4**: `text-lg font-medium text-white` - карточки

**BODY TEXT**:

- **Primary**: `text-white` - основной текст
- **Secondary**: `text-white/70` - вспомогательный
- **Muted**: `text-white/60` - дополнительный
- **Disabled**: `text-white/40` - отключенные элементы

**CODE & TECHNICAL**:

- **Code**: `font-mono text-xs text-white/60` - техническая информация
- **Badges**: `text-xs font-medium` - статусы и метки

---

## 🧩 **3. КОМПОНЕНТЫ**

### 3.1 Кнопки

**ВАРИАНТЫ**:

```css
default: bg-primary hover:bg-primary/90
glass: glass-button (основной стиль)
glass-secondary: glass-secondary hover:text-white/90
outline: border hover:bg-accent
ghost: hover:bg-accent/50
destructive: bg-destructive hover:bg-destructive/90
```

**РАЗМЕРЫ**:

- **sm**: `h-8 px-3` - компактные формы
- **default**: `h-9 px-4` - стандартные
- **lg**: `h-10 px-6` - акцентные действия
- **icon**: `size-9` - иконочные кнопки

**ГРАДИЕНТЫ**:

- **Accent**: `bg-gradient-to-r from-purple-600 to-pink-600`
- **Success**: `bg-gradient-to-r from-green-500 to-emerald-500`
- **Info**: `bg-gradient-to-r from-blue-500 to-cyan-500`

### 3.2 Карточки

**БАЗОВЫЕ СТИЛИ**:

```css
glass-card: bg-white/5 backdrop-blur border-white/10
hover: border-white/20 transition-all
interactive: cursor-pointer group
```

**ИНТЕРАКТИВНОСТЬ**:

- **Hover**: `hover:border-white/20 hover:bg-white/10`
- **Scale**: `hover:scale-105 transition-transform`
- **Shadow**: `hover:shadow-xl hover:shadow-purple-500/20`

### 3.3 Формы

**ИНПУТЫ**:

```css
glass-input: backdrop-blur border-white/20
placeholder: placeholder:text-white/50
focus: focus-visible:ring-ring/50
invalid: aria-invalid:border-destructive
```

**СОСТОЯНИЯ**:

- **Default**: `glass-input text-white`
- **Error**: `border-red-500/50 ring-red-500/20`
- **Success**: `border-green-500/50 ring-green-500/20`
- **Disabled**: `opacity-50 pointer-events-none`

---

## ✨ **4. АНИМАЦИИ И ПЕРЕХОДЫ**

### 4.1 Стандартные переходы

**DURATION**:

- **Fast**: `duration-200` - hover эффекты
- **Normal**: `duration-300` - стандартные переходы
- **Slow**: `duration-500` - сложные анимации

**EASING**:

- **Default**: `transition-all` - универсальный
- **Transform**: `transition-transform` - масштабирование
- **Colors**: `transition-colors` - смена цветов

### 4.2 Hover эффекты

**МАСШТАБИРОВАНИЕ**:

```css
hover:scale-105 - легкое увеличение
hover:scale-110 - заметное увеличение
hover:scale-95 - уменьшение при нажатии
hover:-translate-y-1 - поднятие
```

**ЦВЕТОВЫЕ ИЗМЕНЕНИЯ**:

```css
hover:bg-white/10 - осветление фона
hover:text-white - усиление текста
hover:border-white/40 - усиление границ
```

### 4.3 Системные анимации

**LOADING**:

- **Spin**: `animate-spin` - индикаторы загрузки
- **Pulse**: `animate-pulse` - уведомления
- **Bounce**: `animate-bounce` - привлечение внимания
- **Ping**: `animate-ping` - статусы онлайн

---

## 📐 **5. СЕТКИ И ОТСТУПЫ**

### 5.1 Spacing система

**ВНУТРЕННИЕ ОТСТУПЫ**:

- **xs**: `p-2` (8px) - плотные элементы
- **sm**: `p-3` (12px) - компактные карточки
- **md**: `p-4` (16px) - стандартные карточки
- **lg**: `p-6` (24px) - основные секции
- **xl**: `p-8` (32px) - страницы

**ВНЕШНИЕ ОТСТУПЫ**:

- **Между элементами**: `space-y-4` / `gap-4`
- **Между секциями**: `space-y-6` / `gap-6`
- **Между страницами**: `space-y-8`

### 5.2 Responsive сетки

**BREAKPOINTS**:

```css
sm: 640px - мобильные
md: 768px - планшеты
lg: 1024px - десктопы
xl: 1280px - широкие экраны
```

**GRID PATTERNS**:

```css
grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4
grid-cols-2 md:grid-cols-4 lg:grid-cols-6
flex flex-wrap gap-4
```

---

## 🎯 **6. СОСТОЯНИЯ И СТАТУСЫ**

### 6.1 Визуальные индикаторы

**SUCCESS STATES**:

```css
bg-green-500/10 border-green-500/30 text-green-300
CheckCircle - иконка успеха
```

**ERROR STATES**:

```css
bg-red-500/10 border-red-500/30 text-red-300
XCircle - иконка ошибки
```

**WARNING STATES**:

```css
bg-yellow-500/10 border-yellow-500/30 text-yellow-300
AlertTriangle - иконка предупреждения
```

**INFO STATES**:

```css
bg-blue-500/10 border-blue-500/30 text-blue-300
Info - иконка информации
```

### 6.2 Бейджи и метки

**СТАТУСЫ WORKFLOW**:

- **Pending**: `bg-yellow-500/20 text-yellow-300`
- **Approved**: `bg-green-500/20 text-green-300`
- **In Progress**: `bg-blue-500/20 text-blue-300`
- **Completed**: `bg-emerald-500/20 text-emerald-300`
- **Cancelled**: `bg-red-500/20 text-red-300`

---

## 📱 **7. АДАПТИВНОСТЬ**

### 7.1 Mobile-first подход

**ПРИНЦИПЫ**:

- Базовые стили для мобильных
- Прогрессивное улучшение для больших экранов
- Минимальная ширина 320px
- Максимальная производительность

### 7.2 Responsive компоненты

**SIDEBAR**:

```css
Мобильные: overlay sidebar
Планшеты: collapsible sidebar
Десктоп: full sidebar
```

**CARDS**:

```css
Мобильные: 1 колонка
Планшеты: 2 колонки
Десктоп: 3-4 колонки
```

**FORMS**:

```css
Мобильные: stack layout
Планшеты: 2-column layout
Десктоп: optimized layout
```

---

## ♿ **8. ДОСТУПНОСТЬ**

### 8.1 Контрастность

**МИНИМАЛЬНЫЕ ТРЕБОВАНИЯ**:

- Текст на фоне: 4.5:1
- Иконки и элементы: 3:1
- Интерактивные элементы: 4.5:1

**ПРОВЕРКА КОНТРАСТА**:

```css
text-white на bg-white/10 ✅
text-white/70 на bg-white/5 ✅
text-white/40 на bg-white/10 ⚠️
```

### 8.2 Фокус и навигация

**FOCUS STYLES**:

```css
focus-visible:ring-ring/50 focus-visible:ring-[3px]
focus-visible:border-ring
outline-none
```

**KEYBOARD NAVIGATION**:

- Tab order логичен
- Все интерактивные элементы доступны
- Escape закрывает модалы
- Enter активирует кнопки

---

## 🔧 **9. ТЕХНИЧЕСКИЕ ТРЕБОВАНИЯ**

### 9.1 CSS Architecture

**UTILITY-FIRST**:

- Tailwind CSS как основа
- Custom CSS только для уникальных компонентов
- CSS переменные для тем

**NAMING CONVENTIONS**:

```css
glass-card - основные карточки
glass-button - стеклянные кнопки
glass-input - поля ввода
glass-secondary - вторичные элементы
```

### 9.2 Performance

**ОПТИМИЗАЦИЯ**:

- Minimal CSS bundle
- Tree-shaking неиспользуемых стилей
- Critical CSS inline
- Progressive enhancement

**LAZY LOADING**:

- Изображения: `loading="lazy"`
- Компоненты: React.lazy()
- Анимации: только при необходимости

---

## 🎯 **10. ПРАВИЛА ИЕРАРХИИ ТАБОВ**

### 10.1 Принцип отдельного блока табов

**ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА**:

> 1. ТАБЫ ВСЕГДА НАХОДЯТСЯ В ОТДЕЛЬНОМ БЛОКЕ, независимо от количества уровней иерархии
> 2. БЛОК ТАБОВ ИМЕЕТ СТИЛИ КАК У САЙДБАРА
> 3. ТАБЫ ОТДЕЛЕНЫ ОТ РАБОЧЕГО ПРОСТРАНСТВА

**СТИЛИ БЛОКА ТАБОВ**:

```css
bg-white/10 backdrop-blur-xl border border-white/20 rounded-2xl p-6
```

**СТИЛИ РАБОЧЕГО ПРОСТРАНСТВА**:

```css
bg-white/10 backdrop-blur-xl border border-white/20 rounded-2xl
```

**ЗАПРЕЩЕНО**:

- Размещать табы в блоке с другими модулями
- Смешивать табы с основным контентом
- Использовать glass-card вместо правильных стилей сайдбара
- Объединять блок табов с рабочим пространством

### 10.2 Визуальная иерархия

**УРОВЕНЬ 1 (Главные табы)**:

```css
h-11                    /* Высота 44px */
bg-white/15             /* Контрастный фон */
border-white/30         /* Яркая граница */
rounded-xl              /* Крупное скругление */
font-semibold           /* Жирный шрифт */
purple-500/40           /* Интенсивный градиент */
shadow-lg               /* Глубокая тень */
```

**УРОВЕНЬ 2 (Подтабы)**:

```css
h-9                     /* Высота 36px */
bg-white/8              /* Средний фон */
border-white/20         /* Средняя граница */
rounded-lg              /* Среднее скругление */
font-medium             /* Средний шрифт */
white/15                /* Простая активация */
ml-4                    /* Отступ показывает иерархию */
```

**УРОВЕНЬ 3 (Подподтабы)**:

```css
h-8                     /* Высота 32px */
bg-white/5              /* Слабый фон */
border-white/15         /* Деликатная граница */
rounded-md              /* Мелкое скругление */
font-normal             /* Обычный шрифт */
white/10                /* Слабая активация */
ml-8                    /* Больший отступ */
text-white/50           /* Приглушенный текст */
```

### 10.3 Отступы и spacing

**ИЕРАРХИЧЕСКИЕ ОТСТУПЫ**:

- **Уровень 1**: `ml-0` - прижат к краю
- **Уровень 2**: `ml-4` - показывает подчинение
- **Уровень 3**: `ml-8` - максимальная вложенность

**ВЕРТИКАЛЬНЫЕ ОТСТУПЫ**:

- Между уровнями: `space-y-3`
- После TabsList: `mb-3`
- В контенте: `space-y-0` (без лишних отступов)

### 10.4 Размеры элементов

**ПРОГРЕССИВНОЕ УМЕНЬШЕНИЕ**:

- **Высота табов**: 44px → 36px → 32px
- **Размер иконок**: 16px → 12px → 10px
- **Размер текста**: sm → xs → xs
- **Толщина шрифта**: semibold → medium → normal

### 10.5 Цветовая деградация

**КОНТРАСТНОСТЬ**:

- **Уровень 1**: Максимальная (white/15, border-white/30)
- **Уровень 2**: Средняя (white/8, border-white/20)
- **Уровень 3**: Минимальная (white/5, border-white/15)

**АКТИВАЦИЯ**:

- **Уровень 1**: Градиент + тень + border
- **Уровень 2**: Простой фон white/15
- **Уровень 3**: Слабый фон white/10

---

## 📐 **11. ПРАВИЛО ВЫРАВНИВАНИЯ БЛОКОВ С САЙДБАРОМ**

### 11.1 Принцип выравнивания

**🎯 ОСНОВНОЙ ПРИНЦИП:**

> Все блоки контента справа от сайдбара должны быть выровнены точно по верхнему и нижнему краю сайдбара без отступов.

**📐 ВИЗУАЛЬНАЯ СХЕМА:**

```
┌─────────────────────────────────────┐
│ SIDEBAR    │ ← блоки начинаются     │ ← ТОП САЙДБАРА
│            │   точно здесь          │
│            │                        │
│            │ [КОНТЕНТ БЛОКИ]        │
│            │                        │
│            │ ← блоки заканчиваются  │ ← НИЗ САЙДБАРА
│            │   точно здесь          │
└─────────────────────────────────────┘
```

### 11.2 Техническая реализация

**✅ ПРАВИЛЬНО:**

```jsx
<div className="h-screen flex overflow-hidden">
  <Sidebar />
  <main className={`flex-1 ${getSidebarMargin()} overflow-hidden transition-all duration-300`}>
    <div className="h-full flex flex-col">
      {/* Блоки занимают всю доступную область */}
      <div className="flex-1 flex gap-2 min-h-0">
        {/* Блоки без внешних отступов */}
      </div>
    </div>
  </main>
</div>
```

**❌ НЕПРАВИЛЬНО:**

```jsx
// НЕ ИСПОЛЬЗОВАТЬ px-2 py-2 в main контейнере!
<main className={`flex-1 ${getSidebarMargin()} px-2 py-2 overflow-hidden`}>
```

### 11.3 Требования к структуре

**MAIN КОНТЕЙНЕР:**

- ✅ БЕЗ `px-2 py-2` отступов  
- ✅ Только `overflow-hidden` и `transition-all duration-300`
- ✅ Использовать `${getSidebarMargin()}` для отступа от сайдбара

**БЛОКИ КОНТЕНТА:**

- ✅ Занимают всю высоту: `h-full flex flex-col`
- ✅ Минимальные gap между блоками: `gap-2`
- ✅ Начинаются от самого верха экрана
- ✅ Заканчиваются у самого низа экрана

**SPACING МЕЖДУ БЛОКАМИ:**

- ✅ Горизонтальный gap: `gap-2` (8px)
- ✅ Вертикальный gap: `gap-2` (8px)
- ❌ НЕ использовать внешние отступы `px-* py-*`

### 11.4 Области применения

**✅ ПРИМЕНЯЕТСЯ К:**

- Все страницы с сайдбаром
- Дашборды и кабинеты пользователей
- Модальные окна полной высоты
- Списки, таблицы и каталоги
- Формы создания и редактирования

**❌ ИСКЛЮЧЕНИЯ:**

- Модальные окна (центрированные)
- Всплывающие уведомления (toast)
- Dropdown меню
- Контекстные меню

### 11.5 Проверка соответствия

**КРИТЕРИИ СООТВЕТСТВИЯ:**

1. **Верхний край**: Первый блок начинается на уровне верха сайдбара
2. **Нижний край**: Последний блок заканчивается на уровне низа сайдбара  
3. **Без отступов**: Отсутствуют `px-* py-*` отступы в main
4. **Только gap**: Используется только `gap-2` между блоками

**ИНСТРУМЕНТЫ ПРОВЕРКИ:**

- Инспектор браузера для проверки CSS
- Визуальное сравнение с краями сайдбара
- Проверка на разных размерах экрана

---

## 📋 **12. ЧЕКЛИСТ ПРИМЕНЕНИЯ**

### 12.1 Перед внедрением компонента

- [ ] Соответствует цветовой палитре системы
- [ ] Использует правильную типографику
- [ ] Имеет корректные состояния (hover, focus, disabled)
- [ ] Адаптивен для всех breakpoints
- [ ] Соответствует требованиям доступности
- [ ] Использует стандартные анимации
- [ ] Оптимизирован для производительности
- [ ] **Блоки выровнены с сайдбаром (правило 11)**

### 12.2 При создании новых компонентов

- [ ] Базируется на существующих паттернах
- [ ] Совместим с UI Kit системы
- [ ] Документирован в Storybook/UI Kit демо
- [ ] Протестирован на различных устройствах
- [ ] Соответствует принципам дизайн-системы
- [ ] **Применяет правило выравнивания с сайдбаром**

---

## 🎨 **13. ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ**

### 13.1 Базовая карточка

```tsx
<Card className="glass-card border-white/10 hover:border-white/20 transition-all">
  <CardHeader>
    <CardTitle className="text-white">Заголовок</CardTitle>
    <CardDescription className="text-white/70">Описание</CardDescription>
  </CardHeader>
  <CardContent>
    <p className="text-white/80">Содержимое карточки</p>
  </CardContent>
</Card>
```

### 13.2 Интерактивная кнопка

```tsx
<Button
  variant="glass"
  className="hover:scale-105 transition-transform"
  onClick={handleClick}
>
  <Icon className="h-4 w-4 mr-2" />
  Действие
</Button>
```

### 13.3 Форма с валидацией

```tsx
<div className="space-y-2">
  <Label className="text-white/90">Поле ввода</Label>
  <Input
    className="glass-input text-white placeholder:text-white/50"
    placeholder="Введите значение..."
  />
  {error && <p className="text-red-300 text-xs">{error}</p>}
</div>
```

### 13.4 Правильное выравнивание с сайдбаром

```tsx
// ✅ ПРАВИЛЬНАЯ структура страницы с сайдбаром
function PageWithSidebar() {
  const { getSidebarMargin } = useSidebar();
  
  return (
    <div className="h-screen flex overflow-hidden">
      <Sidebar />
      <main className={`flex-1 ${getSidebarMargin()} overflow-hidden transition-all duration-300`}>
        <div className="h-full flex flex-col">
          {/* Структура из 3 блоков согласно rules1.md */}
          <div className="flex-1 flex gap-2 min-h-0">
            {/* Левые блоки */}
            <div className="flex-1 flex flex-col gap-2 min-h-0">
              <div className="bg-white/10 backdrop-blur-xl border border-white/20 rounded-2xl">
                {/* Блок 1: Основной контент */}
              </div>
              <div className="bg-white/10 backdrop-blur-xl border border-white/20 rounded-2xl flex-1">
                {/* Блок 2: Дополнительный контент */}
              </div>
            </div>
            {/* Правый блок */}
            <div className="w-96 flex-shrink-0">
              <div className="bg-white/10 backdrop-blur-xl border border-white/20 rounded-2xl h-full">
                {/* Блок 3: Боковая панель */}
              </div>
            </div>
          </div>
        </div>
      </main>
    </div>
  );
}
```

---

**📊 СТАТУС**: Действующие правила v1.0  
**🔄 ОБНОВЛЕНО**: На основе анализа UI Kit системы  
**📅 ДАТА**: Основано на текущем состоянии проекта