figma-to-swiftui

What this skill does

# Figma to SwiftUI Implementation Skill

Translate Figma nodes into production-ready SwiftUI views with pixel-perfect accuracy. Combines MCP integration rules with a structured implementation workflow for iOS projects.

## Prerequisites

- Figma MCP server must be connected and accessible
- User must provide a Figma URL, e.g.: https://www.figma.com/design/:fileKey/:fileName?node-id=3166-70147&m=dev
  - May include &m=dev or other query params — only node-id matters
  - :fileKey — path segment after /design/
  - node-id value — the specific component or frame to implement
- OR when using figma-desktop MCP: select a node directly in the Figma desktop app (no URL required)
- Xcode project with an established SwiftUI codebase (preferred)
- Optional `.txt` / `.md` / ticket / brief describing scope, behavior, actions, and states

## MCP Connection

If any MCP call fails because Figma MCP is not connected, pause and ask the user to configure it. See references/figma-mcp-setup.md for troubleshooting.

---

## Workflow

Follow these steps in order. Do not skip steps.

**Two modes:** If the user wants to build a new screen from scratch, follow all steps sequentially. If the user wants to adapt/update an existing screen to match a Figma design, follow Steps 1–5, then do Step 5b (Adaptation Audit) before Step 6. Step 5b ensures every difference between the existing code and the design is identified and addressed — this is where most mistakes happen during adaptation.

### Step 0 — Read Source Document (if provided)

If the user provides a `.txt`, `.md`, ticket, PM brief, or inline spec together with Figma work, read it before any Figma MCP call. Extract the feature goal, expected screens, entry point, actions, async work, required states, constraints, out-of-scope items, and unclear points. See references/source-document.md.

Use the extracted contract to narrow the Figma work. If the document and Figma disagree on screen count, scope, or primary action mapping, ask before fetching or implementing the wrong node.

### Step 1 — Parse the Figma URL

Extract fileKey and nodeId from the URL.

Accepted URL patterns (with or without www.):
- figma.com/design/:fileKey/:fileName?node-id=...
- figma.com/file/:fileKey/:fileName?node-id=... (legacy, same behavior)

Parsing rules:
- fileKey: first path segment after /design/ or /file/
- nodeId: value of node-id query parameter. Always replace "-" with ":" (URLs use "3166-70147", MCP expects "3166:70147")
- Ignore all other query parameters (m=dev, t=..., page-id=..., etc.)
- Reject /proto/ and /board/ URLs — they are prototypes and FigJam boards, not implementable designs. Ask the user for a /design/ link instead.

When using figma-desktop MCP without a URL, tools automatically use the currently selected node. Only nodeId is needed; fileKey is inferred.

### Step 1b — Screen Discovery (metadata-first when needed)

Before calling `get_design_context`, decide whether the node is clearly one implementable screen/component. If the URL points to a root node, page node, large container, flow, multi-screen frame, or a source document names more screens than the URL obviously contains, run `get_metadata` first.

Build a candidate screen map with confidence and continue only when the target node is clear. If multiple candidates would materially change the implementation, ask the user before fetching design context. See references/screen-discovery.md and references/fetch-strategy.md.

### Step 2 — Fetch Design Context

get_design_context(fileKey=":fileKey", nodeId="1-2", prompt="generate for iOS using SwiftUI")

The `prompt` parameter steers the default code output toward SwiftUI. You can also pass project-specific hints: `"use components from Components/"`, `"generate using my design system tokens"`.

Returns structured design data: layout, typography, colors, spacing, and a code representation. Even with an iOS prompt, treat the output as a design specification, not code to port.

For large/complex designs: If the response is truncated or times out, do not retry the same node. Run `get_metadata`, identify smaller sections and child IDs, then fetch each section individually. See references/fetch-strategy.md.

For multi-device designs: If Figma contains frames for different screen sizes (iPhone + iPad), fetch all device-specific frames, not just one. See references/responsive-layout.md for merging them into adaptive SwiftUI views.

### Step 3 — Capture Screenshot

get_screenshot(fileKey=":fileKey", nodeId="1-2")

This screenshot is the source of truth for visual validation throughout implementation.

### Step 4 — Fetch Design Tokens (if available)

get_variable_defs(fileKey=":fileKey", nodeId="1-2")

Returns colors, spacing, typography tokens. Map to the project's SwiftUI design system. See references/design-token-mapping.md.

### Step 5 — Build Asset Inventory and Download Assets

Before writing SwiftUI, build a visual asset inventory from the screenshot and design context. See references/asset-handling.md for the full decision flow.

1. Open the screenshot from Step 3 and list every visible non-text element: icons, logos, photos, illustrations, decorative artwork, and image fills
2. Cross-check each row against `get_design_context` and `get_metadata` to find localhost URLs, image fills, vector nodes, and node IDs
3. Classify each row as `download`, `code`, or `remote`
4. Download Figma-owned assets during the active MCP session:
   - Use `get_screenshot(fileKey, nodeId)` by default for icons, logos, illustrations, and artwork nodes
   - Use localhost URLs from `get_design_context` only when they validate as PNG
5. Validate downloaded files with `file <asset>`: visible Figma assets must be real PNG files, then add them to Asset Catalog with @1x/@2x/@3x variants and the correct rendering mode

Asset rules:
- Figma assets first: do NOT replace Figma icons, logos, or illustrations with SF Symbols or hand-drawn SwiftUI shapes
- Visible Figma-owned assets should be exported as Figma-rendered PNG by default; SVG/text/XML responses are failed exports, not final assets
- SF Symbols are allowed only for iOS system chrome or when the user explicitly approves substitution
- Do NOT create placeholder images or fake logos with `Text`, `Rectangle`, `Circle`, or custom `Shape`
- If a visible asset has no download URL and no identifiable node ID, stop and ask the user instead of improvising
- Do NOT import new icon packages unless the project already uses them
- Remote content images (avatars, feeds, CDN photos) should use the project's existing image loading path, not bundled assets

### Step 5b — Adaptation Audit (when modifying an existing screen)

When the user asks to adapt/update an existing screen to match a Figma design, perform a full element-by-element audit before writing any code. See **references/adaptation-workflow.md** for the complete process.

Key steps:
1. Read the existing code and all its subcomponents
2. Build a categorized diff checklist (ADD / UPDATE / REMOVE) with exact old → new values
3. Pay special attention to spacing — it's the most commonly missed difference
4. Present the checklist to the user and clarify unknowns before implementing
5. Apply all changes — do not skip items that seem minor

### Step 6 — Implement in SwiftUI

Before writing any code:

1. Run `get_code_connect_map(fileKey, nodeId)` to check if Figma components in the design already have mapped code components. If a mapping exists — use that code directly instead of building from scratch.
2. Inspect the project's dependencies (Package.swift, Podfile, .xcodeproj) and existing codebase for UI-related libraries and patterns. The project may use third-party solutions for things you would otherwise implement with native SwiftUI. Examples:
- Image loading: Kingfisher, SDWebImage, Nuke instead of AsyncImage
- Animations: Lottie instead of SwiftUI animations
- UI components: custom design system, SnapKit for layout, etc.
- Networking + image caching: Alamofir