Игорь Надеин
9df9f78666
SCSS Architecture 2.0 - Feature-based structure ### Major Changes: - ✅ Reorganized 51 SCSS files into logical categories - ✅ Created feature-based structure: core/, layout/, features/, utilities/ - ✅ Merged duplicate components: badges (2→1), modals (3→1), lists (2→1), spacing (2→1) - ✅ Renamed files: ios-search→search, team-wheel→team-viz, recipientPicker→recipient-picker - ✅ Cleaned custom-bootstrap.scss from all app components - ✅ Moved chat components from custom-bootstrap to main.scss ### Results: - Files: 51 → 38 (-13 files, -25%) - bootstrap-custom.css: 301 KB → 229 KB (-72 KB, -24%) - app.css: 95 KB → 137 KB (+42 KB, expected) - Total CSS: 396 KB → 366 KB (-30 KB, -7.5%) ### New Structure: scss/ ├── abstracts/ # Variables, mixins (4 files) ├── core/ # UI Kit - reusable components (9 files) │ ├── buttons, badges, cards, lists, modals, etc. ├── layout/ # App structure (6 files) │ ├── grid, navbar, sidebar, rightbar, etc. ├── utilities/ # Utility classes (1 file) │ └── spacing └── features/ # Feature-specific styles (18 files in 6 folders) ├── feed/ (3 files) ├── requests/ (3 files) ├── documents/ (1 file) ├── employees/ (2 files) ├── notifications/ (1 file) └── chat/ (10 files) ### Benefits: - Clear categorization - No duplicate imports (removed 8 duplicates) - Logical feature grouping - Easier maintenance - Clean architecture - Better naming conventions ### Documentation: - scss/README.md - full architecture documentation - scss/MIGRATION_MATRIX.md - file migration matrix - docs/reports/SCSS_REORGANIZATION_COMPLETE.md - completion report Bootstrap remains as base UI framework.
258 lines
8.8 KiB
Markdown
258 lines
8.8 KiB
Markdown
# 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)
|