# 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
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\wireframe\init-artifacts.ps1
```

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

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

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

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

## Hot Update

В Origin:

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

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

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

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

```powershell
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
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. Старт проекта

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

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

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

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

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

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

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

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

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

### 6. Создание wireframes

```text
Используй $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. Редактирование экрана

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