Figma to unity

Figma to Unity (Figma MCP → UI Toolkit)

Translate a Figma design into production-ready Unity UI Toolkit code: UXML for structure, USS for style (wired to the project's design tokens), exported assets with correct import settings, and a thin C# controller. The Figma MCP server output (typically React + Tailwind) is a representation of the design, not final code — always re-express it in UXML/USS following the host project's conventions.

Prerequisites

Verify all three before starting. If one fails, stop and tell the user.

1. Figma MCP server connected. Check that Figma MCP tools (e.g. get_design_context) are available. If not, guide the user to enable the Figma MCP server (included with the Figma desktop app / plugin) and restart their MCP client.
2. Figma URL with a node id, in the format https://figma.com/design/:fileKey/:fileName?node-id=1-2. If the URL has no node-id, ask the user to select the frame/component and copy its link.
3. Unity project using UI Toolkit. Look for .uxml/.uss files and UIDocument usage under Assets/. If the project's UI is uGUI (Canvas + TextMeshPro), say so and stop — this skill does not cover uGUI.

Required workflow

Follow these steps in order. Do not skip steps.

Step 1: Extract file key and node ID

From https://figma.com/design/:fileKey/:fileName?node-id=1-2:

• File key: the segment after /design/
• Node ID: the node-id query parameter value (e.g. 1461-137)

Step 2: Fetch design context

Run get_design_context(fileKey, nodeId). It returns layout (Auto Layout, constraints, sizing), typography, colors/tokens, component structure, and spacing.

If the response is too large or truncated:

1. Run get_metadata(fileKey, nodeId) to get the high-level node map.
2. Identify the child nodes you need.
3. Fetch each child individually with get_design_context(fileKey, childNodeId).

Step 3: Capture the visual reference

Run get_screenshot(fileKey, nodeId). This screenshot is the source of truth for visual validation — keep it accessible throughout implementation.

Step 4: Map design tokens to USS variables

Run get_variable_defs(fileKey, nodeId) to retrieve colors, typography, and spacing variables used by the design.

Then locate the project's existing theme/token stylesheet (search for USS files defining --* custom properties, often named Theme.uss, Tokens.uss, or referenced from a .tss theme file):

• Reuse existing tokens first. Map each Figma variable to the closest existing USS variable (var(--accent), var(--font-size-md), ...).
• Add new tokens to the theme stylesheet only when nothing close exists. Name them following the project's convention.
• On conflict (project token value differs from Figma): prefer the project token for consistency, and adjust spacing/sizing minimally to preserve visual fidelity.
• If the project has no token stylesheet, propose creating one rather than hardcoding values across files.

Step 5: Export required assets

Download any images/icons returned by the Figma MCP server into the project's UI art folder (follow the host project's layout, e.g. Assets/Art/UI/<Feature>/ or Assets/UI/<Feature>/Sprites/).

Asset rules:

• If the MCP server returns a localhost source for an image or SVG, use that source directly. Do not substitute placeholders and do not import icon packages.
• Prefer vector data (SVG, supported by UI Toolkit in Unity 6.2+) for icons when the project already imports SVGs; otherwise export PNG at 2x.
• After import, set Texture Type to Sprite (2D and UI). For panels, frames, and bars that stretch, configure 9-slice borders in the Sprite Editor and use -unity-slice-* / -unity-background-image-tint-color in USS as needed.
• Decorative gradients and flat shapes usually do not need an asset — recreate them in USS (or a custom VisualElement with generateVisualContent) instead of exporting a bitmap.

Step 6: Translate to UXML + USS

Build the VisualElement hierarchy in UXML and style it in USS. Key principles:

• Treat the Figma MCP code output (React + Tailwind) as a design spec: read flex direction, padding, gap, radius, colors from it — do not transliterate JSX or Tailwind classes.
• Mirror Figma Auto Layout frames as containers with flex-direction, and convert gap/padding/sizing per figma-to-uss-mapping.md. Consult that reference for the full property mapping and USS limitations (no gap in most versions, no box-shadow, no z-index...).
• Reuse existing UXML components, USS utility classes, and custom VisualElements from the project before creating new ones. When a similar component exists, extend it (new USS class/variant) rather than duplicating it.
• Name elements (name="HealthBarFill") only when C# needs to query them; style through classes, not names.
• Follow the host project's file layout and naming (e.g. one feature folder containing Feature.uxml, Feature.uss, FeatureController.cs).

Step 7: Write the minimal C# controller

• MonoBehaviour with a [SerializeField] UIDocument (or follow the project's established UI wiring pattern if it differs).
• Query elements once in OnEnable via root.Q<T>("Name"); cache references.
• The controller binds data to the view (set style.width, text, toggle USS classes). No game logic in the view layer, no game logic in VisualElement subclasses.
• Hook into the project's existing data flow (events, view models, ScriptableObject channels) instead of polling in Update when possible.

Step 8: Validate against the Figma screenshot

Compare the rendered result (Game view / UI Builder preview) with the Step 3 screenshot before marking the task complete:

• Layout matches: spacing, alignment, sizing, element order
• Typography matches: font, size, weight, letter spacing, alignment
• Colors match (through tokens, not hardcoded values)
• Assets render correctly (no stretching artifacts; 9-slice borders correct)
• Interactive states styled where designed (:hover, :active, :disabled)
• Behavior verified with representative data (e.g. bar at 0%, 50%, 100%)

If the user can run the Editor, ask them to confirm visually; otherwise list any known deviations and why.

Rules

• DO prefer project tokens over raw Figma values when they conflict.
• DO reuse existing components, classes, and custom elements before creating new ones.
• DO document any intentional deviation from the Figma design (accessibility, technical constraint) in a short code comment.
• DON'T hardcode a color/size/font when a token exists for it.
• DON'T invent or placeholder assets when the MCP payload provides a source.
• DON'T port Tailwind class names, web-only CSS properties, or React component structure into USS/UXML.

Additional resources

• Property-by-property translation tables and USS limitations: figma-to-uss-mapping.md
• For broader Unity UI Toolkit architecture guidance (design systems, MVP/MVVM, data binding), use the unity6-aaa-best-practices skill if available.