/using-figma

name: using-figma
description: Read and inspect Figma designs via the Dev Mode MCP server — selects the right tool, parses Figma URLs into fileKey and nodeId, and turns design context into useful input for critique, copy review, handoff prep, and Design System work.
when_to_use: Use when a task reads design context from Figma without generating production code or modifying Figma state. Triggers — Figma URL shared, "look at this design", "extract tokens from Figma", "what variables does this use", "what's in this Figma file", "compare these two Figma frames", "inspect this component". Not for framework-bound code generation (use `figma-to-angular` in the clients repo, external — not bundled), and not for Figma mutations (this skill's `allowed-tools` is read-only).
allowed-tools: Skill, mcp__figma__get_design_context, mcp__figma__get_metadata, mcp__figma__get_screenshot, mcp__figma__get_variable_defs, mcp__figma__get_libraries, mcp__figma__search_design_system, mcp__figma__get_figjam, mcp__figma__whoami, mcp__figma__get_code_connect_map, mcp__figma__get_code_connect_suggestions, mcp__figma__get_context_for_code_connect

Using Figma via the Dev Mode MCP Server

This skill grounds the designer in the Figma Dev Mode MCP server — Figma's official MCP that exposes design context, variables, screenshots, metadata, and design-system search to Claude. Apply it whenever a task needs to _read_ a Figma design — extract structure, tokens, screenshots, or strings. Composing skills like `design-review`, `content-style-guide`, `preparing-design-handoff`, and `evolving-design-system-components` call into here whenever a Figma file is referenced.

The Figma MCP server also exposes write tools (creating files, uploading assets, generating diagrams, mapping Code Connect, mutating Figma objects). Those are intentionally **out of scope** for this skill — its `allowed-tools` is read-only. If a task genuinely needs a Figma mutation, invoke the underlying MCP tool directly with explicit user consent rather than extending this skill's surface.

Prerequisite: the MCP server must be installed

The Figma Dev Mode MCP server is not bundled with this plugin. It is Figma's own product and the user installs and authenticates it themselves — either the desktop server (which requires a Dev or Full seat on a paid Figma plan) or the remote server. If the Figma MCP tools are not available in the session, stop and tell the user to install and authenticate the Figma MCP server before continuing.

Some MCP tools are remote-only and unavailable on the desktop server; check Figma's docs when a tool isn't where you expect it. Detailed setup notes live in `references/setup.md`.

Anatomy of a Figma URL

Every interaction starts from a Figma URL. The two pieces that matter are the **fileKey** and the **nodeId**.

https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeIdWithDashes>&...

Conversion: the URL's node-id uses `-` as the separator (`123-456`), but the MCP server expects `:` (`123:456`). Convert before passing it into a tool.

If the user pastes a URL without a `node-id`, the URL points at the whole file. Ask which frame they mean before extracting anything — operating on the whole file is rarely what's wanted and returns far too much context.

The read tools, by job to be done

The Figma MCP server exposes many tools. Pick the smallest one that answers the question.

| Job to be done | Tool | Notes | | ------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------- | | Read a frame's design context (code + screenshot + metadata) | `get_design_context` | Most common entry point. Accepts a framework parameter; defaults to React + Tailwind. | | Get just the structural outline | `get_metadata` | Sparse XML of layer IDs, names, types, positions, sizes. Cheap. | | Get just the rendered image | `get_screenshot` | Visual reference without the code or token noise. | | Extract design tokens used in selection | `get_variable_defs` | Variables and styles — colors, spacing, typography. | | Discover available libraries on the file | `get_libraries` | Shows which subscribed/available design libraries are linked. | | Find a component in the design system | `search_design_system` | Text query against components, variables, styles. | | Inspect a FigJam board | `get_figjam` | Same role as `get_metadata` but for FigJam content. | | Identify the authenticated Figma user | `whoami` | Useful when permission / seat type matters. |

Code Connect tools (read-only)

These map Figma components to their code counterparts. Mostly relevant inside `evolving-design-system-components`; rarely needed for critique or copy review.

• `get_code_connect_map` — returns existing mappings, source files, and snippets for selected

instances.

• `get_code_connect_suggestions` — suggested mappings for selected components.
• `get_context_for_code_connect` — property definitions and variant options for a component.

(The two write Code Connect tools — `add_code_connect_map` and `send_code_connect_mappings` — are out of scope for this skill. Invoke them directly with explicit user consent if needed.)

Decision rules

• **Don't reach for `get_design_context` by reflex.** It returns code and screenshots even when

the question