# ТРОПЫ КАВКАЗА — инструкция по дизайн-системе
Гостевой визуальный язык «Троп Кавказа» (Атажукинский сад, Нальчик). Из него собираются публичный сайт, PWA и приложения для посетителей. Админ-панель Trails в эту систему **не входит**: она остаётся тёмной и операционной.
Живой каталог: [index.html](index.html).
Демо-лендинг на реальных данных: [../landing/index.html](../landing/index.html).
Соседняя система (не путать): [../../Saki/design-system/INSTRUCTION.md](../../Saki/design-system/INSTRUCTION.md).
---
## 0. Какую систему брать
| Бренд (`VITE_BRAND`) | Папка | Префикс | Характер |
|---|---|---|---|
| `kavkaz` (по умолчанию) | `examples/kavkaz/design-system` | `kvk-` / `--kvk-*` | Холодный туман, сланец, высота |
| `saki` | `examples/Saki/design-system` | `spk-` / `--spk-*` | Тёплая бумага, шалфей, жёлтый нажим |
| `crimea` | `examples/crimea/design-system` | `crm-` / `--crm-*` | Море / песок / кипарис, каталог зон |
`user-web` — **мультитенантный**. Не навешивать правило «всегда Саки» на весь `user-web/**`. Гостевая тема выбирается по бренду (`kavkazTheme` / `sakiTheme` / `crimeaTheme`). Админку не перекрашивать этими системами. Крым: [../../crimea/design-system/INSTRUCTION.md](../../crimea/design-system/INSTRUCTION.md).
---
## 1. Что это и зачем
«Тропы Кавказа» — один парк, не мультизонный каталог как Крым. Домашняя страница продукта — park landing → карта и маршруты.
Система «Сланец и горизонтали» снимает характер с уже работающей темы [`user-web/src/theme/kavkazTheme.ts`](../../../user-web/src/theme/kavkazTheme.ts) и логотипа (хвоя / небо / крем), добавляя медь высоты и текстуру топографических горизонталей.
Правило: **сначала каталог и эта инструкция, потом код**. Не копировать индиго MUI. Не тащить токены Саки «потому что уже есть».
Префикс CSS: `kvk-`. Токены: `--kvk-*`.
---
## 2. Состав папки
| Файл | Роль |
|---|---|
| [INSTRUCTION.md](INSTRUCTION.md) | Эта инструкция |
| [index.html](index.html) | Живой каталог |
| [tokens.css](tokens.css) | CSS-переменные |
| [tokens.json](tokens.json) | Токены для JS / натива |
| [components.css](components.css) | Кит классов `kvk-*` |
| [kavkazTheme.ts](kavkazTheme.ts) | Тема MUI для React |
Рядом: `examples/kavkaz/landing` — демо с GPS-треками и профилем высот из прод-дампа.
---
## 3. Как смотреть
Из корня репозитория:
```bash
python -m http.server 8765
```
- Каталог: http://127.0.0.1:8765/examples/kavkaz/design-system/
- Лендинг: http://127.0.0.1:8765/examples/kavkaz/landing/
- Саки (для сравнения): http://127.0.0.1:8765/examples/Saki/design-system/
Шрифты с Google Fonts — нужен интернет. В каталоге клик по цвету копирует HEX.
---
## 4. Принципы (не нарушать)
1. **Туман, не кремовая бумага.** Фон `#e6ebef` + горизонтали. Карточка **белая** `#ffffff`. Это намеренно против Саки.
2. **Хвоя действует на CTA.** Primary = fir `#4a6741`, текст **белый** (`#fff`). Нажим `0 3px 0 #3a5234`. Не наследуйте цвет ссылки на `.kvk-btn`.
3. **Сланец — структура.** Slate `#3d4f5f` для навигации, outline-чипов и вторичных акцентов, не как «чёрная плита» primary.
4. **Антиква только для имён.** Manrope — UI. Source Serif 4 — названия маршрутов и POI.
5. **Холодная тень.** `rgba(36, 48, 56, …)`, не тёплый коричневый Саки.
6. **Медь = высота. Вода = озеро.** Copper `#b07a45` — профиль высот и набор метров. Water `#88c4ce` — озеро, река, минеральные источники (цвет из логотипа). Не красить ими весь хром.
7. **Сложность = backend enum.** `EASY / MEDIUM / HARD / PRO` → четыре цвета в токенах.
8. **Медицина без терракоты.** Записка — холодный slate на `#e8eef2`, не персиковый `#f7ede6` Саки.
9. **Мобильная навигация — нижние вкладки.**
10. **Нет тёмной темы у гостя.** Есть `prefers-reduced-motion`.
---
## 5. Чем отличается от Саки
| Ось | Кавказ | Саки |
|---|---|---|
| Температура | холодный mist | тёплый cream |
| Карточка | белая | кремовая (белый запрещён) |
| Primary | slate, белый текст | sage, оливковый текст |
| Нажим | сланцевый шаг | жёлтая ступенька |
| Шрифты | Manrope + Source Serif 4 | Golos Text + Lora |
| Радиусы | 10 / 14 / 20 | 14 / 18 / 26 |
| Текстура | топографические горизонтали | зерно из точек |
| Сигнатура | профиль высот (медь) | план парка / станции терренкура |
| Префикс | `kvk-` | `spk-` |
Блок сравнения — в каталоге, секция «Кавказ против Саки».
---
## 6. Шрифты
```html
```
| Роль | Шрифт | Класс |
|---|---|---|
| Display | Manrope 700 | `.kvk-display` |
| Заголовок секции | Manrope 700 | `.kvk-title` |
| Имя места / маршрута | Source Serif 4 600 | `.kvk-named` |
| Лид | Manrope 400 | `.kvk-lead` |
| Eyebrow / kicker | Manrope 600 | `.kvk-eyebrow`, `.kvk-kicker` |
| Бренд | Manrope 700 uppercase | `.kvk-brand-text` |
---
## 7. Цвета и роли
### Поверхности
| Токен | HEX | Куда |
|---|---|---|
| `--kvk-mist` | `#e6ebef` | Фон страницы |
| `--kvk-mist-2` | `#d8e0e7` | Чередующая секция |
| `--kvk-stone` | `#f7f5f2` | Мягкая подложка |
| `--kvk-card` | `#ffffff` | Карточка, инпут |
| `--kvk-ghost` | `#d5dde5` | Вторичная кнопка |
| `--kvk-fir-tint` | `#e2ebe0` | Eyebrow |
| `--kvk-slate-surface` | `#eef2f5` | Выбранная карточка |
| `--kvk-map-stage` | `#dfe6ec` | Подложка карты |
### Бренд
| Токен | HEX | Куда |
|---|---|---|
| `--kvk-slate` | `#3d4f5f` | Primary |
| `--kvk-slate-2` | `#2c3a46` | Hover / press |
| `--kvk-fir` | `#4a6741` | Secondary |
| `--kvk-copper` | `#b07a45` | Высота, MEDIUM |
| `--kvk-water` | `#88c4ce` | Вода, info |
| `--kvk-here` | `#2f7bd6` | «Вы здесь» |
### Сложность
| Enum | Токен | HEX |
|---|---|---|
| `EASY` | `--kvk-diff-easy` | `#4a6741` |
| `MEDIUM` | `--kvk-diff-medium` | `#b07a45` |
| `HARD` | `--kvk-diff-hard` | `#c45c3e` |
| `PRO` | `--kvk-diff-pro` | `#3d4f5f` |
---
## 8. Форма, тень, шаг
| Радиус | Значение | Куда |
|---|---|---|
| `--kvk-r` / `--kvk-r-sm` | 10px | Кнопка, инпут |
| `--kvk-r-md` | 14px | Карточка |
| `--kvk-r-lg` | 20px | Крупный блок / карта |
| `--kvk-r-pill` | 999px | Чип |
Тени: `--kvk-shadow-sm`, `--kvk-shadow`, `--kvk-press` (`0 3px 0` slate-2).
Шаг: 4 / 8 / 12 / 16 / 20 / 24 / 32 / 48. Поля: `--kvk-page-x`. Контент: `--kvk-max` 1240px.
---
## 9. Компоненты (классы)
```html
```
На `body`: `class="kvk-page"` — шрифт, mist, горизонтали.
### Кнопки
```html
```
Модификаторы: `kvk-btn-lg`, `kvk-btn-sm`.
### Чипы и теги
- Фильтр: `.kvk-chip` + `.is-on` (заливка slate, белый текст).
- Сортировка: `.kvk-chip.kvk-chip-outline` + `.is-on`.
- Режимы: `.kvk-tag-slate` / `.kvk-tag-copper` / `.kvk-tag-fir` / `.kvk-tag-water`.
### Карточки и смысл
- `.kvk-card` / `.kvk-card-lg` / `.kvk-card-hover`
- `.kvk-stat`, `.kvk-note`, `.kvk-empty`, `.kvk-pin`, `.kvk-num`
### Профиль высот (сигнатура)
```html
```
Классы внутри: `.fill` (медная заливка), `.line`, `.axis`, `.label`, `.poi`. Чип высоты: `.kvk-glass` + `.kvk-elev-dot`.
### Формы
`.kvk-field` / `.kvk-label` / `.kvk-input` — фокус = обводка slate.
---
## 10. Как внедрять в HTML-сайт
1. Подключить `tokens.css` + `components.css` и шрифты.
2. `class="kvk-page"` на `body`.
3. Собрать экраны из классов каталога / лендинга.
4. Новые экраны (логин, история) — те же токены, не Саки.
Минимальный каркас:
```html
…
…
```
---
## 11. Как внедрять в React / MUI (`user-web`)
1. Шрифты Manrope + Source Serif 4 в `index.html` (уже есть для кавказа).
2. Тема: существующий [`user-web/src/theme/kavkazTheme.ts`](../../../user-web/src/theme/kavkazTheme.ts) **или** расширенная копия из этой папки (`kavkazTheme.ts`) — подтянуть отдельно, когда решите синхронизировать.
3. `ThemeProvider` + `CssBaseline` при `VITE_BRAND=kavkaz`.
4. Не оставлять дефолтный MUI indigo.
5. Где MUI не покрывает (чип-фильтр, профиль высот) — `components.css` или `sx` из токенов этой инструкции.
Админ-панель **не** менять.
---
## 12. Другие платформы
Брать [tokens.json](tokens.json):
- `color.mist`, `color.slate`, `color.fir`, `color.copper`, `color.water`
- `radius.md` = 10, `radius.lg` = 14, `radius.xl` = 20
- `shadow.press` = `0 3px 0 #2c3a46`
- Шрифты: Manrope + Source Serif 4
На нативе горизонтали можно упростить до сплошного mist.
---
## 13. Данные лендинга
`landing/data.js` генерируется скриптом [`_migrate_check/_extract_kavkaz_landing_data.py`](../../../_migrate_check/_extract_kavkaz_landing_data.py) из SQL-дампа (зона Атажукинский сад, 3 маршрута с GPS и профилем высот, 27 точек). Перегенерация:
```bash
python _migrate_check/_extract_kavkaz_landing_data.py
```
---
## 14. Да / нет
**Да:** mist и горизонтали; fir-кнопка с белым текстом; Source Serif только в именах; медный профиль высот; холодные тени; нижние вкладки; выбор темы по бренду; GPS-трек поверх картографической подложки.
**Нет:** крем Саки; Golos/Lora; жёлтый нажим; sage primary; смешение `spk-` и `kvk-`; тёмная тема гостя; emoji как прод-иконки; перекраска админки.
---
## 15. Как расширять
1. Новый цвет — только с ролью. Добавить в `tokens.css` **и** `tokens.json`, плашку в `index.html`, строку в §7.
2. Новый компонент — сначала в каталоге, потом в `components.css`.
3. Не ломать `--kvk-*`. Короткие алиасы `--mist` / `--slate` нужны лендингу.
4. Синхронизация с `user-web/src/theme/kavkazTheme.ts` — отдельный осознанный шаг (не делать молча).
---
## 16. Для агента / разработчика
Источник правды для Кавказа: эта папка. Для Саки — `examples/Saki/design-system`. Перед вёрсткой гостевого UI определить бренд и открыть **его** каталог. Не применять кавказскую систему к `admin-panel`, пока пользователь явно не попросил.