Figma screen blueprint

Figma Screen Blueprint

Turn full-screen Figma designs into a verified implementation plan, then optionally build it. This skill inspects the Figma node tree, decomposes a screen into meaningful UI targets, generates and validates child-node links, collects real design context, and produces a manifest — the single source of truth for the rest of the work. It is framework-agnostic and adapts to the target codebase after inspecting it.

The core value is not raw code generation; it is planning, validation, and reproducibility. Most Figma-to-code tools convert a single frame. This skill plans the whole screen, proves every node exists, and checks the result back against Figma so no UI is invented.

Two modes

Both modes share the same front half (Phases 1–6). They diverge at the manifest, which is the natural handoff artifact.

• Document mode — Stop after the manifest (Phase 6). Deliver the decomposition document, validated links, layout/token notes, and open questions. Write no code. Triggered by: "create a breakdown / manifest / decomposition doc", "document this screen", "review-only", "don't implement yet".
• Implementation mode — Continue through Phases 7–15: inspect the stack, map to it, build, then review target-by-target against Figma. Triggered by: "implement", "build", "convert to code", "make it like Figma".

If intent is ambiguous (a Figma link with no clear verb), ask which mode before proceeding.

Relationship to official Figma skills

This skill is the read-direction (Figma → code), framework-agnostic planning/verification layer that the official Figma skills do not provide. It runs on top of the official Figma MCP tools; it is not a replacement MCP server. Defer correctly:

• Code → Figma (writing to canvas) is out of scope. Use the official figma-use / figma-generate-design / figma-generate-library skills instead.
• SwiftUI targets: if the official figma-swiftui skill is available, it already handles iOS pattern recognition, SF Symbols round-tripping, and HIG token mapping. Use this skill for the decomposition/manifest/planning, and either hand the per-target code emit to figma-swiftui or follow its conventions. Do not duplicate its iOS-specific mapping.
• Linking published components to code: use figma-code-connect. This skill consumes Code Connect mappings (see Phase 8) but does not create them.

Figma MCP tools

Tool names and availability vary by client (some namespace them, e.g. a figma- prefix) and by server (the remote server needs a frame/layer link; the desktop server also supports the current selection). First confirm which tools are actually exposed in this session — do not hardcode names. The tools this skill relies on, by current official naming:

• get_design_context — primary context tool. Returns a structured React + Tailwind representation of a layer/selection — i.e. the "generated code," used as reference only (see Core rule 3).
• get_metadata — node-tree / structure for a node. Use this, not the screenshot or the generated code, to decide implementation structure.
• get_screenshot — the visual ground truth for a node.
• get_variable_defs — design variables/tokens for the selection. Pull these for token fidelity instead of inferring colors/spacing visually.
• Code Connect tools (e.g. a get_code_connect_map / mapping tool) — optional. The exact name varies by server and the tool may not be exposed; even when present it returns nothing unless the team has configured Code Connect mappings. If such a tool is available, use it to map Figma instances to existing code components. If unavailable or empty, do not invent the mapping — fall back to codebase search and document the assumption.

Reads are rate-limited; writes are exempt. Budget calls accordingly (see Phase 5).

Precondition: this workflow depends on the Figma MCP server. If none of these tools are available in the session, do not proceed — tell the user to connect/enable the Figma MCP server (and note that without it this is not the right skill). Verify availability before Phase 1.

Core rules

1. Do not start coding immediately. Inspect the node tree first.
2. Triangulate three sources — trust none alone. get_metadata decides structure/layout, get_screenshot resolves visual ambiguity, get_design_context is the code scaffold (see rule 3).
3. get_design_context output is a reference, not the final implementation. DO use it for hierarchy, auto-layout direction, spacing relationships, and text. DON'T copy its JSX/Tailwind verbatim, DON'T inherit its absolute pixel dimensions, DON'T let it choose components. Re-map everything to the target framework + existing components + tokens.
4. Decompose the screen into meaningful UI targets — not every low-level text/icon node.
5. Generate child-node URLs from node IDs, then validate them. Do not implement an invalid node.
6. Inspect the target codebase before choosing patterns. Reuse existing components, tokens (get_variable_defs / Code Connect), routing, and state patterns.
7. Do not invent UI that is not present in Figma.
8. Do not hardcode Figma canvas widths as fixed layout widths unless the node is truly fixed.
9. In implementation mode, build only after all targets are planned, then review target-by-target against Figma. If review fails, fix and rebuild.
10. The final response includes a target-by-target completion table.

