# Figma Requirements From Figma MCP

> ---

- Skill: `222333555/figma-requirements-from-figma-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 222333555/figma-requirements-from-figma-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/222333555/figma-requirements-from-figma-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: 222333555 (https://skillmd.com/u/222333555)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/222333555/figma-requirements-from-figma-mcp

---

---

## name: figma-requirements-from-figma-mcp
description: Generate structured Chinese requirement documents from Figma file URLs using the user-Framelink Figma MCP server. Use when the user provides a Figma link and wants a Markdown requirement specification describing pages, components, interactions, and states.

# Figma 需求文档生成（基于 Framelink Figma MCP）

## 使用时机

- 当用户提供 Figma 文件或页面地址，希望自动生成结构化的中文需求文档（需求说明 / PRD 片段）时。
- 在需求分析、测试范围梳理或开发评估前，需要从设计稿快速产出文字版需求说明时。

## 输入要求

- 必填：至少一个 Figma 文件或页面 URL，例如：
  - `https://www.figma.com/file/<fileKey>/xxx`
  - `https://www.figma.com/design/<fileKey>/xxx?node-id=<nodeId>`
- 可选：用户指定需求文档输出文件路径（相对于项目根目录），例如：
  - `docs/requirements-from-figma.md`
  - 未指定时，**根据 Figma 链接自动生成文件名**（见下方「输出文件名生成规则」），不再统一使用固定路径。

> 约定：默认策略为**覆盖写入**——每次基于 Figma 生成需求文档时，重新写入整个 Markdown 文件。如果用户明确要求“追加”或“多份文档”，可以按用户说明改为在文件尾部追加新的章节，或写入新的文件路径。

### 输出文件名生成规则（用户未指定路径时）

根据用户提供的 Figma URL 生成合适的 Markdown 文件名，写入 `docs/` 目录下：

1. **从 URL 中提取“文件名称”**
  - Figma URL 形如：`https://www.figma.com/file/<fileKey>/<fileName>` 或 `https://www.figma.com/design/<fileKey>/<fileName>?...`  
  - `<fileName>` 为 URL 路径中 fileKey 之后的那一段（可能已 slug 化，如 `My-App-Design`、`login-flow`）。  
  - 若该段存在且非空，用作文件名基础；否则用 `fileKey` 作为后备。
2. **规范化**
  - 将文件名中的空格、`/`、`?`、`#` 等替换为 `-` 或去掉。  
  - 仅保留字母、数字、中文（可选）、连字符、下划线，得到安全且可读的片段（如 `My-App-Design` → `my-app-design` 或保留原样，视实现统一一种风格）。
3. **最终路径**
  - 单 URL：`docs/requirements-<规范化名称>.md`，例如 `docs/requirements-my-app-design.md`。  
  - 多 URL：可为每个 URL 生成一个文件，命名如 `docs/requirements-<名称1>.md`、`docs/requirements-<名称2>.md`；若用户希望合并为一份，则取第一个链接生成的主文件名或用户指定的单一路径。
4. **无法从链接得到可用名称时**
  - 使用后备：`docs/requirements-from-figma.md`（或带 `fileKey`：`docs/requirements-<fileKey>.md`）。

## 总体流程

当用户请求“基于这个 Figma 链接生成需求文档”时，按以下步骤执行：

1. 解析用户输入，提取：
  - Figma URL 列表
  - 可选的输出文件路径
2. 为每个 Figma URL 解析出：
  - `fileKey`（必需）
  - `nodeId`（如 URL 中携带 `node-id` 参数，则一并提取）
3. 通过 `user-Framelink Figma MCP` 调用 `get_figma_data` 获取结构化设计数据。
4. 从返回数据中整理出页面、流程、组件、交互等信息。
5. 按“需求文档模板”组装为中文 Markdown 文档。
6. 将文档写入项目中的目标 Markdown 文件：若用户指定了路径则用该路径，否则按「输出文件名生成规则」根据 Figma 链接生成（如 `docs/requirements-<从链接解析的名称>.md`），并在对话中给出摘要和实际写入的文件路径。

## 调用 MCP 获取 Figma 数据

### 1. 先读取工具描述 JSON

在调用任何 MCP 工具之前，**必须先读取工具 schema**，以确认参数结构与约束。工具描述文件位于（相对于 Cursor 项目工作区）：

- `mcps/user-Framelink_Figma_MCP/tools/get_figma_data.json`
- `mcps/user-Framelink_Figma_MCP/tools/download_figma_images.json`

