Figma Context

Figma context

Hard technique for pulling design context from Figma via the Figma desktop MCP server during documentation workflows.

Purpose

During discovery and drafting, users often have components, patterns, or foundations already designed in Figma. Rather than requiring the user to manually describe everything, this skill reads Figma files directly — pulling component structure, variants, properties, variables, and screenshots to ask better questions and verify documentation completeness.

The LLM does not write documentation from Figma data. Figma context is used to:

• Ask more informed questions ("I see you have 3 size variants in Figma — small, medium, large. Do you want to document all three?")
• Cross-reference what is documented against what is designed ("Your Figma component has an isLoading prop that is not mentioned in the Props section yet")
• Understand anatomy without requiring the user to describe every detail from scratch

Connection modes

The Figma MCP server supports two connection methods.

Desktop server (local)

Runs locally through the Figma desktop app at http://127.0.0.1:3845/mcp. Supports both selection-based and link-based workflows.

Setup:

1. Open the Figma desktop app (latest version)
2. Open a Figma Design file and toggle to Dev Mode (Shift+D)
3. In the MCP server section of the inspect panel, select Enable desktop MCP server
4. Add to Claude Code: claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp

Remote server

Connects directly to Figma's hosted endpoint at https://mcp.figma.com/mcp. Uses OAuth authentication — no desktop app required. Supports link-based workflows only.

When to use Figma context

During discovery

• User mentions they have a Figma file or component
• User provides a Figma URL
• User says "it's already designed" or references existing designs
• User selects a node in the Figma desktop app

During drafting

• Anatomy section: Use get_metadata to pull the layer structure, then get_design_context for full detail
• Variants section: Use get_design_context to pull variant definitions (size, style, state) for full coverage
• Props/API section: Use get_design_context to pull component properties and cross-reference with documented props
• States section: Pull interactive states visible in the Figma component
• Foundations (tokens): Use get_variable_defs to pull design variables (colours, spacing, typography tokens)

During completeness review

• Cross-reference documented variants against Figma variants
• Check if documented props match Figma component properties
• Verify anatomy descriptions match the Figma layer structure
• Use get_screenshot to visually verify what the component looks like

Available Figma desktop MCP tools

get_design_context

• Use: Primary tool — generates code and design context for a node
• When: Translating a design into code, pulling component properties, variants, layout data
• Input: Optional nodeId (for example, "123:456"). If omitted, uses the currently selected node in Figma.
• Params: artifactType (WEB_PAGE_OR_APP_SCREEN, COMPONENT_WITHIN_A_WEB_PAGE_OR_APP_SCREEN, REUSABLE_COMPONENT, DESIGN_SYSTEM), taskType (CREATE_ARTIFACT, CHANGE_ARTIFACT, DELETE_ARTIFACT), forceCode (boolean, forces code output for large nodes)
• Note: This is the main tool to call. Always prefer this over get_metadata when you need design details.

get_metadata

• Use: Get a structural overview of a node or page in XML format
• When: Understanding the layer hierarchy, finding specific node IDs to drill into, getting an overview before calling get_design_context
• Input: Optional nodeId. If omitted, uses the currently selected node.
• Returns: XML with node IDs, layer types, names, positions, and sizes — structure only, no design details
• Important: After calling this, follow up with get_design_context on specific node IDs to get actual design information.

get_variable_defs

