nextjs-style-guide/generated/ru/RULES.md

<!-- /index -->
# NextJS Style Guide

Правила и стандарты разработки на NextJS и TypeScript: архитектура, типизация, стили, компоненты, API и инфраструктурные разделы.

## Для ассистентов

Полная документация в одном MD файле: https://gromlab.ru/docs/nextjs-style-guide/raw/branch/main/generated/ru/RULES.md

## Структура документации

### Workflow

**Что делать и в каком порядке** — пошаговые инструкции.

| Раздел | Отвечает на вопрос |
|--------|-------------------|
| Начало работы | Что нужно знать перед началом разработки? |
| Создание проекта | Как начать новый проект? |
| Генерация кода | Какие модули должны генерироваться из шаблонов? |
| Добавление страницы | Как добавить новую страницу в проект? |
| Добавление UI-модуля | Как создать компонент, фичу, виджет, сущность или layout? |
| Стилизация | Как стилизовать компоненты в проекте? |
| Получение данных | Как получать данные с сервера? |
| Управление состоянием | Как работать с состоянием? |
| Локализация | Как добавлять переводы и подключать локализацию? |

### Базовые правила

**Каким должен быть код** — стандарты, не привязанные к конкретной технологии.

| Раздел | Отвечает на вопрос |
|--------|-------------------|
| Технологии и библиотеки | Какой стек используем? |
| Архитектура | Как устроены слои FSD, зависимости, публичный API? |
| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
| Именование | Как называть файлы, переменные, компоненты, хуки? |
| Документирование | Как писать JSDoc: что документировать, а что нет? |
| Типизация | Как типизировать: type vs interface, any/unknown? |

### Прикладные разделы

**Как это настроить и использовать** — конфигурация, структура и примеры кода для конкретных областей.

| Раздел | Отвечает на вопрос |
|--------|-------------------|
| Настройка VS Code | Как настроить редактор для проекта? |
| Структура проекта | Как организованы папки и файлы по FSD? |
| Компоненты | Как устроен компонент: файлы, пропсы, clsx? |
| Page-level компоненты | Как описывать layout, page, loading, error, not-found? |
| Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? |
| Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? |
| Изображения | _(не заполнен)_ |
| SVG-спрайты | _(не заполнен)_ |
| Видео | _(не заполнен)_ |
| API | _(не заполнен)_ |
| Stores | _(не заполнен)_ |
| Хуки | _(не заполнен)_ |
| Шрифты | _(не заполнен)_ |
| Локализация | _(не заполнен)_ |

<!-- /workflow -->
## Workflow

Порядок действий при разработке — от создания проекта до реализации фич.

### Создание проекта

Инициализация нового проекта из готового шаблона.

1. Создать проект из шаблона:
   ```bash
   npx tiged git@gromlab.ru:templates/nextjs.git my-app
   cd my-app
   npm install
   ```
2. Проект готов к разработке — стек, структура FSD, конфигурация
   редактора и шаблоны генерации уже настроены.

### Генерация кода

Создание модулей из шаблонов `.templates/` вместо ручного создания файлов.

1. Определить тип модуля и соответствующий шаблон:

   | Модуль     | Слой         | Шаблон      |
   |------------|--------------|-------------|
   | Компонент  | `shared/ui/` | `component` |
   | Фича       | `features/`  | `feature`   |
   | Виджет     | `widgets/`   | `widget`    |
   | Сущность   | `entities/`  | `entity`    |
   | Layout     | `layouts/`   | `layout`    |
   | Экран      | `screens/`   | `screen`    |
   | Стор       | `model/`     | `store`     |

2. Сгенерировать модуль из шаблона.
3. Если подходящего шаблона нет — сначала создать шаблон, затем использовать.

Ручное создание файловой структуры модулей запрещено.

### Добавление страницы

Создание нового маршрута: экран + точка входа для роутинга.

1. Сгенерировать экран из шаблона `screen` в `src/screens/`.
2. Заполнить экран логикой и стилями.
3. Создать `page.tsx` в нужном маршруте `src/app/`.

`page.tsx` — тонкая обёртка: только `metadata` и рендер экрана.
Логика, стили и хуки размещаются в экране, не в `page.tsx`.

### Добавление UI-модуля

Создание компонента, фичи, виджета, сущности или layout.

1. Сгенерировать модуль из соответствующего шаблона в целевой слой.
2. Заполнить модуль логикой и стилями.
3. Дочерние компоненты — генерировать из шаблона `component` в папку `ui/`
   внутри родителя.

Дочерние компоненты не экспортируются через `index.ts` родителя.

### Стилизация

Выбор инструмента стилизации по приоритету.

1. Использовать Mantine-компоненты и их пропсы.
2. Если Mantine не покрывает — использовать CSS-токены
   (`--color-*`, `--space-*`, `--radius-*`).
3. Если нужна кастомная стилизация — PostCSS Modules.

Инлайн-стили (`style`), магические значения и глобальные стили
вне `app/styles/` запрещены.

### Получение данных

*Раздел в разработке* — SWR, генерация API-клиентов, сокеты.

### Управление состоянием

*Раздел в разработке* — когда создавать стор, что хранить локально и глобально.

### Локализация

*Раздел в разработке* — переводы и i18next.

<!-- /basics/tech-stack -->
## Технологии и библиотеки

Этот раздел описывает базовый стек технологий и библиотек, принятый в проекте.

### Что используем

#### Стек
- `React` / `TypeScript` — основной стек для UI и приложения.
- `Next.js` — для продуктовых сайтов.

#### Архитектура
- `FSD (Feature-Sliced Design)` — структура проекта и границы модулей. Используется кастомизированная версия — подробнее в разделе [Архитектура](/basics/architecture).

#### UI компоненты
- `Mantine UI` — базовые UI-компоненты.

#### Работа с данными (API)
- `@gromlab/api-codegen` — генерация API‑клиентов и типов.
- `SWR` — получение, кеширование, ревалидация, дедубликация.
- `SWR (useSWRSubscription)` — сокеты, реалтайм подписки.

#### Store
- `Zustand` — глобальное состояние.

#### Локализация
- `i18next (i18n)` — локализация всех пользовательских текстов.

#### Тестирование
- `Vitest` — тестирование.

#### Стили
- `PostCSS Modules` — изоляция стилей.
- `Mobile First` — подход к адаптивной верстке.
- `clsx` — конкатенация CSS‑классов.

#### Генерация
- `@gromlab/create` — шаблонизатор для создания слоёв и других файлов из шаблонов.

<!-- /basics/naming -->
## Именование

Этот раздел описывает соглашения об именовании в проекте. Единые правила делают код предсказуемым и упрощают навигацию по проекту.

### Базовые правила

| Что              | Рекомендуется          |
| ---------------- | ---------------------- |
| Папки            | `kebab-case`           |
| Файлы            | `kebab-case`           |
| Переменные       | `camelCase`            |
| Константы        | `SCREAMING_SNAKE_CASE` |
| Классы           | `PascalCase`           |
| React-компоненты | `PascalCase`           |
| Хуки             | `useSomething`         |
| CSS классы       | `camelCase`            |
| Ключи enum       | `SCREAMING_SNAKE_CASE` |


