Last Update
This commit is contained in:
Vadim Flowed
@@ -0,0 +1,165 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user