• Use: Get design variable definitions (design tokens) for a node
• When: Documenting foundations (colour, typography, spacing) or understanding which tokens a component uses
• Input: Optional nodeId. If omitted, uses the currently selected node.
• Returns: Variable name-to-value mappings (for example, {'icon/default/secondary': #949494})

get_screenshot

• Use: Generate a visual screenshot of a node
• When: Visually verifying what a component looks like, cross-referencing documentation descriptions with actual appearance
• Input: Optional nodeId. If omitted, uses the currently selected node.
• Returns: An image of the node

create_design_system_rules

• Use: Generate a prompt for analysing the codebase to create design system integration rules
• When: Setting up Code Connect, aligning codebase structure with Figma design system
• Returns: A structured prompt covering token definitions, component library, frameworks, asset management, icon system, styling approach, and project structure

get_figjam

• Use: Generate context from FigJam files
• When: Pulling content from FigJam diagrams — architecture maps, flows, brainstorming boards
• Input: Optional nodeId. If omitted, uses the currently selected node.
• Note: Only works for FigJam files, not regular Figma Design files.

How to provide Figma context

Selection-based (desktop server only)

The user selects a frame or layer inside Figma, then asks the LLM to work with it. Call tools without a nodeId to use the current selection.

Link-based

The user copies a Figma URL. Extract the node-id from the URL to pass as nodeId.

How to extract Figma URLs

Figma URLs follow these patterns:

Design file:  https://www.figma.com/design/{FILE_KEY}/{FILE_NAME}?node-id={NODE_ID}
Branch:       https://www.figma.com/design/{FILE_KEY}/branch/{BRANCH_KEY}/{FILE_NAME}
FigJam:       https://www.figma.com/board/{FILE_KEY}/{FILE_NAME}?node-id={NODE_ID}

To extract a node ID from a URL: parse the node-id query parameter. The URL format uses hyphens (for example, 1-2) but the MCP tools expect colons (for example, 1:2). Convert node-id=1-2 to nodeId: "1:2".

For branch URLs (/design/{FILE_KEY}/branch/{BRANCH_KEY}/), use the BRANCH_KEY as the file key.

Interpreting Figma data

Component properties → Props/API section

Figma component properties map to documentation props:

• Boolean properties → boolean props (for example, isDisabled, showIcon)
• Text properties → string props (for example, label, helperText)
• Instance swap properties → slot/child component props (for example, icon, leadingElement)
• Variant properties → enum props or variant names (for example, size: sm | md | lg)

Variant structure → Variants section

Figma component sets define variants as property combinations:

• Each variant property (size, style, state) becomes a documentation variant axis
• The values for each property become the variant options
• Combinations that exist in Figma should be documented

Layer structure → Anatomy section

Use get_metadata to reveal layer hierarchy, then get_design_context for detail:

• Top-level frames within the component are major parts
• Named layers correspond to anatomical elements
• Auto-layout structure reveals container relationships
• Hidden layers may represent conditional or optional parts

Variables → Foundations documentation

Use get_variable_defs to pull design tokens:

• Colour variables → colour tokens
• Spacing variables → spacing tokens
• Typography variables → typography tokens
• These map directly to design token documentation

Recommended tool sequence

For documenting a component:

1. get_screenshot — see what the component looks like visually
2. get_metadata — understand the layer structure and find key node IDs
3. get_design_context — pull full design details for the component (or specific child nodes)
4. get_variable_defs — pull associated design tokens/variables

For documenting foundations:

1. get_variable_defs — pull all token definitions
2. get_screenshot — visually verify the token usage

Questioning patterns with Figma context

When you have pulled Figma data, use it to ask informed questions.

Variants

• "I can see your Figma component has these variant properties: {list}. Should we document all of these, or are some internal/deprecated?"
• "There are {N} size variants in Figma. Do you want to walk through each one and describe when to use it?"

Props

• "Figma shows these component properties: {list}. Do these map 1:1 to your code props, or are there differences?"
• "I see a boolean property called {name} in Figma — what does it control?"

Anatomy

• "Based on the Figma layers, this component has these parts: {list}. Does that match how you think about its anatomy?"
• "I see an optional layer called {name} — when is that shown?"

States

• "Figma shows variants for these states: {list}. Are there additional interactive states not captured in Figma?"

Tokens / Variables

• "I pulled these design variables from your component: {list}. Should these be documented as part of the component's token usage?"

Anti-patterns

• Do not dump raw Figma data on the user. Summarise what you found and ask focused questions.
• Do not assume Figma is the source of truth. The code implementation may differ from the design. Always ask.
• Do not auto-generate documentation from Figma. Use it to ask better questions, not to write content.
• Do not request Figma access unprompted. Only use Figma tools when the user provides a URL, selects a node, or asks you to look at their designs.
• Do not overload the user with Figma details. Surface what is relevant to the current section being drafted.
• Do not call get_metadata alone and stop. It only returns structure — always follow up with get_design_context for actual design information.

Output format

When presenting Figma context to the user during drafting:

━━━ Figma Context ━━━

From: {component/frame name} (node {nodeId})

Variants found:
  - Size: sm, md, lg
  - Style: filled, outlined, text
  - State: default, hover, disabled

Properties:
  - label (text)
  - isDisabled (boolean)
  - icon (instance swap)
  - size (variant: sm | md | lg)

Layer structure:
  - Container
    - Icon (optional)
    - Label
    - Trailing icon (optional)

Variables:
  - color-background-layer2: #F5F5F5
  - dimension-200: 16px

━━━

Follow this with questions, not with drafted documentation.