sync

docs/ru/applied/components.md

@@ -0,0 +1,89 @@
+---
+title: Компоненты
+---
+
+# Компоненты
+
+Раздел описывает правила создания UI‑компонентов. Эти правила обязательны для всех слоёв FSD: `app`, `screens`, `layouts`, `widgets`, `features`, `entities`, `shared`.
+
+## Базовая структура компонента
+
+Минимальный набор файлов: компонент, стили, типы и публичный экспорт.
+
+```text
+container/
+├── styles/
+│   └── container.module.scss
+├── types/
+│   └── container.interface.ts
+├── container.ui.tsx
+└── index.ts
+```
+
+## Пример базового компонента
+
+`styles/container.module.scss`
+```scss
+.root {}
+```
+В CSS Modules использование имени класса **.root** — это общепринятое соглашение (best practice)
+
+`types/container.interface.ts`  
+```ts
+import type { HTMLAttributes } from 'react'
+
+/**
+ * Параметры контейнера.
+ */
+export interface ContainerProps extends HTMLAttributes<HTMLDivElement> {}
+```
+Интерфес параметров компонента всегда наследует свойства своего тега: div, button, итд..
+
+`container.ui.tsx`
+
+```tsx
+import type { FC } from 'react'
+import cl from 'clsx'
+import type { ContainerProps } from './types/container.interface'
+import styles from './styles/container.module.scss'
+
+/**
+ * Контейнер с адаптивной максимальной шириной.
+ *
+ * Используется для:
+ *  - ограничения ширины контента
+ *  - центрирования содержимого
+ *  - построения адаптивной сетки страницы
+ */
+export const Container: FC<ContainerProps> = ({ className, ...htmlAttr }) => {
+  return (
+    <div {...htmlAttr} className={cl(styles.root, className)}>
+      Container...
+    </div>
+  )
+}
+```
+
+- Компонент объявляется через `const` и экспортируется именованно.
+- Пропсы деструктурируются в сигнатуре; если их больше двух — деструктуризацию переносим в тело компонента.
+- Из пропсов отдельно извлекаются `className` и `...htmlAttr`, чтобы корректно объединять классы и прокидывать остальные атрибуты.
+- `cl` — короткое имя функции для конкатенации CSS‑классов.
+- `FC<>` используется для декларации `children`.
+
+`index.ts`
+
+```ts
+export { Container } from './container.ui'
+```
+
+## Шаблоны и генерация кода
+
+Создание компонентов — **только через шаблоны**. Ручное создание файловой структуры компонента запрещено. Это обеспечивает единообразие каркаса, одинаковые папки и имена файлов, уменьшает ручные ошибки и ускоряет старт работы.
+
+После генерации через **@gromlab/create** — проверить название компонента/файлов и заполнить описание назначения. Подробный порядок действий и перечень обязательных шаблонов — в разделе «Workflow».
+
+## Вложенные (дочерние) компоненты
+
+Если для реализации функционала нужны компоненты, которые используются только внутри текущего компонента, создавайте их как вложенные в папке `ui/`. Такие компоненты не экспортируются наружу и используются только локально.
+
+Вложенные компоненты подчиняются тем же правилам по структуре, именованию и стилю (включая папку `styles/` для их стилей).

docs/ru/applied/project-structure.md

