docs: добавить раздел «Алиасы»

- Добавлен прикладной раздел с конфигом tsconfig.paths и правилами использования
- Зафиксирован отказ от префикса @/
- Пункт «Алиасы» добавлен в сайдбар после «Структуры проекта»

.vitepress/config.ts

@@ -33,18 +33,34 @@ const sidebar = [
     text: 'Прикладные разделы',
     items: [
       { text: 'Структура проекта', link: '/docs/applied/project-structure' },
+      { text: 'Алиасы', link: '/docs/applied/aliases' },
       { text: 'Компоненты', link: '/docs/applied/components' },
       { text: 'Страницы (App Router)', link: '/docs/applied/page-level' },
       { text: 'Шаблоны и генерация кода', link: '/docs/applied/templates-generation' },
-      { text: 'Стили', link: '/docs/applied/styles' },
+      {
+        text: 'Стили',
+        collapsed: true,
+        items: [
+          { text: 'PostCSS', link: '/docs/applied/styles/postcss' },
+          { text: 'Использование', link: '/docs/applied/styles/usage' },
+        ],
+      },
       { text: 'Изображения', link: '/docs/applied/images-sprites' },
-      { text: 'SVG-спрайты', link: '/docs/applied/svg-sprites' },
+      {
+        text: 'SVG-спрайты',
+        collapsed: true,
+        items: [
+          { text: 'Установка и настройка', link: '/docs/applied/svg-sprites/setup' },
+          { text: 'Использование', link: '/docs/applied/svg-sprites/usage' },
+        ],
+      },
       { text: 'Видео', link: '/docs/applied/video' },
       { text: 'API', link: '/docs/applied/api' },
       { text: 'Stores', link: '/docs/applied/stores' },
       { text: 'Хуки', link: '/docs/applied/hooks' },
       { text: 'Шрифты', link: '/docs/applied/fonts' },
       { text: 'Локализация', link: '/docs/applied/localization' },
+      { text: 'Biome', link: '/docs/applied/biome' },
       { text: 'Настройка VS Code', link: '/docs/applied/vscode' },
     ],
   },

README.md

@@ -6,12 +6,12 @@
 
 **Для AI-агентов:**
 
