figma-plan

Figma Plan — 设计数据采集与存储

Overview

从 Figma MCP 采集设计数据并结构化存储。本 skill 的产出物是 figma-context.md + 截图 + 已下载资产，后续实现阶段不需要再访问 Figma MCP。

Prerequisites

• Figma MCP server must be connected and accessible
• User must provide a Figma URL in the format: https://figma.com/design/:fileKey/:fileName?node-id=1-2
  • :fileKey is the file key
  • 1-2 is the node ID (the specific component or frame to implement)
• OR when using figma-desktop MCP: User can select a node directly in the Figma desktop app (no URL required)

如果缺少 Figma URL，且当前运行环境不能读取 Figma Desktop 选中节点，先用 AskUserQuestion 要链接或让用户选中节点。

Skill Boundaries

• Use this skill when the task is to collect and store Figma design data for downstream implementation.
• If the user asks to create/edit/delete nodes inside Figma itself, switch to figma-use.
• If the user asks to build or update a full-page screen in Figma from code or a description, switch to figma-generate-design.
• If the user asks only for Code Connect mappings, switch to figma-code-connect-components.

Required Workflow

Follow these steps in order. Do not skip steps.

Step 1: Get Node ID

Option A: Parse from Figma URL

When the user provides a Figma URL, extract the file key and node ID to pass as arguments to MCP tools.

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

Extract:

• File key: :fileKey (the segment after /design/)
• Node ID: 1-2 (the value of the node-id query parameter)

Note: When using the local desktop MCP (figma-desktop), fileKey is not passed as a parameter to tool calls. The server automatically uses the currently open file, so only nodeId is needed.

Example:

• URL: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15
• File key: kL9xQn2VwM8pYrTb4ZcHjF
• Node ID: 42-15

Option B: Use Current Selection from Figma Desktop App (figma-desktop MCP only)

When using the figma-desktop MCP and the user has NOT provided a URL, the tools automatically use the currently selected node from the open Figma file in the desktop app.

Note: Selection-based prompting only works with the figma-desktop MCP server. The remote server requires a link to a frame or layer to extract context. The user must have the Figma desktop app open with a node selected.

Step 2: Fetch Design Context

Run get_design_context with the extracted file key and node ID.

get_design_context(fileKey=":fileKey", nodeId="1-2")

This provides the structured data including:

• Layout properties (Auto Layout, constraints, sizing)
• Typography specifications
• Color values and design tokens
• Component structure and variants
• Spacing and padding values

If the response is too large or truncated:

1. Run get_metadata(fileKey=":fileKey", nodeId="1-2") to get the high-level node map
2. Identify the specific child nodes needed from the metadata
3. Fetch individual child nodes with get_design_context(fileKey=":fileKey", nodeId=":childNodeId")

Step 3: Capture Visual Reference

Run get_screenshot with the same file key and node ID for a visual reference.

get_screenshot(fileKey=":fileKey", nodeId="1-2")

This screenshot serves as the source of truth for visual validation.

Step 4: Download Required Assets

Download any assets (images, icons, SVGs) returned by the Figma MCP server.

IMPORTANT: Follow these asset rules:

• If the Figma MCP server returns a localhost source for an image or SVG, download it and save to output_dir/attachments/
• DO NOT import or add new icon packages - all assets should come from the Figma payload
• DO NOT use or create placeholders if a source is provided
• Assets are served through the Figma MCP server's built-in assets endpoint — download and persist them, because the execute phase may not have MCP access

Step 5: Scan Existing Project Components

在写入 figma-context.md 之前，必须先扫描项目中已有的公共组件，避免下游实现阶段重复造轮子。

执行方式：

1. 用 Glob 和 Grep 扫描项目中的公共组件目录（常见路径：src/components/, src/ui/, src/common/, src/shared/, lib/components/, packages/ui/, design-system/ 等）。如果项目结构不明确，先读取项目根目录的 README、package.json、或框架配置文件确定组件目录
2. 对 Step 2 获取的设计数据中出现的每种 UI 元素（按钮、输入框、卡片、弹窗、导航栏、图标、标签、表格等），在项目中搜索是否已有对应的公共组件
3. 整理出 可复用组件清单 和 需新建组件清单

产出格式（写入 figma-context.md）：

## Existing Project Components

### 可直接复用
| Figma 元素 | 项目组件 | 文件路径 | 说明 |
|-----------|---------|---------|------|
| Button / Primary | AppButton | src/components/AppButton.tsx | 已有 primary variant |

### 需新建
| Figma 元素 | 原因 |
|-----------|------|
| StatsCard | 项目中无类似卡片组件 |

原则：

• 只要项目里有功能相近的组件，就标记为可复用，即使 props 需要扩展
• 如果现有组件缺少设计稿要求的 variant/状态，标注"可扩展"而不是"需新建"
• 宁可多标一个可复用组件，也不要遗漏——下游实现阶段会做最终判断

产出物存储

figma-context.md

将 get_design_context 的完整返回内容写入 output_dir/figma-context.md。这是设计数值的 ground truth——所有 layout、typography、color、spacing、token、component structure 都在里面，零转录。格式：

---
figma-file-key: {fileKey}
figma-node-id: {nodeId}
figma-url: {原始 URL}
---

## Figma Design Context

{get_design_context 的完整返回内容，原样保存，不做任何改写或摘要}

截图

将 get_screenshot 的截图保存到 output_dir/attachments/，在 figma-context.md 顶部用 ![[attachments/figma-screenshot.png]] 嵌入。

资产

将 Step 4 下载的资产保存到 output_dir/attachments/，在 figma-context.md 中记录资产清单和本地路径。

Examples

Example 1: Collecting a Button Component

User says: "Plan implementation for this Figma button: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"

Actions:

1. Parse URL to extract fileKey=kL9xQn2VwM8pYrTb4ZcHjF and nodeId=42-15
2. Run get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")
3. Run get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15") for visual reference
4. Download any button icons from the assets endpoint to attachments/
5. Write figma-context.md with full design context data
6. Save screenshot to attachments/figma-screenshot.png

Result: figma-context.md + screenshot + assets ready for downstream implementation.

Example 2: Collecting a Dashboard Layout

User says: "Plan this dashboard: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5"

Actions:

1. Parse URL to extract fileKey=pR8mNv5KqXzGwY2JtCfL4D and nodeId=10-5
2. Run get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5") to understand the page structure
3. Identify main sections from metadata (header, sidebar, content area, cards) and their child node IDs
4. Run get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId") for each major section
5. Run get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5") for the full page
6. Download all assets (logos, icons, charts) to attachments/
7. Write figma-context.md with all collected design context data

Result: Complete design data captured for downstream implementation.

Common Issues

Issue: Figma output is truncated

Cause: The design is too complex or has too many nested layers to return in a single response. Solution: Use get_metadata to get the node structure, then fetch specific nodes individually with get_design_context.

完成条件

• figma-context.md 已生成且包含完整的 get_design_context 返回内容
• 截图已保存到 attachments/
• 资产已下载到 attachments/
• 资产路径有效

Additional Resources

• Figma MCP Server Documentation
• Figma MCP Server Tools and Prompts
• Figma Variables and Design Tokens