Skip to content

t1k:cocos:base:figma-to-ui

FieldValue
Modulebase
Version4.51.9
Efforthigh
Tools—

Keywords: auto layout, constraints, design handoff, design to ui, figma, figma rest api, figma to cocos, pixel perfect, screen prefab, ui from design, ui reconstruction, widget

/t1k:cocos:base:figma-to-ui
<figma-url|file-key> [--node <id>] [--project <root>] [--screens <names>]

Turn a Figma file into independent screen prefabs built from native Cocos nodes, with reusable components extracted and artwork exported only where a native node genuinely cannot reproduce it.

Figma is the source of truth for the visual design. It is not the source of truth for hierarchy, responsiveness, or naming — those are engineering decisions this skill makes deliberately, because a design file carries no anchors, no cc.Widget, and no notion of what a player can tap.

OwnsDelegates to
Screen discovery, layer analysis, geometry normalizationscripts/figma-ui.cjs
Native-vs-export decision, hierarchy design, component extraction, namingthe skill body — judgment
Asset export from Figmascripts/figma-ui.cjs export-assets
Writing into an existing prefabt1k:cocos:playable:ui-from-image composer
Creating new nodes, components, prefabs, wiring @propertyCocos MCP — manage_node, manage_component, manage_prefab
Importing and naming the exported filest1k:cocos:base:asset-import

This skill never writes a .prefab by hand and never builds UI in TypeScript. rules/prefab-only-construction-cocos.md binds here without exception: hierarchies are authored in the editor through the MCP, and cross-node references are editor-assigned @property, never find() lookups. A generated scene-building script is not authoring — it is the thing that rule exists to forbid.

A Figma personal access token with file_content:read scope, in .env at the project root:

FIGMA_TOKEN=figd_...

A FIGMA_TOKEN environment variable works too and is the better choice when the same token serves several projects, since it needs no per-project file. Confirm before anything else — this separates “no token” from “wrong file key” from “no network”:

Terminal window
bun scripts/figma-ui.cjs doctor --file <figma-url> --project <root>

Intermediate output lands in .figma/ at the project root: the screen manifest, one spec per screen, and the progress file. Add .figma/ and .env to the project’s .gitignore — the specs are large, regenerable, and carry the design’s full text content.

Run it one screen at a time, end to end. Analyzing twenty screens before building any of them produces twenty stale specs and no working UI.

Every command, flag, exit code, and output shape is specified in cli-contract.md (references/cli-contract.md) — read it before improvising a curl.

discover → select screens → ┌─ per screen ────────────────────────┐ → report
│ analyze → decide → export → build │
│ → validate → fix │
└─────────────────────────────────────┘
Terminal window
bun scripts/figma-ui.cjs discover --file <url> --out .figma/screens.json

Classification in the manifest is a proposal with a stated reason, not a verdict. Present the candidates and confirm the screen list with the user before building anything — a frame that is a design note and a frame that is a real screen are indistinguishable to a size heuristic.

Terminal window
bun scripts/figma-ui.cjs analyze --file <url> --node <id> --out .figma/home.spec.json

The spec carries the arithmetic you must not do by hand: parent-relative geometry, the Y-axis flip, anchor-aware position, negated rotation, constraints already mapped to cc.Widget fields, and auto layout already mapped to cc.Layout. Read mapping.md (references/mapping.md) for what each field means and where the mapping is approximate.

3. Decide — the three judgments the script cannot make

Section titled “3. Decide — the three judgments the script cannot make”

Native or exported. The spec’s exportHint proposes; you decide. The objective test is not “does it look complex” but: can a cc.Sprite with a solid colour, a nine-slice, a cc.Label, or a Graphics call reproduce this within a few pixels? If yes it stays native, however decorative it looks. Text is never exported. Overruling a hint is fine and must name the node and the reason.

Hierarchy. Preserve the structure a player and a programmer need, not Figma’s grouping accidents. A Button stays Background + Icon + Label so it can animate, localize, and change state. Collapse a group only when every child is decoration that will never move independently.

Reuse before creation. Before extracting a component, search the project for one that already exists — t1k:cocos:playable:ui-from-image’s catalog command ranks existing prefabs and sprite frames by hint. Rebuilding a Button.prefab that already ships is the most expensive mistake available here, and theonekit-core/.claude/modules/t1k-engineering/rules/search-before-you-build.md makes the search mandatory, not optional.

Terminal window
bun scripts/figma-ui.cjs export-assets --file <url> --spec .figma/home.spec.json \
--out assets/game-assets/UI/home --scale 2

Deduplicates identical content, refuses to write outside assets/, never touches a .meta. Name assets semantically before import — icon_coin.png, never Vector 8.png — and follow the project’s asset-pipeline.json prefix rules through t1k:cocos:base:asset-import rather than inventing a parallel scheme.

