warframe-bilder/wireframe-system/docs/usage-guide.ru.md

Wireframe Gen: краткий гайд

Проект превращает документацию в UX-спецификацию и редактируемые mid-fi wireframes в Figma. Репозиторий является origin-шаблоном: не храните здесь данные клиентских проектов, кроме общего UX research registry.

Клиентская работа живет в workspace/. Системные файлы Origin обновляются через Hot Update по wireframe-system.manifest.json, а workspace/, artifacts/, maintenance/ и dist/ не входят в пакет обновления.

Как работает пайплайн

1. documentation-normalizer извлекает TXT/MD/PDF/DOCX и создает normalized_project.json.
2. wireframe-coordinator выводит блокирующие open_questions в диалог.
3. ux-constructor создает UX architecture, flows, decisions и screen_blueprints.json.
4. figma-wireframe-builder создает или обновляет Figma wireframes через native Figma MCP.
5. Результаты и решения сохраняются в workspace/artifacts/wireframe-gen/.

Open Questions

• Open Questions - обязательный gate между нормализацией и UX/Figma этапами.
• Если вопрос блокирует ux-construction, screen-blueprints или figma-build, пайплайн останавливается.
• Ответ пользователя записывается в decision_log.md, а вопрос получает status: "answered" или status: "resolved".
• Неблокирующие вопросы можно пройти по default_assumption, но assumption нужно записать в decision_log.md.

Правила Figma результата

• Контент бывает только screen и element.
• screen: ширина 1440, высота минимум 800; высота растет под контент.
• element: свободный размер в рамках реального размера элемента на экране.
• Auto Layout, 8px сетка, целые размеры/отступы, кратность 4 или 8.
• Каждый экран и его состояния/элементы лежат в отдельной Figma Section.
• Product screen frame содержит только UI конечного продукта.
• Пояснения, requirement trace, UX notes, citations и комментарии выносятся в отдельный Notes / Annotations frame в той же Section, но вне screen frame.
• При нескольких ролях/приложениях создается отдельная Figma page для каждой роли с полным набором доступных ей экранов.

Команды

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\wireframe\init-artifacts.ps1

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\system\init-workspace.ps1

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\wireframe\extract-documents.ps1 -InputPath .\docs-input -OutputDir .\workspace\artifacts\wireframe-gen\extracted

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\wireframe\validate-artifacts.ps1 -ArtifactDir .\workspace\artifacts\wireframe-gen -Stage pre-ux

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\wireframe\validate-artifacts.ps1 -ArtifactDir .\workspace\artifacts\wireframe-gen -Stage pre-figma

Hot Update

В Origin:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\system\export-update-package.ps1 -OutputDir .\dist\wireframe-system

В клиентской копии сначала dry-run:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\system\apply-hot-update.ps1 -PackagePath <package> -TargetRoot <client-copy> -DryRun

Затем применение:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\system\apply-hot-update.ps1 -PackagePath <package> -TargetRoot <client-copy>

Скрипт обновляет только allowlist из manifest, проверяет SHA256 и создает backup в workspace/.hot-update/backups/.

Багрепорты

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\system\new-bug-report.ps1 -Title "<title>" -Area "<area>" -Expected "<expected>" -Actual "<actual>"

Отчет создается в workspace/system-feedback/bug-reports/ как report.json и report.md. Клиентские документы, имена, Figma-контент и приватные идентификаторы не прикладываются автоматически; вручную можно добавить только очищенные фрагменты в sanitized-snippets/.

Промты

1. Старт проекта

Используй $wireframe-coordinator. Запусти пайплайн для нового проекта из <путь>. Сначала нормализуй документацию, затем выведи open_questions в диалог. UX и Figma не запускай, пока блокирующие вопросы не закрыты.

2. Нормализация

Используй $documentation-normalizer. Проанализируй документы из <путь>. Создай source_inventory, normalized_project и summary. Все противоречия и недостающие решения вынеси в open_questions с blocks/status.

3. Ответы на Open Questions

Используй $wireframe-coordinator. Вот ответы на open_questions: <ответы>. Обнови normalized_project и decision_log, затем проверь, можно ли продолжить UX construction.

4. UX-конструктор

Используй $ux-constructor. На основе workspace/artifacts/wireframe-gen/normalized_project.json создай UX architecture, user flows, screen inventory, UX decisions с citations и screen_blueprints.json.

5. Проверка перед Figma

Проверь workspace/artifacts/wireframe-gen на готовность к Figma generation. Запусти pre-figma gate, найди блокирующие open_questions и провалидируй screen_blueprints.

6. Создание wireframes

Используй $figma-wireframe-builder. Создай mid-fi wireframes в Figma file <file_key> на основе screen_blueprints.json. Внутри product screen frame размещай только финальный UI; notes/metadata/comments вынеси в Notes / Annotations вне screen frame.

7. Редактирование экрана

Используй $figma-wireframe-builder. Обнови экран <screen_id>: <описание правки>. Меняй только затронутые screen/element frames; notes меняй отдельно и обнови figma_build_manifest.