222333555 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>/xxxhttps://www.figma.com/design/<fileKey>/xxx?node-id=<nodeId>
- 可选：用户指定需求文档输出文件路径（相对于项目根目录），例如：
docs/requirements-from-figma.md- 未指定时，根据 Figma 链接自动生成文件名（见下方「输出文件名生成规则」），不再统一使用固定路径。
约定：默认策略为覆盖写入——每次基于 Figma 生成需求文档时，重新写入整个 Markdown 文件。如果用户明确要求“追加”或“多份文档”，可以按用户说明改为在文件尾部追加新的章节，或写入新的文件路径。
输出文件名生成规则（用户未指定路径时）
根据用户提供的 Figma URL 生成合适的 Markdown 文件名，写入 docs/ 目录下：
- 从 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作为后备。
- 规范化
- 将文件名中的空格、
/、?、#等替换为-或去掉。 - 仅保留字母、数字、中文（可选）、连字符、下划线，得到安全且可读的片段（如
My-App-Design→my-app-design或保留原样，视实现统一一种风格）。
- 最终路径
- 单 URL：
docs/requirements-<规范化名称>.md，例如docs/requirements-my-app-design.md。 - 多 URL：可为每个 URL 生成一个文件，命名如
docs/requirements-<名称1>.md、docs/requirements-<名称2>.md；若用户希望合并为一份，则取第一个链接生成的主文件名或用户指定的单一路径。
- 无法从链接得到可用名称时
- 使用后备：
docs/requirements-from-figma.md（或带fileKey：docs/requirements-<fileKey>.md）。
总体流程
当用户请求“基于这个 Figma 链接生成需求文档”时，按以下步骤执行：
- 解析用户输入，提取：
- Figma URL 列表
- 可选的输出文件路径
- 为每个 Figma URL 解析出：
fileKey（必需）nodeId（如 URL 中携带node-id参数，则一并提取）
- 通过
user-Framelink Figma MCP调用get_figma_data获取结构化设计数据。 - 从返回数据中整理出页面、流程、组件、交互等信息。
- 按“需求文档模板”组装为中文 Markdown 文档。
- 将文档写入项目中的目标 Markdown 文件：若用户指定了路径则用该路径，否则按「输出文件名生成规则」根据 Figma 链接生成（如
docs/requirements-<从链接解析的名称>.md），并在对话中给出摘要和实际写入的文件路径。
调用 MCP 获取 Figma 数据
1. 先读取工具描述 JSON
在调用任何 MCP 工具之前，必须先读取工具 schema，以确认参数结构与约束。工具描述文件位于（相对于 Cursor 项目工作区）：
mcps/user-Framelink_Figma_MCP/tools/get_figma_data.jsonmcps/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：数字，可选。除非用户明确要求限制层级，否则不要主动设置，以免遗漏深层节点。
调用示例（伪代码，仅作说明）：
- 使用 `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 文件 keynodes：要导出的节点数组，每个元素需要至少：nodeId：图像节点 IDfileName：导出的本地文件名（例如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等）。 - 将变体名称映射为“不同状态/尺寸/语义类型”的需求描述。
- 收集 Component / Component Set 及其变体（如
- 交互规则：
- 对每个带交互的节点，提取：
- 触发方式（点击、悬停、拖拽等）
- 目标页面/画板
- 动画或过渡（如可读则用自然语言简述）
- 对每个带交互的节点，提取：
- 文案与字段：
- 从文本节点、输入占位符、错误提示文本中，推断字段名称、含义、校验规则。
- 备注与说明：
- 如果设计中包含 description、comment、注释插件字段，将其整合到对应页面或组件的说明中。
在无法确定业务含义时，可以做合理推测，但需要在文中显式标记“（推测）”或放入“待确认事项”列表中。
需求文档生成规则
生成的 Markdown 文档统一使用中文说明，必要时在括号中保留原始英文命名辅助理解，例如：
- 页面标题：
用户登录页（Login Page） - 组件名称：
主按钮组件（Primary Button）
生成文档的章节结构尽量与 MasterGo 需求文档 Skill 保持一致，便于与文档解析、测试范围等后续环节串联。
需求文档模板
生成的 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 无法明确、需要产品 / 业务补充确认的问题。
具体执行指引（给智能体）
- 识别触发场景
- 当用户提到“根据 Figma 链接生成需求文档 / PRD / 需求说明”等关键词时，使用此 Skill。
- 解析用户输入
- 收集用户给出的所有 Figma URL 和可选的输出文件路径。
- 若用户未指定路径，则根据 Figma 链接按「输出文件名生成规则」生成输出路径（例如从 URL 中解析文件名称，得到
docs/requirements-<名称>.md），避免所有文档都写进同一固定文件。
- 获取 Figma 数据
- 对每个 URL：
- 从 URL 中解析出
fileKey。 - 如果存在
node-id参数，则解析为nodeId。
- 从 URL 中解析出
- 调用
get_figma_data获取结构化数据，并妥善处理可能的错误（如权限不足、fileKey 无效等），必要时向用户说明。
- 生成需求文档内容
- 按“从 Figma 数据整理结构化信息”的规则提取页面、流程、组件、交互、字段等。
- 按“需求文档模板”组织为 Markdown 内容。
- 对于无法确定的业务规则，用“待确认事项”章节列出，并在正文中避免当作确定事实来表述。
- 写入项目文件
- 确定输出路径：用户指定则用指定路径；未指定则根据 Figma URL 生成（见「输出文件名生成规则」），例如
docs/requirements-<从链接解析的名称>.md。 - 在项目根目录下定位或创建
docs目录（如需要时可提示用户确认该目录结构）。 - 将生成的 Markdown 内容写入目标文件：
- 默认行为：覆盖写入整个文件。
- 如用户要求“追加”，则在原内容后追加一整段新需求章节（例如按日期或 Figma 文件名分段）。
- 结果反馈
- 在对话中返回：
- 实际写入的文件路径（即根据链接生成或用户指定的路径）。
- 文档的目录结构（各章节标题）。
- 关键功能或流程的简要列表，帮助用户快速确认内容大致正确。
实施要点与注意事项
- 语言：除保留 Figma 对象原名外，说明性文字一律使用中文。
- 稳健性：
- 当 Figma 数据缺失或结构不清晰时，一律在“待确认事项”中标记。
- 不要凭空编造具体业务规则，只能在合理的范围内做“推测”，并标注为“（推测）”。
- 性能：
- 对于非常大的 Figma 文件，可以只聚焦主流程页面，例如名称包含
main、home、flow、用户流程等关键字的画板。 - 当用户明确指定只关心某些页面或节点时，优先按用户要求过滤。
- 对于非常大的 Figma 文件，可以只聚焦主流程页面，例如名称包含
可扩展方向（非必需）
- 支持根据标签或命名约定，只生成特定端（Web、移动端等）的需求文档。
- 与
requirement-test-scope、测试用例生成类 Skill 串联，实现从“设计 → 需求 → 测试”的自动链路。