资源描述
一款面向前端开发者的端到端设计转代码工作流工具，将Figma设计稿自动转化为高质量React + TypeScript组件。支持语义化布局解析、响应式适配、TypeScript接口生成、Storybook可视化示例及WCAG 2.1兼容性校验报告，显著提升UI开发效率与可访问性保障能力，适用于Design System建设、快速原型交付及跨职能协同场景。
详细内容
# Figma-to-React+TypeScript Component Generator 工作流指南
本工作流实现从Figma设计稿到生产就绪前端代码的自动化转化，覆盖导出、解析、生成、验证全流程，兼顾开发效率与工程规范。
## 工作流概述
1. **设计准备**：在Figma中完成结构清晰、命名规范、层级合理的组件设计；
2. **插件导出**：使用官方Figma插件导出标准化JSON描述文件；
3. **AI语义解析**：本地/CLI运行解析器，识别布局意图（如Flex/Grid）、交互状态（hover/disabled）与语义角色（button/link/heading）；
4. **代码生成**：输出React函数组件（含useEffect/useCallback优化）、严格类型定义（Props & State）、配套Storybook CSF v3故事文件；
5. **质量验证**：内建A11y扫描（axe-core），生成HTML+ARIA合规性报告，并标注需人工复核项。
## 分步骤操作说明
### 步骤1：Figma端准备与导出
- 在Figma中选中目标Frame或Component，确保图层命名符合BEM或语义化规范（如`btn-primary--disabled`、`header-main`）；
- 安装并运行[Figma Plugin](https://www.figma.com/community/plugin/1234567890)（v2.3+），点击「Export as JSON」→ 选择「Semantic Layout Mode」→ 导出为`design.json`；
- ✅ 关键要求：禁用嵌套过深（≤5层）、避免未命名图层、所有文本节点需有`fontFamily`和`fontSize`属性。
### 步骤2：初始化项目环境
- 确保已安装Node.js ≥18.12.0 和pnpm ≥8.0.0；
- 执行：
```bash
pnpm add -D @figma-ai/react-generator
# 或全局安装（推荐CI/CD场景）
pnpm add -g @figma-ai/react-generator
```
### 步骤3：执行语义解析与代码生成
- 运行CLI命令（支持自定义配置）：
```bash
figma-to-react generate \
--input ./design.json \
--output ./src/components/Button \
--tsconfig ./tsconfig.json \
--storybook \
--a11y-report
```
- 输出目录包含：`Button.tsx`、`Button.types.ts`、`Button.stories.tsx`、`a11y-report.html`。
### 步骤4：集成与类型校验
- 检查生成的`Button.types.ts`是否正确推导了`size?: 'sm' | 'md' | 'lg'`等联合类型；
- 运行`pnpm tsc --noEmit`验证TS类型一致性；
- 启动Storybook（`pnpm storybook`）确认组件渲染、交互状态及响应式断点表现。
### 步骤5：A11y审查与迭代
- 打开生成的`a11y-report.html`，重点关注`critical`/`serious`级别问题（如缺失`aria-label`、颜色对比度<4.5:1）；
- 对报告中标记的「Manual Review Required」项，在`Button.tsx`中补充逻辑（如`aria-label={label ?? 'Submit button'}`）；
- 将修正后代码提交至版本库，触发CI中的`figma-to-react verify`进行回归校验。
## 注意事项与最佳实践
- ⚠️ **设计约束**：Figma中禁止使用自由变换（Free Transform）、模糊效果或未栅格化的位图——这些无法被语义解析器识别；
- 🛡️ **安全边界**：生成器默认不处理内联样式或CSS-in-JS，建议通过CSS Modules或Tailwind预设类名映射；
- 🧩 **扩展性**：可通过`--template-path ./templates/react-ts-custom.hbs`注入自定义JSX模板，支持企业级Design Token注入；
- 🌐 **国际化支持**：若设计稿含多语言文本，需在`design.json`中启用`i18n: true`，生成器将预留`t('button.submit')`占位符；
- 📦 **增量更新**：对已有组件二次生成时，使用`--merge`标志保留手写逻辑（如自定义hook调用），仅覆盖AI生成部分。
## 常见问题提示
- ❓Q：生成的组件缺少`key`或`data-testid`？
→ A：默认不注入测试标识，可在CLI添加`--test-id-prefix "btn-"`启用；
- ❓Q：Storybook中状态切换无效？
→ A：检查Figma图层是否标记了`variant`属性（如`{ "variant": ["default", "loading"] }`），否则仅生成静态故事；
- ❓Q：A11y报告提示「Missing accessible name」但设计稿已标注？
→ A：确认Figma文本图层的`description`字段填写完整（非仅图层名），该字段映射为`aria-label`；
- ❓Q：TypeScript接口中出现`any`类型？
→ A：因Figma未标注数据类型（如`icon: string | null`），请在导出前为关键属性添加`@type`注释（例：`icon /* @type: string */`）。