From 5a773a5b4f9cf821214c7266e1fc1fab49977e57 Mon Sep 17 00:00:00 2001 From: "S.Gromov" Date: Sun, 26 Apr 2026 22:50:51 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=80=D0=B0=D0=B7=D0=B4=D0=B5=D0=BB=D1=8B=20bio?= =?UTF-8?q?me,=20svg-=D1=81=D0=BF=D1=80=D0=B0=D0=B9=D1=82=D0=BE=D0=B2=20?= =?UTF-8?q?=D0=B8=20=D1=81=D0=B3=D1=80=D1=83=D0=BF=D0=BF=D0=B8=D1=80=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=D1=82=D1=8C=20=D1=81=D1=82=D0=B8=D0=BB=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Добавлен раздел «Biome» в прикладные разделы - Раздел «SVG-спрайты» преобразован в группу: установка, использование - Раздел «Стили» преобразован в группу: PostCSS, использование - Обновлён сайдбар VitePress с новыми группами - Перегенерирован README из главной страницы документации --- .vitepress/config.ts | 19 ++- README.md | 6 +- docs/docs/applied/biome.md | 80 +++++++++++++ docs/docs/applied/styles/postcss.md | 71 ++++++++++++ .../applied/{styles.md => styles/usage.md} | 6 +- docs/docs/applied/svg-sprites.md | 5 - docs/docs/applied/svg-sprites/setup.md | 108 ++++++++++++++++++ docs/docs/applied/svg-sprites/usage.md | 55 +++++++++ docs/docs/workflow/styling.md | 2 +- 9 files changed, 338 insertions(+), 14 deletions(-) create mode 100644 docs/docs/applied/biome.md create mode 100644 docs/docs/applied/styles/postcss.md rename docs/docs/applied/{styles.md => styles/usage.md} (97%) delete mode 100644 docs/docs/applied/svg-sprites.md create mode 100644 docs/docs/applied/svg-sprites/setup.md create mode 100644 docs/docs/applied/svg-sprites/usage.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index ef615bb..280a43d 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -36,15 +36,30 @@ const sidebar = [ { 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' }, ], }, diff --git a/README.md b/README.md index 0456939..a54f1b5 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,12 @@ **Для AI-агентов:** -- [Карта разделов](https://nextjs-style-guide.gromlab.ru/llms.txt) — `llms.txt`, оглавление со ссылками на разделы. -- [Полный текст](https://nextjs-style-guide.gromlab.ru/llms-full.txt) — `llms-full.txt`, вся документация одним файлом. +- [llms.txt](/llms.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/` или другую папку проекта. ## Структура документации diff --git a/docs/docs/applied/biome.md b/docs/docs/applied/biome.md new file mode 100644 index 0000000..32c6253 --- /dev/null +++ b/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). diff --git a/docs/docs/applied/styles/postcss.md b/docs/docs/applied/styles/postcss.md new file mode 100644 index 0000000..8200c87 --- /dev/null +++ b/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), раздел «Импорт стилей»). diff --git a/docs/docs/applied/styles.md b/docs/docs/applied/styles/usage.md similarity index 97% rename from docs/docs/applied/styles.md rename to docs/docs/applied/styles/usage.md index 3633133..4169cf8 100644 --- a/docs/docs/applied/styles.md +++ b/docs/docs/applied/styles/usage.md @@ -1,10 +1,10 @@ --- -title: Стили +title: Использование --- -# Стили +# Использование -Правила написания CSS: PostCSS Modules, форматирование, переменные. +Правила написания CSS: PostCSS Modules, форматирование, переменные. Установка и настройка процессора — [PostCSS](/docs/applied/styles/postcss). ## Общие правила diff --git a/docs/docs/applied/svg-sprites.md b/docs/docs/applied/svg-sprites.md deleted file mode 100644 index 2c1a175..0000000 --- a/docs/docs/applied/svg-sprites.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: SVG-спрайты ---- - -# SVG-спрайты diff --git a/docs/docs/applied/svg-sprites/setup.md b/docs/docs/applied/svg-sprites/setup.md new file mode 100644 index 0000000..e1f5eee --- /dev/null +++ b/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//` — это слой `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`. diff --git a/docs/docs/applied/svg-sprites/usage.md b/docs/docs/applied/svg-sprites/usage.md new file mode 100644 index 0000000..c8aa94e --- /dev/null +++ b/docs/docs/applied/svg-sprites/usage.md @@ -0,0 +1,55 @@ +--- +title: Использование +keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color] +--- + +# Использование + +Работа с SVG-иконками через сгенерированный компонент ``. Установка пакета — [Установка и настройка](/docs/applied/svg-sprites/setup). + +## Шаги + +1. **Положить SVG в папку спрайта:** + + ```text + src/shared/sprites/icons/new-icon.svg + ``` + +2. **Импортировать компонент.** Компонент `` генерируется пакетом вместе с типами имён иконок — автодополнение работает без ручных описаний: + + ```tsx + import { SvgSprite } from 'ui/svg-sprite' + + + ``` + +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); +} +``` diff --git a/docs/docs/workflow/styling.md b/docs/docs/workflow/styling.md index 5cadcf0..966d9a4 100644 --- a/docs/docs/workflow/styling.md +++ b/docs/docs/workflow/styling.md @@ -20,4 +20,4 @@ title: Стилизация - **Магические значения** — произвольные цвета, отступы и скругления запрещены, использовать токены. - **Глобальные стили** вне `app/styles/` запрещены. -Правила написания CSS, вложенность, медиа-запросы и токены — [Стили](/docs/applied/styles). +Правила написания CSS, вложенность, медиа-запросы и токены — [Стили: использование](/docs/applied/styles/usage).