chore: переместить 'Именование' после 'Технологии' в сайдбаре и конкатенации

- заменил жирное выделение на форматирование кодом
- добавил ссылку на раздел архитектуры для FSD
- обновил вводное описание раздела
- переименовал 'Fetch (API)' в 'Работа с данными (API)'

.vitepress/config.ts

@@ -9,9 +9,9 @@ const ruSidebar = [
     text: 'Базовые правила',
     items: [
       { text: 'Технологии и библиотеки', link: '/basics/tech-stack' },
+      { text: 'Именование', link: '/basics/naming' },
       { text: 'Архитектура', link: '/basics/architecture' },
       { text: 'Стиль кода', link: '/basics/code-style' },
-      { text: 'Именование', link: '/basics/naming' },
       { text: 'Документирование', link: '/basics/documentation' },
       { text: 'Типизация', link: '/basics/typing' },
     ],
@@ -22,6 +22,7 @@ const ruSidebar = [
       { text: 'Настройка VS Code', link: '/applied/vscode' },
       { text: 'Структура проекта', link: '/applied/project-structure' },
       { text: 'UI и компоненты', link: '/applied/components' },
+      { text: 'Компоненты (new)', link: '/applied/components-new' },
       { text: 'Страницы (App Router)', link: '/applied/page-level' },
       { text: 'Шаблоны и генерация кода', link: '/applied/templates-generation' },
       { text: 'Стили', link: '/applied/styles' },

concat-md.js

@@ -9,9 +9,9 @@ const fileOrder = [
   "workflow.md",
   // basics
   "basics/tech-stack.md",
+  "basics/naming.md",
   "basics/architecture.md",
   "basics/code-style.md",
-  "basics/naming.md",
   "basics/documentation.md",
   "basics/typing.md",
   // applied

docs/ru/basics/architecture.md

@@ -4,57 +4,67 @@ title: Архитектура
 
 # Архитектура
 
-Архитектура построена на FSD (`Feature‑Sliced Design`) и строгих границах модулей.
+Этот раздел описывает архитектуру проекта: из каких слоёв состоит приложение,
-Цель — разделить ответственность, упростить сопровождение и контроль зависимостей.
+как организован код внутри слоёв и какие правила управляют зависимостями.
 
-## Принципы
+## Что важно знать
 
-- Разделять UI, бизнес-логику и инфраструктуру.
+Проект использует [FSD (Feature-Sliced Design)](https://feature-sliced.design/docs/get-started/overview)
-- Держать зависимости однонаправленными.
+как базовую архитектурную методологию. Если вы не знакомы с FSD — начните с официальной документации.
-- Открывать наружу только публичный API модулей.
-- Не допускать циклических зависимостей.
 
-## Слои (FSD)
+Данная архитектура является **надстройкой над FSD**, а не заменой. Все правила FSD действуют
+по умолчанию — если правило явно не переопределено в этом документе, применяется стандарт FSD.
+Единственное отклонение: вместо слайсов используются **компоненты**.
 
-- **app** — инициализация приложения: провайдеры, глобальные стили. В Next.js эта же папка `app/` дополнительно содержит системные файлы роутинга (`layout.tsx`, `page.tsx`).
+## Слои
-- **screens** — UI-компоненты страниц. Каждый экран — отдельный компонент, который собирает виджеты и фичи конкретной страницы. Роутинг только использует эти компоненты — он не является частью слоя `screens`. В Next.js файлы `page.tsx` остаются тонкими: импортируют экран и рендерят его.
-- **layouts** — каркас и шаблоны страниц.
-- **widgets** — крупные блоки интерфейса, собирающие несколько сценариев.
-- **features** — отдельные пользовательские действия и сценарии.
-- **entities** — бизнес-сущности и их модель.
-- **shared** — переиспользуемая инфраструктура, утилиты и базовые UI‑компоненты.
 
-## Модули (FSD)
+| Слой | Назначение |
+|------|-----------|
+| `app` | Инициализация: провайдеры, стили, роутинг Next.js |
+| `screens` | Сборка страницы из виджетов и фич |
+| `layouts` | Каркасы и шаблоны страниц |
+| `widgets` | Крупные блоки интерфейса |
+| `features` | Пользовательские сценарии и действия |
+| `entities` | Бизнес-сущности |
+| `shared` | Утилиты, UI-кит, инфраструктура |
 
-- Модуль — это отдельная папка в слоях `screens`, `layouts`, `widgets`, `features`, `entities`, которая реализует один сценарий/блок. В корне модуля лежит главный файл (`*.screen.tsx`, `*.layout.tsx`, `*.widget.tsx`, `*.feature.tsx`, `*.entity.tsx`) и публичный API (`index.ts`).
+Слой `pages` не используется — конфликтует с Next.js. Вместо него: `screens` и `layouts`.
-- Внутри модуля используются подпапки (по необходимости):
-  - `ui/` — дочерние UI‑компоненты модуля.
-  - `model/` — состояние и бизнес‑логика модуля.
-  - `styles/` — локальные стили модуля.
-  - `helpers/` — локальные хелперы.
-  - `lib/` — утилиты модуля.
-  - `api/` — API‑вызовы модуля.
 
-## Правила зависимостей
+Зависимости идут строго сверху вниз: `app → screens → layouts → widgets → features → entities → shared`.
 
-- Допустимые импорты идут сверху вниз: `app → screens → layouts → widgets → features → entities → shared`.
+## Компоненты
-- Импорты между слоями — через публичный API.
-- Внутри одного слоя — относительные импорты.
 
-## Публичный API модулей
+Компонент — стандартная UI-единица, такая же как в любом React-проекте. Содержит корневой `.tsx`,
+публичный API (`index.ts`) и сегменты.
 
-- Каждый модуль экспортирует наружу только то, что нужно другим слоям.
+Компоненты располагаются в:
-- Внешние импорты идут только через `index`‑файл модуля.
+- `shared/ui/` — переиспользуемые компоненты без бизнес-контекста
-- Внутренние файлы не импортируются напрямую извне.
+- `ui/` внутри master component'а — дочерние компоненты *(подробнее в разделе [Master component](#master-component))*
 
-## Границы ответственности
+## Сегменты
 
-- Бизнес‑логика не размещается в UI‑компонентах.
+Сегмент — папка внутри компонента, группирующая код по техническому назначению. Набор не фиксирован.
-- UI‑компоненты должны быть максимально простыми и предсказуемыми.
-- Связь между независимыми сценариями поднимается на уровень выше.
 
-## Типовые ошибки
+| Сегмент | Назначение |
+|---------|-----------|
+| `styles/` | Стили |
+| `types/` | Интерфейсы, типы, enums, DTO |
+| `ui/` | Компоненты, провайдеры и любые другие элементы интерфейса |
+| `stores/` | Сторы состояния |
+| `hooks/` | React-хуки |
+| `services/` | Внешние источники данных |
+| `lib/` | Утилиты |
+| `helpers/` | Вспомогательные функции |
+| `config/` | Константы, конфигурация |
 
-- Импорт из более высокого слоя в более низкий.
+## Master component
-- Смешивание логики нескольких слоёв в одном модуле.
+
-- Прямые импорты внутренних файлов, минуя публичный API.
+Master component — это обычный компонент, на который наложен ряд дополнительных правил.
+Эти правила определяют его место в архитектуре и границы зависимостей.
+
+- Может располагаться только в слоях: `screens`, `layouts`, `widgets`, `features`, `entities`
+- Импортирует master component'ы только из слоёв ниже по иерархии
+- Корневой `.tsx` именуется с суффиксом слоя: `header.widget.tsx`, `auth.feature.tsx`
+- Корневой `.tsx` необязателен — `index.ts` может экспортировать несколько сущностей напрямую
+- Дочерние компоненты в `ui/` доступны снаружи только через `index.ts`
+- Компоненты внутри одного `ui/` могут импортировать друг друга

docs/ru/basics/documentation.md

@@ -4,7 +4,7 @@ title: Документирование
 
 # Документирование
 
-Документирование должно помогать понять назначение сущности, а не дублировать её типы или очевидные детали.
+Этот раздел описывает правила документирования кода: когда и как писать комментарии к функциям, компонентам, типам и интерфейсам.
 
 ## Правила
 

docs/ru/basics/naming.md

@@ -4,7 +4,7 @@ title: Именование
 
 # Именование
 
-Именование должно быть предсказуемым, коротким и отражать смысл сущности.
+Этот раздел описывает соглашения об именовании в проекте. Единые правила делают код предсказуемым и упрощают навигацию по проекту.
 
 ## Базовые правила
 
@@ -20,80 +20,60 @@ title: Именование
 | CSS классы       | `camelCase`            |
 
 
-## Архитектурный неймспейс
+## Именование файлов
 
-Соглашение о суффиксах, которые обозначают слой (уровень абстракции), роль или тип файла.
+Суффикс обозначает роль или тип файла. Пишется в единственном числе.
+Формат: `name.<suffix>.ts`.
 
-- Суффиксы используются для обозначения слоя, роли или типа файла.
+**Хуки**
-- Суффиксы всегда пишутся в единственном числе.
+- `use-name.hook.ts` — файл хука, функция именуется `useName`
-- Формат имени: `name.<suffix>.ts` или `name.<suffix>.tsx`.
 
-**UI и слои FSD**
+**Логика**
-- `.screen.tsx` — экран
-- `.layout.tsx` — layout
-- `.widget.tsx` — виджет
-- `.feature.tsx` — UI фичи
-- `.entity.tsx` — UI сущности
-
-Остальные `.tsx` файлы (компоненты в `shared/ui/`, дочерние компоненты в `ui/`) не помечаются суффиксами — расширение `.tsx` само по себе означает UI‑компонент.
-
-**Логика и модель**
 - `.store.ts` — стор
 - `.service.ts` — сервис
 
 **Типы и контракты**
 - `.type.ts` — типы и интерфейсы
-- `.interface.ts` — файл с интерфейсами (если нужен отдельный контракт)
+- `.interface.ts` — интерфейсы
 - `.enum.ts` — enum
 - `.dto.ts` — внешние DTO
 - `.schema.ts` — схемы валидации
 - `.constant.ts` — константы
 - `.config.ts` — конфигурация
 
-**Утилиты и хелперы**
+**Утилиты**
 - `.util.ts` — утилиты
 - `.helper.ts` — вспомогательные функции
-- `.lib.ts` — вспомогательные функции
+- `.lib.ts` — библиотечный код
 
 **Тесты**
-- `.test.ts` / `.test.tsx`
+- `.test.ts` — тесты
-- `.mock.ts`
+- `.mock.ts` — моки
-
 
 **Хорошо**
 ```text
-src/
+features/
-├── screens/
+└── auth-by-email/
-│   └── main/
+    ├── ui/
-│       ├── main.screen.tsx
+    │   └── login-form.tsx
-│       └── index.ts
+    ├── hooks/
-├── features/
+    │   └── use-auth.hook.ts
-│   └── auth-by-email/
+    ├── stores/
-│       ├── ui/
+    │   └── auth.store.ts
-│       │   └── login-form.tsx
+    ├── types/
-│       ├── auth-by-email.feature.tsx
+    │   └── auth.interface.ts
-│       └── index.ts
+    ├── auth-by-email.feature.tsx
-└── shared/
+    └── index.ts
-    └── ui/
-        └── icon/
-            ├── styles/
-            │   └── icon.module.css
-            ├── types/
-            │   └── icon.interface.ts
-            ├── icon.tsx
-            └── index.ts
 ```
 
 **Плохо**
 ```text
-// Плохо: нет единых правил для слоёв и публичных файлов.
+features/
-src/
+└── authByEmail/
-├── screens/
+    ├── LoginForm.tsx
-│   └── Main/
+    ├── useAuth.ts
-│       └── Main.tsx
+    ├── authStore.ts
-└── features/
+    └── index.ts
-    └── authByEmail/
-        └── login-form.tsx
 ```
 
 ## Булевы значения

docs/ru/basics/tech-stack.md

@@ -4,38 +4,38 @@ title: Технологии и библиотеки
 
 # Технологии и библиотеки
 
-Базовый стек технологий и библиотек, на который опираются проекты и примеры в документации.
+Этот раздел описывает базовый стек технологий и библиотек, принятый в проекте.
 
 ## Что используем
 
 ### Стек
-- **React/TypeScript** — основной стек для UI и приложения.
+- `React` / `TypeScript` — основной стек для UI и приложения.
-- **Next.js** — для продуктовых сайтов.
+- `Next.js` — для продуктовых сайтов.
 
 ### Архитектура
-- **FSD (Feature-Sliced Design)** — структура проекта и границы модулей.
+- `FSD (Feature-Sliced Design)` — структура проекта и границы модулей. Используется кастомизированная версия — подробнее в разделе [Архитектура](/basics/architecture).
 
 ### UI компоненты
-- **Mantine UI** — базовые UI-компоненты.
+- `Mantine UI` — базовые UI-компоненты.
 
-### Fetch (API)
+### Работа с данными (API)
-- **@gromlab/api-codegen** — генерация API‑клиентов и типов.
+- `@gromlab/api-codegen` — генерация API‑клиентов и типов.
-- **SWR** — получение, кеширование, ревалидация, дедубликация.
+- `SWR` — получение, кеширование, ревалидация, дедубликация.
-- **SWR (useSWRSubscription)** - сокеты, реалтайм подписки.
+- `SWR (useSWRSubscription)` — сокеты, реалтайм подписки.
 
 ### Store
-- **Zustand** — глобальное состояние.
+- `Zustand` — глобальное состояние.
 
 ### Локализация
-- **i18next (i18n)** — локализация всех пользовательских текстов.
+- `i18next (i18n)` — локализация всех пользовательских текстов.
 
 ### Тестирование
-- **Vitest** — тестирование.
+- `Vitest` — тестирование.
 
 ### Стили
-- **PostCSS Modules** — изоляция стилей.
+- `PostCSS Modules` — изоляция стилей.
-- **Mobile First** — подход к адаптивной верстке.
+- `Mobile First` — подход к адаптивной верстке.
-- **clsx** — конкатенация CSS‑классов.
+- `clsx` — конкатенация CSS‑классов.
 
 ### Генерация
-- **@gromlab/create** — шаблонизатор для создания слоёв и других файлов из шаблонов.
+- `@gromlab/create` — шаблонизатор для создания слоёв и других файлов из шаблонов.

docs/ru/basics/typing.md

@@ -4,8 +4,7 @@ title: Типизация
 
 # Типизация
 
-Типизация обязательна для всех публичных интерфейсов, функций и компонентов.
+Этот раздел описывает правила типизации: как типизировать компоненты, функции и работу с `any`/`unknown`.
-Цель — предсказуемость, безопасность и автодополнение.
 
 ## Общие правила
 

generated/en/RULES.md

@@ -62,6 +62,11 @@ Full documentation in a single MD file: https://gromlab.ru/docs/frontend-style-g
 
 Base technology stack and libraries used in projects.
 
+<!-- /basics/naming -->
+## Naming
+
+Naming should be predictable, concise, and reflect the meaning of the entity.
+
 <!-- /basics/architecture -->
 ## Architecture
 
@@ -72,11 +77,6 @@ Architecture based on FSD (Feature-Sliced Design) and strict module boundaries.
 
 Unified code formatting rules: indentation, line breaks, quotes, import order, and readability.
 
-<!-- /basics/naming -->
-## Naming
-
-Naming should be predictable, concise, and reflect the meaning of the entity.
-
 <!-- /basics/documentation -->
 ## Documentation
 

generated/ru/RULES.md

@@ -64,14 +64,6 @@
 
 Порядок действий при разработке — от создания проекта до реализации фич.
 
-### Начало работы
-
-Подготовка окружения перед началом разработки.
-
-1. Открыть проект в VS Code.
-2. Установить рекомендуемые расширения (редактор предложит автоматически).
-3. Ознакомиться со стеком: Next.js (App Router), Mantine, Zustand, FSD.
-
 ### Создание проекта
 
 Инициализация нового проекта из готового шаблона.
@@ -155,99 +147,245 @@
 <!-- /basics/tech-stack -->
 ## Технологии и библиотеки
 
-Базовый стек технологий и библиотек, на который опираются проекты и примеры в документации.
+Этот раздел описывает базовый стек технологий и библиотек, принятый в проекте.
 
 ### Что используем
 
 #### Стек
-- **React/TypeScript** — основной стек для UI и приложения.
+- `React` / `TypeScript` — основной стек для UI и приложения.
-- **Next.js** — для продуктовых сайтов.
+- `Next.js` — для продуктовых сайтов.
 
 #### Архитектура
-- **FSD (Feature-Sliced Design)** — структура проекта и границы модулей.
+- `FSD (Feature-Sliced Design)` — структура проекта и границы модулей. Используется кастомизированная версия — подробнее в разделе [Архитектура](/basics/architecture).
 
 #### UI компоненты
-- **Mantine UI** — базовые UI-компоненты.
+- `Mantine UI` — базовые UI-компоненты.
 
-#### Fetch (API)
+#### Работа с данными (API)
-- **@gromlab/api-codegen** — генерация API‑клиентов и типов.
+- `@gromlab/api-codegen` — генерация API‑клиентов и типов.
-- **SWR** — получение, кеширование, ревалидация, дедубликация.
+- `SWR` — получение, кеширование, ревалидация, дедубликация.
-- **SWR (useSWRSubscription)** - сокеты, реалтайм подписки.
+- `SWR (useSWRSubscription)` — сокеты, реалтайм подписки.
 
 #### Store
-- **Zustand** — глобальное состояние.
+- `Zustand` — глобальное состояние.
 
 #### Локализация
-- **i18next (i18n)** — локализация всех пользовательских текстов.
+- `i18next (i18n)` — локализация всех пользовательских текстов.
 
 #### Тестирование
-- **Vitest** — тестирование.
+- `Vitest` — тестирование.
 
 #### Стили
-- **PostCSS Modules** — изоляция стилей.
+- `PostCSS Modules` — изоляция стилей.
-- **Mobile First** — подход к адаптивной верстке.
+- `Mobile First` — подход к адаптивной верстке.
-- **clsx** — конкатенация CSS‑классов.
+- `clsx` — конкатенация CSS‑классов.
 
 #### Генерация
-- **@gromlab/create** — шаблонизатор для создания слоёв и других файлов из шаблонов.
+- `@gromlab/create` — шаблонизатор для создания слоёв и других файлов из шаблонов.
+
+<!-- /basics/naming -->
+## Именование
+
+Этот раздел описывает соглашения об именовании в проекте. Единые правила делают код предсказуемым и упрощают навигацию по проекту.
+
+### Базовые правила
+
+| Что              | Рекомендуется          |
+| ---------------- | ---------------------- |
+| Папки            | `kebab-case`           |
+| Файлы            | `kebab-case`           |
+| Переменные       | `camelCase`            |
+| Константы        | `SCREAMING_SNAKE_CASE` |
+| Классы           | `PascalCase`           |
+| React-компоненты | `PascalCase`           |
+| Хуки             | `useSomething`         |
+| CSS классы       | `camelCase`            |
+
+
+### Именование файлов
+
+Суффикс обозначает роль или тип файла. Пишется в единственном числе.
+Формат: `name.<suffix>.ts`.
+
+**Хуки**
+- `use-name.hook.ts` — файл хука, функция именуется `useName`
+
+**Логика**
+- `.store.ts` — стор
+- `.service.ts` — сервис
+
+**Типы и контракты**
+- `.type.ts` — типы и интерфейсы
+- `.interface.ts` — интерфейсы
+- `.enum.ts` — enum
+- `.dto.ts` — внешние DTO
+- `.schema.ts` — схемы валидации
+- `.constant.ts` — константы
+- `.config.ts` — конфигурация
+
+**Утилиты**
+- `.util.ts` — утилиты
+- `.helper.ts` — вспомогательные функции
+- `.lib.ts` — библиотечный код
+
+**Тесты**
+- `.test.ts` — тесты
+- `.mock.ts` — моки
+
+**Хорошо**
+```text
+features/
+└── auth-by-email/
+    ├── ui/
+    │   └── login-form.tsx
+    ├── hooks/
+    │   └── use-auth.hook.ts
+    ├── stores/
+    │   └── auth.store.ts
+    ├── types/
+    │   └── auth.interface.ts
+    ├── auth-by-email.feature.tsx
+    └── index.ts
+```
+
+**Плохо**
+```text
+features/
+└── authByEmail/
+    ├── LoginForm.tsx
+    ├── useAuth.ts
+    ├── authStore.ts
+    └── index.ts
+```
+
+### Булевы значения
+
+- Использовать префиксы `is`, `has`, `can`, `should`.
+
+**Хорошо**
+```ts
+const isReady = true;
+const hasAccess = false;
+const canSubmit = true;
+const shouldRedirect = false;
+```
+
+**Плохо**
+```ts
+// Плохо: неясное булево значение без префикса.
+const ready = true;
+const access = false;
+const submit = true;
+```
+
+### События и обработчики
+
+- Обработчики начинать с `handle`.
+- События и колбэки начинать с `on`.
+
+**Хорошо**
+```ts
+const handleSubmit = () => { ... };
+const onSubmit = () => { ... };
+```
+
+**Плохо**
+```ts
+// Плохо: неочевидное назначение имени.
+const submitClick = () => { ... };
+```
+
+### Коллекции
+
+- Для массивов использовать имена во множественном числе.
+- Для словарей/мап — использовать суффиксы `ById`, `Map`, `Dict`.
+
+**Хорошо**
+```ts
+const users = [];
+const usersById = {} as Record<string, User>;
+const userIds = ['u1', 'u2'];
+const ordersMap = new Map<string, Order>();
+const featureFlagsDict = { beta: true, legacy: false } as Record<string, boolean>;
+```
+
+**Плохо**
+```ts
+// Плохо: имя не отражает, что это коллекция.
+const user = [];
+// Плохо: словарь назван как массив.
+const usersMap = [];
+// Плохо: по имени непонятно, что это словарь.
+const users = {} as Record<string, User>;
+```
 
 <!-- /basics/architecture -->
 ## Архитектура
 
-Архитектура построена на FSD (`Feature‑Sliced Design`) и строгих границах модулей.
+Этот раздел описывает архитектуру проекта: из каких слоёв состоит приложение,
-Цель — разделить ответственность, упростить сопровождение и контроль зависимостей.
+как организован код внутри слоёв и какие правила управляют зависимостями.
 
-### Принципы
+### Что важно знать
 
-- Разделять UI, бизнес-логику и инфраструктуру.
+Проект использует [FSD (Feature-Sliced Design)](https://feature-sliced.design/docs/get-started/overview)
-- Держать зависимости однонаправленными.
+как базовую архитектурную методологию. Если вы не знакомы с FSD — начните с официальной документации.
-- Открывать наружу только публичный API модулей.
-- Не допускать циклических зависимостей.
 
-### Слои (FSD)
+Данная архитектура является **надстройкой над FSD**, а не заменой. Все правила FSD действуют
+по умолчанию — если правило явно не переопределено в этом документе, применяется стандарт FSD.
+Единственное отклонение: вместо слайсов используются **компоненты**.
 
-- **app** — инициализация приложения: провайдеры, глобальные стили. В Next.js эта же папка `app/` дополнительно содержит системные файлы роутинга (`layout.tsx`, `page.tsx`).
+### Слои
-- **screens** — UI-компоненты страниц. Каждый экран — отдельный компонент, который собирает виджеты и фичи конкретной страницы. Роутинг только использует эти компоненты — он не является частью слоя `screens`. В Next.js файлы `page.tsx` остаются тонкими: импортируют экран и рендерят его.
-- **layouts** — каркас и шаблоны страниц.
-- **widgets** — крупные блоки интерфейса, собирающие несколько сценариев.
-- **features** — отдельные пользовательские действия и сценарии.
-- **entities** — бизнес-сущности и их модель.
-- **shared** — переиспользуемая инфраструктура, утилиты и базовые UI‑компоненты.
 
-### Модули (FSD)
+| Слой | Назначение |
+|------|-----------|
+| `app` | Инициализация: провайдеры, стили, роутинг Next.js |
+| `screens` | Сборка страницы из виджетов и фич |
+| `layouts` | Каркасы и шаблоны страниц |
+| `widgets` | Крупные блоки интерфейса |
+| `features` | Пользовательские сценарии и действия |
+| `entities` | Бизнес-сущности |
+| `shared` | Утилиты, UI-кит, инфраструктура |
 
-- Модуль — это отдельная папка в слоях `screens`, `layouts`, `widgets`, `features`, `entities`, которая реализует один сценарий/блок. В корне модуля лежит главный файл (`*.screen.tsx`, `*.layout.tsx`, `*.widget.tsx`, `*.feature.tsx`, `*.entity.tsx`) и публичный API (`index.ts`).
+Слой `pages` не используется — конфликтует с Next.js. Вместо него: `screens` и `layouts`.
-- Внутри модуля используются подпапки (по необходимости):
-  - `ui/` — дочерние UI‑компоненты модуля.
-  - `model/` — состояние и бизнес‑логика модуля.
-  - `styles/` — локальные стили модуля.
-  - `helpers/` — локальные хелперы.
-  - `lib/` — утилиты модуля.
-  - `api/` — API‑вызовы модуля.
 
-### Правила зависимостей
+Зависимости идут строго сверху вниз: `app → screens → layouts → widgets → features → entities → shared`.
 
-- Допустимые импорты идут сверху вниз: `app → screens → layouts → widgets → features → entities → shared`.
+### Компоненты
-- Импорты между слоями — через публичный API.
-- Внутри одного слоя — относительные импорты.
 
-### Публичный API модулей
+Компонент — стандартная UI-единица, такая же как в любом React-проекте. Содержит корневой `.tsx`,
+публичный API (`index.ts`) и сегменты.
 
-- Каждый модуль экспортирует наружу только то, что нужно другим слоям.
+Компоненты располагаются в:
-- Внешние импорты идут только через `index`‑файл модуля.
+- `shared/ui/` — переиспользуемые компоненты без бизнес-контекста
-- Внутренние файлы не импортируются напрямую извне.
+- `ui/` внутри master component'а — дочерние компоненты *(подробнее в разделе [Master component](#master-component))*
 
-### Границы ответственности
+### Сегменты
 
-- Бизнес‑логика не размещается в UI‑компонентах.
+Сегмент — папка внутри компонента, группирующая код по техническому назначению. Набор не фиксирован.
-- UI‑компоненты должны быть максимально простыми и предсказуемыми.
-- Связь между независимыми сценариями поднимается на уровень выше.
 
-### Типовые ошибки
+| Сегмент | Назначение |
+|---------|-----------|
+| `styles/` | Стили |
+| `types/` | Интерфейсы, типы, enums, DTO |
+| `ui/` | Компоненты, провайдеры и любые другие элементы интерфейса |
+| `stores/` | Сторы состояния |
+| `hooks/` | React-хуки |
+| `services/` | Внешние источники данных |
+| `lib/` | Утилиты |
+| `helpers/` | Вспомогательные функции |
+| `config/` | Константы, конфигурация |
 
-- Импорт из более высокого слоя в более низкий.
+### Master component
-- Смешивание логики нескольких слоёв в одном модуле.
+
-- Прямые импорты внутренних файлов, минуя публичный API.
+Master component — это обычный компонент, на который наложен ряд дополнительных правил.
+Эти правила определяют его место в архитектуре и границы зависимостей.
+
+- Может располагаться только в слоях: `screens`, `layouts`, `widgets`, `features`, `entities`
+- Импортирует master component'ы только из слоёв ниже по иерархии
+- Корневой `.tsx` именуется с суффиксом слоя: `header.widget.tsx`, `auth.feature.tsx`
+- Корневой `.tsx` необязателен — `index.ts` может экспортировать несколько сущностей напрямую
+- Дочерние компоненты в `ui/` доступны снаружи только через `index.ts`
+- Компоненты внутри одного `ui/` могут импортировать друг друга
 
 <!-- /basics/code-style -->
 ## Стиль кода
@@ -399,166 +537,10 @@ const options = { id: 1,name: 'User' };
 const config = { url: '/api/users', method: 'GET', params: { page: 1, pageSize: 20 } };
 ```
 
-<!-- /basics/naming -->
-## Именование
-
-Именование должно быть предсказуемым, коротким и отражать смысл сущности.
-
-### Базовые правила
-
-| Что              | Рекомендуется          |
-| ---------------- | ---------------------- |
-| Папки            | `kebab-case`           |
-| Файлы            | `kebab-case`           |
-| Переменные       | `camelCase`            |
-| Константы        | `SCREAMING_SNAKE_CASE` |
-| Классы           | `PascalCase`           |
-| React-компоненты | `PascalCase`           |
-| Хуки             | `useSomething`         |
-| CSS классы       | `camelCase`            |
-
-
-### Архитектурный неймспейс
-
-Соглашение о суффиксах, которые обозначают слой (уровень абстракции), роль или тип файла.
-
-- Суффиксы используются для обозначения слоя, роли или типа файла.
-- Суффиксы всегда пишутся в единственном числе.
-- Формат имени: `name.<suffix>.ts` или `name.<suffix>.tsx`.
-
-**UI и слои FSD**
-- `.screen.tsx` — экран
-- `.layout.tsx` — layout
-- `.widget.tsx` — виджет
-- `.feature.tsx` — UI фичи
-- `.entity.tsx` — UI сущности
-
-Остальные `.tsx` файлы (компоненты в `shared/ui/`, дочерние компоненты в `ui/`) не помечаются суффиксами — расширение `.tsx` само по себе означает UI‑компонент.
-
-**Логика и модель**
-- `.store.ts` — стор
-- `.service.ts` — сервис
-
-**Типы и контракты**
-- `.type.ts` — типы и интерфейсы
-- `.interface.ts` — файл с интерфейсами (если нужен отдельный контракт)
-- `.enum.ts` — enum
-- `.dto.ts` — внешние DTO
-- `.schema.ts` — схемы валидации
-- `.constant.ts` — константы
-- `.config.ts` — конфигурация
-
-**Утилиты и хелперы**
-- `.util.ts` — утилиты
-- `.helper.ts` — вспомогательные функции
-- `.lib.ts` — вспомогательные функции
-
-**Тесты**
-- `.test.ts` / `.test.tsx`
-- `.mock.ts`
-
-
-**Хорошо**
-```text
-src/
-├── screens/
-│   └── main/
-│       ├── main.screen.tsx
-│       └── index.ts
-├── features/
-│   └── auth-by-email/
-│       ├── ui/
-│       │   └── login-form.tsx
-│       ├── auth-by-email.feature.tsx
-│       └── index.ts
-└── shared/
-    └── ui/
-        └── icon/
-            ├── styles/
-            │   └── icon.module.css
-            ├── types/
-            │   └── icon.interface.ts
-            ├── icon.tsx
-            └── index.ts
-```
-
-**Плохо**
-```text
-// Плохо: нет единых правил для слоёв и публичных файлов.
-src/
-├── screens/
-│   └── Main/
-│       └── Main.tsx
-└── features/
-    └── authByEmail/
-        └── login-form.tsx
-```
-
-### Булевы значения
-
-- Использовать префиксы `is`, `has`, `can`, `should`.
-
-**Хорошо**
-```ts
-const isReady = true;
-const hasAccess = false;
-const canSubmit = true;
-const shouldRedirect = false;
-```
-
-**Плохо**
-```ts
-// Плохо: неясное булево значение без префикса.
-const ready = true;
-const access = false;
-const submit = true;
-```
-
-### События и обработчики
-
-- Обработчики начинать с `handle`.
-- События и колбэки начинать с `on`.
-
-**Хорошо**
-```ts
-const handleSubmit = () => { ... };
-const onSubmit = () => { ... };
-```
-
-**Плохо**
-```ts
-// Плохо: неочевидное назначение имени.
-const submitClick = () => { ... };
-```
-
-### Коллекции
-
-- Для массивов использовать имена во множественном числе.
-- Для словарей/мап — использовать суффиксы `ById`, `Map`, `Dict`.
-
-**Хорошо**
-```ts
-const users = [];
-const usersById = {} as Record<string, User>;
-const userIds = ['u1', 'u2'];
-const ordersMap = new Map<string, Order>();
-const featureFlagsDict = { beta: true, legacy: false } as Record<string, boolean>;
-```
-
-**Плохо**
-```ts
-// Плохо: имя не отражает, что это коллекция.
-const user = [];
-// Плохо: словарь назван как массив.
-const usersMap = [];
-// Плохо: по имени непонятно, что это словарь.
-const users = {} as Record<string, User>;
-```
-
 <!-- /basics/documentation -->
 ## Документирование
 
-Документирование должно помогать понять назначение сущности, а не дублировать её типы или очевидные детали.
+Этот раздел описывает правила документирования кода: когда и как писать комментарии к функциям, компонентам, типам и интерфейсам.
 
 ### Правила
 
@@ -620,8 +602,7 @@ export enum TodoFilter {
 <!-- /basics/typing -->
 ## Типизация
 
-Типизация обязательна для всех публичных интерфейсов, функций и компонентов.
+Этот раздел описывает правила типизации: как типизировать компоненты, функции и работу с `any`/`unknown`.
-Цель — предсказуемость, безопасность и автодополнение.
 
 ### Общие правила