Input types

• Single screen: one Figma frame link. Decompose it automatically.
• Multiple states of one view: several links labelled by the user (e.g. initial / result / empty / loading). Implement one view with state, not separate screens (Phase 10).
• Screen plus explicit children: a full-screen link plus a list of important components. Honor the listed components and still decompose the rest.

---

Phase 1 — Parse Figma links

Extract: file key, file name (if present), node ID, mode/dev flag, and any state label from the user's text.

Figma URL node IDs use hyphens; MCP node IDs usually use colons. Convert both ways:

URL node-id 1234-5678  <->  MCP node id 1234:5678

Phase 2 — Fetch screen context (triangulate)

For each full screen / state node, in parallel:

1. get_metadata — read the hierarchy.
2. get_screenshot — see the actual rendering.
3. get_design_context — get the structural code scaffold (reference only).

Decide structure from metadata, resolve visual ambiguity from the screenshot, and use the generated code as a scaffold — per Core rules 2–3.

Phase 3 — Auto-decompose the node tree

Group nodes into implementation targets. Common types and clues:

Target type	Figma clues
Screen shell	top-level / device frame
App / header / nav bar	Header, Navigation, Top Bar, Toolbar
Search / input	Search Bar, Input, Text Field
Section	title + content group; repeated vertical blocks
Card	repeated fixed-size content containers
Row / list item	repeated same-height rows
Tabs	Tab, Segmented, Underline Tab
Button	Button, Icon Button, CTA
Divider / badge / chip	thin rectangle; Badge, Chip, Tag, count bubble
Empty / loading / error	state-specific placeholder frames
Bottom action	bottom fixed area, sticky CTA

Heuristics: repeated same-name/size siblings are usually one reusable component; a parent with a title plus repeated children is usually a section; hidden nodes are variants/disabled slots — record but don't implement unless required; generic names (Frame 2117…) require inferring from children, position, and repetition.

Phase 4 — Generate child node URLs

For every target, build a URL:

https://www.figma.com/design/<fileKey>/<fileName>?node-id=<node-id-with-hyphen>&m=dev

Example: MCP node id 4386:9467 → URL node-id 4386-9467.

Phase 5 — Validate generated nodes (with a cost cap)

Reads are rate-limited, so do not blindly validate every generated node. Validate only the targets that will actually be implemented (or, in document mode, those that will appear in the manifest). For each:

1. Call get_metadata (batch independent reads in parallel).
2. Mark valid or invalid.
3. If invalid, do not implement it; report it and either ask for clarification or fall back to the nearest valid parent.

| Target      | Node ID     | URL | Status |
|-------------|-------------|-----|--------|
| Search Bar  | 2709:122973 | ... | valid  |
| Result Row  | 3291:61543  | ... | valid  |

Phase 6 — Produce the manifest ← FORK POINT

Create the manifest before any implementation. Document mode stops here and delivers it (plus the sections below). Implementation mode consumes it.

| Order | Target | Node ID | URL | Type | Parent/State | Implementation unit | Detail needed | Status |

Also include: screen states and transition assumptions; repeated component groups; ambiguous/unknown nodes; and nodes intentionally ignored, with reason.

Document-mode deliverable structure:

# <Screen Name> — Figma Screen Blueprint
## Source screens
## Generated + validated target links
## Screen states (and triggers)
## Implementation manifest
## Component reuse candidates (from a Code Connect tool if exposed; otherwise from codebase search)
## Token notes (get_variable_defs)
## Layout conversion notes (fill / hug / fixed)
## Open questions
## Implementation checklist
## Review checklist

---

Implementation mode (Phases 7–15)

Phase 7 — Inspect the target stack

Before coding, inspect the codebase. Do not infer the stack from Figma generated code (Figma emits React/Tailwind even for non-web targets). Find: UI framework + language; component library; design-token system; routing/navigation pattern; state-management pattern; preview/storybook conventions; existing similar screens; build/test commands.

Phase 8 — Map Figma to the implementation system

