docs: define ux contract and scorecard

docs/ux-contract.md

@@ -0,0 +1,68 @@
+# UX-контракт и scorecard RF4 Spotter
+
+Версия: 20 сентября 2026 года. Документ задаёт проверяемый смысловой
+контракт публичного интерфейса. Он не заменяет ручной visual review и
+production-метрики.
+
+## Главная задача игрока
+
+Ответ должен вести по цепочке:
+
+`рыба → водоём → точка → что взять → почему доверять`
+
+Первый полезный ответ — первая видимая карточка, в которой одновременно
+есть точка, координаты или их честнее отсутствие, действие/снасть и evidence
+свежести, выборки, доверия и источника. Регистрация и внешний поиск не нужны.
+
+## Контракт маршрутов
+
+| Маршрут | Первый смысловой блок | Основное действие | Обязательное объяснение |
+|---|---|---|---|
+| `/` | контекст запроса и горячие точки | открыть точку | период, сортировка, freshness и evidence |
+| `/spots/:id` | координаты и точность | сохранить/скопировать точку | активность, выборка, доверие и источник |
+| `/waterbodies/:slug` | водоём и подтверждённые сведения | выбрать рыбу | источник справочника и свежесть |
+| `/plan` | сохранённые варианты | открыть, удалить, поделиться или печатать | локальность данных и лимит 5 |
+| `/tackle` | подтверждённый каталог | выбрать снасть | источник, полнота и отсутствие догадок |
+
+Вторичные provenance-поля могут быть ниже первого ответа, но не должны
+исчезать, заменяться декоративным рейтингом или становиться единственным
+способом понять статус.
+
+## Словарь состояний
+
+| Код | Текст для игрока | Поведение |
+|---|---|---|
+| `fresh` | Свежие данные | Можно использовать как текущий сигнал, но не как гарантию улова |
+| `stale` | Данные устарели | Показывать возраст и снижать доверие; не называть точку горячей без оговорки |
+| `insufficient_data` | Недостаточно данных | Показывать размер выборки и не выдавать рекомендацию как уверенную |
+| `blocked` | Источник временно ограничен | Сохранить старые подтверждённые данные, показать ограничение и не делать новый импорт |
+| `temporary_error` | Данные временно недоступны | Не заменять последнюю дату свежей; дать понятный retry/следующий шаг |
+| `verified` | Учтено | Есть разрешённый источник и достаточный контекст |
+| `incomplete` | Неполные данные | Перечислить отсутствующие поля, а не скрывать карточку за цветом |
+
+## Scorecard
+
+| Метрика | Как измеряем | Цель альфы |
+|---|---|---:|
+| Time-to-first-useful-answer | от загрузки главной до первой видимой полной activity-карточки | ≤ 2 высот экрана на 390 px |
+| Filter-to-result steps | число действий от выбора фильтра до результата | ≤ 4 действия |
+| Query completion | доля участников, получивших точку без подсказки | ≥ 80% |
+| Context retention | back/reload сохраняют query или plan | 100% regression-сценариев |
+| Viewport integrity | `scrollWidth ≤ clientWidth` | 100% матрицы 320/390/768/1280 |
+| Accessibility | axe serious/critical, landmarks, labels, keyboard focus | 0 serious/critical |
+| Evidence completeness | источник, freshness, status и доменные поля доступны текстом | 100% публичных рекомендаций |
+| Print/share | plan печатается и открывается по ссылке | 100% smoke-сценариев |
+
+## Gates перед закрытием UI-задачи
+
+1. `npm --prefix apps/web run check` проходит без diagnostics.
+2. Адресный Playwright-тест покрывает новый journey и empty/error-state.
+3. Visual matrix проверяет 320/390/768/1280 px и light/dark/system.
+4. Не остаётся горизонтального overflow, ложных координат или статуса,
+   различимого только цветом.
+5. Для скорости production нужны реальные Lighthouse/Web Vitals; локальный
+   build подтверждает только лабораторный baseline.
+
+Текущий документ фиксирует контракт и критерии. Фактический completion rate,
+INP и production p95 появятся только после пилота и не должны подменяться
+headless-тестами.