t1k:unity:ui:figma-import
| Field | Value |
|---|---|
| Module | ui |
| Version | 3.43.4 |
| Effort | high |
| Tools | — |
Keywords: design handoff, figma, figma import, figma mcp, figma to unity, import ui from figma, layer naming convention, sprite export, ugui prefab from figma, unity_ready
How to invoke
Section titled “How to invoke”/t1k:unity:ui:figma-import<figma file url> [source page] [section ids...]Figma → Unity uGUI Import
Section titled “Figma → Unity uGUI Import”Turns an art team’s Figma screens into Unity uGUI prefabs with no paid plugin: Figma MCP reads and edits the file,
t1k unity (the Unity Editor CLI) builds the prefabs. Every stage is a stored script plus a verification gate, so it runs the same way on
any project. Proven end to end on a 96-screen portrait game (layout, transparent sprites, TMP text with outline,
frame fills, drop shadows, buttons): the built prefab rendered pixel-identical across rebuilds and matched Figma.
When to use / not
Section titled “When to use / not”| Situation | Use |
|---|---|
| Figma screens → Unity uGUI prefabs | this skill |
| Layout from a screenshot, no Figma file | t1k:unity:ui:describe-image + t1k:unity:ui:create-prefab |
| Base-template screen/popup variants (com.gdk.core) | t1k:unity:ui:create-prefab (import here first, then re-parent) |
| UI Toolkit (UXML/USS) | out of scope; uGUI only |
Prerequisites (check, do not assume)
Section titled “Prerequisites (check, do not assume)”- Figma MCP connected (
mcp__figma__use_figma,download_assets). Load thefigma-useskill/resource before the firstuse_figma. - A Unity Editor open on the project and
t1k unity statusreporting ready (t1k:unity:editor:cli; runt1k unity doctorif not). Builds go throught1k unity eval/menu/refresh; there is no other Editor channel. - TMP Essentials imported, Newtonsoft JSON available (
com.unity.nuget.newtonsoft-json). - Never edit the art team’s pages. All work happens on a copy page
Unity_Ready; sprites ship via pageUnity_Sprites.
Run the stages in the session that owns the Figma MCP server and the Editor (or a native, never routed, sub-agent: a routed hop has no MCP tools).
Stages
Section titled “Stages”| # | Stage | Tool | Gate |
|---|---|---|---|
| 0 | Install Figma scripts into the file (once per file) | bun scripts/install-figma-scripts.cjs → paste as one use_figma | returns each script’s length |
| 1 | Clone sections to Unity_Ready | clone-sections | section/screen counts as expected |
| 2 | Standardize each section (pilot one screen first) | standardize then refine | leftN: 0 per screen |
| 3 | Page-wide fixes + naming audit | fixups | badN: 0 |
| 4 | Geometry gate vs. the source page | geometry-diff | every screen ok (explain any exception) |
| 5 | Art review of guessed names on Unity_Ready | human, in Figma | ask with AskUserQuestion |
| 6 | Export a section (or one screen) as a bundle | export → download_assets(rect) → rawImages[0] | newSprites, bundle unpacks |
| 7 | Unpack into the project | bun scripts/unpack-bundle.cjs bundle.png <UI root> | layouts + sprites written |
| 8 | Install builder (once per project), build | template → FigmaLayoutBuilder.BuildAll() | no console errors |
| 9 | Visual check | RenderPreview(...) vs. get_screenshot of the screen | side-by-side review |
Calling a stored script (stages 1–4, 6) is three lines inside use_figma:
const AF = Object.getPrototypeOf(async function () {}).constructor;const code = figma.root.getSharedPluginData('unity_ready', 'standardize');return await new AF('SECTION_ID', 'SKIP_IDS', code)('<section id>', []);Parameters per script: scripts/install-figma-scripts.cjs (PARAMS). Independent sections run as parallel use_figma
calls (one section per call); export merges its sprite registry on write, so parallel exports are safe.
Preview first: pilot one screen through stages 2–9 and show the side-by-side before scaling past 10 screens
(rules/preview-first-batch.md).
Details
Section titled “Details”- Layer contract (prefixes, popup structure, constraint zones): references/layer-contract.md
- Figma side: script behaviour, data-carrier bundle, failure modes: references/figma-pipeline.md
- Unity side: builder install,
font-map.json, outline tuning, preview: references/unity-builder.md - Project-specific widget names via
EXTRA_RULES: references/refine-extensions.md
Hard rules
Section titled “Hard rules”download_assetsexport is not a node export. It renders the node over its frame and section background (opaque mint/white corners). Never use it for sprites; use theexportbundle (raw image fill = byte-exact PNG).- The plugin sandbox has no
fetch: the only way out of Figma is a return value or an image fill. Large payloads go through the bundle, never through ause_figmareturn (it lands in the model context). - Figma Desktop MCP is unreliable for this: it can be bound to another window/tab and report nodes or newly created pages as missing. The cloud Figma MCP path above needs no Desktop app.
- Constraint codes:
MINandMAXshare a first letter. Use the exporter’s L/R/T/B/C/S/K codes, never[0]. - Figma
Scaleconstraint is exact in uGUI as proportional anchors (codeK); the builder supports it. - Do not judge the copy by PNG export: clip is off on
Unity_Ready, so exports include overflow. Usegeometry-diff. - Fonts: Google Fonts may have renamed a family (e.g. “Fredoka One” → variable “Fredoka”); fetch a static weight
and record it in
font-map.jsonwith adilateto match weight. A missing mapping is a hard error by design. - Fill-less frame shadows are cast by children; the builder mirrors them with
UnityEngine.UI.Shadowon child Images.
Executed by
Section titled “Executed by”Every stage ships a stored script, so the mechanical steps run on a cheap tier; only the
decisions stay on a reasoning tier (routing SSOT: rules/orchestration-rules.md):
| Step | Agent |
|---|---|
| Run a stage script and report its verification-gate output | t1k-fact-fetcher |
| Compare geometry-diff / export results against the layer contract | t1k-list-classifier |
| Decide how to resolve a failing gate or an ambiguous layer | reasoning tier (t1k-fullstack-developer or the main session) |
Visual change notice
Section titled “Visual change notice”A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:
- Capture OLD before the first edit and NEW after the last (screen:
ScreenCapturein Play mode pert1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file). - Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries
visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending:”, never a fake image.