nextjs-style-guide/CONTRIBUTING.md

# Правила работы над документацией

Мета-документ: как устроен проект, как писать и редактировать разделы.

## О проекте

Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.

- Движок: VitePress
- Язык: русский
- Контент: `docs/docs/`

## Команды

| Команда | Что делает |
|---------|-----------|
| `npm run dev` | Локальный сервер разработки |
| `npm run build` | Сборка статического сайта |
| `npm run llms` | Генерация `llms.txt` (карта документации для LLM) и README |

## Структура файлов

```
docs/
├── index.md                     # Лендинг (URL `/`)
└── docs/                        # Контент документации (URL `/docs/...`)
    ├── index.md                 # Главная страница
    ├── workflow.md              # Подсказки
    ├── basics/                  # Базовые правила: каким должен быть код
    │   ├── tech-stack.md
    │   ├── architecture/
    │   ├── code-style.md
    │   ├── naming.md
    │   ├── documentation.md
    │   └── typing.md
    ├── creating-project/        # Создание проекта: как поднять новый проект
    │   ├── from-template.md
    │   ├── manual.md
    │   └── nextjs.md
    ├── data/                     # Работа с данными
    │   ├── index.md
    │   ├── realtime.md
    │   └── rest/
    └── applied/                  # Прикладные разделы: настройка и использование
        ├── project-structure.md
        ├── page-level.md
        ├── component.md
        ├── module.md
        ├── styles/               # Стили: настройка + использование
        │   ├── styles-setup.md
        │   └── styles-usage.md
        ├── svg-sprites/          # SVG-спрайты: введение + настройка + использование
        │   ├── svg-sprites-intro.md
        │   ├── svg-sprites-setup.md
        │   └── svg-sprites-usage.md
        ├── images.md
        ├── fonts.md
        ├── aliases.md
        ├── templates/            # Шаблоны генерации: введение + настройка + использование
        │   ├── templates-intro.md
        │   ├── templates-setup.md
        │   ├── templates-create.md
        │   └── templates-usage.md
        ├── biome.md
        ├── postcss.md
        ├── vscode.md
        ├── localization.md
        └── stores.md
.vitepress/
└── config.ts                    # Конфигурация VitePress, сайдбар
generate-llms.ts                 # Скрипт генерации llms.txt и README
```

Сгенерированные артефакты (`docs/public/`): `llms.txt`, `llms-full.txt`,
`nextjs-style-guide.zip`, `manifest.json`, копии `.md` в `docs/public/docs/`.

### Добавление нового раздела

1. Создать `.md`-файл в нужной папке: `basics/`, `creating-project/`,
   или `applied/`.
2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
   Сайдбар — единственный источник порядка и группировки для `llms.txt`.
3. Запустить `npm run llms` для обновления `llms.txt` и README.

## Типы разделов

Документация разделена на четыре группы. Каждая отвечает на свой вопрос
и имеет свою природу — это влияет на содержимое и структуру страницы.

### Базовые правила (`basics/`)

**Отвечает на вопрос:** «Каким должен быть любой код?»

Универсальные стандарты, **не привязанные к конкретной области**.
Правило базовое, если оно применимо ко всему коду одинаково: именование
переменных, оформление импортов, когда использовать `type` vs `interface`.

Примеры в базовых правилах допускаются, но служат иллюстрацией принципа,
а не инструкцией по конкретной области.

