Added to Git
This commit is contained in:
Vadim Flowed
@@ -0,0 +1,14 @@
|
||||
# Alternative Landscape
|
||||
|
||||
Use this as background when positioning the system. Do not treat it as a generation dependency.
|
||||
|
||||
- Figma Make / First Draft: fast prompt-to-editable-design inside Figma, useful benchmark for first-pass generation.
|
||||
- Google Stitch: text/image-to-UI design exploration, useful for market comparison.
|
||||
- Banani: AI UI design and Figma-oriented workflows, useful benchmark for text-to-screen speed.
|
||||
- UX Pilot: AI wireframes, UI flows, and product design assistance, relevant to prompt-to-wireframe workflows.
|
||||
- Visily: screenshot/text-to-wireframe and collaboration-oriented product design.
|
||||
- Uizard: text/sketch/screenshot-to-wireframe and mockup generation.
|
||||
- Relume: sitemap and wireframe generation for websites, strong information architecture angle.
|
||||
- Wireframe Pilot: text-to-wireframe niche benchmark.
|
||||
|
||||
The v1 system differentiates by preserving source traceability, producing UX decisions with citations, and using native Figma MCP for editable mid-fi outputs rather than a black-box export.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Figma MCP Workflow
|
||||
|
||||
Use native Figma MCP for v1 generation and edits.
|
||||
|
||||
## Creation Flow
|
||||
|
||||
1. Confirm `screen_blueprints.json` is current and validated.
|
||||
2. Load `figma-use` before any `use_figma` call.
|
||||
3. If building full screens, load `figma-generate-design` as workflow guidance.
|
||||
4. Inspect the Figma file first: pages, sections, existing frames, components, variables, styles.
|
||||
5. Search/import existing design-system components and variables before creating primitives.
|
||||
6. Create role/application pages when multiflow rules require them.
|
||||
7. Create one Figma Section per concrete screen, named after the screen.
|
||||
8. Inside each Section, create product screen frames, state frames, element frames, and optional `Notes / Annotations` frames.
|
||||
9. Keep notes/annotations outside product screen frames.
|
||||
10. Return all created, mutated, and annotation node IDs from every write.
|
||||
11. Validate each screen with metadata and screenshots.
|
||||
12. Update `figma_build_manifest.json` and `figma_validation.md`.
|
||||
|
||||
## Edit Flow
|
||||
|
||||
1. Read `figma_build_manifest.json` and identify target `screen_id`.
|
||||
2. Inspect current node hierarchy before mutating.
|
||||
3. Modify only affected sections or components.
|
||||
4. Preserve node IDs whenever possible.
|
||||
5. Re-screenshot changed screens and append validation notes.
|
||||
6. If a requested note/comment change does not affect final product UI, mutate only the notes/annotations frame.
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- All text is readable and not clipped.
|
||||
- Sections do not overlap.
|
||||
- Auto-layout is used for screen structure and repeated groups.
|
||||
- Every concrete screen has its own Figma Section containing the main screen, states, and related elements.
|
||||
- Product screen frames contain only final-product UI, not blueprint metadata, comments, citations, requirement chips, or UX rules.
|
||||
- Notes/annotations sit in the same Section but outside the product screen frame.
|
||||
- Screen frames are `1440` wide and at least `800` high.
|
||||
- Element frames fit the real bounds they occupy within the parent screen.
|
||||
- Coordinates, dimensions, and spacing are whole numbers and multiples of 4, with 8px rhythm preferred.
|
||||
- Multiflow pages contain complete role/application screen sets, including shared screens.
|
||||
- Empty, loading, and error states are represented when the blueprint requires them.
|
||||
- The manifest lists every created or mutated node ID.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Prompt Guidelines
|
||||
|
||||
Use these guidelines when drafting prompts for the four wireframe skills.
|
||||
|
||||
- Put the role, goal, inputs, output contract, and quality gates near the top.
|
||||
- Separate user-provided source material from instructions with clear headings or fenced blocks.
|
||||
- Ask for structured JSON when downstream tools depend on exact keys.
|
||||
- Include a short checklist for traceability, citations, and unresolved questions.
|
||||
- Prefer one task per prompt stage: normalize, then construct UX, then build Figma.
|
||||
- Do not ask the model to hide uncertainty. Preserve contradictions and missing decisions.
|
||||
- Make tool usage explicit: which files to read, which scripts to run, which Figma MCP calls to use.
|
||||
- Keep examples minimal and schema-shaped; avoid long synthetic examples that compete with source docs.
|
||||
- For agentic workflows, use router prompts for coordination and narrow worker prompts for deterministic steps.
|
||||
- Treat UX research claims as citations, not decoration. If a source does not support the decision, do not cite it.
|
||||
|
||||
## Prompt Skeleton
|
||||
|
||||
```text
|
||||
Role: <specialized skill>
|
||||
Goal: <one workflow step>
|
||||
Inputs:
|
||||
- <artifact paths>
|
||||
- <source constraints>
|
||||
Output:
|
||||
- <exact artifact paths and schema keys>
|
||||
Quality gates:
|
||||
- <validation checks>
|
||||
- <traceability/citation checks>
|
||||
Process:
|
||||
1. Inspect inputs.
|
||||
2. Produce the artifact.
|
||||
3. Validate and list open questions.
|
||||
```
|
||||
@@ -0,0 +1,25 @@
|
||||
# Quality Gates
|
||||
|
||||
## Documentation Normalization
|
||||
|
||||
- Every extracted source has `source_id`, path, type, status, and notes.
|
||||
- Every requirement-like claim has at least one `source_ref`.
|
||||
- Duplicates are merged, contradictions are preserved.
|
||||
- Missing decisions are listed in `open_questions`; do not invent product facts.
|
||||
|
||||
## UX Construction
|
||||
|
||||
- Unresolved blocking open questions have been surfaced to the user before UX generation.
|
||||
- Every screen maps to a user goal, flow step, or explicit assumption.
|
||||
- Major UX decisions have citations or explicit rationale.
|
||||
- Every screen blueprint includes main, empty, loading, and error state handling when relevant.
|
||||
- Acceptance criteria are testable.
|
||||
|
||||
## Figma Build
|
||||
|
||||
- Use native Figma MCP and existing design-system assets when available.
|
||||
- Create/edit incrementally and return node IDs from each write.
|
||||
- Product screen frames contain only final-product UI.
|
||||
- Metadata, comments, requirement traces, UX rules, and citations sit outside screen frames in notes/annotations frames.
|
||||
- Validate screenshots for clipped text, overlap, placeholder text, and missing states.
|
||||
- Update `figma_build_manifest.json` after every write session.
|
||||
@@ -0,0 +1,22 @@
|
||||
# UX Research Policy
|
||||
|
||||
Use a curated-first, live-web fallback policy.
|
||||
|
||||
1. Search `.agents/skills/_shared/references/ux-research-registry.json` first.
|
||||
2. If no registry source supports the UX decision, search the web for authoritative sources.
|
||||
3. Prefer primary or recognized UX sources: W3C/WCAG, platform HIG/Material guidance, NN/g, Baymard, official product/design-system docs, peer-reviewed or well-scoped research.
|
||||
4. Add useful live-web findings back to the registry with `scripts/wireframe/update-research-registry.ps1`.
|
||||
5. Cite sources in `ux_spec.json` with `registry_id`, `url`, `claim`, and `used_for`.
|
||||
6. Do not write "research shows" unless the cited source directly supports the claim.
|
||||
|
||||
## Citation Object
|
||||
|
||||
```json
|
||||
{
|
||||
"registry_id": "nng-heuristics",
|
||||
"title": "10 Usability Heuristics for User Interface Design",
|
||||
"url": "https://www.nngroup.com/articles/ten-usability-heuristics/",
|
||||
"claim": "Systems should keep users informed about status through timely feedback.",
|
||||
"used_for": ["loading-state-patterns", "action-feedback"]
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,87 @@
|
||||
{
|
||||
"last_updated": "2026-05-03",
|
||||
"sources": [
|
||||
{
|
||||
"id": "nng-heuristics",
|
||||
"title": "10 Usability Heuristics for User Interface Design",
|
||||
"url": "https://www.nngroup.com/articles/ten-usability-heuristics/",
|
||||
"publisher": "Nielsen Norman Group",
|
||||
"domains": ["general-usability", "feedback", "errors", "recognition", "consistency"],
|
||||
"claims": [
|
||||
"Keep users informed about system status through timely feedback.",
|
||||
"Use language and concepts familiar to users.",
|
||||
"Prevent errors and provide clear recovery paths."
|
||||
],
|
||||
"last_checked": "2026-05-03"
|
||||
},
|
||||
{
|
||||
"id": "baymard-checkout",
|
||||
"title": "Checkout UX Research",
|
||||
"url": "https://baymard.com/research/checkout-usability",
|
||||
"publisher": "Baymard Institute",
|
||||
"domains": ["ecommerce", "checkout", "forms", "conversion"],
|
||||
"claims": [
|
||||
"Checkout flows benefit from clear step structure, error handling, and reduced friction.",
|
||||
"Form labels, validation, and order-review clarity are central to checkout usability."
|
||||
],
|
||||
"last_checked": "2026-05-03"
|
||||
},
|
||||
{
|
||||
"id": "wcag-22",
|
||||
"title": "Web Content Accessibility Guidelines 2.2",
|
||||
"url": "https://www.w3.org/TR/wcag-2.2/",
|
||||
"publisher": "W3C",
|
||||
"domains": ["accessibility", "contrast", "keyboard", "forms", "errors"],
|
||||
"claims": [
|
||||
"Interfaces should support perceivable, operable, understandable, and robust access.",
|
||||
"Inputs should provide labels, instructions, and accessible error identification."
|
||||
],
|
||||
"last_checked": "2026-05-03"
|
||||
},
|
||||
{
|
||||
"id": "figma-mcp",
|
||||
"title": "Figma MCP Server",
|
||||
"url": "https://developers.figma.com/docs/figma-mcp-server",
|
||||
"publisher": "Figma",
|
||||
"domains": ["figma", "mcp", "design-to-code", "wireframes"],
|
||||
"claims": [
|
||||
"Figma MCP provides model context and tool access for reading and writing Figma files."
|
||||
],
|
||||
"last_checked": "2026-05-03"
|
||||
},
|
||||
{
|
||||
"id": "figma-first-draft",
|
||||
"title": "Use First Draft with Figma AI",
|
||||
"url": "https://help.figma.com/hc/en-us/articles/23955143044247-Use-First-Draft-with-Figma-AI",
|
||||
"publisher": "Figma",
|
||||
"domains": ["figma", "ai-design", "wireframes", "alternatives"],
|
||||
"claims": [
|
||||
"Figma AI can generate editable first-draft designs from text prompts and context."
|
||||
],
|
||||
"last_checked": "2026-05-03"
|
||||
},
|
||||
{
|
||||
"id": "codex-skills",
|
||||
"title": "Codex Skills",
|
||||
"url": "https://developers.openai.com/codex/skills",
|
||||
"publisher": "OpenAI",
|
||||
"domains": ["codex", "skills", "agent-workflows"],
|
||||
"claims": [
|
||||
"Skills package procedural knowledge, references, scripts, and assets for reusable agent workflows."
|
||||
],
|
||||
"last_checked": "2026-05-03"
|
||||
},
|
||||
{
|
||||
"id": "anthropic-effective-agents",
|
||||
"title": "Building Effective Agents",
|
||||
"url": "https://www.anthropic.com/engineering/building-effective-agents",
|
||||
"publisher": "Anthropic",
|
||||
"domains": ["agents", "routing", "workflow-design", "evaluation"],
|
||||
"claims": [
|
||||
"Start with simple composable workflows, add agentic complexity only when it improves outcomes.",
|
||||
"Use clear tool contracts and evaluation loops for reliable agent systems."
|
||||
],
|
||||
"last_checked": "2026-05-03"
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user