使用 `Read` 工具读取这些 JSON 文件，理解其：

- `arguments.properties`、`required` 字段
- 参数类型与正则约束（如 `fileKey`、`nodeId` 的格式）

### 2. get_figma_data

- MCP 服务器：`user-Framelink Figma MCP`
- 工具名：`get_figma_data`
- 主要参数（根据工具 JSON）：
  - `fileKey`：字符串，Figma 文件 key，来自 URL 中的 `<fileKey>`；必填。
  - `nodeId`：字符串，可选。如果 URL 带有 `node-id=<nodeId>`，则一并传入，格式类似 `1234:5678` 或 `I5666:180910;1:10515;1:10336`。
  - `depth`：数字，可选。**除非用户明确要求限制层级，否则不要主动设置**，以免遗漏深层节点。

调用示例（伪代码，仅作说明）：

```markdown
- 使用 `CallMcpTool`：
  - `server`: "user-Framelink Figma MCP"
  - `toolName`: "get_figma_data"
  - `arguments`: { "fileKey": "<fileKey>", "nodeId": "<nodeId-如果有>" }
```

返回值中通常包含：

- 页面（Pages）及其下的 Frame / Node 结构
- 组件、组件变体及其属性
- 原型连线（从节点到目标节点、触发方式）
- 文字内容与备注（用于补充业务描述）

### 3. download_figma_images（可选）

仅在**用户明确要求导出截图或图标文件**来辅助说明时使用：

- 工具名：`download_figma_images`
- 关键参数（参考工具 JSON）：
  - `fileKey`：Figma 文件 key
  - `nodes`：要导出的节点数组，每个元素需要至少：
    - `nodeId`：图像节点 ID
    - `fileName`：导出的本地文件名（例如 `login-banner.png`）
  - `localPath`：项目中用于存放图片的绝对目录路径（例如 `e:/myProject/rainaSeries/raina_skills/assets/figma`，由运行环境决定）

在本 Skill 的核心流程中，**不依赖图片下载**，只在用户明确提出“需要图片导出”时再调用。

## 从 Figma 数据整理结构化信息

拿到 `get_figma_data` 的结果后，按以下思路提取信息：

- **页面列表与层级**：
  - 遍历 Figma 文件中的 Pages，记录每个页面的名称、备注。
  - 从 Page 下的 Frame/Artboard 节点中识别关键画板（例如名称包含 `home`、`login`、`flow` 等）。
- **用户流程（原型连线）**：
  - 解析原型交互连接（source → target），按连线顺序组合出主要用户路径。
  - 可根据起始画板或包含“主流程”关键字的画板作为流程入口。
- **组件与状态**：
  - 收集 Component / Component Set 及其变体（如 `default`、`hover`、`disabled`、`error` 等）。
  - 将变体名称映射为“不同状态/尺寸/语义类型”的需求描述。
- **交互规则**：
  - 对每个带交互的节点，提取：
    - 触发方式（点击、悬停、拖拽等）
    - 目标页面/画板
    - 动画或过渡（如可读则用自然语言简述）
- **文案与字段**：
  - 从文本节点、输入占位符、错误提示文本中，推断字段名称、含义、校验规则。
- **备注与说明**：
  - 如果设计中包含 description、comment、注释插件字段，将其整合到对应页面或组件的说明中。

在无法确定业务含义时，可以做**合理推测**，但需要在文中显式标记“（推测）”或放入“待确认事项”列表中。

## 需求文档生成规则

生成的 Markdown 文档统一使用**中文**说明，必要时在括号中保留原始英文命名辅助理解，例如：

- 页面标题：`用户登录页（Login Page）`
- 组件名称：`主按钮组件（Primary Button）`

生成文档的章节结构尽量与 MasterGo 需求文档 Skill 保持一致，便于与文档解析、测试范围等后续环节串联。

## 需求文档模板

生成的 Markdown 文档建议遵循以下结构，可根据具体项目裁剪或扩展章节：

