# SCSS Architecture

**Дата реорганизации:** 15 января 2026  
**Версия:** 2.0  
**Архитектура:** Feature-based с Core UI Kit

---

## 📁 Структура

```
scss/
├── abstracts/              # Переменные, миксины, функции
│   ├── _variables.scss     # SCSS переменные
│   ├── _css-variables.scss # CSS custom properties
│   ├── _mixins.scss        # Миксины
│   └── _index.scss         # Экспорт
│
├── core/                   # UI Kit - переиспользуемые компоненты
│   ├── _buttons.scss       # Кнопки
│   ├── _badges.scss        # Бейджи (объединены BEM + Telegram стили)
│   ├── _cards.scss         # Карточки
│   ├── _comments.scss      # Комментарии
│   ├── _common.scss        # Общие стили
│   ├── _lists.scss         # Списки (объединены card-list + list-view)
│   ├── _modals.scss        # Модалы (объединены 3 файла)
│   ├── _search.scss        # Поиск (было ios-search)
│   └── _ui-elements.scss   # UI элементы (было ios-components)
│
├── layout/                 # Структура приложения
│   ├── _grid.scss          # Grid система (было base-app)
│   ├── _chat-layout.scss   # Layout чата
│   ├── _navbar.scss        # Навигация
│   ├── _page-header.scss   # Заголовок страницы
│   ├── _sidebar.scss       # Боковая панель
│   └── _rightbar.scss      # Правая панель + календарь
│
├── utilities/              # Вспомогательные классы
│   └── _spacing.scss       # Spacing утилиты (объединены 2 файла)
│
└── features/               # Feature-specific стили
    ├── feed/              # Лента новостей
    │   ├── _layout.scss
    │   ├── _post-form.scss
    │   └── _members-scroller.scss
    │
    ├── requests/          # Заявки
    │   ├── _list.scss
    │   ├── _detail.scss
    │   └── _recipient-picker.scss
    │
    ├── documents/         # Документы
    │   └── _list.scss
    │
    ├── employees/         # Сотрудники
    │   ├── _controls.scss
    │   └── _team-viz.scss
    │
    ├── notifications/     # Уведомления
    │   └── _center.scss
    │
    └── chat/             # Чат (10 файлов)
        ├── _message-inputs.scss
        ├── _chat-detail.scss
        ├── _chat-date-groups.scss
        ├── _chat-list-enhanced.scss
        ├── _chat-enhanced.scss
        ├── _chat-polls.scss
        ├── _chat-new-messages-indicator.scss
        ├── _message-selection.scss
        ├── _message-context-menu.scss
        └── _message-reactions.scss
```

---

## 🎯 Entry Points

### 1. main.scss → css/app.css (137 KB)
Основной файл приложения. Содержит:
- Core UI Kit
- Layout системы
- Utilities
- Feature-specific стили

**Команда:** `npm run build:app`

### 2. custom-bootstrap.scss → css/bootstrap-custom.css (229 KB)
Bootstrap с переопределенными переменными. Содержит **ТОЛЬКО**:
- Переопределения Bootstrap переменных
- Импорт Bootstrap
- CSS custom properties

**Команда:** `npm run build:bootstrap`

**НЕ СОДЕРЖИТ** компонентов приложения!

---

## 📊 Статистика

**Всего файлов:** 38 (было 51)  
**Уменьшение:** -13 файлов (-25%)

**Распределение:**
- Abstracts: 4 файла
- Core: 9 файлов
- Layout: 6 файлов
- Utilities: 1 файл
- Features: 18 файлов (в 6 папках)

**Размеры CSS:**
- app.css: 137 KB
- bootstrap-custom.css: 229 KB
- **Итого:** 366 KB (было 376 KB, экономия 10 KB)

---

## 🔄 Изменения от предыдущей версии

### Объединения (8 файлов → 4):
1. ✅ `badges-bem.scss` + `badges-telegram-style.scss` → `core/_badges.scss`
2. ✅ `modals.scss` + `modal-overrides.scss` + `logout-modal.scss` → `core/_modals.scss`
3. ✅ `card-list.scss` + `list-view.scss` → `core/_lists.scss`
4. ✅ `spacing-utils.scss` + `layout-spacing.scss` → `utilities/_spacing.scss`