### Именование файлов

Суффикс обозначает роль или тип файла. Пишется в единственном числе.
Формат: `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 -->
## Архитектура

Раздел описывает архитектуру проекта: из каких слоёв состоит приложение,
как организован код внутри слоёв и какие правила управляют зависимостями.

### Что нужно знать

SLM Design (Scoped Layered Module Design) — архитектурный подход
к проектированию фронтенд-приложений, предложенный Громовым Сергеем в 2026 г.

Вырос на основе:

- [Feature-Sliced Design](https://feature-sliced.design) — слои и направление зависимостей
- Screaming Architecture — структура говорит сама за себя
- Colocation Principle — код рядом с местом использования

Переосмыслив эти подходы, SLM Design отличается от FSD в трёх аспектах:
где живёт код (колокация), как он организован (модули)
и как масштабируется (подъём при переиспользовании).

### Терминология

Архитектура оперирует четырьмя ключевыми понятиями:

- **Слой** — содержит модули
- **Модуль** — содержит сегменты
- **Компонент** — содержит сегменты
- **Сегмент** — папка внутри модуля или компонента, группирующая код по назначению: UI-элементы (`ui/`), хуки (`hooks/`), типы (`types/`), стили (`styles/`) и другие

Модуль и компонент устроены одинаково — оба имеют сегменты. Разница в том, где они живут и обязателен ли UI.

```text
Слой
└── Модуль
    ├── Сегменты (hooks/, stores/, types/, styles/, lib/...)
    └── ui/
        └── Компонент
            ├── Сегменты (hooks/, stores/, types/, styles/, lib/...)
            └── ui/
                └── Компонент → ...
```

#### Слой

Архитектурный уровень. Содержит только модули. Определяет назначение кода и правила зависимостей.

#### Модуль

Единица первого уровня слоя, объединённая по смыслу. Может содержать компонент, логику, типы, стили — или любую комбинацию. Имеет публичный API (`index.ts`) и внутреннюю структуру из сегментов.

Модуль — не обязательно UI. Feature `analytics` может быть только стором и сервисом. Entity `session` может быть только типами и хуком.

Модуль не может содержать вложенных модулей. Вложенные единицы с UI размещаются в сегменте `ui/` как компоненты.

#### Компонент

Вложенная единица внутри сегмента `ui/` модуля (или другого компонента). Публичный `.tsx` файл обязателен. Именуется без суффикса слоя.

Компонент может иметь собственные сегменты (`hooks/`, `styles/`, `types/` и т.д.), `index.ts` и свой `ui/` с ещё более вложенными компонентами.

Отличия от модуля:

| | Модуль | Компонент |
|--|--------|-----------|
| Где живёт | В корне слоя | В `ui/` модуля или другого компонента |
| Публичный `.tsx` | С суффиксом слоя, опционален | Без суффикса, обязателен |
| Может не иметь UI | Да | Нет |

Пример:

```text
features/auth-by-email/                        # модуль
├── auth-by-email.feature.tsx                  # публичный .tsx модуля (с суффиксом, опционален)
├── ui/                                        # сегмент: компоненты
│   ├── login-form/                            # компонент
│   │   ├── login-form.tsx                     # публичный .tsx компонента (без суффикса, обязателен)
│   │   ├── ui/                                # вложенные компоненты
│   │   │   └── password-field/
│   │   │       └── password-field.tsx
│   │   ├── hooks/
│   │   │   └── use-validation.hook.ts
│   │   ├── styles/
│   │   │   └── login-form.module.css
│   │   └── index.ts
│   └── reset-password/                        # компонент
│       ├── reset-password.tsx
│       └── index.ts
├── hooks/
│   └── use-auth.hook.ts
├── stores/
│   └── auth.store.ts
└── index.ts
```

#### Сегмент

Техническая папка внутри модуля или компонента, группирующая код по назначению. Набор не фиксирован — включаются только те сегменты, которые нужны.

| Сегмент | Назначение |
|---------|-----------|
| `ui/` | Вложенные компоненты |
| `hooks/` | React-хуки |
| `stores/` | Сторы состояния |
| `types/` | Интерфейсы, типы, enums, DTO |
| `styles/` | Стили |
| `lib/` | Утилиты |
| `services/` | Внешние источники данных |
| `helpers/` | Вспомогательные функции |
| `config/` | Константы, конфигурация |

### Ключевой принцип

> Модуль живёт на самом низком уровне, где он используется.
> Поднимается выше только при переиспользовании в 2+ местах.

Если модуль используется только в одном месте — он остаётся на текущем уровне.
Как только он начинает использоваться в 2+ местах — выносится на уровень выше.
В крайнем случае — в `shared/`, где он доступен всем.

### Слои

Каждый нижний слой не знает о существовании верхних. Импорты идут строго сверху вниз.

```
app → layouts → screens → widgets → features → entities → shared
```

| Слой | Что лежит | Импортирует |
|------|-----------|-------------|
| **App** | Роутинг, провайдеры, глобальные стили. Композиция layout + screen для маршрута. | Все слои ниже |
| **Layouts** | Каркас страницы, общий для группы маршрутов. | widgets, features, entities, shared |
| **Screens** | Контент конкретной страницы. | widgets, features, entities, shared |
| **Widgets** | Составные блоки с данными/логикой, переиспользуемые в 2+ местах. | features, entities, shared |
| **Features** | Пользовательское действие или интерактивный сценарий. | entities, shared |
| **Entities** | Бизнес-сущность с отображением и типами. | shared |
| **Shared** | Переиспользуемые компоненты, утилиты, стили без бизнес-логики. | ничего |

Принципы:

- Импорты строго сверху вниз
- Модули одного слоя не знают друг о друге
- Layout получает контекстно-зависимые блоки через пропсы от app, а не импортирует их сам
- `entities/` и `features/` создаются осознанно — это не результат «вынесения» компонента из screen

#### App

Точка входа приложения: роутинг (Next.js App Router), провайдеры, глобальные стили.
Находится на самом высоком уровне абстракции — может импортировать любой слой ниже.
Никакой бизнес-логики — только композиция.

```text
app/
├── layout.tsx              # RootLayout: провайдеры, глобальные стили
├── page.tsx                # Главная: MainLayout + HomeScreen
├── knv-new/
│   └── page.tsx            # КНВ: MainLayout + KnvScreen
└── catalog/
    └── page.tsx            # Каталог: MainLayout + CatalogScreen
```

```tsx
// app/knv-new/page.tsx
import { MainLayout } from '@/layouts/main'
import { KnvScreen } from '@/screens/knv'

export default function KnvNewPage() {
  return (
    <MainLayout>
      <KnvScreen />
    </MainLayout>
  )
}
```

Если layout требует разный контент в зависимости от страницы — app передаёт его через пропсы:

```tsx
// app/knv-new/page.tsx
import { MainLayout } from '@/layouts/main'
import { KnvScreen } from '@/screens/knv'
import { KnvHeader } from '@/widgets/knv-header'

