docs: добавить стайлгайд nextjs-style-guide в репозиторий

- Добавлена документация SLM-архитектуры, базовых правил и прикладных разделов - Добавлены разделы: стили, SVG-спрайты, шаблоны генерации, PostCSS, REST, Realtime - Удалены устаревшие файлы (спрайты, скрипты, стили из app/)
2026-04-30 19:32:10 +03:00
parent bf792f6159
commit f2358da397
60 changed files with 5308 additions and 372 deletions
--- a/ai/nextjs-style-guide/applied/templates/templates-create.md
+++ b/ai/nextjs-style-guide/applied/templates/templates-create.md
@@ -0,0 +1,91 @@
+---
+title: Создание шаблонов генерации
+description: "Структура шаблонов, синтаксис переменных и примеры."
+keywords: [шаблоны, templates, .templates, syntax, переменные, kebabCase, pascalCase, scaffold]
+---
+
+<!-- @formatter:off -->
+::: v-pre
+
+# Создание шаблонов генерации
+
+Структура шаблонов, синтаксис переменных и примеры.
+
+## Структура шаблонов
+
+Все шаблоны лежат в `.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
+```
+
+## Синтаксис шаблонов
+
+### Переменные
+
+Переменные работают в именах файлов/папок и внутри файлов:
+
+```text
+{{variable}}
+```
+
+Переменные могут быть любыми. `name` — дефолтная, подставляется генератором автоматически. Если реализация требует дополнительных параметров — можно использовать произвольные наборы переменных.
+
+### Модификаторы
+
+Модификаторы меняют регистр и формат записи переменной:
+
+```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'
+```
+
+## Дальше
+
+- [Использование](./templates-usage.md) — генерация через VS Code плагин и CLI.
+
+:::
--- a/ai/nextjs-style-guide/applied/templates/templates-intro.md
+++ b/ai/nextjs-style-guide/applied/templates/templates-intro.md
@@ -0,0 +1,32 @@
+---
+title: Шаблоны генерации
+description: "Что такое шаблоны кодогенерации и какие проблемы они решают."
+---
+
+# Шаблоны генерации
+
+Что такое шаблоны кодогенерации и какие проблемы они решают.
+
+## Проблема
+
+Каждый новый модуль в проекте — компонент, стор, бизнес-модуль — требует однотипной структуры файлов и boilerplate-кода. Ручное создание приводит к трём проблемам:
+
+- **Расхождения.** Разные разработчики создают модули по-разному: забывают `index.ts`, называют типы не по канону, пропускают стили.
+- **Время.** Создание одного компонента с типами, стилями и экспортом — 5–10 минут рутины. За спринт набегают часы.
+- **Ошибки копипасты.** Копирование существующего модуля и переименование — источник опечаток и забытых ссылок.
+
+## Решение
+
+Шаблоны кодогенерации — это папки с файлами-заготовками в `.templates/`. Вместо ручного создания файлов разработчик вызывает генератор, указывает имя — и получает готовый модуль со всей структурой, именами и boilerplate, подставленными автоматически.
+
+Что дают шаблоны:
+
+- **Единообразие.** Все модули одного типа идентичны по структуре. Канон живёт в шаблоне, а не в памяти разработчика.
+- **Скорость.** Генерация модуля — одна команда. Остальное время — на бизнес-логику.
+- **Согласованность с архитектурой.** Шаблоны учитывают SLM: правильные слои, сегменты, экспорты. Отклонение от стайлгайда требует осознанного усилия, а не случайного упущения.
+
+## Состав раздела
+
+- [Настройка](./templates-setup.md) — первичная установка: скачивание стандартного набора шаблонов в проект.
+- [Создание шаблонов](./templates-create.md) — структура файлов, синтаксис переменных, примеры.
+- [Использование](./templates-usage.md) — генерация через VS Code плагин и CLI.
--- a/ai/nextjs-style-guide/applied/templates/templates-setup.md
+++ b/ai/nextjs-style-guide/applied/templates/templates-setup.md
@@ -0,0 +1,44 @@
+---
+title: Настройка шаблонов генерации
+description: Первичная установка шаблонов кодогенерации в проект.
+keywords: [шаблоны, templates, .templates, tiged, generator, генератор шаблонов, скачать шаблоны, scaffold]
+---
+
+# Настройка шаблонов генерации
+
+Первичная установка шаблонов кодогенерации в проект.
+
+## Установка
+
+1. Проверить, что `.templates/` отсутствует (или согласовать перезапись, если папка уже есть).
+
+2. Скачать папку из эталонного репозитория:
+
+   ```bash
+   npx tiged git@gromlab.ru:templates/nextjs-template.git/.templates .templates
+   ```
+
+3. Если `tiged` падает в default-режиме (HTTP-tarball у Gitea) — повторить с явным git-режимом:
+
+   ```bash
+   npx tiged --mode=git git@gromlab.ru:templates/nextjs-template.git/.templates .templates
+   ```
+
+4. Проверить генерацию:
+
+   ```bash
+   npx @gromlab/create component test src/ui
+   ```
+
+   После проверки — удалить тестовый модуль.
+
+## Проверка установки
+
+- В корне проекта есть папка `.templates/`.
+- Внутри `.templates/` присутствуют стандартные шаблоны (или согласованный кастомный набор).
+- Пробная генерация через `npx @gromlab/create ...` отрабатывает без ошибок.
+
+## Дальше
+
+- [Создание шаблонов](./templates-create.md) — структура файлов, синтаксис переменных, примеры.
+- [Использование](./templates-usage.md) — генерация через VS Code плагин и CLI.
--- a/ai/nextjs-style-guide/applied/templates/templates-usage.md
+++ b/ai/nextjs-style-guide/applied/templates/templates-usage.md
@@ -0,0 +1,39 @@
+---
+title: Использование шаблонов генерации
+description: Генерация файлов из шаблонов через VS Code плагин и CLI.
+keywords: [шаблоны, templates, generate, VS Code, CLI, gromlab/create, npx, scaffold]
+---
+
+# Использование шаблонов генерации
+
+Генерация файлов из шаблонов через VS Code плагин и CLI.
+
+## Через 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` | Компонент в текущей папке |
+| `npx @gromlab/create module auth src/business` | Бизнес-модуль |
+| `npx @gromlab/create widget header src/widgets` | Виджет |
+| `npx @gromlab/create layout admin src/layouts` | Layout |
+| `npx @gromlab/create store auth src/business/auth/stores` | Стор |
+
+CLI вызывается через `npx`, в `package.json` отдельно не добавляется.