warframe-bilder/wireframe-system/.agents/skills/_shared/references/artifact-contracts.md

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:

{
  "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.

{
  "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:

{
  "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.

{
  "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":

{
  "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:

{
  "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.