Figma → Cocos Creator 2.x UI — Workflow

Turn a Figma screen into a Cocos 2.4.x scene/prefab. Speed comes from: read the design once → build the whole screen in ONE `node_create_node_tree` call → capture once → fix only what drifted. Never create nodes one-by-one.

Companion files (load on demand — keep this file lean)

• `templates.md` — copy-paste node templates (high reuse / error-prone). Load at Phase 2 to pick the right node shapes by their "Use when".
• `knowledge.md` — the create_node_tree spec, how to call tools, component rules, and recurring pitfalls. Skim before Phase 2; open the matching pitfall when capture looks wrong.

(Tools come from the cocos-ui MCP. If those tools aren't loaded in the session, call them over HTTP — see knowledge.md §0. Editor must be running with a scene open.)

Phase 1 — Analyze the design → a spec (don't build yet)

Run the Figma reads (cheap, parallel): get_metadata (tree: ids/names/types/x/y/w/h), get_design_context {excludeScreenshot:true} (colors, gradients, fonts, text, radii, asset urls), get_screenshot + Read it, get_variable_defs (color tokens). Produce a short spec (palette + fonts + any text/box shadows + element tree parent→child with rect + node type — typography & depth are what make it look like the design, §7) and decide:

• Node type per element: image→cc.Sprite; text→cc.Label; tappable→cc.Button(+bg); fill bar→cc.ProgressBar; scrolling list→cc.ScrollView+content cc.Layout; repeated row stack→cc.Layout.
• Grouping (same-level siblings): mirror Figma frames/auto-layout as container nodes. Text sitting on a background = a Content group node that is a sibling of the background node (not interleaved). An auto-layout frame → a node with cc.Layout.
• Widget / target-to-screen per group: header→Top, bottom action bar (buttons/cards/footer)→Bottom, backgrounds/hero→stretch/Top, centered content→Center. (Presets in knowledge.md §3.)
• 2-state elements (toggle / select / on-off / default-vs-active): build BOTH states as sibling children, one active:true one active:false, so switching = flip active (no rebuild). Use the 2-state card template.

Phase 1.5 — Download & import assets

• download_assets {nodeId} per asset node; prefer PNG for Cocos 2.x (defaultFormat:"png", scale 2 for icons). curl urls into <project>/assets/<Screen>/textures/.
• Skip device chrome (OS status bar, gesture nav). Gradients & rounded backgrounds: don't download — build natively (apply_gradient / draw_rounded_rect).
• Get each PNG's spriteFrameUuid: either asset_import_asset, or if the file is already under assets/, read <name>.png.meta → subMetas.<name>.uuid (knowledge.md §2).
• Bake the PNGs you can't render natively with the shipped helper bake.py (knowledge.md §0): persistent cards/borders (P6), per-corner badges (P9), and fixing Figma's opaque-black export (P7 — mask-circle/black-key). Download a custom font .ttf here too if the design uses one (§7).

Phase 2 — Build the WHOLE screen in ONE create_node_tree call

The #1 speed lever. Per-node creation is 10× slower and error-prone.

1. scene_get_scene_hierarchy → Canvas uuid (parent).
2. Open `templates.md`, pick the node shapes you need by their "Use when".
3. Author the tree as script-generated JSON (Python → curl -d @file.json): root = a fixed-size screen node (e.g. 1080×2400, NO widget — see pitfall P1), every section as nested children. Use space:"figma" + frameW/frameH to paste Figma top-left x/y directly. Each node carries inline components/background/labelStyle/widget/button. POST once → returns all uuids. (Full tree shape: knowledge.md §1.)
4. Fall back to individual create_node/set_* calls only for targeted fixes after capture — never for the initial build.

Phase 3 — Capture & verify (active checklist, not an eyeball pass)

1. scene_capture_node {uuid:<rootUuid>, maxSize:1000–1200} (capture the root, not Canvas — P5; go bigger than the 720 default so text/edges are legible) → Read the PNG next to the Figma screenshot. Don't glance-and-approve a thumbnail — small captures hide real drift (a zig-zag icon column, a wrong corner radius). Run the §6 compare checklist (knowledge.md): scan each error-prone spot on purpose — left items share one edge? (P8) corners rounded only where Figma rounds them? (P9) left titles / right prices flush? (P2) button/badge labels centered & unclipped? (P3) solid cards still present? (P6) no black box behind icons? (P7). Zoom into a section node (maxSize:600+) if unsure — never approve a region you couldn't actually see.
2. Fix drift with node_set_node_properties_batch / set_node_transform / component_apply_widget, or delete-and-recreate the affected subtree — don't rebuild the whole screen. If text/layout looks wrong, check knowledge.md pitfalls (P2 anchor, P3 overflow, P8 layout-center, P9 corners) first. Re-capture the changed area to confirm the fix.
3. scene_save_scene; if reusable → prefab_create_prefab {uuid, dir, name}.
4. (Optional) responsiveness — only if the screen must flex across aspect ratios. Costly in edit mode (resize root → apply_widget every child → capture). Skip for single-resolution screens. (Procedure: knowledge.md P4.)

Speed checklist (< 10 min)

1. Figma reads → spec (~2′) · 2. assets (~2′) · 3. ONE create_node_tree (~1′) · 4. capture big + run §6 checklist + batch-fix drift (~2–3′) · 5. save + prefab (~1′) · 6. responsive = optional.

The <10′ holds for a non-prefab static screen. If it becomes a prefab with cards/badges, add ~3–5′ for baking persistent PNGs (P6/P9) — fast with bake.py (knowledge.md §0), but it's real work the budget above doesn't include.

Maintaining this skill (when you learn something new)

• New template → add to templates.md ONLY if it's high-reuse OR error-prone/slow-to-build-from-scratch. Give it a clear "Use when".
• New knowledge → add to knowledge.md ONLY if high-value: a component-usage technique, or a bug you could repeat. Write it as symptom → fix.
• Don't dump low-value notes. Keep both files' index tables in sync.

Worked example built with this skill: NewProject/assets/IAP/ (Figma node 52:8739, a paywall) — the templates are generalized from it.