export default function KnvNewPage() {
  return (
    <MainLayout header={<KnvHeader />}>
      <KnvScreen />
    </MainLayout>
  )
}
```

#### Layouts

Каркас страницы — общие элементы, одинаковые для группы маршрутов (header, footer, sidebar).

Если компонент внутри layout начинает использоваться в 2+ местах — он выносится в `widgets/` или `shared/ui/`.

```text
src/layouts/
└── main/
    ├── main.layout.tsx
    ├── ui/
    │   ├── header/
    │   │   └── header.tsx
    │   └── footer/
    │       └── footer.tsx
    └── index.ts
```

#### Screens

Контент конкретной страницы. Собирает локальные секции и переиспользуемые модули из нижних слоёв.

Если компонент внутри screen начинает использоваться в 2+ местах — он выносится в `widgets/` или `shared/ui/`.

```text
src/screens/
└── knv/
    ├── knv.screen.tsx
    ├── ui/
    │   ├── hero-section/
    │   │   └── hero-section.tsx
    │   ├── products-section/
    │   │   └── products-section.tsx
    │   └── diseases-section/
    │       └── diseases-section.tsx
    └── index.ts
```

#### Widgets

Составные блоки с данными и логикой, переиспользуемые в 2+ местах.

Если блок с логикой нужен только в одном месте — это компонент внутри `screens/{name}/ui/` или `layouts/{name}/ui/`, а не widget.

```text
src/widgets/
└── popular-products-slider/
    ├── popular-products-slider.widget.tsx
    ├── ui/
    │   └── slider-card/
    │       └── slider-card.tsx
    ├── hooks/
    │   └── use-products.hook.ts
    └── index.ts
```

#### Features

Пользовательское действие или интерактивный сценарий: авторизация, заказ, добавление в корзину.

Feature создаётся осознанно, когда есть действие пользователя с бизнес-логикой. Компонент опционален — feature может экспортировать хуки, сторы, компоненты или всё вместе.

```text
src/features/
└── auth-by-email/
    ├── auth-by-email.feature.tsx
    ├── ui/
    │   ├── login-form/
    │   │   └── login-form.tsx
    │   └── reset-password/
    │       └── reset-password.tsx
    ├── hooks/
    │   └── use-auth.hook.ts
    ├── stores/
    │   └── auth.store.ts
    └── index.ts
