UX Specification Builder

UX Specification Builder

Продуктовая дизайн-спецификация — для дизайнеров, аналитиков и продукта. В документе нет кода (без API-контрактов, без CSS). Источник правды при сборке и синхронизации — реализация в репозитории.

Целевой файл: docs/UX_SPECIFICATION.md (или другое имя в docs/, если согласовано).

Язык документа: русский, если UI и проект на русском; подписи UI — дословно как в интерфейсе.

Эталон структуры: template.md. Чеклист аудита: gap-checklist.md.

Когда применять

Не подменяет:

• DESIGN_SYSTEM.md / DESIGN.md — визуальные токены (в т.ч. Impeccable)
• PRODUCT.md — стратегический контекст продукта (Impeccable)
• ARCHITECTURE.md — техника
• HANDOVER.md — чеклист передачи

Режимы работы

A. С нуля

Полный проход по Workflow: создать с нуля.

B. Синхронизация по рассказу пользователя (основной режим агента-спеки)

Пользователь сообщает факт изменений без обязательного diff, например: «сделали онбординг вариантов, обнови спеку», «добавили empty state на ранжировании».

1. Распарсить, что изменилось (экраны, поведение, подписи, состояния)
2. Найти в коде подтверждение (pages/, components/, mocks/, composables/)
3. Если в коде нет — спросить или занести в §18 / §21, не выдумывать
4. Точечно обновить § экранов, US/UF/CJM, §16, §20
5. Gap-checklist только по затронутым областям
6. Строка версии внизу + при необходимости HANDOVER

C. Синхронизация по git

Workflow: синхронизация после изменений кода.

Не переписывай весь документ — точечные правки и новые подразделы.

Принципы документа

1. Язык UI — те же подписи, что в интерфейсе (дословно из mocks/компонентов).
2. Истина в коде — при расхождении spec уступает реализации; расхождение → §21 «Ограничения прототипа» или §18 «Бэклог».
3. Экраны E0, E1… — стабильные ID в карте экранов; ссылайся на них в US/UF.
4. Заглушки явно — кнопки без handler, UI-only toggle, static mocks.
5. Таблицы markdown — число колонок в separator | --- | равно заголовку и строкам; первая колонка с именем, не пустая | |.
6. Версия — одна строка в конце: дата + краткий список изменений.

Workflow: создать с нуля

1. Разведка (параллельно)
   - pages/, components/, composables/, mocks/ (адаптируй под стек проекта)
   - routes, store / use*State, labels навигации
2. Каркас по template.md
3. Заполнить §1 (продукт), §6 (экраны), §7–14 (экраны по приоритету)
4. CJM (≥2–3 пути), US (по доменам продукта), UF (mermaid flowchart)
5. §15 матрица связей, §16 состояния, §17 адаптив
6. §18 бэклог, §19 связанные docs, §20 глоссарий, §21 ограничения прототипа
7. Ссылки в ARCHITECTURE.md и HANDOVER.md (1–2 строки), если файлы есть

Workflow: синхронизация после изменений кода

1. git log -3 / git diff / git show — что изменилось
   (или описание от пользователя в режиме B)
2. Прочитать затронутые компоненты и mocks
3. Grep по UX_SPECIFICATION — устаревшие утверждения
4. Пройти gap-checklist.md для изменённых областей
5. Обновить US/UF/CJM только если меняется поведение
6. Обновить §18/§21 и строку версии
7. HANDOVER: [x] сделано / [ ] открыто — если есть факты для передачи

Источники фактов (порядок)

Для большого репо — subagent explore с запросом: gap report: code vs docs/UX_SPECIFICATION.md.

Форматы артефактов

User Story

| US-NN | Как [роль], я хочу [действие], чтобы [ценность] | Критерии приёмки (проверяемые в UI) |

Нумерация блоками по доменам продукта (пример): 01–09 навигация, 10–19 сущности, 20–29 моделирование, 30–39 показатели. Подстрой блоки под фактические домены проекта — не копируй чужие номера вслепую.

CJM

Таблица: Шаг | Действие | Touchpoint | Мысль | Барьер | Возможность дизайна.
Минимум 2–3 пути (типичные: обзор → сущность; ключевой сценарий; edge / empty).

User Flow

Mermaid flowchart TD; ветвления empty state; возврат «Назад» / закрытие.

Экран

• Назначение (1 абзац)
• ASCII-схема зон (опционально)
• Таблица: Элемент | Назначение | Связи
• Пустые состояния
• Отличия от соседних экранов

Ограничения прототипа (§21)

| Область | Ожидание продукта | Прототип сейчас | — только проверяемые расхождения.

Типичные ловушки

Общие:

• Не описывать как работающее то, у чего нет handler / binding.
• CTA в разных местах (карта, сайдбар, pill) — проверить, что handler один и тот же.
• Мультивыбор vs одиночный выбор — разное поведение селектора.
• Empty / 0 / — / blank — уточнить в mock, не смешивать в тексте.
• UI-only toggle — не описывать как фильтр данных.
• Онбординг / tooltip — где живёт (in-memory, session, localStorage).
• Модал — заголовок и тексты дословно из компонента.

Доменные (если в продукте есть) — см. необязательные блоки в template.md и gap-checklist.md.

Связанные навыки

Output пользователю

По умолчанию кратко: что обновлено + список файлов. Полный diff spec — только по запросу.

После крупного аудита: 3–5 bullet «главные находки» в ответе.