Figma Sync

Figma Sync Workflow (Figma-WF)

Repeatable workflow for syncing Figma designs to local cache and Xcode assets. Follows PM-WF 1.8 format.

Project Config

Workflow Overview

flowchart TD
    S0["Stage 0: Check for Changes"] --> NeedSync{"Changes detected?"}
    NeedSync -->|"No"| SkipDone["Done - No changes"]
    NeedSync -->|"Yes"| S1["Stage 1: Discover Figma Pages"]
    S1 --> S2["Stage 2: Export Design Context + Screenshots"]
    S2 --> CP1{"CP1: All pages exported?"}
    CP1 -->|"Incomplete"| S2
    CP1 -->|"Complete"| S3["Stage 3: Export Illustrations/Assets"]
    S3 --> S4["Stage 4: Generate Figma-Task Mapping"]
    S4 --> S5["Stage 5: Atomic Swap to Local"]
    S5 --> CP2{"CP2: Final Verification"}
    CP2 -->|"Failed"| S2
    CP2 -->|"Passed"| Done["Done - Ready for Dev"]

Incremental Update Strategy

Figma has NO per-node timestamps. Only file-level lastModified exists.

Tier 1 -- File-level gate: Read figma/sync-state.json. If lastModified unchanged since last sync, skip entirely (zero MCP calls).

Tier 2 -- Node-level metadata hash: If file changed, call get_metadata on root (1 MCP call). Hash each node's metadata (name, type, position, size, child count). Compare against hashes in sync-state.json. Only re-export nodes whose hash changed.

Limitation: Metadata hash misses pure visual changes (e.g. color swap without structural change). Use --force flag or periodic full sync for those.

MCP Tool Quick Reference

get_metadata

{
  "server": "user-Figma",
  "toolName": "get_metadata",
  "arguments": { "fileKey": "tZhdm3G4gxrUrXsTK6iPYh", "nodeId": "0:1" }
}

Returns: Sparse XML with layer IDs, names, types, positions, sizes. Use to enumerate pages and detect structural changes.

get_design_context

{
  "server": "user-Figma",
  "toolName": "get_design_context",
  "arguments": { "fileKey": "tZhdm3G4gxrUrXsTK6iPYh", "nodeId": "{PAGE_NODE_ID}" }
}

Returns: Code reference (React+Tailwind default), screenshot, design tokens, contextual hints. Primary tool for extracting design details.

get_screenshot

{
  "server": "user-Figma",
  "toolName": "get_screenshot",
  "arguments": { "fileKey": "tZhdm3G4gxrUrXsTK6iPYh", "nodeId": "{NODE_ID}" }
}

Returns: High-res screenshot of the specified node. Use for page-level screenshots and individual asset exports.

Stage 0: Check for Changes

1. Read figma/sync-state.json (create empty state if not found)
2. Call get_metadata on root node 0:1
3. Compare file lastModified against stored value
4. If unchanged: STOP -- print "No changes detected" and exit
5. If changed or first sync:
   • Parse metadata XML to extract all top-level nodes
   • Compute SHA-256 hash of each node's metadata string
   • Compare against stored hashes
   • Build changedNodes[] list (or all nodes if first sync)
6. If --force flag: treat all nodes as changed

Checklist:

• sync-state.json read (or initialized)
• get_metadata called on root
• lastModified compared
• Changed nodes identified

Stage 1: Discover Figma Pages

1. From Stage 0 metadata, extract all top-level frames/pages
2. Build page index:

   | nodeId | Name | Status | Notion Task |
   |--------|------|--------|-------------|
   | 0:1    | Home | changed | F1         |
   | ...    | ...  | ...     | ...        |
   

3. Map each page to corresponding Notion task (F1-F10) by name matching
4. Save index to figma/.tmp/index.json

Checklist:

• All top-level pages enumerated
• Each page mapped to Notion task
• Status (new/changed/unchanged) assigned
• index.json written to .tmp/

Stage 2: Export Design Context + Screenshots

For each changed page (or all if full sync):