```

#### Entities

Бизнес-сущность с отображением и типами: препарат, заболевание, врач, пользователь.

Entity создаётся осознанно, когда появляется бизнес-сущность. Компонент опционален — entity может быть только типами и хуком.

Отличие от `shared/ui/`: entity-компонент знает о бизнес-домене (принимает `Product`, а не абстрактные пропсы).

```text
src/entities/
├── product/
│   ├── product.entity.tsx
│   ├── ui/
│   │   └── product-card/
│   │       └── product-card.tsx
│   ├── types/
│   │   └── product.type.ts
│   └── index.ts
│
├── session/
│   ├── types/
│   │   └── session.type.ts
│   ├── hooks/
│   │   └── use-session.hook.ts
│   └── index.ts
```

#### Shared

Переиспользуемые компоненты, утилиты, стили без бизнес-логики. Не знает о бизнес-домене — работает с абстрактными данными.

Структурирован как набор сегментов:

```text
src/shared/
├── ui/
│   ├── icon/
│   │   └── icon.tsx
│   ├── carousel/
│   │   ├── carousel.tsx
│   │   ├── ui/
│   │   │   ├── carousel-slide/
│   │   │   │   └── carousel-slide.tsx
│   │   │   └── carousel-dots/
│   │   │       └── carousel-dots.tsx
│   │   └── index.ts
│   ├── container/
│   └── button/
├── lib/
│   ├── format-date.ts
│   └── cn.ts
├── styles/
│   ├── variables.css
│   └── media.css
└── sprites/
```

### Модуль

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

```text
{name}/
├── {name}.{суффикс}.tsx     # компонент (опционален)
├── ui/                      # вложенные компоненты
├── hooks/                   # хуки
├── stores/                  # сторы
├── types/                   # типы, интерфейсы, enums
├── styles/                  # стили
├── lib/                     # утилиты
├── services/                # внешние источники данных
├── helpers/                 # вспомогательные функции
├── config/                  # константы, конфигурация
└── index.ts                 # публичный API
```

#### Именование компонента

Суффикс слоя получают **только модули первого уровня слоя** — те, что лежат непосредственно в корне слоя. Все компоненты (в `ui/`, любой глубины) именуются без суффикса. Без исключений.

| Слой | Суффикс | Пример |
|------|---------|--------|
| Layouts | `.layout.tsx` | `main.layout.tsx` |
| Screens | `.screen.tsx` | `knv.screen.tsx` |
| Widgets | `.widget.tsx` | `popular-products-slider.widget.tsx` |
| Features | `.feature.tsx` | `auth-by-email.feature.tsx` |
| Entities | `.entity.tsx` | `product.entity.tsx` |

Примеры:

```text
features/auth-by-email/auth-by-email.feature.tsx       # модуль первого уровня → суффикс
features/auth-by-email/ui/login-form/login-form.tsx     # компонент в ui/ → без суффикса
shared/ui/carousel/carousel.tsx                         # компонент в shared → без суффикса
```

#### Правила импорта

Три уровня правил:

**Между слоями** — импорты строго сверху вниз:

```
app → layouts → screens → widgets → features → entities → shared
```

**Внутри модуля (не shared)** — сегменты доступны друг другу и компонентам. Компоненты внутри одного `ui/` не импортируют друг друга:

```text
features/auth-by-email/
├── ui/
│   ├── login-form/          # НЕ может импортировать reset-password
│   └── reset-password/      # НЕ может импортировать login-form
```

Если двум компонентам нужен общий код — он поднимается на уровень выше:

```text
features/auth/ui/login-form/ui/email-input/    # нужен соседу
→ features/auth/ui/email-input/                 # поднимаем на уровень
→ shared/ui/email-input/                        # если нужен за пределами фичи
```

Компоненты наследуют правила зависимостей **родительского слоя**:

- Компонент внутри `features/auth/ui/login-form/` может импортировать `entities/` и `shared/` — как и сам feature
- Компонент внутри `widgets/hero/ui/hero-stats/` может импортировать `features/`, `entities/`, `shared/` — как и сам widget

**Shared** — без ограничений на внутренние импорты. Компоненты в `shared/ui/` могут импортировать друг друга (`button` использует `icon`), `ui/` может использовать `lib/` и другие сегменты. Shared — фундамент, его компоненты строятся друг на друге.

Правила импорта между слоями enforceable через ESLint — настройка границ слоёв и запрет обратных зависимостей.

### Жизненный цикл модуля

Модуль не проектируется «на вырост». Он рождается на самом низком уровне
и поднимается только когда появляется реальная потребность.

Пример пути компонента `product-card`:

1. **Начало:** `screens/catalog/ui/product-card/` — нужен только на странице каталога.
2. **Переиспользование:** появился на странице поиска — выносим выше.
   Куда именно зависит от природы:
   - Составной блок с данными и логикой → `widgets/product-card/`
   - Представление бизнес-сущности → `entities/product/ui/product-card/`
   - Абстрактный UI без бизнес-логики → `shared/ui/product-card/`

Основной триггер подъёма — переиспользование в 2+ местах.
Но если очевидно что модуль будет переиспользоваться — разумно разместить его на нужном уровне сразу.

Как происходит подъём на практике:

1. Разработчик обнаруживает что компонент нужен в другом месте
2. Определяет целевой слой по природе компонента (widget / entity / shared)
3. Перемещает папку, обновляет импорты, добавляет суффикс если это модуль первого уровня слоя
4. Ревью подтверждает что подъём обоснован

Подъём — это обычный рефакторинг в рамках задачи, а не отдельная активность.

### Граничные случаи

| Ситуация | Решение | Почему |
|----------|---------|--------|
| Фильтр каталога только на одной странице, но с хуками и стором | Модуль в `screens/catalog/` с сегментами `hooks/`, `stores/` | Не feature — feature это действие пользователя с бизнес-логикой (авторизация, заказ), а не UI с состоянием |
| Компонент используется в 2 местах на одной странице | Остаётся в `screens/{name}/ui/` | Переиспользование внутри одного screen — не повод выносить в widget |
| Entity без UI (только типы и хук) | Нормально | Модуль не обязан иметь UI. `entities/session/` с типами и хуком — валидный модуль |
| Компонент нужен и в layout, и в screen | Выносить в `widgets/` или `shared/ui/` | Два разных слоя используют один компонент → переиспользование → подъём |
| Модуль screen содержит бизнес-логику (хуки, стор, сервисы) | Нормально | Это не значит что он должен стать feature. Модуль с логикой внутри screen — обычное дело, пока он не переиспользуется |
| Компонент в `shared/ui/button` хочет использовать `shared/ui/icon` | Разрешено | Shared — исключение: внутренние импорты без ограничений. Это фундамент, его компоненты строятся друг на друге |

### Запрещено

- **Не создавать feature без бизнес-логики** — кнопка без состояния и сайд-эффектов это компонент в `ui/`, а не feature
- **Не класть доменные типы в shared** — если тип знает о Product, Disease, User — он живёт в `entities/`, не в `shared/`
- **Не создавать entity или feature как результат «вынесения»** — они создаются осознанно: появилась бизнес-сущность → entity, появилось действие пользователя → feature
- **Не импортировать соседние компоненты в `ui/` (кроме shared)** — если двум компонентам нужен общий код, он поднимается на уровень выше
- **Не хранить в shared «помойку для всего»** — shared содержит переиспользуемые компоненты и утилиты без бизнес-логики, а не код который «непонятно куда положить»

### Почему так, а не иначе

#### Почему `ui/` а не `modules/`

Внутри сегмента `ui/` всегда лежат единицы с обязательным UI (компоненты). Название точно отражает содержимое. `modules/` был нейтральнее, но скрывал природу вложенных единиц и создавал путаницу — модуль внутри модуля размывал понятие «модуль как единица слоя».

#### Почему модуль и компонент — разные понятия

Модуль — единица первого уровня слоя, может не иметь UI. Компонент — вложенная единица с обязательным UI. Разделение снимает вопрос «а если нет `.tsx` — это всё ещё компонент?» и делает название сегмента `ui/` честным.

#### Почему shared без ограничений на внутренние импорты

Shared — фундамент. Его компоненты строятся друг на друге: `button` использует `icon`, `carousel` использует `button`. Запрещать это — бороться с реальностью. Поднимать некуда — shared уже нижний слой.

#### Почему нет слоя pages

Роутинг живёт в `app/` (Next.js App Router). Отдельный слой `pages` конфликтовал бы с файловой структурой Next.js и дублировал ответственность `app/`.

#### Почему компоненты в одном `ui/` не импортируют друг друга (кроме shared)

Независимые компоненты легко выносить в другой слой при переиспользовании. Если компонент A зависит от соседа B — при подъёме A придётся тянуть B. Это усложняет рефакторинг и нарушает принцип колокации.

<!-- /basics/code-style -->
## Стиль кода

Раздел описывает единые правила оформления кода: отступы, переносы, кавычки, порядок импортов и базовую читаемость.

### Отступы

- 2 пробела (не табы).

### Длина строк

- Ориентироваться на 100 символов, но превышение допустимо, если строка читается легко.
- Переносить выражение на новые строки, когда строка становится плохо читаемой.
- Не переносить строку внутри строковых литералов без необходимости.

**Хорошо**
```ts
const config = createRequestConfig(
  endpoint,
  {
    headers: {
      'X-Request-Id': requestId,
      'X-User-Id': userId,
    },
    params: {
      page,
      pageSize,
      sort: 'createdAt',
    },
  },
  timeoutMs,
);
```

**Плохо**
```ts
// Плохо: длинная строка с вложенными структурами плохо читается.
const config = createRequestConfig(endpoint, { headers: { 'X-Request-Id': requestId, 'X-User-Id': userId }, params: { page, pageSize, sort: 'createdAt' } }, timeoutMs);
```

### Кавычки

- В JavaScript/TypeScript использовать одинарные кавычки.
- В JSX/TSX для атрибутов использовать двойные кавычки.
- Шаблонные строки использовать только при интерполяции или многострочном тексте.

**Хорошо**
```ts
const label = 'Сохранить';
const title = `Привет, ${name}`;
```

```tsx
<input type="text" placeholder="Введите имя" />
```

**Плохо**
```ts
// Плохо: двойные кавычки в TS и конкатенация вместо шаблонной строки.
const label = "Сохранить";
const title = 'Привет, ' + name;
```

```tsx
// Плохо: одинарные кавычки в JSX-атрибутах.
<input type='text' placeholder='Введите имя' />
```

### Точки с запятой и запятые

- Допускаются упущения точки с запятой, если код остаётся читаемым и однозначным.
- В многострочных массивах, объектах и параметрах функции запятая в конце допускается, но не обязательна.

### Импорты

- В именованных импортах использовать пробелы внутри фигурных скобок.
- Типы импортировать через `import type`.
- `default` экспорт избегать, использовать именованные. `default` импорт допустим (например, стили CSS Modules, сторонние библиотеки).
- Избегать импорта всего модуля через `*`.

**Хорошо**
```ts
import { MyComponent } from 'MyComponent';
import type { User } from '../model/types';
import styles from './styles/button.module.css';
```

**Плохо**
```ts
// Плохо: отсутствие пробелов в именованном импорте.
import type {User} from '../model/types';
// Плохо: default экспорт.
export default MyComponent;
```

### Ранние возвраты (early return)

- Использовать ранние возвраты для упрощения чтения.
- Избегать `else` после `return`.

**Хорошо**
```ts
const getName = (user?: { name: string }) => {
  if (!user) {
    return 'Гость';
  }

  return user.name;
};
```

**Плохо**
```ts
// Плохо: лишний else после return усложняет чтение.
const getName = (user?: { name: string }) => {
  if (user) {
    return user.name;
  } else {
    return 'Гость';
  }
};
```

### Форматирование объектов и массивов

- В многострочных объектах каждое свойство на новой строке.
- В многострочных массивах каждый элемент на новой строке.
- Объекты и массивы можно писать в одну строку, если длина строки не превышает 100 символов.
- В однострочных объектах и массивах использовать пробелы после запятых.

**Хорошо**
```ts
const roles = ['admin', 'editor', 'viewer'];
const options = { id: 1, name: 'User' };

