Last Update
This commit is contained in:
Vadim Flowed
@@ -0,0 +1,122 @@
|
||||
---
|
||||
name: figma-wireframe-builder
|
||||
description: Build and update mid-fidelity editable Figma wireframes from screen_blueprints using native Figma MCP. Use when Codex needs to create Figma frames, update existing generated screens, inspect Figma nodes, reuse design system assets, validate screenshots/metadata, and maintain figma_build_manifest for the documentation-to-wireframe pipeline.
|
||||
---
|
||||
|
||||
# Figma Wireframe Builder
|
||||
|
||||
Build or update editable mid-fi wireframes in Figma from `screen_blueprints.json`.
|
||||
|
||||
## Load First
|
||||
|
||||
- `.agents/skills/_shared/references/artifact-contracts.md`
|
||||
- `.agents/skills/_shared/references/figma-mcp-workflow.md`
|
||||
- `.agents/skills/_shared/references/quality-gates.md`
|
||||
- The built-in `figma:figma-use` skill before every `use_figma` call.
|
||||
- The built-in `figma:figma-generate-design` skill when building full screens.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Read `workspace/artifacts/wireframe-gen/screen_blueprints.json`.
|
||||
2. Read `workspace/artifacts/wireframe-gen/figma_build_manifest.json` if it exists.
|
||||
3. Run the pre-Figma open question gate:
|
||||
`powershell -File scripts/wireframe/validate-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen -Stage pre-figma`
|
||||
4. Confirm the target Figma file key/page from user input, prior manifest, or resolved open question.
|
||||
5. Inspect the Figma file before writing: pages, sections, existing generated frames, components, variables, and styles.
|
||||
6. Search design system assets before drawing primitives.
|
||||
7. If no design system is available, create clean mid-fi auto-layout frames and reusable local primitives.
|
||||
8. Route each blueprint by `content_type`.
|
||||
9. Build one screen wrapper or element wrapper at a time.
|
||||
10. Return every created or mutated node ID from every write.
|
||||
11. Validate each screen with `get_metadata` and `get_screenshot`.
|
||||
12. Update `figma_build_manifest.json` and `figma_validation.md`.
|
||||
|
||||
## Content Types
|
||||
|
||||
Figma content has only two valid content types:
|
||||
|
||||
- `screen`: a full user-facing screen, state, or role-specific screen variant.
|
||||
- `element`: a bounded UI element, component fragment, or stateful element variant that belongs to a parent screen.
|
||||
|
||||
Do not create a third content type. Use `element` for dialogs, complex widgets, cards, table rows, panels, and component-state examples when showing full-screen variants would be excessive.
|
||||
|
||||
## Dimensions
|
||||
|
||||
- `screen` frames use width `1440` and minimum height `800`.
|
||||
- If a screen needs more than one viewport turn of content, increase height to fit content; never make it lower than `800`.
|
||||
- `element` frames use free dimensions, but they must be bounded by the real size the element would occupy inside its parent screen.
|
||||
- Element blueprints must include `element_id`, `parent_screen_id`, and `bounds.width` / `bounds.height`.
|
||||
- Do not use fractional coordinates, dimensions, or spacing values.
|
||||
|
||||
## Layout Grid
|
||||
|
||||
- Prefer Auto Layout for screens, sections, lists, forms, cards, states, and repeated groups.
|
||||
- Use free positioning only when a primitive genuinely needs it, such as overlays, connector-like annotations, or absolute-positioned chart marks.
|
||||
- Use an 8px grid as the default rhythm.
|
||||
- All spacing and dimensions must be whole numbers and multiples of 4. Prefer multiples of 8 for primary layout values.
|
||||
- Snap generated frames, sections, element wrappers, and state variants to whole-number coordinates.
|
||||
|
||||
## Visual Style
|
||||
|
||||
- Keep the wireframe visually restrained and client-ready.
|
||||
- Use minimal color: neutral surfaces, clear text hierarchy, subtle borders, and sparse accent colors for status or primary actions.
|
||||
- Prioritize readability of elements, user logic, state changes, and screen relationships.
|
||||
- Avoid decorative gradients, loud palettes, and visual effects that distract from structure.
|
||||
|
||||
## Naming and Grouping
|
||||
|
||||
- Put each concrete screen and all related states/elements into a Figma Section named after that 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.
|
||||
- Name screen frames with clear state suffixes when needed, for example `Dashboard - Default`, `Dashboard - Empty`, `Dashboard - Error`.
|
||||
- Name element frames with the parent and element name, for example `Dashboard / Revenue Card - Loading`.
|
||||
- Name service notes frames as `Notes / Annotations` or `Notes / <screen name>`.
|
||||
- Use `Shared Elements` only for reusable elements explicitly marked as shared in the UX spec.
|
||||
|
||||
## Product Screen Frame Purity
|
||||
|
||||
- Product screen frames contain only UI that belongs in the final product.
|
||||
- Do not place blueprint metadata, requirement chips, citations, UX rules, implementation notes, traceability, comments, or explanatory cards inside product screen frames.
|
||||
- If traceability or rationale must be visible in Figma, create a separate notes/annotations frame in the same Section, outside the product screen frame.
|
||||
- Notes/annotations are not `screen` or `element` content. Track their node IDs separately in `figma_build_manifest.annotation_node_ids`.
|
||||
- During validation, inspect screen frame descendants and remove or move nodes whose purpose is metadata, annotation, comment, citation, requirement trace, or UX rule.
|
||||
|
||||
## Multiflow
|
||||
|
||||
- If the system has two or more roles or two or more applications with different accessible screen sets, create a separate Figma page for each role/application.
|
||||
- Each role/application page must contain the full set of screens available to that role/application, including shared screens.
|
||||
- Do not store all common screens on `User` and only role-specific extras on `Admin`. Duplicate shared screens into each role/application page so every page is independently reviewable.
|
||||
- Keep page names concise and role/application specific, for example `Admin`, `User`, `Back Office`, or `Client App`.
|
||||
|
||||
## Creation Rules
|
||||
|
||||
- Use native Figma MCP only for generation and edits.
|
||||
- Do not use black-box exports as the primary output.
|
||||
- Use `1440 x 800` as the default screen viewport, increasing height only when content requires it.
|
||||
- Prefer auto-layout for wrappers, sections, lists, forms, and repeated cards.
|
||||
- Use realistic text from the blueprint. Avoid "Lorem ipsum" and placeholder labels.
|
||||
- Represent main, empty, loading, and error states when required.
|
||||
- Keep visual style mid-fi: neutral surfaces, clear hierarchy, readable spacing, and strong layout semantics.
|
||||
|
||||
## Edit Rules
|
||||
|
||||
- Use `screen_id` and prior node IDs from `figma_build_manifest.json` to target edits.
|
||||
- Inspect current hierarchy before mutation.
|
||||
- Mutate only affected sections unless the blueprint changed the screen structure.
|
||||
- Preserve existing node IDs when practical.
|
||||
- Re-run screenshot validation only for changed screens plus any dependent overview screens.
|
||||
|
||||
## Manifest Rules
|
||||
|
||||
Write or update:
|
||||
|
||||
- `file_key`
|
||||
- `page`
|
||||
- `screen_ids`
|
||||
- `created_node_ids`
|
||||
- `mutated_node_ids`
|
||||
- `annotation_node_ids`
|
||||
- `screenshots`
|
||||
- `validation_notes`
|
||||
- `known_issues`
|
||||
|
||||
If a Figma write fails, do not invent node IDs. Record the blocker in `known_issues` and keep the manifest consistent.
|
||||
Reference in New Issue
Block a user