design-to-code-workflows

name	design-to-code-workflows
description	将 Figma 设计和截图转换为生产就绪的代码组件，内置无障碍性支持

Design to Code 工作流程

本 skill 提供设计到代码转换的完整工作流程，通过 MCP 服务器的 3 个工具支持从 Figma 设计文件和截图生成 React、Svelte 或 Vue 组件。

可用的 MCP 工具

本插件通过 MCP 服务器提供以下 3 个工具：

1. parse_figma - 解析 Figma 设计

从 Figma JSON 导出中提取组件信息。

输入参数：

{
  "json": "Figma JSON 导出内容（字符串格式）",
  "framework": "react | svelte | vue（默认: react）"
}

返回内容：

• framework: 目标框架
• components: 提取的组件列表（名称、类型、尺寸）
• colors: 设计中使用的颜色
• typography: 字体设置（字体族、大小、粗细）

使用场景：

• 从 Figma 导出 JSON 文件后解析设计结构
• 提取设计系统的颜色和字体信息
• 为代码生成准备组件规格

2. analyze_screenshot - 分析截图

分析 UI 截图的布局并提取 UI 元素。

输入参数：

{
  "imagePath": "截图文件的路径",
  "framework": "react | svelte | vue（默认: react）"
}

返回内容：

• framework: 目标框架
• layout: 布局结构（类型、子元素列表）

使用场景：

• 从设计稿截图快速生成代码
• 逆向工程现有 UI
• 快速原型设计

注意：截图文件需要是可访问的本地路径。

3. generate_component - 生成组件代码

根据布局规格生成代码组件。

输入参数：

{
  "layout": {
    "type": "容器类型（如 container）",
    "children": [
      { "type": "text", "content": "内容" },
      { "type": "button", "label": "标签" }
    ],
    "styles": { "key": "value" }  // 可选
  },
  "framework": "react | svelte | vue（默认: react）",
  "includeA11y": true  // 是否包含无障碍性特性（默认: true）
}

返回内容：

• code: 生成的组件代码
• framework: 使用的框架
• a11yCompliant: 是否符合无障碍性标准

使用场景：

• 从解析的 Figma 数据生成代码
• 从分析的截图生成代码
• 从自定义布局规格生成代码

完整工作流程

工作流程 1：Figma 设计转代码

步骤 1：导出 Figma 设计

引导用户：

1. 在 Figma 中打开设计文件
2. 选择要转换的 Frame 或 Component
3. 右键 → "Copy as" → "Copy as JSON"
4. 将 JSON 内容粘贴给你

步骤 2：解析 Figma JSON

使用 parse_figma 工具：

const parsedDesign = await parse_figma({
  json: "用户粘贴的 JSON 内容",
  framework: "react"  // 或用户选择的框架
});

步骤 3：生成组件代码

使用解析结果生成代码：

const component = await generate_component({
  layout: parsedDesign.components[0],
  framework: "react",
  includeA11y: true
});

步骤 4：优化和调整

• 显示生成的代码
• 询问用户是否需要调整
• 可以添加样式、状态管理、交互逻辑
• 确保无障碍性特性完整

输出：生产就绪的 React/Svelte/Vue 组件，包含：

• 语义化 HTML
• ARIA 标签
• 键盘导航支持
• 适当的样式

---

工作流程 2：截图转代码

步骤 1：获取截图

引导用户：

1. 提供 UI 截图的路径
2. 或上传截图文件
3. 确认要使用的框架

步骤 2：分析截图布局

使用 analyze_screenshot 工具：

const analysis = await analyze_screenshot({
  imagePath: "/path/to/screenshot.png",
  framework: "svelte"
});

步骤 3：生成组件代码

基于分析结果生成代码：

const component = await generate_component({
  layout: analysis.layout,
  framework: "svelte",
  includeA11y: true
});

步骤 4：完善组件

• 检查生成的代码
• 添加缺失的交互逻辑
• 优化响应式布局
• 验证无障碍性

输出：可用的组件代码，基于截图中的视觉设计。

---

工作流程 3：自定义布局生成

步骤 1：理解需求

询问用户想要创建什么类型的组件：

• 表单组件
• 导航栏
• 卡片布局
• 模态框
• 等等

步骤 2：定义布局规格

根据需求构建布局对象：

const layout = {
  type: "container",
  children: [
    {
      type: "header",
      content: "标题"
    },
    {
      type: "form",
      children: [
        { type: "input", label: "用户名", name: "username" },
        { type: "input", label: "密码", name: "password", inputType: "password" },
        { type: "button", label: "登录", action: "submit" }
      ]
    }
  ],
  styles: {
    display: "flex",
    flexDirection: "column",
    gap: "1rem"
  }
};

步骤 3：生成组件

const component = await generate_component({
  layout: layout,
  framework: "react",
  includeA11y: true
});

步骤 4：迭代优化

• 根据反馈调整布局
• 添加样式细节
• 实现业务逻辑
• 测试无障碍性

---

支持的框架

React

• JSX 语法
• Hooks（useState, useEffect 等）
• 函数式组件
• TypeScript 支持（可选）

Svelte

• 单文件组件
• 响应式声明
• 简洁的语法
• 内置状态管理

Vue

• Composition API
• <template> + <script> + <style>
• 响应式数据
• TypeScript 支持（可选）

---