const config = {
  url: '/api/users',
  method: 'GET',
  params: { page: 1, pageSize: 20 },
};
```

**Плохо**
```ts
// Плохо: нет пробелов после запятых и объект слишком длинный для одной строки.
const roles = ['admin','editor','viewer'];
const options = { id: 1,name: 'User' };
const config = { url: '/api/users', method: 'GET', params: { page: 1, pageSize: 20 } };
```

<!-- /basics/documentation -->
## Документирование

Этот раздел описывает правила документирования кода: когда и как писать
комментарии к компонентам, функциям, типам и интерфейсам.

### Общие правила

- Документировать публичные функции, компоненты, типы, интерфейсы и enum.
- Не документировать очевидное — если название говорит само за себя, комментарий не нужен.
- Не документировать параметры, возвращаемые значения и типы пропсов — они видны из сигнатуры.
- Описание через пользу и назначение, а не через внутреннюю реализацию.
- Описание завершается точкой.

### Функции

Для документирования функций используется шаблон. Описание механики опционально —
добавляется когда логика нетривиальна.

**Шаблон**
```ts
/**
 * <Что делает функция в 1 строке>.
 *
 * <Опционально: описание сложной механики или важных нюансов>.
 */
```

**Хорошо**
```ts
/**
 * Форматирует цену с символом валюты.
 */
export const formatPrice = (value: number): string => { ... }

/**
 * Рекурсивно собирает дерево категорий из плоского списка.
 *
 * Группирует элементы по parentId, начиная с корневых (parentId = null).
 * Категории без родителя попадают в корень дерева.
 */
export const buildCategoryTree = (categories: Category[]): CategoryTree[] => { ... }
```

**Плохо**
```ts
// Плохо: дублирует сигнатуру.
/**
 * @param value - число
 * @returns строка с ценой
 */
```

### Компоненты

Компонент описывает своё **назначение** и **сценарии применения** — это помогает понять, когда и где его использовать, без необходимости читать реализацию.

**Шаблон**
```ts
/**
 * <Назначение компонента в 1 строке>.
 *
 * Используется для:
 *  - <сценарий 1>
 *  - <сценарий 2>
 *  - <сценарий 3>
 */
```

**Хорошо**
```tsx
/**
 * Контейнер с адаптивной максимальной шириной.
 *
 * Используется для:
 *  - обёртки контента страниц с ограничением ширины
 *  - центрирования блоков в лейауте
 */
export const Container = (props: ContainerProps) => { ... }
```

**Плохо**
```tsx
// Плохо: описывает реализацию, а не назначение.
/**
 * Рендерит div с className и htmlAttr.
 */

// Плохо: нет описания вообще.
export const Container = (props: ContainerProps) => { ... }
```

### Типы, интерфейсы, enum

Документируются назначение сущности и каждое её поле.

**Хорошо**
```ts
/**
 * Фильтры списка задач.
 */
export enum TodoFilter {
  /** Все задачи. */
  ALL = 'all',
  /** Только активные. */
  ACTIVE = 'active',
  /** Только завершённые. */
  COMPLETED = 'completed',
}

/**
 * Задача пользователя.
 */