-- [Карта разделов](https://nextjs-style-guide.gromlab.ru/llms.txt) — `llms.txt`, оглавление со ссылками на разделы.
+- [llms.txt](/llms.txt) — Карта разделов, оглавление со ссылками на разделы.
-- [Полный текст](https://nextjs-style-guide.gromlab.ru/llms-full.txt) — `llms-full.txt`, вся документация одним файлом.
+- [llms-full.txt](/llms-full.txt) — Вся документация одним файлом.
 
 **Для проекта:**
 
-- [Архив с правилами](https://nextjs-style-guide.gromlab.ru/nextjs-style-guide.zip) — `nextjs-style-guide.zip`, набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
+- [nextjs-style-guide.zip](/nextjs-style-guide.zip) — Набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
 
 ## Структура документации
 

docs/docs/applied/aliases.md

@@ -0,0 +1,78 @@
+---
+title: Алиасы
+keywords: [алиасы, aliases, paths, tsconfig, импорты, baseUrl, app, layouts, screens, widgets, business, infrastructure, ui, shared]
+---
+
+# Алиасы
+
+Импорты в проекте идут через алиасы слоёв SLM-архитектуры — по одному на каждый слой `src/`. Префикс `@/` **не используется**: имя слоя само по себе однозначно адресует код.
+
+Слои и направление зависимостей — [Архитектура: слои](/docs/basics/architecture/reference/layers).
+
+## Конфиг
+
+`tsconfig.json` в корне проекта:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "app/*":            ["./src/app/*"],
+      "layouts/*":        ["./src/layouts/*"],
+      "screens/*":        ["./src/screens/*"],
+      "widgets/*":        ["./src/widgets/*"],
+      "business/*":       ["./src/business/*"],
+      "infrastructure/*": ["./src/infrastructure/*"],
+      "ui/*":             ["./src/ui/*"],
+      "shared/*":         ["./src/shared/*"]
+    }
+  }
+}
+```
+
+Восемь алиасов — ровно по числу слоёв. Других алиасов в проекте нет.
+
+## Правила
+
+- **Каждый импорт между модулями — через алиас слоя.** Относительные пути (`../../`) запрещены за пределами своего модуля.
+- **Внутри одного модуля** допустимы относительные импорты (`./model`, `./ui/button`) — это часть инкапсуляции модуля.
+- **Префикс `@/` не используется.** Имя слоя — само по себе адрес.
+- **Направление импортов** определяется архитектурой, не алиасами. Алиас разрешает импорт технически, но не отменяет правила слоёв (→ [Слои](/docs/basics/architecture/reference/layers)).
+
+**Хорошо**
+
+```ts
+import { Button } from 'ui/button'
+import { useUser } from 'business/user'
+import { formatDate } from 'shared/utils/date'
+```
+
+**Плохо**
+
+```ts
+// Относительный путь между модулями
+import { Button } from '../../../ui/button'
+
+// Префикс @/, которого нет в paths
+import { Button } from '@/ui/button'
+
+// Алиас на src — не предусмотрен
+import { Button } from 'src/ui/button'
+```
+
+## Внутри модуля
+
+Внутри своего модуля — относительные пути:
+
+```ts
+// src/ui/button/button.tsx
+import styles from './button.module.css'
+import { Icon } from './icon'
+```
+
+Не использовать алиас на самого себя:
+
+```ts
+// Плохо — алиас вместо относительного пути внутри модуля
+import { Icon } from 'ui/button/icon'
+```

docs/docs/applied/biome.md

@@ -0,0 +1,80 @@
+---
+title: Biome
+keywords: [biome, линтер, форматтер, lint, format, biome.json, "@biomejs/biome", замена eslint, замена prettier]
+---
+
+# Biome
+
+Единый линтер и форматтер для JS/TS/JSON в проекте. Заменяет связку ESLint + Prettier одним инструментом.
+
+## Требования
+
+- Node.js 18+.
+- Проект без установленного ESLint и Prettier (они конфликтуют с Biome).
+
+## Установка
+
+1. Установить пакет:
+
+   ```bash
+   npm install --save-dev --save-exact @biomejs/biome
+   ```
+
+2. Инициализировать конфиг:
+
+   ```bash
+   npx @biomejs/biome init
+   ```
+
+   В корне появится `biome.json` с дефолтными настройками.
+
+3. Привести `biome.json` к стандартному виду — добавить override для `*.css` (см. «Стандартный `biome.json`»). Делается сразу после `init`, до первого запуска `lint`/`check`.
+
+4. Добавить скрипты в `package.json`:
+
+   ```json
+   {
+     "scripts": {
+       "lint": "biome lint .",
+       "format": "biome format --write .",
+       "check": "biome check --write ."
+     }
+   }
+   ```
+
+   | Скрипт | Что делает |
+   |--------|-----------|
+   | `lint` | Проверка правил без правок |
+   | `format` | Автоформатирование всех файлов |
+   | `check` | Lint + format + organize imports в один проход (основная команда) |
+
+## Стандартный `biome.json`
+
+Дефолтный `biome.json`, созданный `biome init`, кастомизируется ровно одним блоком — `overrides` для `*.css` с отключённым правилом `suspicious/noUnknownAtRules`. Этот override **обязателен по умолчанию во всех проектах**, независимо от того, подключены ли уже стили: проектный CSS-стек использует `@custom-media` и другие нестандартные at-правила, которые Biome не распознаёт; без override `npm run lint` падает.
+
+Фрагмент, который добавляется в `biome.json`:
+
+```jsonc
+{
+  "overrides": [
+    {
+      "includes": ["**/*.css"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noUnknownAtRules": "off"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+Если в `biome.json` уже есть массив `overrides` — добавить элемент в него; не дублировать массив.
+
+Прочая настройка правил Biome — отдельная задача, не входит в стандартный канон.
+
+## Интеграция с VS Code
+
+Расширение `biomejs.biome` и автоформатирование при сохранении настраиваются в [Настройка VS Code](/docs/applied/vscode).

docs/docs/applied/styles/postcss.md

@@ -0,0 +1,71 @@
+---
+title: PostCSS
+keywords: [postcss, postcss.config.mjs, postcss-custom-media, postcss-nesting, autoprefixer, postcss-global-data, csstools, "@custom-media", "@nest", css-процессор]
+---
+
+# PostCSS
+
+Установка и настройка CSS-процессора PostCSS в проекте: набор плагинов, конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.
+
+Правила написания CSS в компонентах — [Использование](/docs/applied/styles/usage).
+
+## Зачем PostCSS
+
+Подключаем ради двух вещей:
+
+- **Вложенность** — `&:hover`, `&::before`, `&._active` и `@media` внутри селектора. Без процессора нативный CSS не покрывает всех нужных кейсов вложенности.
+- **`@custom-media`** — единые breakpoints проекта (`@media (--md)`) вместо магических `min-width`. Определяются в одном месте, переиспользуются везде.
+
+Autoprefixer и `@csstools/postcss-global-data` идут довеском под эти две задачи.
+
+## Требования
+
+- Next.js 14+ (App Router).
+- Node.js 18+.
+
+CSS Modules поддерживаются Next.js из коробки — отдельной установки не требуют.
+
+## Установка
+
+1. Установить PostCSS-плагины как devDependencies:
+
+   ```bash
+   npm install -D postcss-custom-media postcss-nesting autoprefixer @csstools/postcss-global-data
+   ```
+
+2. Создать `postcss.config.mjs` в корне проекта (см. «Конфиг»).
+
+## Конфиг
+
+Файл `postcss.config.mjs` в корне проекта.
+
+```js
+// postcss.config.mjs
+export default {
+  plugins: {
+    '@csstools/postcss-global-data': {
+      files: ['src/shared/styles/media.css'],
+    },
+    'postcss-custom-media': {},
+    'postcss-nesting': {},
+    autoprefixer: {},
+  },
+}
+```
+
+### Разбор плагинов
+
+| Плагин | Назначение |
+|--------|------------|
+| `@csstools/postcss-global-data` | Подгружает определения `@custom-media` из `src/shared/styles/media.css` перед обработкой каждого CSS-модуля. Семантика — «глобальный файл определений, который не импортируется в исходники» |
+| `postcss-custom-media` | Поддержка `@custom-media --md (...)` и использования `@media (--md) {}`. Определения берутся из файла, который подгрузил `postcss-global-data` |
+| `postcss-nesting` | Нативная CSS-вложенность: `&:hover`, `&::before`, `&._active` |
+| `autoprefixer` | Добавление вендорных префиксов по browserslist |
+
+### Почему внешний файл с `@custom-media`, а не `@import`
+
+`@custom-media` — глобальные определения, одинаковые для всего проекта. Держим их в `src/shared/styles/media.css`. `@csstools/postcss-global-data` подгружает этот файл перед каждым модулем, а `postcss-custom-media` заменяет `@media (--md)` на конкретные `@media (min-width: ...)` на этапе сборки. Сами определения в бандл не попадают.
+
+Опция `importFrom` у `postcss-custom-media` удалена в v10+; её роль теперь выполняет `@csstools/postcss-global-data`.
+
+Импортировать `media.css` в файлы компонентов **не нужно** и запрещено правилами (см. [Использование](/docs/applied/styles/usage), раздел «Импорт стилей»).

docs/docs/applied/styles/usage.md

@@ -1,10 +1,10 @@
 ---
-title: Стили
+title: Использование
 ---
 
-# Стили
+# Использование
 
-Правила написания CSS: PostCSS Modules, форматирование, переменные.
+Правила написания CSS: PostCSS Modules, форматирование, переменные. Установка и настройка процессора — [PostCSS](/docs/applied/styles/postcss).
 
 ## Общие правила
 

docs/docs/applied/svg-sprites.md

@@ -1,5 +0,0 @@
----
-title: SVG-спрайты
----
-
-# SVG-спрайты

docs/docs/applied/svg-sprites/setup.md

@@ -0,0 +1,108 @@
+---
+title: Установка и настройка
+keywords: [svg-sprites, установка, настройка, config, пакет, "@gromlab/svg-sprites", svg-sprites.config.ts]
+---
+
+# Установка и настройка
+
+Первичная настройка пакета `@gromlab/svg-sprites` в проекте. Выполняется один раз при заведении проекта и при смене мажорной версии пакета.
+
+Что такое спрайты, как с ними работать и как управлять цветом — [Использование](/docs/applied/svg-sprites/usage).
+
+## Требования
+
+- Node.js 18+
+- React 18+
+
+## Установка
+
+1. Установить пакет:
+
+   ```bash
+   npm install @gromlab/svg-sprites
+   ```
+
+2. Создать `svg-sprites.config.ts` в корне проекта (см. «Стандартный конфиг»).
+
+3. Создать папку входа для SVG-файлов в слое `shared`:
+
+   ```bash
+   mkdir -p src/shared/sprites/icons
+   ```
+
+   Источники спрайтов живут в `src/shared/sprites/<group>/` — это слой `shared` SLM-архитектуры (см. [Структура проекта](/docs/applied/project-structure), [Архитектура](/docs/basics/architecture/)). В `src/` посторонних каталогов вне слоёв не заводим.
+
+4. Добавить скрипты в `package.json`:
+
+   ```json
+   {
+     "scripts": {
+       "sprite": "svg-sprites",
+       "predev": "svg-sprites",
+       "prebuild": "svg-sprites"
+     }
+   }
+   ```
+
+   Хуки `predev` и `prebuild` гарантируют, что спрайты и типы всегда актуальны перед запуском и сборкой.
+
+5. Добавить сгенерированные артефакты в `.gitignore`:
+
+   ```text
+   # Сгенерированные спрайты и React-компонент
+   /public/sprites/
+   /src/ui/svg-sprite/
+   ```
+
+6. Выполнить первую генерацию:
+
+   ```bash
+   npm run sprite
+   ```
+
+## Стандартный конфиг
+
+Файл `svg-sprites.config.ts` в корне проекта. Это канон — отклонения только по явной причине.
+
+```ts
+// svg-sprites.config.ts
+import { defineConfig } from '@gromlab/svg-sprites'
+
+export default defineConfig({
+  output: 'public/sprites',
+  publicPath: '/sprites',
+  react: 'src/ui/svg-sprite',
+  sprites: [
+    { name: 'icons', input: 'src/shared/sprites/icons' },
+  ],
+})
+```
+
+### Фиксированные значения
+
+| Опция | Значение | Почему так |
+|-------|----------|------------|
+| `output` | `public/sprites` | Единая папка статики Next.js |
+| `publicPath` | `/sprites` | URL-путь без `public/` (Next.js раздаёт `public/` как `/`) |
+| `react` | `src/ui/svg-sprite` | Слой `ui/` из архитектуры проекта (→ [Архитектура](/docs/basics/architecture/)) |
+| `sprites[0].name` | `icons` | Основной спрайт всегда называется `icons` |
+
+### Трансформации
+
+Все значения по умолчанию оставлять включёнными:
+
+```ts
+transform: {
+  removeSize: true,
+  replaceColors: true,
+  addTransition: true,
+}
+```
+
+Явно прописывать блок `transform` не нужно — пакет применяет эти значения по умолчанию.
+
+Отключать `replaceColors` — только для отдельного спрайта с фиксированной палитрой (например, брендовые логотипы). Делать это на уровне спрайта, не глобально.
+
+### Режим
+
+По умолчанию `mode: 'stack'` — не указывать явно. Переход на `symbol` требует обоснования: превью и примеры в пакете оптимизированы под `stack`.

docs/docs/applied/svg-sprites/usage.md

@@ -0,0 +1,55 @@
+---
+title: Использование
+keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color]
+---
+
+# Использование
+
+Работа с SVG-иконками через сгенерированный компонент `<SvgSprite/>`. Установка пакета — [Установка и настройка](/docs/applied/svg-sprites/setup).
+
+## Шаги
+
+1. **Положить SVG в папку спрайта:**
+
+   ```text
+   src/shared/sprites/icons/new-icon.svg
+   ```
+
+2. **Импортировать компонент.** Компонент `<SvgSprite/>` генерируется пакетом вместе с типами имён иконок — автодополнение работает без ручных описаний:
+
+   ```tsx
+   import { SvgSprite } from 'ui/svg-sprite'
+
+   <SvgSprite icon="new-icon" />
+   ```
+
+3. **Посмотреть и пощупать иконку — в превью.** Пакет генерирует HTML-превью рядом со спрайтом (`public/sprites/icons.preview.html`). Там виден набор иконок, имена и поведение цвета.
+
+## Управление цветом
+
+При сборке цвета в SVG заменяются на CSS-переменные `--icon-color-N`. Управление — через обычный CSS родителя.
+
+**Моно-иконка** наследует `color` родителя (`--icon-color-1` по умолчанию `currentColor`):
+
+```css
+.button {
+  color: var(--color-primary);
+}
+```
+
+**Точечное переопределение** — через переменную:
+
+```css
+.icon-danger {
+  --icon-color-1: var(--color-danger);
+}
+```
+
+**Мульти-иконка** — переменные задаются явно, порядок виден в превью:
+
+```css
+.folder {
+  --icon-color-1: var(--color-folder-bg);
+  --icon-color-2: var(--color-folder-accent);
+}
+```

docs/docs/workflow/styling.md

@@ -20,4 +20,4 @@ title: Стилизация
 - **Магические значения** — произвольные цвета, отступы и скругления запрещены, использовать токены.
 - **Глобальные стили** вне `app/styles/` запрещены.
 
-Правила написания CSS, вложенность, медиа-запросы и токены — [Стили](/docs/applied/styles).
+Правила написания CSS, вложенность, медиа-запросы и токены — [Стили: использование](/docs/applied/styles/usage).