资源描述
一款面向前端工程师的高效设计-开发协同工作流：通过 Figma 插件导出设计元数据，结合 LLM（如 Claude 或 GPT）自动生成符合最佳实践的 TypeScript + Tailwind React 组件、JSDoc 注释及 Storybook CSF v3 演示文件，并自动同步 Props 文档至 Storybook Canvas 和 Docs tab。适用于设计系统建设、组件库快速迭代与跨职能团队协作。
详细内容
# Figma → React Component Generator with Storybook Sync 工作流指南
## 工作流概述
本工作流实现从 Figma 设计稿到可维护、可测试、可文档化的 React 组件的端到端自动化生成。核心链路为：Figma 插件提取图层结构与属性 → 本地/云端 LLM 解析语义并生成代码 → 脚本自动注入组件文件、Storybook CSF 文件及 JSDoc → 同步更新 Storybook 的 Props 表与交互式文档。全程无需手动编写 props 接口或 Story 示例，显著降低设计还原偏差与重复劳动。
## 分步骤操作说明
### 步骤 1：安装并配置 Figma 插件
- 在 Figma 社区插件市场搜索并安装 `Figma React Exporter`（官方配套插件）
- 打开目标设计文件，选中需导出的组件（支持 Frame / Component Set），运行插件
- 设置导出选项：启用 `Include Variants`、`Export Text Styles as Tokens`、`Preserve Layout Hierarchy`，输出格式选择 `JSON (React Schema)`
- 点击「Export」生成 `component.json` 并保存至项目 `./design/` 目录
### 步骤 2：准备本地 LLM 推理环境
- 确保已安装 Node.js ≥18.17 及 Python ≥3.10（用于部分 LLM 本地运行时）
- 运行 `npm install -D @figma-react-gen/cli`（或克隆仓库后执行 `pnpm install`）
- 配置 `.env`：设置 `LLM_PROVIDER=claude` 或 `LLM_PROVIDER=openai`，并填入对应 API KEY 与 `MODEL_NAME=claude-3-5-sonnet-20240620`（推荐）
- 可选：在 `config/generation.config.ts` 中定制组件命名规则、Tailwind 响应式断点映射及禁用默认样式重置
### 步骤 3：执行组件代码生成
- 在项目根目录运行命令：`npx @figma-react-gen/cli generate --input ./design/component.json --output ./src/components/Button`
- CLI 将解析 JSON 中的 `name`、`variants`、`properties`（如 `size`, `variant`, `disabled`）、`textStyles` 和 `constraints`，调用 LLM 生成：
- `Button.tsx`（含泛型 Props 接口、useMemo 优化、Tailwind 动态类组装）
- `Button.stories.tsx`（CSF v3 格式，含 argsType、play function 及 canvas-only controls）
- `Button.types.ts`（导出独立 Props 类型定义）
- `Button.md`（Markdown 文档片段，含设计意图说明与使用约束）
### 步骤 4：自动注入 Storybook 并同步 Props 文档
- 运行 `npx @figma-react-gen/cli sync-storybook --component-path ./src/components/Button`
- 脚本将：
- 更新 `.storybook/preview.ts` 的 `argTypes` 自动注册逻辑（基于 JSDoc `@param` 和 `@default`）
- 在 `Button.stories.tsx` 中注入 `docs: { page: () => <ButtonDocs /> }` 并生成 `ButtonDocs.mdx`（含 Props 表、设计规范引用链接、Figma 原稿截图嵌入）
- 触发 Storybook 的 `--quiet` 模式热重载，确保 Canvas 与 Docs Tab 实时一致
### 步骤 5：验证与提交
- 启动 Storybook：`npm run storybook`，检查：
- 所有变体（Primary/Secondary, Small/Medium/Large）是否正确渲染
- Controls 面板是否完整映射 JSON 中定义的 `properties`，且默认值匹配设计稿
- Docs Tab 中 Props 表字段类型（`string | boolean | 'sm' | 'md'`）与 JSDoc 描述一致
- 运行 `npm run type-check` 和 `npm run lint` 确保生成代码符合项目 ESLint/Prettier 规则
- 提交生成文件（排除 `node_modules/` 和临时缓存），建议 `.gitignore` 中保留 `*.generated.ts` 以区分人工修改文件
## 注意事项与最佳实践
- ✅ **设计稿要求**：Figma 组件必须使用 `Variant` 功能组织状态（而非手动复制图层），文本节点需绑定 `Text Style` 以支持 token 映射
- ✅ **命名一致性**：Figma 组件名应遵循 PascalCase（如 `PrimaryButton`），避免空格或特殊字符，CLI 将直接映射为 React 组件名
- ⚠️ **LLM 输出校验**：首次生成后务必人工复核 `asChild`、`ref` 处理、事件回调签名（如 `onClick?: (e: React.MouseEvent) => void`）是否符合项目约定
- ⚠️ **Tailwind 安全性**：生成器默认启用 `safelist` 模式，对动态 class（如 `bg-${color}`）自动添加至 `tailwind.config.js`，需定期清理冗余条目
- 🌟 **进阶集成**：可配合 GitHub Actions，在 PR 提交 `design/` 下 JSON 文件时自动触发生成并创建 Draft PR；支持 Vite 插件实时监听设计变更
## 常见问题提示
- **Q：生成的组件缺少响应式行为？**
A：检查 Figma 中是否为容器设置了 `Constraints`（如 `Width: Fill container`），并在 `config/generation.config.ts` 中启用 `responsiveLayout: true`
- **Q：Storybook Props 表未显示 JSDoc 描述？**
A：确认 `Button.tsx` 中 JSDoc 使用标准格式（`/** @param size - 按钮尺寸，支持 'sm' | 'md' | 'lg' */`），且 `preview.ts` 已导入 `@storybook/addon-docs` 并启用 `docs: { autodocs: 'tag' }`
- **Q：LLM 生成报错 `RateLimitError`？**
A：降低并发请求数（CLI 默认 `--concurrency=2`），或切换至本地模型（如 Ollama + `llama3.1:8b`），详见 `./docs/local-llm-setup.md`
- **Q：如何扩展支持自定义 Hook（如 useTheme）？**
A：在 `config/templates/component.hbs` 中添加 Handlebars 条件块，并在 `config/generation.config.ts` 的 `customHooks` 字段声明依赖路径