**Граница:** если правило касается только одной области (только стили,
только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.

### Создание проекта (`creating-project/`)

**Отвечает на вопрос:** «Как поднять новый проект?»

Сценарии запуска нового проекта целиком: из шаблона, вручную, чистая
установка фреймворка. Раздел описывает порядок шагов на уровне всего
проекта; детали отдельных инструментов лежат в `applied/`.

**Граница:** не дублирует разделы `applied/`. Ссылается на них как на
шаги в общем сценарии.

### Прикладные разделы (`applied/`)

**Отвечает на вопрос:** «Как поставить инструмент и как им пользоваться?»

Прикладные разделы объединяют настройку и использование инструментов
и подсистем. Каждый раздел — самостоятельная предметная область.

Разделы делятся на два типа:

1. **Только настройка** — разовая установка инструмента (линтер,
   CSS-процессор, алиасы). Файл без суффикса: `biome.md`, `postcss.md`.

2. **Настройка + использование** — область, требующая и установки,
   и повседневных правил. Два файла с суффиксами: `styles-setup.md`
   (настройка) и `styles-usage.md` (использование). В сайдбаре
   оборачиваются в collapsed-группу.

**Граница:** прикладной раздел не дублирует базовые правила. Если правило
уже описано в `basics/` — прикладной раздел ссылается на него, но не
повторяет.

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

Шаблон ниже относится к usage-страницам прикладных разделов (`applied/*-usage.md`).
Setup-страницы (`applied/*-setup.md`) и `creating-project/` имеют другую
структуру — ориентированную на пошаговую установку (требования → установка →
проверка).

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

```markdown
# {Название}

{Одно-два предложения, по которым читатель за секунду решает, нужен ли ему раздел.
Правила оформления — секция «Заголовок и описание» ниже.}

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

Неочевидная информация, которую читатель должен знать перед чтением раздела.
Если для раздела нет такой вводной — секция не создаётся.

## Структура

Файловая организация: какие файлы создавать и куда класть.
Обязательно — дерево файлов через code-block.

## Правила

Конкретные требования, специфичные для области. Делятся на две подсекции:

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

Как написан код внутри файла: синтаксис, паттерны, API.
Отвечает на вопрос: «Как писать код?»

Примеры: объявление через `const`, деструктуризация пропсов, формат вызова `cl()`, способ подключения стилей, структура хука.

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

Как компонент/модуль встроен в проект: файловые границы, зоны ответственности, экспорт.
Отвечает на вопрос: «Где что лежит и за что отвечает?»

Примеры: один компонент — один файл, вложенные компоненты в `ui/`, логика выносится в `model/`.

Формат обеих подсекций — маркированный список.
Для неочевидных случаев — блоки «Хорошо / Плохо».
Если в области нет правил одной из категорий — подсекция не создаётся.

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

Соглашения по именам, специфичные для этой области.
Только то, что НЕ покрыто в базовом разделе «Именование».

## Типизация

Правила типизации, специфичные для этой области.
Только то, что НЕ покрыто в базовом разделе «Типизация».

## Документирование

Что и как документировать в этой области.
Только то, что НЕ покрыто в базовом разделе «Документирование».

## Примеры

Полноценные примеры кода.
Каждый пример с путём к файлу и пояснениями.

```

### Порядок секций

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

Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.

### Секции-расширения базовых правил

«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил.

- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc.
- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).

Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.

## Конвенции оформления

### Frontmatter

Каждый `.md`-файл начинается с YAML frontmatter:

```yaml
---
title: Название раздела
description: Описание раздела одним предложением.
---
```

- `title` совпадает с текстом `h1`-заголовка в файле.
- `description` совпадает с абзацем-описанием сразу под `h1`.

Подробнее о требованиях к самому заголовку и описанию — секция
«Заголовок и описание» ниже.

### Заголовок и описание

Каждая страница начинается с `h1`-заголовка и абзаца-описания сразу под ним.
Эта пара — **навигационный маркер**: попадает в сайдбар, `llms.txt`,
`MAP.md` архива и должна за секунду давать читателю или LLM понять,
**когда сюда нужно идти**.

#### Структура заголовков

- Один `h1` на файл, совпадает с `title` во frontmatter.
- Сразу после `h1` — описание (одно-два предложения, см. ниже).
- Основные секции — `h2`.
- Подсекции внутри `h2` — `h3`.
- `h4` не используется.

#### Имя `h1` (заголовок страницы)

- Называет предметную область, а не реализацию.
- Без имён пакетов, опций, конфигов и путей.
- Самодостаточен — читается без контекста сайдбара.
- Исключение: имя инструмента допустимо, если оно — единственное
  устойчивое имя самой области (`PostCSS`, `Biome`, `VS Code`).
- Если страница вложена в семантическую группу
  (`Архитектура → Слои`, `Данные → REST → Серверные компоненты`)
  и короткое имя теряет смысл при прямой ссылке — `h1` поднимает
  имя родителя в заголовок: `Слои SLM`, `Сегменты SLM`. В сайдбаре
  допустимо оставить короткий вариант (`Слои`, `Сегменты`) — там
  путь группы виден через дерево.