export interface TodoItem {
  /** Уникальный идентификатор задачи. */
  id: string;
  /** Текст задачи. */
  text: string;
  /** Статус выполнения. */
  completed: boolean;
}
```

**Плохо**
```ts
// Плохо: описывает очевидное.
export interface TodoItem {
  /** id — это id */
  id: string;
}
```

<!-- /basics/typing -->
## Типизация

Этот раздел описывает правила типизации: как типизировать компоненты, функции и работу с `any`/`unknown`.

### Общие правила

- Указывать типы для параметров компонентов, возвращаемых значений и параметров функций.
- Предпочитать `type` для описания сущностей и `interface` для расширяемых контрактов.
- Избегать `any` и `unknown` без необходимости.
- Не использовать `ts-ignore`, кроме крайних случаев с явным комментарием причины.

### Функции

- Для публичных функций указывать возвращаемый тип.
- Не полагаться на неявный вывод для важных API.

**Хорошо**
```ts
export const formatPrice = (value: number): string => {
  return `${value} ₽`;
};
```

**Плохо**
```ts
// Плохо: нет явного возвращаемого типа.
export const formatPrice = (value: number) => {
  return `${value} ₽`;
};
```

### Работа с any/unknown

- `any` использовать только для временных заглушек.
- `unknown` сужать через проверки перед использованием.

**Хорошо**
```ts
const parse = (value: unknown): string => {
  if (typeof value === 'string') {
    return value;
  }

  return '';
};
```

**Плохо**
```ts
// Плохо: any отключает проверку типов.
const parse = (value: any) => value;
```

<!-- /applied/project-structure -->
## Структура проекта

Раздел описывает расположение файлов и папок в проекте Next.js (App Router).

### Корень репозитория

```text
project-root/
├── .templates/           # Шаблоны для генерации модулей
├── .vscode/              # Настройки и рекомендуемые расширения VS Code
├── public/               # Статика, доступная по прямому URL
├── src/                  # Исходный код приложения
├── .env.example          # Переменные окружения проекта (шаблон)
├── .env                  # Переменные окружения проекта (не коммитить)
├── .gitignore
├── AGENTS.md             # Инструкции для AI-агентов
├── biome.json            # Линтер и форматтер (вместо ESLint + Prettier)
├── next.config.ts        # Конфигурация Next.js
├── package.json          # Зависимости и скрипты
├── postcss.config.mjs    # Конфигурация PostCSS
└── tsconfig.json         # Конфигурация TypeScript
```

### Папка `public/`

Хранит статические файлы, которые отдаются по прямому URL без обработки сборщиком:

```text
public/
└── og-image.png
```

Компоненты, стили и другой исходный код здесь не размещаются.

### Папка `src/`

```text
src/
├── app/        # Роутинг Next.js, провайдеры, глобальные стили
├── screens/    # Собраные страницы (UI)
├── layouts/    # Шаблоны
├── widgets/    # Крупные самостоятельные блоки интерфейса
├── features/   # Пользовательские сценарии
├── entities/   # Бизнес-сущности
└── shared/     # Переиспользуемый код (UI, утилиты, типы и др.)
```

Принципы организации слоёв описаны в разделе [Архитектура](../basics/architecture).

#### Папка `app/`

Совмещает два слоя: инициализацию приложения по FSD (провайдеры, глобальные стили) и файловый роутинг Next.js (`layout.tsx`, `page.tsx`, route-сегменты).

```text
src/app/
├── providers/    # Провайдеры приложения
├── styles/       # Глобальные стили
├── layout.tsx    # Корневой layout
└── page.tsx      # Главная страница
```

### Папка `.templates/`

Содержит шаблоны для генерации кода. Каждый подкаталог — шаблон отдельного типа модуля:

```text
.templates/
├── component/    # Шаблон компонента
├── screen/       # Шаблон экрана
├── layout/       # Шаблон layout
├── widget/       # Шаблон виджета
├── feature/      # Шаблон фичи
├── entity/       # Шаблон сущности
└── store/        # Шаблон стора
```

Подробнее о генерации описано в разделе [Шаблоны и генерация кода](./templates-generation).

### Конфигурационные файлы

| Файл | Назначение |
|---|---|
| `next.config.ts` | Настройки Next.js: редиректы, переменные окружения, webpack |
| `tsconfig.json` | Настройки TypeScript: пути, строгость, таргет |
| `biome.json` | Правила линтера и форматтера Biome |
| `postcss.config.mjs` | Подключение PostCSS-плагинов (CSS Modules, custom media) |
| `package.json` | Зависимости, версии, npm-скрипты |
| `AGENTS.md` | Инструкции для AI-агентов, работающих в проекте |

### Переменные окружения

- `.env` — переменные окружения проекта, запрещено коммитить
- `.env.example` — шаблон, коммитится в репозиторий

Переменные с префиксом `NEXT_PUBLIC_` доступны в клиентском коде. Остальные доступны только на сервере.

<!-- /applied/components -->
## Компоненты

Правила написания React-компонентов: файловая структура модуля, типизация пропсов, документирование и реализация. Раздел охватывает компоненты всех слоёв — от `shared/ui` до `screens`.

Архитектурные слои и их назначение описаны в разделе [Архитектура](/basics/architecture).


### Правила организации

1. Один компонент — один файл.
2. Компонент не содержит бизнес-логики — логика и сайд-эффекты выносятся в хуки или сторы.
3. Дочерние компоненты размещаются в сегменте `ui/` и подчиняются тем же правилам структуры.
4. Публичный API модуля — только `index.ts`. Прямые импорты внутренних файлов запрещены.

### Базовая структура компонента

Минимальный набор файлов: компонент, стили, типы и публичный экспорт.

```text
container/
├── styles/
│   └── container.module.css
├── types/
│   └── container.type.ts
├── container.tsx
└── index.ts
```

### Именования

- Имя корневого css класса всегда `.root`
- Тип пропсов именуется `{ComponentName}Props`.
- Тип пользовательских параметров именуется `{ComponentName}Params`.

### Типизация

Структура типов компонента показана в [примере](#пример). Ниже — обоснования ключевых решений.

- **`type` вместо `interface`** — гибче для пропсов: поддерживает union, intersection, mapped types. Declaration merging пропсам не нужно.
- **Без `FC`** — неявно добавляет `children`, усложняет дженерики, не даёт преимуществ перед аннотацией параметра.
- **Типы в `types/`, а не в `.tsx`** — предотвращает циклические зависимости (компонент импортирует хук, хук импортирует тип из компонента) и разделяет ответственность: `.tsx` для рендера, `.type.ts` для данных.
- **Без возвращаемого типа** — TypeScript выводит из JSX. Осознанное исключение из [базового правила](/basics/typing).

### Реализация

- Пропсы деструктурируются в теле компонента, не в параметрах.
- Порядок: пользовательские → системные (`children`, `className`) → `...htmlAttr`.
- `className` объединяется с корневым классом через `cl()`: `cl(styles.root, className)`.
- `...htmlAttr` прокидывается на корневой элемент.

### Пример

`container/types/container.type.ts`

```ts
import type { HTMLAttributes } from 'react'

/**
 * Параметры компонента Container.
 */
export type ContainerParams = {}

/** HTML-атрибуты корневого элемента. */
type RootAttrs = HTMLAttributes<HTMLDivElement>

export type ContainerProps = RootAttrs & ContainerParams
```

`container/styles/container.module.css`

```css
.root {
  max-width: var(--content-width);
  margin: 0 auto;
  padding: 0 var(--spacing-4);
}
```

`container/container.tsx`

```tsx
import cl from 'clsx'
import type { ContainerProps } from './types/container.type'
import styles from './styles/container.module.css'

/**
 * Контейнер с адаптивной максимальной шириной.
 *
 * Используется для:
 *  - обёртки контента страниц с ограничением ширины
 *  - центрирования блоков в лейауте
 */
export const Container = (props: ContainerProps) => {
  const { children, className, ...htmlAttr } = props

  return (
    <div {...htmlAttr} className={cl(styles.root, className)}>
      {children}
    </div>
  )
}
```

`container/index.ts`

```ts
export { Container } from './container'
```

<!-- /applied/page-level -->
## Файлы роутинга

Правила для специальных файлов App Router (`page.tsx`, `layout.tsx`, `error.tsx`, `not-found.tsx` и др.) — чем наш подход отличается от дефолтного.

### Организация

- `page.tsx` — тонкий файл: только `metadata` и рендер экрана. Логика, стили и зависимости живут в экране, не в `page.tsx`.
- `error.tsx` и `not-found.tsx` делегируют разметку экранам по тому же принципу.
- `layout.tsx` — точка подключения провайдеров и глобальных стилей. Вёрстка layout-обёрток выносится в слой `layouts/`.
- Стили в файлах роутинга не используются — стилизация только внутри вызываемых компонентов.

### Реализация

- Каждый `page.tsx` экспортирует `metadata` с `title` — он подставляется в шаблон корневого layout (`%s | App`).
- Корневой `layout.tsx` задаёт `metadata` с `title.template`, `description`, `metadataBase` и OpenGraph-настройками.

### Примеры

`src/app/profile/[id]/page.tsx`

```tsx
import type { Metadata } from 'next'
import { ProfileScreen } from '@/screens/profile'

export const metadata: Metadata = {
  title: 'Профиль',
  description: 'Страница профиля пользователя',
}

type ProfilePageProps = {
  params: Promise<{ id: string }>
}

export default async function ProfilePage({ params }: ProfilePageProps) {
  const { id } = await params

  return <ProfileScreen id={id} />
}
```

`src/app/error.tsx`

```tsx
'use client'

import { ErrorScreen } from '@/screens/error'

type ErrorPageProps = {
  error: Error & { digest?: string }
  reset: () => void
}

const ErrorPage = ({ error, reset }: ErrorPageProps) => {
  return <ErrorScreen error={error} reset={reset} />
}

