用途
Figma to React Components 用于将 Figma 组件设计转换为生产就绪的 React 组件，集成设计令牌、通过 React Aria 提供无障碍支持，并生成完整文档。它可与任意设计令牌系统配合使用，包括 SCSS 变量、CSS 自定义属性、Tailwind 或 JavaScript 令牌。
前提条件
- Figma MCP：需配置并运行 Figma MCP 服务器。
- React Aria：需安装 react-aria 与 react-stately。
- 设计令牌（可选）：若项目已有令牌系统（SCSS、CSS 变量、Tailwind、JS/TS），则映射到该系统；若没有，则从 Figma 提取令牌并在工作流中生成。
- Storybook（可选）：用于组件文档和可视化测试。
项目配置发现
首次在项目中使用时，先搜索代码库以确定：令牌导入路径（SCSS、CSS、Tailwind、JS/TS 各自的导入方式）、组件输出目录、故事目录、样式方案（SCSS modules、CSS modules、Tailwind 工具类、styled-components 等）、图标/资源策略。若不存在令牌文件，则从 Figma 提取令牌并在第二阶段生成，届时询问用户生成格式（SCSS、CSS 自定义属性或 Tailwind）与保存位置。这些发现结果会在会话期间缓存；若不确定任何设置，应在生成代码前询问用户。
工作流程
按顺序执行以下阶段：
第一阶段：提取 Figma 设计上下文
使用 Figma MCP 工具收集组件信息，包括 get_design_context（组件结构与令牌）、get_variable_defs（用于令牌映射的变量定义）、get_screenshot（视觉参考）。需要提取的内容有：组件结构与层级、已应用的变量/令牌（颜色、间距、排版）、变体属性（尺寸、状态、层级）、交互状态（悬停、按下、禁用、聚焦）、文本样式及其令牌映射、布局约束与间距值、图标与图像填充。
第二阶段：映射设计令牌
若项目已有令牌：通过 references/token-mapping-guide.md 将 Figma 变量与项目令牌系统交叉引用。若项目没有令牌文件：直接从 Figma 提取并生成令牌文件。流程为：使用 get_variable_defs 拉取 Figma 文件中全部变量集合；询问用户偏好的格式（SCSS、CSS 自定义属性或 Tailwind）与输出目录；使用语义化命名约定生成有组织的令牌文件（颜色、间距、排版、圆角、海拔）；创建导入所有令牌分片的索引/桶文件；然后继续将组件值映射到新生成的令牌。需映射（或生成）的令牌类别包括颜色（背景、文本、边框、图标）、间距（内边距、外边距、间隙）、排版（字体系列、字号、字重、行高）、边框圆角、海拔/阴影、组件尺寸（高度、宽度、图标尺寸）。重要：使用项目的令牌变量名，绝不使用原始值。
第三阶段：生成 Props 文档
按照 references/props-template.md 创建 Props 文档。必需章节包括：概述（最多 200 字符）、组件属性（Props 表 + React Aria 属性表）、尺寸变体（使用排版令牌名）、层级变体、状态变体（默认、悬停、按下、禁用、聚焦）、图标（图标尺寸的令牌引用）、排版（来自 Figma 描述的令牌名）、无障碍（聚焦状态、键盘导航、禁用状态、颜色对比度）、使用指南。Prop 命名遵循 references/figma-property-conventions.md。
第四阶段：生成 React 组件代码
遵循 references/component-patterns.md 创建组件。要求：使用 React Aria hooks 实现无障碍；使用 TypeScript 并显式声明 prop 接口；CSS 类采用 BEM 命名约定；正确的禁用状态处理；使用 :focus-visible 进行聚焦管理；props 应基于实际 Figma MCP 提取结果而非假设来构建。
第五阶段：生成样式
使用项目令牌系统创建样式表。结构包括：从发现的项目路径导入令牌、使用令牌引用的基础样式、状态修饰符（:hover、:active、:disabled、:focus-visible）、尺寸变体修饰符、层级/变体修饰符。使用语义化令牌名。
第六阶段：创建 Storybook 故事
生成展示所有变体的 Storybook 文档：带主要 args 的默认故事、并排的尺寸变体、层级/视觉变体、状态演示（默认、禁用），并包含 React Aria 属性控件（aria-label、aria-labelledby、aria-describedby）。
第七阶段：测试与验证
实现后验证：与 Figma 设计进行视觉比较（容差 2px 以内）、所有变体正确渲染、交互状态（悬停、聚焦、按下、禁用）按预期工作、键盘导航正常、无剩余硬编码值（所有视觉属性均使用令牌）。
第八阶段：清理垃圾文件
Figma MCP 有时在提取期间生成临时文件，需移除 Figma MCP 生成的根级 SVG 文件、不在项目资源目录中的临时图像，并确认没有来自 MCP 提取过程的孤立文件。
输出结构
按以下顺序交付所有产物：
- Props 文档（[ComponentName]-props.md）：所有令牌按变量名引用；完整的无障碍文档。
- React 组件（[ComponentName].tsx）：TypeScript 完整类型安全；React Aria 集成；无内联 SVG 代码，使用项目图标库。
- 样式（[ComponentName].[scss|module.scss|css]）：基于令牌的样式；BEM 方法论；所有状态变体。
- Storybook 故事（[ComponentName].stories.tsx）：带 React Aria 属性的交互示例；展示所有变体。
示例
正向触发：用户说「把这个 Figma 按钮组件连同所有变体和状态转换为 React」。预期行为：使用 figma-to-react-components 指引，通过 MCP 提取 Figma 上下文、映射令牌、生成带 React Aria 的类型化 React 组件、使用项目令牌创建样式并生成 Storybook 故事。
非触发：用户说「为这个支付服务编写单元测试」。预期行为：不应优先使用 figma-to-react-components，应选择更相关的技能或直接处理。
故障排除
Figma 令牌未找到：错误为 Figma 变量未映射到任何项目令牌。原因可能是 Figma 中的令牌变量名与项目令牌名不同、令牌文件位置异常或项目尚无令牌文件。解决：先搜索代码库中的令牌文件；若找到，使用 references/token-mapping-guide.md 将 Figma 变量名映射到项目令牌名；若无令牌文件，使用 get_variable_defs 从 Figma 提取令牌并生成令牌文件。
React Aria Hook 选择不明确：错误为不确定给定组件应使用哪个 React Aria hook。原因是组件类型不匹配标准模式（Button、TextField、Select 等）。解决：查看 rules/aria-use-react-aria-hooks.md 中的 React Aria hooks 表；对于复杂组件，组合多个 hooks 或以 useFocusRing 作为基线。
生成的样式使用原始值：错误为组件样式包含硬编码像素值或十六进制颜色而非令牌。原因是第二阶段跳过了令牌映射或不完整。解决：针对项目令牌系统重新执行令牌映射，将每个原始值替换为令牌引用；若不存在令牌，用 /* TODO */ 注释标记为缺口。
组件 Props 与 Figma 不匹配：错误为生成的 React props 与 Figma 组件属性不一致。原因是 props 是假设的而非从 Figma MCP 提取的。解决：使用 get_design_context 重新提取，并基于实际 Figma 组件定义重建 props，遵循 references/figma-property-conventions.md 中的命名约定。
工作流要点
识别请求是否匹配 Figma 转 React 转换任务；遵循八阶段工作流（提取设计上下文、映射令牌、生成 props 文档、构建组件、创建样式、编写故事、验证、清理）；确认所有输出使用项目令牌（无硬编码值）并包含 React Aria 无障碍支持。