- Подъём в заголовок применяется только когда читается грамматически
  естественно (`Слои SLM`, `Автогенерация REST-клиента`). Если
  получается натянутая конструкция (`REST в серверных компонентах`) —
  заголовок остаётся коротким, а контекст полностью переносится
  в описание. Заголовок и описание — пара: если один не несёт
  контекст, его обязательно несёт второй.

**Хорошо:** «Алиасы импортов», «Структура проекта», «SVG-спрайты»,
«Слои SLM», «Автогенерация REST-клиента».

**Плохо:** «Установка и настройка» (что устанавливаем?),
«Использование» (что используем?), «Введение» (во что?),
«Сегменты» (чего сегменты?), «REST в серверных компонентах»
(грамматически натянуто — лучше короткий h1 + контекст в описании).

#### Описание

Описание — короткий ответ на вопрос «у меня задача X, мне сюда?».
Не аннотация. Не оглавление.

**Запреты:**

- Не упоминать конкретные пакеты, библиотеки, инструменты
  (`@gromlab/svg-sprites`, `Mantine`, `Zustand`).
- Не упоминать конкретные файлы и пути
  (`postcss.config.mjs`, `.templates/`, `biome.json`).
- Не упоминать конкретные опции, ключи API, имена функций
  (`baseUrl`, `cl()`, `useStore`).
- Не начинать с «Раздел описывает», «Этот раздел»,
  «В этом разделе», «Здесь рассмотрено».
- Не использовать дежурные префиксы как шаблон
  («Правила работы с...», «Правила написания...») — само то,
  что раздел про правила, и так понятно из секции и заголовка.
- Не пересказывать содержимое перечислением подсекций
  («организация, реализация, делегирование, метаданные»).
- Не аргументировать пользу
  («обеспечит единообразие», «упростит поддержку»).

**Требования:**

- 1 предложение, обычно 5–12 слов.
- Звучит как ответ человека другу, а не как техспек.
- Описание читается **самостоятельно**, без контекста сайдбара.
- Если страница вложена в семантическую группу
  (например, `Данные → REST → Клиенты → ...`) и её заголовок
  без этой группы теряет смысл — описание явно содержит имя
  родительской области, чтобы читалось без сайдбара.

**Подходящие формы:**

- «Как X.»
- «Что такое X.»
- «Из чего состоит X.»
- «Установка X.»
- «Какие X есть и как ими пользоваться.»

Перечисление аспектов через двоеточие — только если без него читатель
не сможет различить раздел от соседнего.

**Тест навигации.** Читатель видит описание — за секунду должен понять
«мне сюда» или «нет, не сюда». Если приходится перечитывать —
описание слишком длинное.

**Тест на изменение.** Если в разделе сменится пакет, переименуется
файл или добавится правило — придётся ли править описание?
Если да — оно слишком конкретное.

**Хорошо:**

```markdown
Какие алиасы импортов есть в проекте и как ими пользоваться.
```

```markdown
Установка и настройка линтера-форматтера в новом проекте.
```

```markdown
Из чего состоит проект и где что лежит.
```

```markdown
Получение REST-данных в серверных компонентах.
```

**Плохо:**

```markdown
Раздел описывает, какие алиасы используются в проекте: их полный список,
где они объявлены и как ими пользоваться между модулями и внутри модуля.
```

_Начинается с «Раздел описывает», пересказывает содержимое._

```markdown
Установка и настройка CSS-процессора PostCSS в проекте: набор плагинов,
конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.
```

_Упомянут конкретный файл, перечисление аспектов превратилось в оглавление._

```markdown
Правила работы с React-компонентами: файловая структура,
типизация пропсов, документирование, реализация.
```

_Дежурный префикс «Правила работы с...» плюс оглавление подсекций._

### Примеры кода

- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
- Путь к файлу указывается перед блоком кода текстом или комментарием внутри блока.
- Дерево файлов — ` ```text ` с символами `├──`, `└──`, `│`.

### Блоки «Хорошо / Плохо»

Используются для контрастного сравнения правильного и неправильного подхода.

Формат:

```markdown
**Хорошо:**

\`\`\`tsx
// правильный код
\`\`\`

**Плохо:**

\`\`\`tsx
// неправильный код
\`\`\`
```

### Таблицы

Используются для структурированных перечислений: настройки, команды, соответствия.
Формат — стандартный Markdown: `| Ключ | Описание |`.

### Ссылки между разделами

Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.

## Принципы

1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
3. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
4. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.