1. Call get_design_context with page's nodeId
2. Save response to figma/.tmp/pages/{nodeId}/design-context.md
3. Call get_screenshot with page's nodeId
4. Save screenshot to figma/.tmp/pages/{nodeId}/screenshot.png
5. Save raw metadata to figma/.tmp/pages/{nodeId}/metadata.json

For unchanged pages: copy from existing figma/pages/{nodeId}/ to .tmp/pages/{nodeId}/

Rate limit handling:

• If MCP returns rate limit error, wait 60 seconds and retry
• Track progress in figma/.tmp/export-progress.json
• On retry, skip already-exported nodes
• After 3 consecutive failures, stop and report partial progress

CP1 Checklist:

• Every page in index has a directory in .tmp/pages/
• Each directory contains design-context.md, screenshot.png, metadata.json
• No errors in export-progress.json

Stage 3: Export Illustrations / Custom Assets

1. For each changed page, parse design-context.md for illustration/image components
2. Identify nodes that are custom illustrations (not system icons)
3. For each illustration node:
   • Call get_screenshot at 2x scale
   • Call get_screenshot at 3x scale
   • Save to figma/.tmp/assets/{name}/
   • Generate Contents.json for Xcode imageset:

     {
       "images": [
         { "filename": "{name}@2x.png", "idiom": "universal", "scale": "2x" },
         { "filename": "{name}@3x.png", "idiom": "universal", "scale": "3x" }
       ],
       "info": { "author": "figma-sync", "version": 1 }
     }
     

Checklist:

• All illustration nodes identified
• 2x and 3x PNGs exported
• Contents.json generated per imageset
• Assets ready for Assets.xcassets copy

Stage 4: Generate Figma-Task Mapping

Generate figma/.tmp/FIGMA_MAPPING.md using the template in mapping-template.md.

Three sections:

1. Page-to-Task mapping -- Figma page nodeId to Notion task (F1-F10)
2. Component-to-Swift mapping -- Figma component to Swift source file
3. Design token comparison -- Figma values vs DesignTokens.swift values

For design token comparison:

• Extract colors, fonts, spacing from get_design_context responses
• Read current Chrona/Design/DesignTokens.swift
• Compare and flag mismatches

Checklist:

• All pages mapped to Notion tasks
• Components mapped to Swift files
• Design tokens compared
• Mismatches flagged with specific values

Stage 5: Atomic Swap to Local

Only execute after CP1 passes (all exports successful).

1. If figma/ directory exists:
   • Create backup: mv figma/ figma/.backup-{YYYYMMDD-HHmmss}/
2. Create fresh figma/ directory
3. Move from .tmp/:
   • figma/.tmp/pages/ -> figma/pages/
   • figma/.tmp/assets/ -> figma/assets/
   • figma/.tmp/index.json -> figma/index.json
   • figma/.tmp/FIGMA_MAPPING.md -> figma/FIGMA_MAPPING.md
4. Copy each asset imageset to Chrona/Assets.xcassets/:
   • figma/assets/{name}/ -> Chrona/Assets.xcassets/{name}.imageset/
5. Write updated figma/sync-state.json with new lastModified and node hashes
6. Remove figma/.tmp/ directory
7. Remove backups older than 7 days

Rollback: If any step 2-6 fails, restore from .backup-{timestamp}/

CP2 Final Checklist:

• figma/pages/ has all page directories
• figma/assets/ has all illustration imagesets
• figma/index.json lists all pages
• figma/FIGMA_MAPPING.md is complete
• figma/sync-state.json updated
• Assets.xcassets/ has new imagesets
• .tmp/ directory removed
• No errors during swap

Usage

Full Sync (First Time)

User: "Sync all Figma designs to local"

Agent reads this skill, executes Stage 0-5 with all nodes.

Incremental Sync

User: "Update Figma designs"

Agent reads this skill, executes Stage 0 gate, only re-exports changed nodes.

Force Full Sync

User: "Force full Figma sync"

Agent treats all nodes as changed, bypasses incremental gate.

Single Page Sync

User: "Sync Figma page for Home Screen"

Agent runs Stage 0, then only exports the matching page node.

Additional Resources

• For detailed stage prompts and MCP examples, see reference.md
• For FIGMA_MAPPING.md template, see mapping-template.md
• For sync-state.json schema, see sync-state-schema.json