### Переименования:
1. ✅ `ios-search.scss` → `core/_search.scss`
2. ✅ `ios-components.scss` → `core/_ui-elements.scss`
3. ✅ `base-app.scss` → `layout/_grid.scss`
4. ✅ `rightbar-calendar.scss` → `layout/_rightbar.scss`
5. ✅ `feed-specific.scss` → `features/feed/_layout.scss`
6. ✅ `join-scroller.scss` → `features/feed/_members-scroller.scss`
7. ✅ `recipientPicker.scss` → `features/requests/_recipient-picker.scss`
8. ✅ `team-wheel.scss` → `features/employees/_team-viz.scss`

### Перемещения:
- ✅ Все компоненты из `components/` распределены по категориям
- ✅ Chat компоненты перемещены в `features/chat/`
- ✅ Layout компоненты собраны в `layout/`

---

## 🚀 Build Commands

```bash
# Собрать app.css
npm run build:app

# Собрать bootstrap-custom.css
npm run build:bootstrap

# Собрать оба
npm run build

# Watch mode (автоперекомпиляция при изменениях)
npm run dev
```

---

## 📝 Правила добавления новых стилей

### Core компоненты
**Когда:** Переиспользуемый UI элемент (кнопка, карточка, бейдж и т.д.)  
**Где:** `core/_component.scss`  
**Пример:**
```scss
// core/_alerts.scss
.alert {
  // базовые стили
}

.alert--success { }
.alert--danger { }
```

### Layout компоненты
**Когда:** Структура приложения (header, sidebar, grid)  
**Где:** `layout/_component.scss`  
**Пример:**
```scss
// layout/_header.scss
.app-header {
  // стили header
}
```

### Feature-specific стили
**Когда:** Стили специфичные для конкретной функции  
**Где:** `features/{feature}/_component.scss`  
**Пример:**
```scss
// features/calendar/_widget.scss
.calendar-widget {
  // специфичные стили календаря
}
```

### После добавления:
1. Добавить `@import` в `main.scss`
2. Запустить `npm run build:app`
3. Проверить в браузере

---

## ⚠️ Важно!

### ❌ НЕ добавляйте компоненты в custom-bootstrap.scss!
Этот файл содержит только Bootstrap с переопределенными переменными.

### ✅ Все компоненты приложения идут в main.scss

### 🔄 Обратная совместимость
Старые классы сохранены через `@extend`:
- `.badge-telegram` → расширяет `.badge`
- `.badge-telegram-sm` → расширяет `.badge--sm`

---

## 🧪 Тестирование

После изменений проверить:
1. ✅ Сборка без ошибок: `npm run build`
2. ✅ Размер файлов не вырос значительно
3. ✅ Визуальное тестирование всех страниц
4. ✅ Консоль браузера без ошибок

---

## 📚 Документация

- [SCSS Quick Reference](../../docs/guides/SCSS_QUICK_REFERENCE.md) - быстрый справочник
- [Buttons Component](../../docs/guides/BUTTONS_COMPONENT.md) - документация по кнопкам
- [SCSS Reorganization Plan](../../docs/reports/SCSS_REORGANIZATION_PLAN.md) - план реорганизации
- [Migration Matrix](MIGRATION_MATRIX.md) - матрица миграции файлов

---

## 🎨 Соглашения

### Naming
- BEM notation: `.block`, `.block__element`, `.block--modifier`
- Feature prefixes: `.feed-card`, `.request-detail`
- Kebab-case для файлов: `_my-component.scss`

### Imports
- Используем `@import` (позже мигрируем на `@use`/`@forward`)
- Порядок критичен: abstracts → core → layout → utilities → features

### Variables
- SCSS переменные: `$variable-name` (compile-time)
- CSS переменные: `--variable-name` (runtime)

---

**Вопросы?** См. [План реорганизации](../../docs/reports/SCSS_REORGANIZATION_PLAN.md)