export default ErrorPage
```

<!-- /applied/templates-generation -->
<!-- @formatter:off -->
::: v-pre

## Шаблоны и генерация кода

Как работают шаблоны, как их создавать, синтаксис переменных и как генерировать код с помощью расширения VS Code и CLI.

### Структура шаблонов

Все шаблоны лежат в `.templates/` в корне проекта. Каждая папка — отдельный шаблон.

```text
.templates/
├── component/                  # шаблон компонента
│   └── {{name.kebabCase}}/
│       ├── styles/
│       │   └── {{name.kebabCase}}.module.css
│       ├── types/
│       │   └── {{name.kebabCase}}.type.ts
│       ├── {{name.kebabCase}}.tsx
│       └── index.ts
└── store/                      # шаблон Zustand стора
    └── {{name.kebabCase}}/
        ├── {{name.kebabCase}}.store.ts
        ├── {{name.kebabCase}}.type.ts
        └── index.ts
```

### Синтаксис шаблонов

Переменные работают в именах файлов/папок и внутри файлов. Базовая переменная — `name`.

```text
{{variable}}
```

Модификаторы меняют регистр и формат записи:

```text
{{name.pascalCase}}          → MyButton
{{name.camelCase}}           → myButton
{{name.kebabCase}}           → my-button
{{name.snakeCase}}           → my_button
{{name.screamingSnakeCase}}  → MY_BUTTON
```

### Как создать новый шаблон

1. Создать папку в `.templates/` с именем шаблона (например `hook`).
2. Внутри разместить файлы и папки, используя `{{name}}` и модификаторы в именах и содержимом.
3. Шаблон сразу доступен и в расширении VS Code, и в CLI.

Пример — создание шаблона для хука:

```text
.templates/
└── hook/
    └── {{name.kebabCase}}/
        ├── {{name.kebabCase}}.hook.ts
        └── index.ts
```

```ts
// .templates/hook/{{name.kebabCase}}.hook.ts
export const {{name.camelCase}} = () => {

}
```

```ts
// .templates/hook/index.ts
export { {{name.camelCase}} } from './{{name.kebabCase}}.hook'
```

### Примеры шаблонов

#### Шаблон компонента

```ts
// .templates/component/index.ts
export { {{name.pascalCase}} } from './{{name.kebabCase}}'
```

```ts
// .templates/component/types/{{name.kebabCase}}.type.ts
import type { HTMLAttributes } from 'react'

/**
 * Параметры {{name.pascalCase}}.
 */
export type {{name.pascalCase}}Params = {}

/** HTML-атрибуты корневого элемента. */
type RootAttrs = HTMLAttributes<HTMLDivElement>

export type {{name.pascalCase}}Props = RootAttrs & {{name.pascalCase}}Params
```

```tsx
// .templates/component/{{name.kebabCase}}.tsx
import cl from 'clsx'
import type { {{name.pascalCase}}Props } from './types/{{name.kebabCase}}.type'
import styles from './styles/{{name.kebabCase}}.module.css'

/**
 * {{name.pascalCase}}.
 */
export const {{name.pascalCase}} = (props: {{name.pascalCase}}Props) => {
  const { children, className, ...htmlAttr } = props

  return (
    <div {...htmlAttr} className={cl(styles.root, className)}>
      {children}
    </div>
  )
}
```

```css
/* .templates/component/styles/{{name.kebabCase}}.module.css */
.root {

}
```

### Генерация через VS Code

Template File Generator | gromlab ([Marketplace](https://marketplace.visualstudio.com/items?itemName=gromlab.vscode-templateFileGenerator), [Open VSX](https://open-vsx.org/extension/gromlab/vscode-templateFileGenerator)) — расширение для генерации файлов и папок из шаблонов через интерфейс редактора.

1. ПКМ на целевой папке в проводнике VS Code.
2. **Generate from template** → выбрать шаблон.
3. Ввести имя (например `button`) — расширение подставит его во все переменные `{{name}}`.

### Генерация через CLI

[@gromlab/create](https://www.npmjs.com/package/@gromlab/create) — CLI для генерации из тех же шаблонов. Используется через npx, глобальная установка не требуется.

```bash
npx @gromlab/create <шаблон> <имя> <путь>
```

| Команда | Что создаёт |
|---|---|
| `npx @gromlab/create component button src/shared/ui` | Компонент |
| `npx @gromlab/create feature auth src/features` | Фичу |
| `npx @gromlab/create widget header src/widgets` | Виджет |
| `npx @gromlab/create entity user src/entities` | Сущность |
| `npx @gromlab/create layout admin src/layouts` | Layout |
| `npx @gromlab/create store auth src/shared/model` | Стор |

:::

<!-- /applied/styles -->
## Стили

Раздел описывает правила написания CSS: PostCSS Modules, вложенность, медиа-запросы, переменные, форматирование.

### Общие правила

- Только **PostCSS** и **CSS Modules** для кастомной стилизации.
- Подход **Mobile First** — стили пишутся от мобильных к десктопу.
- Именование классов — `camelCase` (`.root`, `.buttonNext`, `.itemTitle`).
- Модификаторы — отдельный класс с `_`, применяется через `&._modifier`.

**Хорошо**
```css
.submitButton {
  padding: 8px 16px;

  &._disabled {
    opacity: 0.5;
  }
}
```

**Плохо**
```css
/* Плохо: kebab-case и вложенный элемент вместо отдельного класса. */
.submit-button {
  padding: 8px 16px;

  &__icon {
    margin-right: 8px;
  }
}
```

### Вложенность

- Вложенность селекторов запрещена.
- Исключения:
  - Псевдоклассы: `&:hover`, `&:active`, `&:focus`, `&:disabled` и т.д.
  - Псевдоэлементы: `&::before`, `&::after`.
  - Медиа-запросы: `@media`.
  - Модификаторы: `&._active`, `&._disabled`.
- Каждый вложенный блок отделяется пустой строкой от предыдущих свойств.

**Хорошо**
```css
.card {
  padding: 16px;
  background-color: var(--color-bg);

  &:hover {
    background-color: var(--color-bg-hover);
  }

  &::after {
    content: '';
    display: block;
  }

  &._highlighted {
    border-color: var(--color-primary);
  }

  @media (--md) {
    padding: 24px;
  }
}

.cardTitle {
  font-size: 16px;

  @media (--md) {
    font-size: 20px;
  }
}
```

**Плохо**
```css
/* Плохо: вложенность селекторов, нет пустых строк между блоками. */
.card {
  padding: 16px;
  .cardTitle {
    font-size: 16px;
  }
  &:hover {
    background-color: var(--color-bg-hover);
  }
}
```

### Медиа-запросы

- Только **Custom Media Queries**: `@media (--md) {}`.
- Запрещены произвольные breakpoints: `@media (min-width: 768px)`.
- `@media` пишется только **внутри** селектора.
- Запрещено писать `@media` на верхнем уровне с селекторами внутри.

**Хорошо**
```css
.sidebar {
  display: none;

  @media (--md) {
    display: block;
  }
}

.sidebarTitle {
  font-size: 14px;

  @media (--md) {
    font-size: 18px;
  }
}
```

**Плохо**
```css
/* Плохо: @media на верхнем уровне с селекторами внутри. */
@media (--md) {
  .sidebar {
    display: block;
  }

  .sidebarTitle {
    font-size: 18px;
  }
}

