warframe-bilder/wireframe-system/.agents/skills/figma-wireframe-builder/SKILL.md

name, description

name	description
figma-wireframe-builder	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.