5. Build — through the MCP, one screen prefab

Section titled “5. Build — through the MCP, one screen prefab”

Author the hierarchy with manage_node / manage_node_hierarchy, attach components with manage_component, save with manage_prefab. t1k:cocos:playable:tooling-gotchas carries the traps that make this succeed on the first attempt rather than the fourth.

Where a suitable base prefab exists, prefer the tested path: plan emits a manifest in the ui-from-image composer’s schema, and that composer mutates the prefab deterministically with a dry-run first.

6. Validate — against the design, not against your intent

Section titled “6. Validate — against the design, not against your intent”

validation.md (references/validation.md) owns the loop and the fix-order. The short version: a screen is not done because it was built, it is done because it was compared.

t1k-gamedev-playable-visual-director (advisory — never edits, never calls editor MCP): brief the screen’s layout, hierarchy, CTA prominence and contrast before the pipeline runs, and review a screenshot of each built prefab against the Figma frame before declaring a screen COMPLETE. Max 2 rounds — after the second, remaining items are the caller’s call, not a third pass. Its fixes land through t1k-cocos-base-developer (prefab/TS) or t1k-cocos-base-editor-operator (editor writes).

A screen is COMPLETE only when all of these hold. Anything short of it is NEEDS_REVIEW, and saying so is the correct outcome, not a failure.

  • Its own prefab exists, under prefabs/screens/, with semantic node names throughout.
  • Every layer is accounted for: implemented, deliberately omitted with a reason, or listed as UNKNOWN. Silence about a layer is a defect.
  • No text was exported as an image. No screen was flattened to a single sprite.
  • Responsive behaviour comes from cc.Widget and cc.Layout, not from hardcoded screenshot coordinates, and it was checked at both aspect-ratio extremes.
  • Reused components are prefab instances of one prefab, not copies.
  • A visual comparison against the Figma frame was actually performed and its result recorded.
  • Every approximation and every missing font is named in the report.

Unknowns are reported, never invented. If a font is unavailable, say so and name the substitute — do not silently pick one.

Discovery, analysis and asset export are scripted; prefab authoring and fidelity are not. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run figma-ui.cjs discover / analyze / doctor / export-assets and report their output verbatimt1k-fact-fetcher
Author each screen prefab through the editor MCPt1k-cocos-base-developer (operator for editor-only/repair)
Judge layout and visual fidelity against the designt1k-gamedev-playable-visual-director — advisory, reasoning tier
  • .meta is identity. Cocos keys an asset by the UUID in its .meta, never its path. Overwrite an asset in place and every reference survives; delete-then-add and every reference silently becomes None. Re-exporting an updated icon means overwriting the same filename. See t1k-cocos-base-asset-import skills/t1k-cocos-base-asset-import/references/asset-slot-handoff.md.
  • A node created at runtime is invisible under a Canvas. It defaults to Layers.Enum.DEFAULT; copy the parent’s layer before addChild. This bites the moment any part of the UI is spawned rather than authored.
  • Figma SCALE constraints have no exact Cocos equivalent. The spec flags scaleApprox and maps to stretch. Check those nodes at both extremes specifically.
  • Auto Layout is not always the right answer. A Figma auto-layout frame whose children never reflow at runtime is better as fixed children with cc.Widget; cc.Layout recalculates every time the content changes and it is not free.
  • A Figma effect list is not a Cocos effect list. Multiple shadows, background blur, and blend modes have no native equivalent. Approximate and say so, or export — never quietly drop it.
  • Figma URLs use 1-234, the REST API uses 1:234. The script converts; a hand-written curl will not.
  • Design-file drift is real. The spec records lastModified and fetchedAt. Re-run analyze before fixing a screen you specced days ago, and diff — the output is deterministic precisely so that diff is readable.
  • t1k:cocos:playable:ui-from-image — the composer this skill plans for; also the reuse catalog.
  • t1k:cocos:playable:layout — responsive sizing, safe areas, aspect-ratio buckets.
  • t1k:cocos:base:asset-import — naming, prefix rules, and promotion of the exported files.
  • t1k:cocos:playable:tooling-gotchas — the Cocos MCP authoring traps.
  • skills/t1k-cocos-playable-localize/SKILL.md — run after the UI exists, so text nodes become bindings.
  • rules/prefab-only-construction-cocos.md — why the build step is MCP-driven, not code-driven.

Rule visual-change-discord-notice: rebuilding a screen from Figma is a visible change. Capture OLD before the first edit and NEW after the last (preview-verify shot steps, or the image file itself for a 2D asset), return the paths and a draft Discord post (what changed, undo = revert the PR) to the orchestrator, who posts; never post from here. Logic-only: no visible change. No capture possible: screenshots pending: <reason>, never a mock image. The PR needs the Discord link or visual-notice-waiver: <reason>; the owning agent’s Visual change notice section has the full steps.