/* Плохо: произвольный breakpoint вместо custom media. */
.sidebar {
  @media (min-width: 992px) {
    display: block;
  }
}
```

### CSS-переменные

- Цвета (`--color-*`), отступы (`--space-*`), скругления (`--radius-*`) определяются в `app/styles/variables.css` через `:root`.
- Файл переменных подключается один раз в корневом layout/entry point — после этого переменные доступны глобально через каскад.
- Не дублировать магические значения в компонентах.

**Хорошо**
```css
/* app/styles/variables.css */
:root {
  --color-primary: #3b82f6;
  --color-bg: #ffffff;
  --color-bg-hover: #f5f5f5;
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --radius-1: 4px;
  --radius-2: 8px;
}
```

```css
/* компонент */
.card {
  padding: var(--space-3);
  border-radius: var(--radius-2);
  background-color: var(--color-bg);
}
```

**Плохо**
```css
/* Плохо: магические значения вместо переменных. */
.card {
  padding: 12px;
  border-radius: 8px;
  background-color: #ffffff;
}
```

### Custom Media

- Breakpoints определяются через Custom Media Queries в `app/styles/media.css`.
- Custom media подключаются глобально через конфиг PostCSS (плагин `postcss-custom-media`) — не импортировать в файлы стилей.

```css
/* app/styles/media.css */
@custom-media --sm (min-width: 36em);
@custom-media --md (min-width: 62em);
@custom-media --lg (min-width: 82em);
```

### Импорт стилей

- Стили компонента импортируются только внутри своего компонента.
- Запрещено импортировать стили одного компонента в другой.
- Custom media не импортируются в файлы стилей — они подключаются глобально через конфиг PostCSS.

### Форматирование

- Пустая строка между селекторами верхнего уровня.
- Пустая строка перед каждым вложенным блоком (медиа, псевдокласс, модификатор).

**Хорошо**
```css
.userBar {
  display: none;
  color: var(--color-text);

  @media (--md) {
    display: flex;
  }
}

.userBarButton {
  background-color: var(--color-bg);

  &:hover {
    background-color: var(--color-bg-hover);
  }

  &._active {
    background-color: var(--color-primary);
  }
}
```

**Плохо**
```css
/* Плохо: нет пустых строк между селекторами и вложенными блоками. */
.userBar {
  display: none;
  color: var(--color-text);
  @media (--md) {
    display: flex;
  }
}
.userBarButton {
  background-color: var(--color-bg);
  &:hover {
    background-color: var(--color-bg-hover);
  }
  &._active {
    background-color: var(--color-primary);
  }
}
```

### Единицы измерения

- `px` — основная единица измерения.
- Остальные (`em`, `rem`, `%`, `vh`/`vw`) — допускаются по необходимости дизайна.

### Порядок CSS-свойств

В стилях рекомендуется придерживаться логического порядка свойств:

1. Позиционирование (`position`, `top`, `left`, `z-index`).
2. Блочная модель (`display`, `width`, `height`, `margin`, `padding`).
3. Оформление (`background`, `border`, `box-shadow`, `border-radius`).
4. Текст (`font`, `color`, `text-align`, `line-height`).
5. Прочее (`transition`, `animation`, `opacity`, `cursor`).

### Комментарии

- Желательно не писать комментарии в CSS.
- Исключение — нетривиальные хаки и обходные решения, к которым стоит оставить пояснение.

<!-- /applied/svg-sprites -->
## SVG-спрайты

<!-- /applied/vscode -->
## Настройка VS Code

Каждый проект содержит папку `.vscode/` с конфигурацией редактора. Это гарантирует, что все участники команды работают с одинаковыми настройками форматирования, линтинга и расширениями.

### Структура `.vscode/`

```text
.vscode/
├── extensions.json   # Рекомендуемые расширения
└── settings.json     # Настройки редактора для проекта
```

Оба файла коммитятся в репозиторий.

### Расширения

Файл `.vscode/extensions.json` определяет список расширений, которые VS Code предложит установить при открытии проекта.

```json
// .vscode/extensions.json
{
  "recommendations": [
    "biomejs.biome",
    "MyTemplateGenerator.mytemplategenerator",
    "csstools.postcss"
  ]
}
```

| Расширение | Назначение |
|---|---|
| [Biome](https://marketplace.visualstudio.com/items?itemName=biomejs.biome) | Линтинг и форматирование кода. Заменяет ESLint и Prettier |
| Template File Generator \| gromlab ([Marketplace](https://marketplace.visualstudio.com/items?itemName=gromlab.vscode-templateFileGenerator), [Open VSX](https://open-vsx.org/extension/gromlab/vscode-templateFileGenerator)) | Генерация файлов и папок из шаблонов `.templates/` через контекстное меню |
| [PostCSS Language Support](https://marketplace.visualstudio.com/items?itemName=csstools.postcss) | Подсветка синтаксиса и автодополнение для PostCSS (`@custom-media`, `@nest` и др.) |

#### Зачем это нужно

- Новый участник команды получает все нужные расширения одним кликом.
- Нет разночтений: все используют одинаковый форматтер и линтер.
- Расширения привязаны к проекту, а не к конкретному разработчику.

### Настройки редактора

Файл `.vscode/settings.json` переопределяет пользовательские настройки VS Code на уровне проекта.

```json
// .vscode/settings.json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  },
  "files.associations": {
    "*.css": "postcss"
  }
}
```

#### Разбор настроек

| Настройка | Значение | Что делает |
|---|---|---|
| `editor.defaultFormatter` | `biomejs.biome` | Biome используется как единственный форматтер для всех файлов |
| `editor.formatOnSave` | `true` | Код автоматически форматируется при каждом сохранении |
| `codeActionsOnSave.source.fixAll.biome` | `explicit` | Biome автоматически применяет безопасные исправления при сохранении |
| `codeActionsOnSave.source.organizeImports.biome` | `explicit` | Импорты сортируются и группируются автоматически при сохранении |
| `files.associations` | `"*.css": "postcss"` | Все CSS-файлы открываются с подсветкой PostCSS вместо стандартного CSS |

#### Зачем это нужно

- **Единый стиль кода** -- форматирование происходит автоматически, невозможно закоммитить неформатированный код.
- **Автофикс при сохранении** -- распространённые ошибки линтинга исправляются без ручного вмешательства.
- **Сортировка импортов** -- импорты всегда в одном порядке, без конфликтов при мерже.
- **PostCSS-подсветка** -- кастомные at-правила (`@custom-media`, `@define-mixin`) подсвечиваются корректно, а не как ошибки.

### Что не должно быть в `.vscode/`

Не коммитятся файлы, специфичные для конкретного разработчика:

- **Не коммитить**: отладочные конфигурации с локальными путями, персональные сниппеты, настройки тем оформления.
- **Коммитить**: только `extensions.json` и `settings.json` с общими для команды настройками.