rf4-spotter/docs/brand-system.md

# Визуальная система RF4 Spotter

## Основа бренда

**RF4 Spotter** — имя продукта и основная подпись во всех интерфейсах, metadata, manifest и социальных карточках. **«Ни хвоста, ни чешуи»** — эмоциональный слоган сообщества; он не заменяет имя и всегда визуально вторичен.

Характер: полевой журнал современного рыболова — точный, спокойный, немного экспедиционный. Интерфейс не имитирует игровой клиент и не обещает гарантированный клёв.

## Визуальные роли

- Тёмная вода (`deep`, `teal`) — навигация, ключевые панели и высокий информационный вес.
- Бумага (`paper`, `white`) — рабочая поверхность и длинное чтение.
- Лайм (`lime`) — активное действие, свежий сигнал и фокус; не декоративная заливка больших площадей.
- Оранжевый — приманка и тёплый акцент, но не системный статус ошибки.
- Антиква Georgia — крупные редакционные заголовки и числа; Inter/system sans — управление, подписи и данные.

Семантические CSS-токены отделяют роль от оттенка: `--surface*`, `--text*`, `--border*`, `--focus`, `--success*`, `--warning*`, `--danger*` и `--source-*`. Компонент не должен вводить новый системный зелёный, жёлтый или красный без отдельной смысловой роли. Основной текст на светлой поверхности использует `--text`, вторичный — `--text-muted`; `--text-subtle` допустим только для крупного или вспомогательного текста, прошедшего WCAG AA.

## Фирменные мотивы

- Крючок — знак бренда и favicon.
- Поплавок — индекс активности и состояние ожидания.
- Леска — время и последовательность наблюдений.
- Рябь — свежесть или обновление, только в спокойной анимации.
- Координатная сетка/радар — точка, но не ложная карта водоёма.
- Силуэт рыбы — различение сущностей каталога, не фоновый орнамент каждой секции.

Один блок использует один главный мотив. Источник и качество всегда передаются текстом вместе с цветом. Декор не должен конкурировать с координатами, весом, свежестью и provenance.

Матрица применения:

| Мотив | Где используется | Где не используется |
|---|---|---|
| Крючок | знак RF4 Spotter, favicon | статусы и кнопки действий |
| Поплавок | индекс активности, ожидание и пустое состояние | ошибка, источник, координаты |
| Леска | временная шкала наблюдений | произвольный разделитель карточки |
| Рябь | живой пульс свежих данных | неполные и устаревшие записи |
| Радар/сетка | точные координаты | фон карточек без координат |
| Силуэт рыбы | каталог и карточка вида | общий орнамент страницы |

Неполные данные получают тёплую верхнюю полевую метку и текстовый статус. Ошибка не изображается «мёртвым поплавком»: она передаётся системным danger-состоянием и понятным действием пользователя.

## Компонентная подпись

`StatePanel` — единая рамка для пустых, недоступных и ошибочных состояний. Пустое состояние имеет роль `status`, недоступное и ошибочное — `alert`; цвет сообщает смысл, а не заменяет заголовок и пояснение. На вложенных карточках компонент используется без внешнего `content-grid`.

CTA задаются смыслом через `data-action`: `primary` — основное безопасное действие, `secondary` — продолжение или навигация, `inverse` — действие на тёмном фоне, `danger` и `quiet-danger` — отрицательное и необратимое действие, `quiet` — сброс или малозаметная отмена. На одном экране по возможности оставляется один визуально главный CTA.

## Движение

Движение объясняет состояние: пульс означает живой сигнал, поплавок — активность точки, sweep — загрузку, короткий сдвиг — отклик интерактивного элемента. Декоративные бесконечные анимации не используются. Длительности берутся из `--motion-fast`, `--motion-base`, `--motion-signal`, easing — из `--ease-out`; `prefers-reduced-motion` сводит все анимации и переходы к одному кадру.

## Каталог как полевой атлас

Каталоги используют собственную редакционную композицию: круглый тёмный seal показывает тип и объём справочника, порядковые номера создают ощущение системного атласа. Водоём обозначается абстрактным береговым контуром и точкой наблюдения, рыба — силуэтом. Эти фоновые знаки всегда декоративны, имеют низкий контраст и не заменяют текстовое название.

Силуэт рыбы выбирается по узнаваемому типу тела, а не случайному hash имени: щуковые, лососёвые, карповые, окуневые, сомовые, угреобразные, плоские и морские. Классификатор поддерживает русские и основные названия источников, неизвестная сущность получает нейтральную форму. Явный `family` имеет приоритет над эвристикой и служит точкой ручной коррекции.

Приманки различаются типовым контуром только при явном указании категории в названии: блесна, воблер, мягкая приманка, бойл, естественная наживка или оснастка. Неизвестное название получает нейтральную каплевидную форму. Один из пяти спокойных акцентных цветов детерминирован normalized name и помогает повторно узнавать строку, но не кодирует эффективность, качество или игровую характеристику.

Водоём получает воспроизводимый абстрактный отпечаток по каноническому slug: один из восьми контуров берега, от одной до трёх линий воды, положение точки и двухсимвольный индекс. Он помогает узнавать сущность между каталогом и detail-страницей, но не изображает карту, реальные координаты или форму игрового водоёма. Текстовое название всегда остаётся главным идентификатором.

На странице сочетания два знака образуют одну атласную эмблему: отпечаток водоёма служит нижним слоем, силуэт рыбы — верхним, а маленький знак пересечения подчёркивает смысл «вид на конкретном водоёме». Эмблема декоративна; названия обеих сущностей остаются в текстовой и навигационной иерархии.

Detail-страницы связывает навигационная леска: каждый уровень представлен текстовым узлом, пунктир между узлами показывает путь, а лаймовый конечный узел — текущую страницу. На мобильном цепочка остаётся однострочной и прокручиваемой, не сокращая названия и не превращая мотив в единственный носитель смысла.

## Brand assets и QA

`favicon.svg` — мастер обычных favicon, Apple Touch и PWA `purpose: any`; PNG генерируются из него напрямую в целевом размере, а не масштабируются из малого растра. `icon-maskable.svg` — полнофоновый мастер для отдельных `purpose: maskable` 192/512 px, чтобы системная маска не открывала прозрачные углы. OG имеет ровно 1200×630 px и использует тот же тёмный водный фон, лаймовый поплавок и координатную сетку. Проверены desktop и 390 px каталоги, 32/180/192/512 px assets, светлая поверхность сайта и тёмные бренд-носители.

Секции данных используют `SectionHeading`: короткий uppercase eyebrow задаёт контекст, антиквенный заголовок называет сущность, необязательное описание объясняет правила, а счётчик всегда расположен справа или под текстом на мобильном. Так число результатов не конкурирует с названием раздела и одинаково читается в рекордах и полевых сигналах.

Каталоги, detail-выборки и страницы прозрачности используют `PageHero`: один контекст, один `h1`, одно короткое пояснение. Это сохраняет одинаковый вертикальный ритм и SEO-иерархию независимо от наличия данных.

## План внедрения

Рабочие статусы B01–B06 ведутся в [ROADMAP.md](ROADMAP.md). После каждого пакета выполняются Astro check/build и адресная визуальная проверка ключевых desktop/mobile-композиций. Новые bitmap-иллюстрации не добавляются, пока существующие SVG/CSS-мотивы решают задачу без лишнего веса.