diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index 74a668e..49eb6e2 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -73,7 +73,7 @@ jobs:
ssh -i ~/.ssh/deploy_key root@188.225.47.78 bash -s <<'SCRIPT'
set -e
IMAGE="${{ env.REGISTRY_IMAGE }}:latest"
- CONTAINER="nextjs-style-guide"
+ CONTAINER="frontend-style-guide"
# Логин в реестр
echo '${{ secrets.CR_TOKEN }}' | docker login ${{ env.DOCKER_REGISTRY }} -u '${{ secrets.CR_USER }}' --password-stdin
diff --git a/notes b/notes
index 7bfbf2f..4d3d5a0 100644
--- a/notes
+++ b/notes
@@ -1,153 +1,23 @@
-ФЛОУ
- - после создания компонента, заменить шаблонный коментарий документа на реальный.
-
-
- Проблема, неочевидность слоев (наследие FSD)
-
+# TODO
-Архитектурные слои проекта
-Каждый нижний слой не знает о существовании верхних. Импорты идут только сверху вниз.
-pages → layouts → screens → widgets → features → entities → shared
----
-1. Pages (pages/)
-Точка входа маршрута. Только связывает layout и screen.
-Правила:
-- Никакой логики, стилей, разметки кроме композиции
-- Один page = один layout + один screen
-Пример:
-// pages/knv-new.js
-import { KnvScreen } from 'src/screens/knv'
-import { MainLayout } from 'src/layouts/main'
-const KnvNewPage = () => (
-
-
-
-)
----
-2. Layouts (src/layouts/)
-Каркас страницы — общие элементы, которые одинаковы на всех страницах в рамках этого layout.
-Содержит в ui/: header, footer, sidebar — дочерние компоненты, которые привязаны к layout и не переиспользуются отдельно.
-Критерий: компонент одинаков на всех страницах, использующих этот layout? → layouts/{name}/ui/
-Пример:
-src/layouts/main/
-├── main.layout.tsx # + children +
-├── ui/
-│ ├── header/ # всегда одинаковый на всех страницах
-│ └── footer/ # всегда одинаковый на всех страницах
----
-3. Screens (src/screens/)
-Контент конкретной страницы. Собирает свои секции и переиспользуемые widgets/features/entities.
-Содержит в ui/: блоки, которые существуют только на этой странице и не переиспользуются.
-Критерий: компонент используется только на одной странице? → screens/{name}/ui/
-Пример:
-src/screens/knv/
-├── knv.screen.tsx
-├── ui/
-│ ├── hero-section/ # hero только на главной КНВ
-│ ├── products-section/ # секция препаратов только на главной
-│ ├── diseases-section/ # секция заболеваний только на главной
-│ └── doctor-section/ # секция врачей только на главной
-Каждая секция внутри может использовать shared/ui компоненты:
-// screens/knv/ui/products-section/products-section.widget.tsx
-import { Carousel } from 'src/shared/ui/carousel'
-import { ProductCard } from './ui/product-card' // локальный, пока не переиспользуется
-Когда локальный компонент начинает использоваться на 2+ страницах — выносим в entities/ или shared/ui.
----
-4. Widgets (src/widgets/)
-Составные блоки с данными/логикой, которые переиспользуются на 2+ страницах.
-Критерий: блок с бизнес-логикой + данными используется на нескольких страницах? → widgets/
-Пример: Слайдер «Популярные препараты» с загрузкой данных из API, который показывается и на главной, и на странице заболевания, и в каталоге:
-src/widgets/
-├── popular-products-slider/
-│ ├── popular-products-slider.widget.tsx # Carousel + ProductCard + useProducts()
-│ ├── hooks/
-│ │ └── use-products.hook.ts # запрос данных
-Не widget: секция «Подобрать врача» которая есть только на главной → screens/knv/ui/
----
-5. Features (src/features/)
-Пользовательское действие или интерактивный сценарий. Содержит бизнес-логику взаимодействия.
-Критерий: это действие пользователя (отправить форму, авторизоваться, добавить в корзину)? → features/
-Примеры:
-src/features/
-├── auth/ # авторизация (форма + логика + стор)
-│ ├── auth.feature.tsx
-│ ├── hooks/
-│ │ └── use-auth.hook.ts
-│ └── stores/
-│ └── auth.store.ts
-│
-├── order-drug/ # заказ препарата (кнопка + модалка + API)
-│ ├── order-drug.feature.tsx
-│ └── hooks/
-│ └── use-order.hook.ts
-Не feature: отображение карточки препарата без взаимодействия → entities/ или shared/ui
----
-6. Entities (src/entities/)
-Бизнес-сущность с её отображением и типами. Привязана к домену (препарат, заболевание, врач, пользователь).
-Критерий: это представление бизнес-объекта, которое переиспользуется в разных контекстах? → entities/
-Примеры:
-src/entities/
-├── product/ # Препарат
-│ ├── ui/
-│ │ └── product-card/ # карточка препарата (каталог, слайдеры, поиск)
-│ ├── types/
-│ │ └── product.type.ts # { id, name, mnn, indication }
-│ └── index.ts
-│
-├── disease/ # Заболевание
-│ ├── ui/
-│ │ └── disease-card/
-│ ├── types/
-│ │ └── disease.type.ts
-│ └── index.ts
-Отличие от shared/ui: entity-компонент знает о бизнес-домене (принимает Product, а не абстрактные пропсы). shared/ui Button не знает ничего о бизнесе.
----
-7. Shared (src/shared/)
-Переиспользуемые компоненты, утилиты, стили без бизнес-логики.
-Критерий: компонент не знает о бизнес-домене, работает с абстрактными данными? → shared/
-src/shared/
-├── ui/ # UI-компоненты
-│ ├── carousel/ # принимает children, не знает о препаратах
-│ ├── container/
-│ ├── section/
-│ └── icon-svg/
-├── styles/ # CSS-переменные, media
-│ ├── variables.css
-│ └── media.css
-├── sprites/ # SVG-спрайты
-└── lib/ # утилиты, хелперы
----
-Сводная таблица принятия решений
-Вопрос Да → Нет ↓
-Это точка входа маршрута? pages/ ↓
-Одинаков на всех страницах layout? layouts/{name}/ui/ ↓
-Используется только на одной странице? screens/{name}/ui/ ↓
-Составной блок с данными на 2+ страницах? widgets/ ↓
-Это действие пользователя с логикой? features/ ↓
-Привязан к бизнес-сущности? entities/ ↓
-Абстрактный UI без бизнес-логики? shared/ui/ —
+## Триггеры: классификация и расширение
+Текущий список триггеров слабо проработан. Нужно:
-И еще размышлений
+1. Классифицировать триггеры по группам:
+ - Создание — новые модули, компоненты, страницы
+ - Ресурсы — ассеты (иконки, шрифты, изображения, видео)
+ - Данные — API, сторы, серверные данные, формы
+ - Навигация — роутинг, middleware, редиректы
+ - Модификация — рефакторинг, перенос, удаление
+ - Инфраструктура — зависимости, переводы, настройка окружения
+2. Добавить недостающие триггеры. Примеры пробелов:
+ - Создание: утилита/хелпер, тип/интерфейс, контекст
+ - Данные: создать форму, добавить валидацию
+ - Навигация: динамический роут, middleware, редирект
+ - Модификация: рефакторинг компонента, перенос модуля, удаление модуля
+ - Обработка ошибок: error boundary, fallback UI, error.tsx, not-found.tsx, loading.tsx
+ - Авторизация: защита страницы, проверка прав
-
-
-
-
-Что у нас по факту
-Мы взяли FSD и добавили:
-- Слой Layouts — каркас страницы
-- Слой Screens — контент страницы с локальными компонентами
-- Правило scope — компонент живёт максимально близко к месту использования, и поднимается на уровень выше только при переиспользовании
-Это не FSD в чистом виде. Но и не что-то принципиально новое.
-Существующие названия
-Feature-Sliced Design (FSD) — то от чего отталкиваемся, но расходимся в деталях.
-Screaming Architecture (Robert C. Martin) — структура проекта "кричит" о том, что он делает. Открываешь screens/knv/ui/ — видишь КНВ. Открываешь widgets/ — видишь глобальное. Это близко к нашему подходу.
-Colocation Principle — держи код рядом с тем, где он используется. Именно этот принцип отличает нас от FSD: page-specific компоненты лежат внутри screen, а не в глобальном widgets/.
-Как назвать
-Я бы не стал придумывать новое название. Это:
-> FSD с принципом колокации (FSD + Colocation)
-Или проще — адаптированный FSD. Суть отличия укладывается в одно правило:
-> Компонент живёт на самом низком уровне, где он используется. Поднимается выше только при переиспользовании на 2+ страницах.
-Если хочется краткое название для внутренней документации — можно SLD (Scoped Layer Design), подчёркивая что каждый компонент привязан к scope (shared → entity → feature → widget → screen → layout → page).
+3. Обновить секцию "Триггеры" в DEVELOP.md — перейти на новые группы.
diff --git a/package-lock.json b/package-lock.json
index d6047c8..04ffc4a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,11 +1,11 @@
{
- "name": "nextjs-style-guide",
+ "name": "frontend-style-guide",
"version": "0.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
- "name": "nextjs-style-guide",
+ "name": "frontend-style-guide",
"version": "0.0.0",
"devDependencies": {
"vitepress": "^1.6.3"
diff --git a/package.json b/package.json
index 0a16148..5f2513e 100644
--- a/package.json
+++ b/package.json
@@ -1,5 +1,5 @@
{
- "name": "nextjs-style-guide",
+ "name": "frontend-style-guide",
"private": true,
"type": "module",
"version": "0.0.0",
diff --git a/scripts/nextjs.build.js b/scripts/nextjs.build.js
index 847c5d2..595bc9e 100644
--- a/scripts/nextjs.build.js
+++ b/scripts/nextjs.build.js
@@ -17,7 +17,6 @@ export default {
"basics/architecture.md": "base/basics/architecture.md",
"basics/code-style.md": "base/basics/code-style.md",
"basics/documentation.md": "base/basics/documentation.md",
- "basics/getting-started.md": "base/basics/getting-started.md",
"basics/naming.md": "base/basics/naming.md",
"basics/tech-stack.md": "base/basics/tech-stack.md",
"basics/typing.md": "base/basics/typing.md",
diff --git a/src/base/basics/architecture.md b/src/base/basics/architecture.md
index 64b94f5..6a17d9d 100644
--- a/src/base/basics/architecture.md
+++ b/src/base/basics/architecture.md
@@ -1,3 +1,10 @@
+---
+title: Архитектура
+scope: basics
+keywords: [SLM Design, слой, модуль, сегмент, архитектура, FSD, scoped layered module]
+when: "Организация кода: слои, модули, зависимости между модулями"
+---
+
# SLM Design
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
diff --git a/src/nextjs/DEVELOP.md b/src/nextjs/DEVELOP.md
index 394e60d..1a2850f 100644
--- a/src/nextjs/DEVELOP.md
+++ b/src/nextjs/DEVELOP.md
@@ -4,48 +4,93 @@
## Как работать
-1. Найди задачу в таблицах ниже → открой триггер.
-2. Триггер укажет какие разделы прочитать и какие шаги выполнить.
-3. Перед каждой подзадачей возвращайся к этой таблице — проверяй, нет ли готового триггера.
-4. Если задачи нет в таблицах — ищи в `applied/` (по области) или `basics/` (общие правила).
+1. **Изучи обязательные правила** (таблица ниже) — они действуют при любой задаче.
+2. Найди задачу в таблицах триггеров → открой триггер.
+3. Триггер укажет какие прикладные разделы прочитать и какие шаги выполнить.
+4. Перед каждой подзадачей возвращайся к триггерам — проверяй, нет ли готового.
+5. Если триггера нет — ищи прикладной раздел по области задачи.
-## Создание
+---
-| Задача | Триггер | Когда / Когда НЕ |
-|--------|---------|-------------------|
-| Создать компонент | triggers/develop/create-component.md | Переиспользуемый UI без бизнес-логики. НЕ для: фичи, виджета, сущности |
-| Создать фичу | triggers/develop/create-feature.md | Самодостаточный блок с бизнес-логикой и UI. НЕ для: утилитарного UI (→ компонент) |
-| Создать виджет | triggers/develop/create-widget.md | Композиция фичей и сущностей. НЕ для: одиночного UI (→ компонент) |
-| Создать сущность | triggers/develop/create-entity.md | Бизнес-объект с UI и моделью данных. НЕ для: UI без модели (→ компонент) |
-| Создать хук | triggers/develop/create-hook.md | Кастомный React-хук. НЕ для: хука внутри стора |
-| Создать стор | triggers/develop/create-store.md | Глобальное или модульное состояние. НЕ для: локального useState |
-| Создать страницу | triggers/develop/create-page.md | Новый route в Next.js. Всегда экран + page.tsx |
-| Создать layout | triggers/develop/create-layout.md | layout.tsx для группы страниц |
-| Создать проект | triggers/develop/create-project.md | Новый проект из шаблона |
-| Сгенерировать модуль | triggers/develop/generate-module.md | Любой модуль из `.templates/`. Ручное создание файлов запрещено |
+## Обязательные правила
-## Стилизация и ресурсы
+Прочитай эти разделы **до начала работы**. Соблюдай при написании любого кода.
-| Задача | Триггер | Когда / Когда НЕ |
-|--------|---------|-------------------|
-| Стилизовать компонент | triggers/develop/style-component.md | Выбор подхода + написание CSS. НЕ для: Mantine-пропсов (они не требуют CSS) |
+| Раздел | Файл | Что внутри |
+|--------|------|------------|
+| Структура проекта | applied/project-structure.md | Организация папок и файлов |
+| Архитектура | basics/architecture.md | SLM Design: слои, модули, сегменты |
+| Стиль кода | basics/code-style.md | Форматирование, импорты, отступы |
+| Именование | basics/naming.md | Имена файлов, переменных, событий |
+| Типизация | basics/typing.md | type vs interface, generic, any/unknown |
+| Документирование | basics/documentation.md | JSDoc для функций, компонентов, типов |
+| Технологии | basics/tech-stack.md | Допустимые библиотеки и зависимости |
+
+---
+
+## Прикладные разделы
+
+Справочник по областям. Читай тот раздел, который относится к текущей задаче.
+
+| Область | Файл | Когда читать |
+|---------|------|--------------|
+| Компоненты | applied/components.md | Создание или редактирование React-компонентов |
+| Стили | applied/styles.md | CSS Modules, PostCSS, переменные, медиа-запросы |
+| Файлы роутинга | applied/page-level.md | page.tsx, layout.tsx, error.tsx, not-found.tsx |
+| Шаблоны и генерация | applied/templates-generation.md | Генерация кода из шаблонов |
+| Настройка VS Code | applied/vscode.md | Расширения, settings.json, сниппеты |
+| SVG-спрайты | applied/svg-sprites.md | Работа с SVG-иконками и спрайтами |
+| Хуки | applied/hooks.md | Создание и использование кастомных хуков *(в разработке)* |
+| Сторы | applied/stores.md | Глобальное состояние, Zustand *(в разработке)* |
+| API | applied/api.md | Запросы, клиенты, обработка ответов *(в разработке)* |
+| Локализация | applied/localization.md | i18next, переводы *(в разработке)* |
+| Изображения | applied/images-sprites.md | Подключение и оптимизация изображений *(в разработке)* |
+| Шрифты | applied/fonts.md | Подключение и настройка шрифтов *(в разработке)* |
+| Видео | applied/video.md | Встраивание видео *(в разработке)* |
+
+---
+
+## Триггеры
+
+Пошаговые инструкции. Найди задачу → открой триггер → выполняй по шагам.
+
+### Создание
+
+| Задача | Триггер | Описание |
+|--------|---------|----------|
+| Создать компонент | triggers/develop/create-component.md | Переиспользуемый UI-элемент без бизнес-логики |
+| Создать фичу | triggers/develop/create-feature.md | Самодостаточный блок с бизнес-логикой и UI |
+| Создать виджет | triggers/develop/create-widget.md | Композиция нескольких фичей и сущностей |
+| Создать сущность | triggers/develop/create-entity.md | Бизнес-объект с моделью данных и UI-представлением |
+| Создать хук | triggers/develop/create-hook.md | Кастомный React-хук с переиспользуемой логикой |
+| Создать стор | triggers/develop/create-store.md | Глобальное или модульное состояние через Zustand |
+| Создать страницу | triggers/develop/create-page.md | Новый route в Next.js — экран + page.tsx |
+| Создать layout | triggers/develop/create-layout.md | Общая обёртка layout.tsx для группы страниц |
+| Создать проект | triggers/develop/create-project.md | Инициализация нового проекта из шаблона |
+| Сгенерировать модуль | triggers/develop/generate-module.md | Создание модуля из шаблонов `.templates/` |
+
+### Стилизация и ресурсы
+
+| Задача | Триггер | Описание |
+|--------|---------|----------|
+| Стилизовать компонент | triggers/develop/style-component.md | Выбор подхода и написание CSS для компонента |
| Добавить иконку | triggers/develop/add-icon.md | SVG-иконка через спрайт-систему |
| Добавить изображение | triggers/develop/add-image.md | Растровое изображение (png, jpg, webp) |
-| Добавить видео | triggers/develop/add-video.md | Встраивание видео |
-| Подключить шрифт | triggers/develop/add-font.md | Новый шрифт в проект |
+| Добавить видео | triggers/develop/add-video.md | Встраивание видео на страницу |
+| Подключить шрифт | triggers/develop/add-font.md | Подключение нового шрифта в проект |
-## Данные и состояние
+### Данные и состояние
-| Задача | Триггер | Когда / Когда НЕ |
-|--------|---------|-------------------|
-| Добавить API-запрос | triggers/develop/add-api-request.md | Клиентский запрос (SWR). НЕ для: серверных данных (→ add-server-data) |
-| Подключить стор | triggers/develop/connect-store.md | Подключение стора к компоненту. НЕ для: создания стора (→ create-store) |
-| Серверные данные (RSC) | triggers/develop/add-server-data.md | Данные в серверных компонентах. НЕ для: клиентских запросов (→ add-api-request) |
+| Задача | Триггер | Описание |
+|--------|---------|----------|
+| Добавить API-запрос | triggers/develop/add-api-request.md | Клиентский запрос данных через SWR |
+| Подключить стор | triggers/develop/connect-store.md | Подключение существующего стора к компоненту |
+| Серверные данные (RSC) | triggers/develop/add-server-data.md | Получение данных в серверных компонентах |
-## Инфраструктура
+### Инфраструктура
-| Задача | Триггер | Когда / Когда НЕ |
-|--------|---------|-------------------|
+| Задача | Триггер | Описание |
+|--------|---------|----------|
| Добавить перевод | triggers/develop/add-localization.md | Ключи перевода и подключение i18next |
-| Добавить зависимость | triggers/develop/add-dependency.md | Новая npm-библиотека. Проверь допустимость |
-| Настроить VS Code | triggers/develop/setup-vscode.md | Расширения, настройки, сниппеты |
+| Добавить зависимость | triggers/develop/add-dependency.md | Подключение новой npm-библиотеки |
+| Настроить VS Code | triggers/develop/setup-vscode.md | Расширения, настройки редактора, сниппеты |