Figma → React Component Generator with Storybook Integration

一款面向前端工程师与设计开发协同团队的高效工作流：通过 Figma 插件导出设计 JSON，经 LLM 语义解析后自动生成符合最佳实践的 TypeScript React 组件、Storybook 可视化 stories 及响应式 Tailwind CSS 样式。显著缩短 UI 实现周期，保障设计-代码一致性，适用于中大型项目组件库建设与 Design System 落地。

# Figma → React Component Generator with Storybook Integration ## 工作流概述 本工作流实现从 Figma 设计稿到可交付、可测试、可复用的 React 组件的端到端自动化生成。核心链路为：Figma 插件提取结构化 JSON → LLM 模型理解布局语义与交互意图 → 输出类型安全的 React（TSX）、配套 Storybook stories（CSF v3）、以及原子化 Tailwind CSS 类名样式。全程无需手写 JSX 或手动映射设计属性，支持响应式断点、暗色模式基础适配及无障碍（a11y）标签注入。 ## 分步骤操作说明 ### 步骤 1：安装并配置 Figma 插件 - 在 Figma Community 中搜索并安装官方插件 `Design2Code Exporter`（或兼容 JSON 导出的插件，如 `Anima` 或 `Figma to Code` 的 JSON 模式） - 在目标设计文件中选中需导出的 Frame/Component，点击插件面板 → 选择「Export as Semantic JSON」→ 勾选「Include variants, constraints, text styles, and layer hierarchy」→ 导出 `.json` 文件 ### 步骤 2：准备 LLM 解析环境 - 确保本地或服务端已部署支持结构化输出的开源 LLM（如 Ollama + `phi3:3.8b` 或 `llama3:8b-instruct-q4_K_M`），并加载预训练的 UI 语义解析 Prompt 模板 - 将导出的 JSON 文件放入指定输入目录（如 `./input/design.json`），运行解析脚本：`npm run parse -- --input ./input/design.json --output ./output/` ### 步骤 3：执行语义解析与代码生成 - LLM 按预设规则解析 JSON 中的层级关系、组件类型（Button/Card/Modal）、状态变体（hover/disabled）、文本样式、间距约束及响应式断点信息 - 自动生成三类产物： - `src/components/Button/Button.tsx`（含 Props 接口、useEffect 处理动态状态） - `src/stories/Button.stories.tsx`（CSF v3 格式，含 Primary/Secondary/Loading 等 args 变体） - `src/components/Button/Button.module.css` → **自动转换为 Tailwind 类名**（如 `p-4 rounded-lg bg-blue-600 text-white hover:bg-blue-700`） ### 步骤 4：集成至现有工程 - 将生成的 `components/` 和 `stories/` 目录复制至项目对应路径（如 `src/`） - 确保项目已安装依赖：`@storybook/react@^8.0`, `tailwindcss@^3.4`, `typescript@^5.0` - 运行 `pnpm storybook` 验证组件渲染与交互逻辑；检查 Storybook Canvas 中 props 控制器是否准确映射设计变体 ### 步骤 5：校验与轻量人工优化 - 使用 ESLint（+ `@typescript-eslint`）和 Stylelint（+ `tailwindcss/no-custom-classname`）扫描生成代码 - 重点审查： - LLM 是否误判嵌套容器语义（如将「图标+文字」误识别为独立 Button 组合） - 动态内容区域（如列表项、表单字段）是否预留 `children` 或 `slots` 属性 - 所有 `aria-*` 属性是否根据 Figma 的 accessibility 注释自动注入 - 对关键组件补充单元测试（Vitest）及视觉回归快照（Storybook + Chromatic） ## 注意事项与最佳实践 - ✅ **设计规范前置**：Figma 文件需启用「Auto Layout」+「Constraints」+「Component Variants」，命名遵循 BEM 或 PascalCase（如 `PrimaryButton/Default`, `PrimaryButton/Hover`） - ✅ **LLM 提示词关键约束**：强制要求输出严格遵循 React 18+ Hooks 规范、无内联 style、所有颜色使用 Tailwind 命名（禁止 HEX/RGB 字符串）、Props 必须类型化且含 JSDoc 注释 - ⚠️ **不支持场景**：复杂交互动画（如拖拽排序、Canvas 绘图）、第三方图表库封装、条件渲染深度嵌套（>3 层 ternary）、非标准字体导入（需手动补充 `@font-face`） - 🛡️ **安全建议**：禁用 LLM 访问公网；JSON 输入需经 `zod` Schema 校验（验证 `type`, `name`, `children`, `style` 字段存在性） ## 常见问题提示 - **Q：生成的 Tailwind 类名过于冗长？** A：运行 `npx tailwindcss -o ./dist/tailwind.css --minify` 后启用 PurgeCSS；或在 LLM Prompt 中添加约束：“合并重复类名，优先使用 `flex gap-2` 替代 `flex flex-row space-x-2`” - **Q：Storybook 中状态切换无效？** A：检查生成的 `args` 是否绑定到组件内部 state（如 `const [loading, setLoading] = useState(args.loading)`），而非仅作为 props 透传；确保 story 中 `argTypes` 定义了 `control: 'boolean'` 或 `control: 'select'` - **Q：Figma 文字样式未正确映射为 Tailwind？** A：确认 Figma 中已定义「Text Styles」并关联至图层；插件导出 JSON 时需启用 `includeTextStyles: true`；若缺失，可在 LLM Prompt 中追加映射表（如 `"H1": "text-4xl font-bold leading-tight"`） - **Q：如何扩展支持自定义主题（如 dark mode）？** A：在 Figma 中为组件添加 `dark:` 前缀的样式变体（如 `bg-white dark:bg-gray-800`），并在 LLM Prompt 中声明：“检测 `dark:` 前缀字段，生成 `className={clsx('bg-white', theme === 'dark' && 'dark:bg-gray-800')}`”