t1k:cocos:base:figma-to-ui
| Field | Value |
|---|---|
| Module | base |
| Version | 4.51.9 |
| Effort | high |
| 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
How to invoke
Section titled “How to invoke”/t1k:cocos:base:figma-to-ui<figma-url|file-key> [--node <id>] [--project <root>] [--screens <names>]Figma → Cocos UI Reconstruction
Section titled “Figma → Cocos UI Reconstruction”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.
What this skill does and does not own
Section titled “What this skill does and does not own”| Owns | Delegates to |
|---|---|
| Screen discovery, layer analysis, geometry normalization | scripts/figma-ui.cjs |
| Native-vs-export decision, hierarchy design, component extraction, naming | the skill body — judgment |
| Asset export from Figma | scripts/figma-ui.cjs export-assets |
| Writing into an existing prefab | t1k:cocos:playable:ui-from-image composer |
Creating new nodes, components, prefabs, wiring @property | Cocos MCP — manage_node, manage_component, manage_prefab |
| Importing and naming the exported files | t1k: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”:
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.
Pipeline
Section titled “Pipeline”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 │ └─────────────────────────────────────┘1. Discover — once per file
Section titled “1. Discover — once per file”bun scripts/figma-ui.cjs discover --file <url> --out .figma/screens.jsonClassification 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.
2. Analyze — per screen
Section titled “2. Analyze — per screen”bun scripts/figma-ui.cjs analyze --file <url> --node <id> --out .figma/home.spec.jsonThe 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.
4. Export — only what step 3 marked
Section titled “4. Export — only what step 3 marked”bun scripts/figma-ui.cjs export-assets --file <url> --spec .figma/home.spec.json \ --out assets/game-assets/UI/home --scale 2Deduplicates 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.
Visual director loop
Section titled “Visual director loop”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.Widgetandcc.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.
Executed by
Section titled “Executed by”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”.
| Step | Agent |
|---|---|
Run figma-ui.cjs discover / analyze / doctor / export-assets and report their output verbatim | t1k-fact-fetcher |
| Author each screen prefab through the editor MCP | t1k-cocos-base-developer (operator for editor-only/repair) |
| Judge layout and visual fidelity against the design | t1k-gamedev-playable-visual-director — advisory, reasoning tier |
Hard rules
Section titled “Hard rules”.metais 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 becomesNone. Re-exporting an updated icon means overwriting the same filename. Seet1k-cocos-base-asset-importskills/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’slayerbeforeaddChild. This bites the moment any part of the UI is spawned rather than authored. - Figma
SCALEconstraints have no exact Cocos equivalent. The spec flagsscaleApproxand 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.Layoutrecalculates 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 uses1:234. The script converts; a hand-writtencurlwill not. - Design-file drift is real. The spec records
lastModifiedandfetchedAt. Re-runanalyzebefore fixing a screen you specced days ago, and diff — the output is deterministic precisely so that diff is readable.
Related
Section titled “Related”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.
Visual change notice
Section titled “Visual change notice”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.