```markdown
# [项目名称] Figma 需求说明

## 1. 概述
- 背景：简要概述本项目/页面的业务背景（根据 Figma 文件名称和用户补充说明推断）。
- 目标：说明本次设计所覆盖的主要目标或用户任务。

## 2. 范围
- 包含范围：列出本次 Figma 中包含的页面/流程。
- 不包含范围：如能从命名或用户说明中判断，可以简单说明暂不覆盖的部分。

## 3. 页面与信息架构

### 3.1 页面 / 模块列表
- 页面 1：[页面名称] — 简要说明用途
- 页面 2：...

### 3.2 主要用户流程
- 流程 A：登录并进入首页
- 流程 B：...

## 4. 详细功能说明

对每个关键页面/画板使用如下结构：

### 4.x [页面名称]
- 入口：用户如何到达此页面（根据原型连线推断）。
- 出口：从此页面可以前往的下一步页面 / 状态。

#### 4.x.1 页面结构
- 区块划分：头部/主体/底部等。
- 关键模块：
  - 模块 A：功能描述。
  - 模块 B：...

#### 4.x.2 交互与状态
- 交互规则：
  - [触发元素] + [操作] → [结果页面 / 状态]。
- 组件状态：
  - 按钮：正常 / hover / disabled / loading。
  - 表单字段：默认 / 校验失败 / 成功。

#### 4.x.3 数据与校验
- 字段列表：字段名、含义、是否必填、校验规则（可从占位文案、错误提示推断）。

## 5. 统一组件与设计规范
- 公共组件：按钮、输入框、弹窗、通知等的行为与文案规则。
- 变体：不同尺寸、语义色（主色 / 警告 / 错误等）、不同状态的表现。

## 6. 非功能性说明（如能从设计中推断）
- 兼容性与响应式（如存在多端或多分辨率画板）。
- 可用性 / 体验要点（例如明显的错误提示、焦点状态、一致的交互反馈等）。

## 7. 待确认事项
- 列出从 Figma 无法明确、需要产品 / 业务补充确认的问题。
```

## 具体执行指引（给智能体）

1. **识别触发场景**
  - 当用户提到“根据 Figma 链接生成需求文档 / PRD / 需求说明”等关键词时，使用此 Skill。
2. **解析用户输入**
  - 收集用户给出的所有 Figma URL 和可选的输出文件路径。
  - 若用户未指定路径，则根据 Figma 链接按「输出文件名生成规则」生成输出路径（例如从 URL 中解析文件名称，得到 `docs/requirements-<名称>.md`），避免所有文档都写进同一固定文件。
3. **获取 Figma 数据**
  - 对每个 URL：
    - 从 URL 中解析出 `fileKey`。
    - 如果存在 `node-id` 参数，则解析为 `nodeId`。
  - 调用 `get_figma_data` 获取结构化数据，并妥善处理可能的错误（如权限不足、fileKey 无效等），必要时向用户说明。
4. **生成需求文档内容**
  - 按“从 Figma 数据整理结构化信息”的规则提取页面、流程、组件、交互、字段等。
  - 按“需求文档模板”组织为 Markdown 内容。
  - 对于无法确定的业务规则，用“待确认事项”章节列出，并在正文中避免当作确定事实来表述。
5. **写入项目文件**
  - 确定输出路径：用户指定则用指定路径；未指定则根据 Figma URL 生成（见「输出文件名生成规则」），例如 `docs/requirements-<从链接解析的名称>.md`。
  - 在项目根目录下定位或创建 `docs` 目录（如需要时可提示用户确认该目录结构）。  
  - 将生成的 Markdown 内容写入目标文件：
    - 默认行为：覆盖写入整个文件。
    - 如用户要求“追加”，则在原内容后追加一整段新需求章节（例如按日期或 Figma 文件名分段）。
6. **结果反馈**
  - 在对话中返回：
    - 实际写入的文件路径（即根据链接生成或用户指定的路径）。
    - 文档的目录结构（各章节标题）。
    - 关键功能或流程的简要列表，帮助用户快速确认内容大致正确。

## 实施要点与注意事项

- **语言**：除保留 Figma 对象原名外，说明性文字一律使用中文。
- **稳健性**：
  - 当 Figma 数据缺失或结构不清晰时，一律在“待确认事项”中标记。
  - 不要凭空编造具体业务规则，只能在合理的范围内做“推测”，并标注为“（推测）”。
- **性能**：
  - 对于非常大的 Figma 文件，可以只聚焦主流程页面，例如名称包含 `main`、`home`、`flow`、`用户流程` 等关键字的画板。
  - 当用户明确指定只关心某些页面或节点时，优先按用户要求过滤。

## 可扩展方向（非必需）

- 支持根据标签或命名约定，只生成特定端（Web、移动端等）的需求文档。
- 与 `requirement-test-scope`、测试用例生成类 Skill 串联，实现从“设计 → 需求 → 测试”的自动链路。