using-figma

通过 Dev Mode MCP 服务使用 Figma

此技能可帮助设计师了解 Figma Dev Mode MCP 服务——这是 Figma 官方的 MCP，可向 Claude 提供设计上下文、变量、截图、元数据和设计系统搜索功能。凡是需要读取 Figma 设计的任务——提取结构、令牌、截图或字符串——都应使用此技能。组合技能（例如 design-review、content-style-guide、preparing-design-handoff 和 evolving-design-system-components）在引用 Figma 文件时都会调用此技能。

Figma MCP 服务也提供写入工具（创建文件、上传资源、生成图表、映射 Code Connect、修改 Figma 对象）。这些操作有意不在此技能的范围内——其 allowed-tools 仅限读取。如果任务确实需要修改 Figma，请在获得用户明确同意后直接调用底层 MCP 工具，而不是扩展此技能的功能范围。

前提条件：必须先安装 MCP 服务

Figma Dev Mode MCP 服务并未随此插件捆绑提供。它是 Figma 自有产品，用户需要自行安装并完成身份验证——可以安装桌面服务（这要求拥有付费 Figma 套餐中的 Dev 或 Full 席位），也可以使用远程服务。如果当前会话中没有可用的 Figma MCP 工具，请停止操作，并告知用户先安装并完成 Figma MCP 服务的身份验证，再继续。

部分 MCP 工具仅适用于远程服务，在桌面服务上不可用；如果找不到预期的工具，请查阅 Figma 文档。详细的设置说明请参阅 references/setup.md。

Figma URL 的结构

每次交互都从 Figma URL 开始。两个关键部分是 fileKey 和 nodeId。

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

转换：URL 中的 node-id 使用 - 作为分隔符（123-456），但 MCP 服务需要使用 :（123:456）。传入工具前请先转换。

如果用户粘贴的 URL 不含 node-id，则该 URL 指向整个文件。提取任何内容前，请询问用户指的是哪个画框——对整个文件进行操作通常并非用户所需，而且会返回过多上下文。

按任务选择读取工具

Figma MCP 服务提供许多工具。请选择能解答问题的最精简工具。

任务	工具	说明
读取画框的设计上下文（代码 + 截图 + 元数据）	get_design_context	最常见的入口。接受框架参数；默认为 React + Tailwind。
仅获取结构大纲	get_metadata	包含图层 ID、名称、类型、位置和尺寸的精简 XML。开销低。
仅获取渲染后的图像	get_screenshot	提供视觉参考，不包含代码或令牌噪声。
提取所选内容中使用的设计令牌	get_variable_defs	变量和样式——颜色、间距、排版。
发现文件中可用的库	get_libraries	显示已关联的订阅库或可用设计库。
在设计系统中查找组件	search_design_system	按文本查询组件、变量和样式。
检查 FigJam 白板	get_figjam	功能与 get_metadata 相同，但用于 FigJam 内容。
确认已通过身份验证的 Figma 用户	whoami	在权限或席位类型很重要时很有用。

Code Connect 工具（只读）

这些工具用于将 Figma 组件映射到对应的代码。主要适用于 evolving-design-system-components；很少用于设计评审或文案审查。

• get_code_connect_map — 返回所选实例的现有映射、源文件和代码片段。
• get_code_connect_suggestions — 为所选组件推荐映射。
• get_context_for_code_connect — 返回组件的属性定义和变体选项。

（两个用于写入的 Code Connect 工具 — add_code_connect_map 和 send_code_connect_mappings — 不属于此技能的范围。如有需要，请在获得用户明确同意后直接调用。）

决策规则

• 不要不假思索地调用 get_design_context。 即使问题只是“这个背景是什么颜色”，它也会返回代码和屏幕截图，而 get_variable_defs 只需一小部分上下文就能回答。
• 先用 get_metadata 了解概况。 当目标是“告诉我这个 画面中有什么”时，元数据 XML 的开销低于完整上下文，通常也足以决定下一步操作。
• 用 get_screenshot 供人参考，用 get_metadata 进行机器推理。 除非两者都必需，否则不要 同时加载。
• 不要用此技能生成代码。 生产代码生成应由特定代码库的输出技能负责，例如客户端代码库中的 figma-to-angular。此技能仅提取设计上下文。

与其他技能配合使用

• design-review。 评审设计时，先用 get_screenshot + get_metadata 了解概况。如果评审涉及设计令牌（非系统颜色、不一致的间距），则调用 get_variable_defs。只有在问题涉及代码结构本身时，才升级到 get_design_context。
• content-style-guide。 使用 get_design_context 或 get_metadata 找出画面中的所有 用户可见文本，然后根据风格指南逐条检查。不要在此技能中改写 Figma 文案 — 返回问题和建议替代方案， 由设计师自行应用。
• preparing-design-handoff。 使用 get_metadata 确认文件包含预期的 Ready-for-Dev 部分，且其名称与工程任务一致。使用 get_variable_defs 确认设计令牌绑定到库，而不是原始十六进制值。
• evolving-design-system-components。 提出新模式前，先使用 search_design_system 和 get_libraries — 大多数“我们需要这个新东西”的情况，最后都会发现“库里已经有了，只是我们不知道”。如果问题涉及 Figma 组件如何映射到对应代码，请使用 Code Connect 只读工具。

提取前征求用户同意

提取前，说明你准备请求哪些内容以及原因：

“我会先对该画面调用 get_metadata，查看图层结构，然后调用 get_variable_defs 查看它使用的设计令牌 — 无需加载完整设计上下文，应该就能回答间距问题。可以吗？”

这比事后为范围过广的调用道歉更快，也能帮助设计师了解哪种 MCP 工具可以回答他们的问题。

Figma 提取结果的输出格式

报告 Figma 文件中的内容时，按以下结构组织回复：

1. 画面和阶段 — 文件名、画面名称，以及已知时的阶段（30/60/90）。
2. 结构 — 与问题相关层级的图层大纲（不要粘贴原始 XML）。
3. 设计令牌和库绑定 — 哪些绑定到设计系统，哪些是原始值。
4. 用户可见文本（任务涉及文案时）— 标注 content-style-guide 的检查结果。
5. 待解决问题 — 文件中任何不明确之处，设计师应在工作继续前予以确认。

其他资源

• references/setup.md — 安装和验证 Figma Dev Mode MCP 服务 （桌面版与远程版）、席位类型要求，以及工具不可用时的故障排除。
• Figma 的权威工具参考： developers.figma.com/docs/figma-mcp-server/tools-and-prompts/ — 工具参数、返回结构以及桌面版与远程版可用性的权威来源。