# Artifact Contracts

Use these contracts for all repo-local wireframe generation workflows. Schema keys stay in English. Human-readable summaries and rationale default to Russian.

## File Layout

Create run artifacts under `workspace/artifacts/wireframe-gen/`. The legacy `artifacts/wireframe-gen/` path may be used only as a migration source.

- `source_inventory.json`: deterministic list of parsed source files and extraction status.
- `normalized_project.json`: consolidated product model with requirement traceability.
- `normalized_project.summary.md`: human summary of the normalized project.
- `ux_spec.json`: IA, flows, UX decisions, citations, acceptance criteria.
- `ux_spec.summary.md`: human summary of UX architecture and unresolved choices.
- `screen_blueprints.json`: array of screen-level build instructions.
- `figma_build_manifest.json`: Figma file/page IDs, screen IDs, node IDs, validation notes.
- `figma_validation.md`: screenshot review notes and remaining issues.
- `decision_log.md`: chronological decisions, assumptions, and user answers.

## NormalizedProject

Required top-level keys:

```json
{
  "project": {},
  "audiences": [],
  "goals": [],
  "actors": [],
  "functional_modules": [],
  "entities": [],
  "rules": [],
  "constraints": [],
  "risks": [],
  "open_questions": [],
  "source_trace": []
}
```

Each requirement-like object should include a stable `id`, a concise `statement`, `source_refs`, and `confidence` (`high`, `medium`, or `low`). Use `open_questions` instead of inventing missing product facts.

## Open Questions

Open questions are a dialogue gate, not a passive note. Missing `status` means `unresolved` for backward compatibility.

```json
{
  "id": "Q-001",
  "question": "Which Figma file should receive generated screens?",
  "status": "unresolved",
  "blocks": ["figma-build"],
  "default_assumption": "",
  "answer": "",
  "answered_at": "",
  "source_refs": []
}
```

- `status`: `unresolved`, `resolved`, or `answered`.
- `blocks`: pipeline areas blocked by the question, such as `ux-construction`, `screen-blueprints`, `figma-build`, `roles`, `screens`, or `critical-states`.
- `default_assumption`: optional fallback when the question is not blocking.
- `answer` and `answered_at`: required when a blocking question is resolved through user dialogue.
- Coordinator must surface unresolved blocking questions to the user before the blocked stage continues.

## UXSpec

Required top-level keys:

```json
{
  "information_architecture": [],
  "user_flows": [],
  "screen_inventory": [],
  "screen_purposes": [],
  "ux_decisions": [],
  "research_citations": [],
  "acceptance_criteria": []
}
```

Every major UX decision must reference either a requirement/source trace, a research citation, or an explicit assumption.

## ScreenBlueprint

`screen_blueprints.json` is an array. Each item must include `content_type`.

```json
{
  "content_type": "screen",
  "screen_id": "screen-dashboard",
  "viewport": { "width": 1440, "height": 800 },
  "purpose": "",
  "sections": [],
  "components": [],
  "states": [],
  "content_requirements": [],
  "interactions": [],
  "empty_error_loading_states": []
}
```

For `content_type: "screen"`:

- `screen_id` is required.
- `viewport.width` must be `1440`.
- `viewport.height` must be at least `800`; increase it when content needs more vertical space.
- The generated Figma frame must be at least `1440 x 800`.

For `content_type: "element"`:

```json
{
  "content_type": "element",
  "element_id": "element-dashboard-revenue-card",
  "parent_screen_id": "screen-dashboard",
  "bounds": { "x": 32, "y": 144, "width": 320, "height": 160 },
  "purpose": "",
  "states": [],
  "components": [],
  "content_requirements": [],
  "interactions": []
}
```

- `element_id`, `parent_screen_id`, and `bounds.width` / `bounds.height` are required.
- Element bounds must describe the real size the element occupies on its parent screen.
- Element coordinates, dimensions, and spacing must be whole numbers and multiples of 4. Prefer multiples of 8.

Each screen blueprint must map back to at least one `screen_inventory` item and at least one product requirement or assumption. Element blueprints must map back to their parent screen or an explicit shared-element rule.

## Figma Naming and Grouping

- Put each concrete screen and related states/elements into one Figma Section named after the screen, for example `Dashboard`.
- Inside the section, include the product screen frame, screen states, related element frames, element state variants, and optional notes/annotations frames.
- Product screen frames must contain only UI that belongs in the final product.
- Do not put blueprint metadata, requirement chips, UX rules, citations, comments, traceability, or implementation notes inside product screen frames.
- Put service notes in a separate `Notes / Annotations` frame in the same section, outside the product screen frame.
- Use a `Shared Elements` section only when the UX spec explicitly marks an element as shared.
- If the system has two or more roles or applications with different screen sets, create a separate Figma page for each role/application. Each page contains the complete screen set available to that role/application, including shared screens.

## FigmaBuildManifest

Required top-level keys:

```json
{
  "file_key": "",
  "page": "",
  "screen_ids": [],
  "created_node_ids": [],
  "mutated_node_ids": [],
  "annotation_node_ids": [],
  "screenshots": [],
  "validation_notes": [],
  "known_issues": []
}
```

Record every MCP write result. Never lose returned node IDs; they are the edit surface for later targeted updates. Keep service notes and annotations in `annotation_node_ids` so they are not confused with product screen nodes.

## System Boundary

- Transferable Origin system files are declared in `wireframe-system.manifest.json`.
- Hot Update must preserve `workspace/`, `artifacts/`, `maintenance/`, and `dist/`.
- Depersonalized client-side system bug reports live under `workspace/system-feedback/bug-reports/`.
- Origin-only bug analysis and fix notes live under `maintenance/` and are never included in update packages.