无障碍性特性

所有生成的组件默认包含以下无障碍性特性（includeA11y: true）：

1. ARIA 标签

• aria-label: 为屏幕阅读器提供描述
• aria-labelledby: 关联标签元素
• aria-describedby: 提供额外描述
• role: 明确元素角色

2. 语义化 HTML

• 使用正确的 HTML 元素（<button> 而非 <div onclick>）
• 表单元素正确关联 <label>
• 标题层级结构（<h1> → <h6>）
• 列表使用 <ul>/<ol>

3. 键盘导航

• Tab 顺序合理
• 焦点状态可见
• Enter/Space 触发按钮
• Esc 关闭模态框

4. 颜色对比

• 检查文本和背景的对比度
• 确保符合 WCAG AA 标准（4.5:1）
• 提示对比度不足的情况

---

使用最佳实践

1. Figma 导出建议

✅ 推荐做法：

• 导出前命名清晰的 Frame/Component
• 使用 Auto Layout（自动布局）
• 定义颜色和文本样式
• 组件化设计（避免扁平化）

❌ 避免：

• 过度嵌套的图层
• 未命名的元素
• 绝对定位（不利于响应式）
• 位图文本（应用文本图层）

2. 截图分析建议

✅ 推荐做法：

• 高分辨率截图（至少 1920x1080）
• 清晰的 UI 边界
• 完整的组件截图（不要裁剪关键部分）
• 单一组件或页面

❌ 避免：

• 模糊或低分辨率图片
• 包含多个无关元素
• 部分截图或不完整的 UI
• 复杂的全屏截图（建议拆分）

3. 框架选择建议

React：

• 企业级应用
• 需要丰富的生态系统
• 团队熟悉 JSX
• 需要 TypeScript 支持

Svelte：

• 性能要求高
• 喜欢简洁的语法
• 中小型项目
• 减少打包体积

Vue：

• 渐进式采用
• 团队熟悉模板语法
• 需要官方路由和状态管理
• 平衡的学习曲线

4. 代码生成后的优化

生成的代码是起点，建议：

• ✅ 添加具体的样式（CSS/Tailwind/CSS-in-JS）
• ✅ 实现交互逻辑和状态管理
• ✅ 添加数据验证
• ✅ 优化性能（懒加载、memo）
• ✅ 添加错误处理
• ✅ 编写单元测试

---

故障排除

Figma JSON 解析失败

原因：

• JSON 格式不正确
• 不是 Figma 的 JSON 导出格式
• JSON 过大或包含特殊字符

解决方法：

1. 确认从 Figma "Copy as JSON" 复制
2. 检查 JSON 是否完整
3. 尝试导出更小的组件

截图分析不准确

原因：

• 截图分辨率太低
• UI 元素边界不清晰
• 包含过多元素

解决方法：

1. 提供更高分辨率的截图
2. 截取单个组件而非整页
3. 手动调整生成的布局规格

生成的代码需要调整

这是正常的！生成的代码是基础模板，需要：

• 添加业务逻辑
• 调整样式细节
• 优化响应式布局
• 添加状态管理

---

高级用法

批量转换

对于多个 Figma 组件：

1. 逐个导出 JSON
2. 批量解析
3. 统一生成组件
4. 组织成组件库

设计系统提取

从 Figma 设计文件提取：

• 颜色变量
• 字体样式
• 间距系统
• 组件规范

使用 parse_figma 的返回值：

const { colors, typography } = await parse_figma({ json, framework });
// colors: ['#000000', '#FFFFFF', ...]
// typography: [{ family: 'Inter', size: 16, weight: 400 }, ...]

创建设计令牌（Design Tokens）文件。

响应式布局

在 layout.styles 中定义响应式样式：

{
  layout: {
    type: "container",
    styles: {
      display: "grid",
      gridTemplateColumns: "repeat(auto-fit, minmax(250px, 1fr))",
      gap: "1rem"
    }
  }
}

TypeScript 支持

生成 TypeScript 组件（React/Vue）：

1. 在生成后手动添加类型
2. 或在提示中明确要求 TypeScript 语法

---

限制和注意事项

1. MCP 服务器需要配置：插件依赖 MCP 服务器，需要正确配置 .mcp.json
2. 简化的实现：当前工具提供基础的解析和生成，复杂设计可能需要手动调整
3. 截图分析限制：基于图像的分析可能不如 Figma JSON 准确
4. 无障碍性基础：生成的无障碍性特性是基础级别，复杂交互需要额外优化
5. 样式提取有限：颜色和字体提取是简化的，详细样式需手动添加

---

相关资源

• Figma API 文档: https://www.figma.com/developers/api
• React 文档: https://react.dev
• Svelte 文档: https://svelte.dev
• Vue 文档: https://vuejs.org
• WCAG 无障碍性指南: https://www.w3.org/WAI/WCAG21/quickref/
• ARIA 最佳实践: https://www.w3.org/WAI/ARIA/apg/

---

工作流程总结

工作流程	输入	MCP 工具	输出
Figma 转代码	Figma JSON	parse_figma → generate_component	生产就绪组件
截图转代码	UI 截图	analyze_screenshot → generate_component	基础组件代码
自定义生成	布局规格	generate_component	定制化组件

所有工作流程都支持 React、Svelte、Vue 三种框架，并默认包含无障碍性特性。