--- 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 / `. - 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.