For each target, in priority order: (1) reuse an existing project component; (2) reuse existing design tokens — pull them via get_variable_defs; resolve component instances via a Code Connect mapping tool if one is exposed, otherwise via codebase search (do not invent a mapping); (3) if no component exists, create a local component near the screen; (4) only change shared design-system components when project convention supports it. Do not introduce a new dependency or styling library unless explicitly requested.

Figma	Web	iOS	Android
Auto layout vertical / horizontal	flex column / row	VStack / HStack	Column / Row
Fill width	width: 100% / flex: 1	maxWidth: .infinity	Modifier.fillMaxWidth()
Hug contents	fit-content	fixedSize / intrinsic	wrapContent
Text / color token	typography / color token	typography modifier / color token	TextStyle / ColorScheme token
Component variant	prop / variant	enum / init param	sealed class / enum param

Phase 9 — Layout conversion rules

Do not blindly copy Figma absolute values. A screen-width result is a fill, not a fixed width.

Bad:  .frame(width: 328)        Good:  .padding(.horizontal, 16); .frame(maxWidth: .infinity)
Bad:  width: 328px              Good:  width: 100%; padding-inline: 16px

Use fixed dimensions only for genuinely fixed things: icons, touch targets, fixed columns, dividers, avatars, thumbnails, and cards Figma marks fixed (not fill).

Record each target's intended sizing (fill / hug / fixed + height) and implement repeated rows/cards once as a reusable component rendered from data — never copy-paste each row unless it is truly unique.

Phase 10 — State handling

If multiple Figma links represent states of one view, implement a single view with state:

| State   | Figma node  | Trigger                         |
|---------|-------------|---------------------------------|
| initial | 2709:122579 | query empty                     |
| result  | 3291:60562  | query non-empty                 |
| empty   | ...         | query non-empty, result count 0 |
| loading | ...         | request in flight               |

If triggers aren't clear from the designs, ask before coding.

Phase 11 — Previews / samples

Every implemented view and meaningful reusable component needs a preview in the project's convention: SwiftUI #Preview, Compose @Preview, a React Storybook story (if the project uses Storybook), a Flutter sample/golden (if used). Minimum: main initial state, main populated state, any empty/loading/error state, and key row/card components. If the project has no preview convention, create only what is idiomatic and local.

Phase 12 — Implementation sequencing

Default order (deviate only for dependencies): data/state model → screen shell → header/nav → shared input/search → sections → reusable rows/cards → buttons/tabs/badges → empty/loading/error states → previews → routing integration → accessibility labels if the project requires them.

Phase 13 — Build / test

Don't build after every small component. Implement all targets, run the project's existing formatter/lint, run the smallest relevant build/test, fix failures, rebuild. Use the project's own tools (xcodebuild/Gradle/npm-yarn-pnpm/flutter). Do not install new tools unless a dependency/build failure requires it.

Phase 14 — Post-build Figma review

Re-open the Figma targets and review target-by-target. Check: target exists; no missing/invented UI; text matches; typography & color tokens match (or document the closest project token); spacing/padding/height match; fill-vs-fixed correct; repeated row/card structure correct; selected/unselected states match; icons & touch areas; truncation/line limits; correct button variant; previews exist.

If a target fails: mark it failed, fix only that target, rebuild, re-review it, continue until all pass or a blocker is reported.

Phase 15 — Final report

Keep it concise and lead with a table:

| Target              | Result | Notes                     |
|---------------------|--------|---------------------------|
| Search initial state| Pass   | Query-empty state         |
| Search result state | Pass   | Same view, query-based    |
| Search Bar          | Pass   | Fill width, 48 height     |
| Build               | Pass   | Debug build succeeded     |

Also mention: changed files; build/test command run; assumptions/limitations; and any failed or unimplemented targets.

---

Subagents and batching

Use parallel tool calls for independent reads (multiple get_metadata / get_screenshot / get_design_context calls, file reads, code searches). Subagents may do read-only extraction/review (build a manifest, compare tokens, search for existing components, inspect platform conventions). The main agent owns implementation and applies edits sequentially — never let multiple agents edit the same files at once.

Stop and ask before coding when

State behavior is ambiguous; Figma has conflicting variants; the target platform is unknown; the design needs data/API behavior not shown in Figma; implementation would require broad routing/navigation changes; a shared design-system component must be changed; generated child nodes are invalid; hidden layers may represent important states; or the Figma MCP tools this workflow requires are not available in the session (in which case stop and ask the user to connect/enable the Figma MCP server).