@@ -0,0 +1,118 @@
+---
+title: Структура проекта
+---
+
+# Структура проекта
+
+Раздел описывает базовую структуру проекта и принципы организации модулей на уровне папок и файлов.
+
+## Базовая структура проекта
+
+Слои FSD не зависят от фреймворка. Различается только содержимое `app/` — в React SPA это конфигурация роутинга, в Next.js — системные файлы фреймворка (`layout.tsx`, `page.tsx`, route-сегменты).
+
+```text
+src/
+├── app/                  # Инициализация приложения (см. «Слой app/»)
+├── screens/              # UI-компоненты страниц
+│   └── profile/
+│       ├── profile.screen.tsx
+│       └── index.ts
+├── layouts/              # Общие шаблоны и каркасы страниц
+│   └── main-layout/
+│       ├── main-layout.layout.tsx
+│       └── index.ts
+├── widgets/              # Крупные блоки интерфейса
+│   └── header/
+│       ├── header.widget.tsx
+│       └── index.ts
+├── features/             # Пользовательские сценарии
+│   └── auth-by-email/
+│       ├── ui/
+│       │   └── login-form.ui.tsx
+│       ├── model/
+│       │   └── auth-by-email.store.ts
+│       ├── auth-by-email.feature.tsx
+│       └── index.ts
+├── entities/             # Бизнес-сущности
+│   └── user/
+│       ├── model/
+│       │   └── user.store.ts
+│       ├── user.entity.tsx
+│       └── index.ts
+└── shared/               # Общие ресурсы проекта
+    ├── ui/               # Повторно используемые UI-элементы
+    │   └── icon/
+    │       ├── styles/
+    │       │   └── icon.module.css
+    │       ├── types/
+    │       │   └── icon.interface.ts
+    │       ├── icon.ui.tsx
+    │       └── index.ts
+    ├── lib/              # Утилиты и хелперы
+    ├── services/         # Общие сервисы и клиенты
+    ├── config/           # Общие конфигурации и константы
+    └── assets/           # Ресурсы
+        ├── images/
+        ├── icons/
+        ├── fonts/
+        └── video/
+```
+
+## Слой app/
+
+Общее для обоих вариантов: провайдеры и глобальные стили. Различается только способ организации роутинга.
+
+### React SPA
+
+```text
+src/app/
+├── providers/            # Провайдеры и обёртки приложения
+├── routing/              # Конфигурация маршрутов (React Router)
+├── styles/               # Глобальные стили, CSS-переменные, custom media
+└── index.ts              # Entry point приложения
+```
+
+### Next.js (App Router)
+
+```text
+src/app/
+├── providers/            # Провайдеры и обёртки приложения
+├── styles/               # Глобальные стили, CSS-переменные, custom media
+├── layout.tsx            # Корневой layout (подключает providers, styles)
+├── page.tsx              # Главная страница
+└── profile/
+    └── page.tsx          # Рендерит ProfileScreen
+```
+
+В Next.js файлы `page.tsx` остаются тонкими — они только импортируют экран из `screens/` и рендерят его. Вся логика, зависимости и стили страницы живут в компоненте экрана, а не в `app/`.
+
+```tsx
+// src/app/profile/page.tsx
+import { ProfileScreen } from '@/screens/profile';
+
+export default function ProfilePage() {
+  return <ProfileScreen />;
+}
+```
+
+**Плохо**
+```text
+// Плохо: слои смешаны, нет понятных границ и публичного API.
+src/
+├── components/
+├── api/
+├── styles/
+└── user.ts
+```
+
+## Правила организации
+
+- В слоях FSD (`features`, `entities`, `widgets`, `screens` и т.д.) `ui/` используется только для дочерних элементов, которые относятся к модулю и не экспортируются отдельно. Главные компоненты, которые составляют сам слой, держат собственные `*.feature.tsx`, `*.widget.tsx` и т. п., а `ui/` служит для вспомогательных мелких компонентов.  
+- В `shared/ui/` хранятся базовые UI-элементы/компоненты, которыми пользуются сразу несколько модулей; в этом случае они экспортируются наружу и не считаются «дочерними» для слоя.
+- Если модуль строится вокруг «главного» компонента (`*.feature.tsx`, `*.screen.tsx`, `*.widget.tsx`), помещайте его в корень модуля и экспортируйте через `index.ts`. Проверяйте, что `ui/` не используется просто как «контейнер» слоя.
+
+- Каждый слой и модуль хранится в собственной папке.
+- Внутренние реализации разделяются на `ui/`, `model/`, `styles/`, `helpers/`, `lib/`, `api/`.
+- Публичный API модуля объявляется в `index.ts`.
+- Внутренние файлы не импортируются напрямую извне.
+- Не смешивать ответственность разных слоёв в одном модуле.

docs/ru/applied/styles.md

