DOCSEARCHbyAlgolia
Submit Docs

Figma MCP Server Guide

repository·main·Indexed 23 days ago

https://github.com/figma/mcp-server-guide

Documentation for the Figma MCP server, which enables AI agents to interact with Figma designs. Features include extracting design context, generating code from frames, writing to the canvas, and Code Connect integration. Includes setup instructions for VS Code, Cursor, Claude Code, and Gemini CLI, as well as a reference for available tools such as get_design_context, get_screenshot, and generate_figma_design.

Tokens
206.4K
Snippets
381
Records
674
Agent score
83%

What's inside Figma MCP Server

  1. Overview of Figma MCP Server Features

    main

    The Figma MCP server connects Figma design data to AI agents to facilitate code generation and design manipulation. Key features include:

    • Write to the canvas (remote server only): Allows agents to create and modify native Figma content like frames, components, variables, and auto layout. (Currently free during beta).
    • Generate code from selected frames: Converts a selected Figma frame directly into code.
    • Extract design context: Pulls variables, components, and layout data into your IDE for design system workflows.
    • Code Connect integration: Reuses your actual codebase components to ensure generated code is consistent with your existing library.
    • Generate Figma designs from web pages (rolling out): Converts web pages into Figma designs via an AI agent.

  2. Overview of Figma MCP Server Capabilities

    main

    The Figma MCP server provides three primary workflows for integrating design and code:

    1. Implement Design: Translates Figma designs into production-ready code with high visual fidelity.
    2. Code Connect Components: Links Figma design components to their actual code implementations using Code Connect.
    3. Create Design System Rules: Generates project-specific guidelines to ensure AI agents follow consistent Figma-to-code workflows.

    Use this integration when you provide Figma URLs or express intent to implement UI, map components, or establish design system conventions.

  3. What is Code Connect?

    main

    Code Connect establishes a bidirectional link between Figma designs and your codebase. It serves three primary purposes:

    • For designers: Allows them to see which specific code component implements a Figma component.
    • For developers: Enables direct navigation from Figma designs to the implementing code.
    • For teams: Maintains a single source of truth for component mappings, ensuring design and code stay in sync through explicit and discoverable connections.

  4. How Figma ↔ SwiftUI translation works

    main

    The figma-swiftui skill enables bidirectional translation between Figma designs and SwiftUI code. It is triggered by mentions of Swift, SwiftUI, iOS, iPhone, or iPad, or when a Figma URL is provided alongside .swift files or an `.xcodeproj$.

    Directions

    1. Design → Code: Translating a Figma design or frame into SwiftUI code for an iOS project. This uses the references/design-to-code.md reference.
    2. Code → Design: Pushing SwiftUI views, screens, or tokens back into a Figma file. This uses the references/code-to-design.md reference and requires loading the figma-use skill.

    If a request is ambiguous (e.g., both a Figma URL and .swift files are present without a clear verb), you must ask the user to clarify the direction before proceeding.

  5. Understand Editor Modes (Design, FigJam, Slides)

    main

    The available API and node types depend on the file type, which can be determined from the URL:

    • Design: figma.com/design/... (Default)
    • FigJam: figma.com/board/...
    • Slides: figma.com/slides/...

    Key Differences:

    • figma.createPage() is only available in Design files. It will throw a TypeError in FigJam or Slides.
    • Design Mode supports nodes like Rectangle, Frame, Component, etc., but blocks FigJam-specific nodes like Sticky or Connector.
    • Slides Mode supports Slide, SlideRow, etc., but blocks Page and Sticky.
    • Note: There is currently no dedicated read tool for Slides; use use_figma with read-only scripts and get_screenshot for visual context.

  6. Handling empty grids in newly created Figma Slides

    main

    When creating a file with editorType: "slides", be aware that the file starts with an empty grid.

    • figma.getSlideGrid() will return [] (zero rows and zero slides).
    • The page's only child is the SLIDE_GRID node, which is empty.

    Important: If your subsequent use_figma script expects existing content (like theme tokens), you must guard against this empty state or explicitly call figma.createSlide() first. The first call to figma.createSlide() will implicitly create row 0 and insert the new slide there.

  7. Organize Variables using Grouping

    main

    Variable names in Figma use slash-delimited strings (e.g., Colors/Brand/Primary) to create visual groups in the Figma UI.

    When mapping code tokens to Figma variables, note that a code prefix might correspond to the name of a Collection rather than a top-level group. It is acceptable for code prefixes to differ from Figma groups, but ensure clarity when performing matching operations.

  8. Understand the TextStyle model

    main

    A TextStyle is a named, reusable typography definition that bundles properties like font family, size, weight, line height, and letter spacing. While text styles are not variables themselves, individual properties within a style can be bound to variables to participate in a design token system.

    Writable Properties:

    PropertyTypeNotes
    namestringSlash-delimited for grouping (e.g. "Heading/XL")
    fontSizenumberIn pixels
    fontNameFontName{ family: string, style: string } — font must be loaded before setting
    letterSpacingLetterSpacing{ value: number, unit: 'PIXELS' | 'PERCENT' }
    lineHeightLineHeight{ value: number, unit: 'PIXELS' | 'PERCENT' } or { unit: 'AUTO' }
    textCaseTextCase'ORIGINAL' | 'UPPER' | 'LOWER' | 'TITLE' | 'SMALL_CAPS'
    textDecorationTextDecoration'NONE' | 'UNDERLINE' | 'STRIKETHROUGH'
    paragraphSpacingnumber
    paragraphIndentnumber
    descriptionstringInherited from BaseStyleMixin

  9. Understand Figma component property types

    main

    Figma components use four primary property types to manage variations and content. To inspect these, use componentPropertyDefinitions on a component set or a non-variant component. Note that for variant components (children of a component set), you must inspect the parent Component Set rather than the variant itself. To map properties to specific descendants, use the following reference keys on the descendant nodes:

    • Variant: Represented as permutations within a Component Set. These are handled via layer naming (e.g., Variant=Primary,Size=Small,State=Disabled).
    • Text/String: Stored on the component parent but mapped to text node descendants. Use node.componentPropertyReferences.characters on a descendant text node to find the reference.
    • Boolean: Stored on the component parent but mapped to any node descendant with toggleable visibility. Use node.componentPropertyReferences.visible on the descendant node to find the reference.
    • Instance Swap: Stored on the component parent but mapped to Instance node descendants (e.g., an icon property). Use node.componentPropertyReferences.mainComponent on the descendant instance node to find the reference.

  10. How to handle multi-page work efficiently

    main

    When a task spans multiple pages, do not loop through pages and call setCurrentPageAsync inside a single script. This causes repeated file reloads and is inefficient.

    The Parallel Fan-out Pattern:

    1. Use a read-only discovery call to find the necessary page IDs/names.
    2. In the next message, emit multiple use_figma tool calls in parallel (one per target page).
    3. Each individual script should call setCurrentPageAsync exactly once at its start.

    Rule: One script must switch pages at most once. If you need to touch 5 pages, issue 5 parallel tool calls in a single assistant message rather than one sequential script.

  11. Use hex/255 notation for FigJam palette colors

    main

    To ensure FigJam recognizes a color as a built-in "palette color" (allowing users to use the UI swatch to change it and enabling color-by-name lookups), you must use exact hex/255 notation. Do not use pre-rounded decimals, as even slight drift causes FigJam to treat the color as a "custom" color.

    Correct approach:

    // Exact palette match
sticky.fills = [{ type: 'SOLID', color: { r: 0xa8/255, g: 0xda/255, b: 0xff/255 } }] // Blue #A8DAFF

    Incorrect approach:

    // Pre-rounded, will be marked as "custom"
sticky.fills = [{ type: 'SOLID', color: { r: 0.66, g: 0.85, b: 1.0 } }]
    // CORRECT — exact palette match
sticky.fills = [{ type: 'SOLID', color: { r: 0xa8/255, g: 0xda/255, b: 0xff/255 } }]  // Blue #A8DAFF

  12. Choose a Token Collection Architecture Pattern

    main

    Select a variable architecture based on your project's complexity and token count:

    1. Simple Pattern (< 50 tokens): A single collection with two modes (e.g., Light and Dark). Best for small projects or brand kits.
    2. Standard Pattern (50–200 tokens): Recommended for most design systems. It separates Primitives (raw values, single mode) from Semantics (aliases to primitives, multiple modes like Light/Dark). This follows the Figma Simple Design System (SDS) model.
    3. Advanced Pattern (200+ tokens): Uses the M3 (Material 3) model. It involves multiple semantic collections and high mode counts (4–8 modes) to handle combinations like Light/Dark × High Contrast or responsive breakpoints. In this model, all semantic color variables live in a single collection to allow simultaneous updates via a single mode switch.