docs: добавить стайлгайд nextjs-style-guide в репозиторий
- Добавлена документация SLM-архитектуры, базовых правил и прикладных разделов - Добавлены разделы: стили, SVG-спрайты, шаблоны генерации, PostCSS, REST, Realtime - Удалены устаревшие файлы (спрайты, скрипты, стили из app/)
This commit is contained in:
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: SVG-спрайты
|
||||
description: "Что такое SVG-спрайты и какие проблемы они решают."
|
||||
---
|
||||
|
||||
# SVG-спрайты
|
||||
|
||||
Что такое SVG-спрайты и какие проблемы они решают.
|
||||
|
||||
## Проблема
|
||||
|
||||
Иконки в проекте — это десятки и сотни SVG-файлов, которые нужно как-то доставлять в интерфейс. Подход «один `<img>` на иконку» или инлайн SVG в каждом компоненте приводят к трём проблемам:
|
||||
|
||||
- **Дублирование.** Инлайн SVG в нескольких компонентах — один и тот же код размазан по проекту. Изменение иконки требует правок в десяти местах.
|
||||
- **Размер бандла.** Каждый инлайн SVG — полный XML-код, который попадает в JS-бандл. Сотня иконок × средний размер SVG = сотни килобайт, которые браузер парсит как JavaScript, а не как статику.
|
||||
- **Нет управления цветом.** Инлайн SVG жёстко закрашивает иконку. Сменить цвет по состоянию (`:hover`, `._disabled`) — значит дублировать SVG или городить `currentColor`-хаки в каждом компоненте.
|
||||
|
||||
## Решение
|
||||
|
||||
SVG-спрайты — это единый файл-контейнер, в который собираются все иконки проекта. В коде используется один React-компонент `<SvgSprite icon="name"/>`, а браузер загружает спрайт как статику — один раз, с кешированием.
|
||||
|
||||
Что дают SVG-спрайты:
|
||||
|
||||
- **Один источник.** Каждая иконка — один SVG-файл в `src/shared/sprites/`. Обновил файл — иконка обновилась везде.
|
||||
- **Лёгкий бандл.** Спрайт отдаётся как статический файл из `public/`, не попадает в JavaScript. Типы имён иконок генерируются автоматически — автодополнение работает без ручных описаний.
|
||||
- **Цвет через CSS.** При сборке цвета в SVG заменяются на CSS-переменные. Цвет иконки меняется через `color` родителя или через переменные `--icon-color-N` — как любой другой стиль.
|
||||
|
||||
## Состав раздела
|
||||
|
||||
- [Настройка](./svg-sprites-setup.md) — подключение пакета, конфигурация, первая генерация.
|
||||
- [Использование](./svg-sprites-usage.md) — добавление иконок, компонент `<SvgSprite/>`, управление цветом.
|
||||
132
ai/nextjs-style-guide/applied/svg-sprites/svg-sprites-setup.md
Normal file
132
ai/nextjs-style-guide/applied/svg-sprites/svg-sprites-setup.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
title: Настройка SVG-спрайтов
|
||||
description: Подключение SVG-спрайтов в новом проекте.
|
||||
keywords: [svg-sprites, установка, настройка, config, пакет, "@gromlab/svg-sprites", svg-sprites.config.ts]
|
||||
---
|
||||
|
||||
# Настройка SVG-спрайтов
|
||||
Подключение SVG-спрайтов в новом проекте.
|
||||
|
||||
## Установка
|
||||
|
||||
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-архитектуры (см. [Структура проекта](../project-structure.md), [Архитектура](../../basics/architecture/index.md)). В `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
|
||||
```
|
||||
|
||||
7. Подключить спрайт в layout. Глобальный спрайт (иконки) подключается через `<link rel="preload">` в корневом layout — браузер загрузит файл заранее и закеширует:
|
||||
|
||||
```tsx
|
||||
// src/app/layout.tsx
|
||||
import 'shared/styles/global.css'
|
||||
|
||||
import type { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'App',
|
||||
description: '',
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<html lang="ru">
|
||||
<head>
|
||||
<link rel="preload" href="/sprites/icons.sprite.stack.svg" as="image" />
|
||||
</head>
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Локальные спрайты (если есть) подключаются аналогично в layout конкретной страницы или маршрута.
|
||||
|
||||
## Стандартный конфиг
|
||||
|
||||
Файл `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/` из архитектуры проекта (→ [Архитектура](../../basics/architecture/index.md)) |
|
||||
| `sprites[0].name` | `icons` | Основной спрайт всегда называется `icons` |
|
||||
|
||||
### Трансформации
|
||||
|
||||
Все значения по умолчанию оставлять включёнными:
|
||||
|
||||
```ts
|
||||
transform: {
|
||||
removeSize: true,
|
||||
replaceColors: true,
|
||||
addTransition: true,
|
||||
}
|
||||
```
|
||||
|
||||
Явно прописывать блок `transform` не нужно — пакет применяет эти значения по умолчанию.
|
||||
|
||||
Отключать `replaceColors` — только для отдельного спрайта с фиксированной палитрой (например, брендовые логотипы). Делать это на уровне спрайта, не глобально.
|
||||
|
||||
### Режим
|
||||
|
||||
По умолчанию `mode: 'stack'` — не указывать явно. Переход на `symbol` требует обоснования: превью и примеры в пакете оптимизированы под `stack`.
|
||||
|
||||
## Дальше
|
||||
|
||||
- [Использование](./svg-sprites-usage.md) — добавление иконок, компонент `<SvgSprite/>`, управление цветом.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Использование SVG-спрайтов
|
||||
description: Как добавлять и использовать SVG-иконки в коде.
|
||||
keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color]
|
||||
---
|
||||
|
||||
# Использование SVG-спрайтов
|
||||
|
||||
Как добавлять и использовать SVG-иконки в коде.
|
||||
|
||||
## Шаги
|
||||
|
||||
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);
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user