@@ -0,0 +1,283 @@
+---
+title: Стили
+---
+
+# Стили
+
+Раздел описывает правила написания CSS: PostCSS Modules, вложенность, медиа-запросы, переменные, форматирование.
+
+## Приоритет стилизации
+
+Приоритет инструментов стилизации (от высшего к низшему):
+
+1. **Mantine-компоненты и их пропсы** — в первую очередь использовать встроенные возможности Mantine.
+2. **Глобальные CSS-токены** (`--color-*`, `--space-*`, `--radius-*`) — для значений, которые не покрываются Mantine.
+3. **PostCSS Module файлы** — когда Mantine не покрывает задачу и нужна кастомная стилизация.
+
+- Инлайн-стили в компонентах запрещены.
+- Произвольные магические значения цветов, отступов и скруглений запрещены — использовать токены.
+- Глобальные стили вне `app/styles/` запрещены.
+
+Подробный порядок действий — в разделе «Workflow».
+
+## Общие правила
+
+- Только **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.
+- Исключение — нетривиальные хаки и обходные решения, к которым стоит оставить пояснение.

docs/ru/applied/svg-sprites.md

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

docs/ru/applied/templates-generation.md

@@ -0,0 +1,138 @@
+---
+title: Шаблоны генерации кода
+---
+
+# Шаблоны генерации кода
+
+Раздел описывает инструменты, синтаксис шаблонов и примеры. Порядок действий при создании модулей и перечень обязательных шаблонов — в разделе «Workflow».
+
+## Обязательность
+
+- Создание типовых модулей — **только через шаблоны**. Ручное создание файловой структуры модуля запрещено, если для него существует шаблон.
+- Перед созданием нового модуля — проверить наличие подходящего шаблона в `.templates/`.
+- Если подходящего шаблона нет — сначала создать шаблон, затем использовать его.
+
+## Что генерируем
+
+- Компоненты (`screens`, `layouts`, `widgets`, `features`, `entities`).
+- Страницы (nextjs `app`, `pages`).
+- Типовые инфраструктурные модули (например, `store`).
+
+## Чем генерируем
+
+### VSCode extension
+
+[расширение VS Code](https://open-vsx.org/extension/MyTemplateGenerator/mytemplategenerator) — создание файлов и папок из шаблонов через UI‑интерфейс внутри редактора.
+
+### CLI (для агентов)
+
+[@gromlab/create](https://gromlab.ru/gromov/create) — CLI для генерации файлов и папок по шаблонам.
+
+Примеры:
+```bash
+# Создать компонент
+create component button
+
+# Создать компонент используя NPX
+npx @gromlab/create component button
+```
+
+## Структура папок
+Все шаблоны лежат в `.templates/` в корне проекта.  
+Каждая папка в `.templates/` — это уникальный шаблон.  
+
+```text
+.templates/                     # корневая папка всех шаблонов
+├── component/                  # шаблон компонента
+│   └── {{name.kebabCase}}/
+│       ├── styles/
+│       │   └── {{name.kebabCase}}.module.css
+│       ├── types/
+│       │   └── {{name.kebabCase}}.interface.ts
+│       ├── {{name.kebabCase}}.ui.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
+```
+
+Пример использования в шаблоне:
+
+```text
+{{name}}.tsx
+{{name.pascalCase}}.tsx
+```
+
+```tsx
+export const {{name.pascalCase}} = () => {
+  return <div>{{name}}</div>
+}
+```
+
+## Шаблон компонента
+
+Структура компонента по шаблону. Создаётся генератором автоматически.
+
+```ts
+// .templates/component/index.ts
+export { {{name.pascalCase}} } from './{{name.kebabCase}}.ui'
+```
+
+```ts
+// .templates/component/types/{{name.kebabCase}}.interface.ts
+import type { HTMLAttributes } from 'react'
+
+/**
+ * Параметры {{name.pascalCase}}.
+ */
+export interface {{name.pascalCase}}Props extends HTMLAttributes<HTMLDivElement> {}
+```
+
+```tsx
+// .templates/component/{{name.kebabCase}}.ui.tsx
+import type { FC } from 'react'
+import cl from 'clsx'
+import type { {{name.pascalCase}}Props } from './types/{{name.kebabCase}}.interface'
+import styles from './styles/{{name.kebabCase}}.module.css'
+
+/**
+ * {{name.pascalCase}}.
+ */
+export const {{name.pascalCase}}: FC<{{name.pascalCase}}Props> = ({ className, ...htmlAttr }) => {
+  return (
+    <div {...htmlAttr} className={cl(styles.root, className)}>
+      {{name.kebabCase}}
+    </div>
+  )
+}
+```
+
+```css
+/* .templates/component/styles/{{name.kebabCase}}.module.css */
+.root {
+
+}
+```