Corp/backend/static/scss/README.md

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

# Собрать 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
Пример:

// core/_alerts.scss
.alert {
  // базовые стили
}

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

Layout компоненты

Когда: Структура приложения (header, sidebar, grid)
Где: layout/_component.scss
Пример:

// layout/_header.scss
.app-header {
  // стили header
}

Feature-specific стили

Когда: Стили специфичные для конкретной функции
Где: features/{feature}/_component.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 - быстрый справочник
• Buttons Component - документация по кнопкам
• SCSS Reorganization Plan - план реорганизации
• Migration Matrix - матрица миграции файлов

---

🎨 Соглашения

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)

---

Вопросы? См. План реорганизации