# UX Specification Builder > Builds and maintains product UX design specifications from a codebase (no implementation code in the doc). Use when the user asks for UX spec, design specification, CJM, user stories, screen map, gap analysis vs code, or to sync docs/UX_SPECIFICATION.md after feature changes — including narrated updates like "сделали X, обнови спеку". - Skill: `igrlebed/ux-specification-builder` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add igrlebed/ux-specification-builder` - Raw SKILL.md: https://api.skillmd.com/api/skills/igrlebed/ux-specification-builder/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: igrlebed (https://skillmd.com/u/igrlebed) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/igrlebed/ux-specification-builder --- # UX Specification Builder Продуктовая **дизайн-спецификация** — для дизайнеров, аналитиков и продукта. **В документе нет кода** (без API-контрактов, без CSS). Источник правды при сборке и синхронизации — **реализация в репозитории**. Целевой файл: `docs/UX_SPECIFICATION.md` (или другое имя в `docs/`, если согласовано). Язык документа: **русский**, если UI и проект на русском; подписи UI — дословно как в интерфейсе. Эталон структуры: [template.md](template.md). Чеклист аудита: [gap-checklist.md](gap-checklist.md). --- ## Когда применять | Запрос пользователя | Действие | | ------------------- | -------- | | «Собери / напиши UX-спецификацию» | Полный документ по шаблону | | «Сделали X / Y — обнови спеку» | Точечная синхронизация по описанию + проверка в коде | | «Обнови спецификацию» / «правки в коде» | Diff / затронутые файлы → правки в spec | | «Полный анализ проекта» | Аудит кода + заполнение пробелов | | «Только CJM / user stories / карта экранов» | Обновить соответствующие разделы | Не подменяет: - `DESIGN_SYSTEM.md` / `DESIGN.md` — визуальные токены (в т.ч. Impeccable) - `PRODUCT.md` — стратегический контекст продукта (Impeccable) - `ARCHITECTURE.md` — техника - `HANDOVER.md` — чеклист передачи --- ## Режимы работы ### A. С нуля Полный проход по [Workflow: создать с нуля](#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: синхронизация после изменений кода](#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] сделано / [ ] открыто — если есть факты для передачи ``` --- ## Источники фактов (порядок) | Приоритет | Где искать | | --------- | ---------- | | 1 | UI-строки в шаблонах (label, aria-label, empty state) | | 2 | `mocks/` — подписи KPI, секции навигации, лимиты данных | | 3 | `composables/` / store — навигация, сохранение контекста | | 4 | `pages/` / routes — что на главной vs overlay / modal | | 5 | Поведение без handler — кнопка есть, обработчика нет | Для большого репо — 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](template.md) и [gap-checklist.md](gap-checklist.md). --- ## Связанные навыки | Задача | Skill | | ------ | ----- | | Структура docs, naming | `cursor-designer-core` | | Mocks, state | `cursor-designer-data` | | Компоненты | `cursor-designer-dev` | | Токены, UI | `cursor-designer-visual` | | Передача команде | `cursor-designer-handover` | | Визуальный стиль / PRODUCT.md | `impeccable` | --- ## Output пользователю По умолчанию кратко: что обновлено + список файлов. Полный diff spec — только по запросу. После крупного аудита: 3–5 bullet «главные находки» в ответе.