figma-restoration-tools
Version:
Professional Figma Component Restoration Kit - MCP tools with snapDOM-powered high-quality screenshots, intelligent shadow detection, and smart debugging for Vue component restoration. Includes figma_compare and snapdom_screenshot tools.
201 lines (177 loc) • 8.33 kB
Markdown
---
alwaysApply: true
---
# 🔄 持续生效规则：Figma组件还原流程
# 工作目录范围
你始终在 figma-restoration-mcp-vue-tools目录下的文件工作
# Figma组件还原流程规则
## 概述
当用户要求还原Figma组件并提供Figma链接时，严格按照以下7步流程执行。
## 流程步骤
### 步骤1: 获取Figma数据
- 使用工具获取Figma JSON数据
- 参数设置：
- `fileKey`: 从Figma链接中提取
- `nodeId`: 从Figma链接中提取
- **⭐ savePath**: **必须使用绝对路径** `/Users/yujie_wu/Documents/study/11111/figma-restoration-mcp-vue-tools/src/components/{ComponentName}`
- 工具会自动保存JSON到指定目录
### 步骤2: 分析JSON内容
分析返回的JSON数据，确认以下关键信息：
1. **页面结构**:
- 组件层级关系
- 布局方式（**优先使用flex布局，非必要不使用绝对定位**）
- 尺寸和位置信息
2. **🆕 智能素材节点识别**:
- **根据节点名字识别**: 检测名字中含有 `ic`、`ic_`、`素材`、`material`、`asset`、`icon`、`img`、`image` 等关键词
- **自动跳过子节点**: 当识别为素材节点时，直接导出该节点，不再分析其子节点
- **图片节点**: imageRef填充的节点
- **图标节点**: SVG矢量图标
- **背景图片**: 背景填充图片
- **优先级**: 名字识别 > 类型+填充识别
3. **子组件识别**:
- 嵌套的组件实例
- 可复用的UI元素
4. **样式信息**:
- 颜色、字体、边框
- 阴影、圆角等效果
- 响应式布局需求
输出：生成符合Web标准、层级分明的优化JSON结构
### 步骤2.5: 🆕 基于位置和可见性优化JSON
**⭐ 新增关键步骤** - 生成符合Web最佳实践的优化JSON：
- **位置分析验证**:
- 对比Figma坐标与预期截图(expected.png)
- 识别和移除在预期图中不可见的冗余元素
- 验证每个元素在视觉输出中的实际作用
- **布局结构优化**:
- 将Figma的绝对定位转换为现代flex布局
- 分析元素间的相对位置关系
- 确定合理的padding和gap值
- 不使用margin
- **HTML结构映射**:
- 确定元素的语义角色（容器、内容、装饰等）
- 规划合理的DOM层级结构
- 考虑flex布局中的元素顺序
- **输出优化JSON**:
- 包含经过验证的元素列表
- 明确的CSS布局策略（flex优先）
- 精确的尺寸和间距规范
- 符合Web标准的实现方案
### 步骤3: 使用tool下载素材
- **🆕 规范目录结构** - **⭐ 素材和结果文件分类存储**：
```
/Users/yujie_wu/Documents/study/11111/figma-restoration-mcp-vue-tools/src/components/{ComponentName}/
├── index.vue # Vue 组件
├── metadata.json # 组件元数据
├── layout-analysis.json # 布局分析JSON
├── figma-{fileKey}-{nodeId}-{timestamp}.json # Figma原始数据
├── images/ # ⭐ 素材文件目录
│ ├── folder-icon.svg # 图标文件
│ ├── project-icon.svg # 项目图标
│ └── background.png # 背景图片等
└── results/ # ⭐ 截图对比结果目录
├── expected.png # Figma原图
├── actual.png # 组件截图
├── diff.png # 差异对比图
├── figma-analysis-report.json # 分析报告
├── figma-analysis-report.md # 分析报告MD
└── region-analysis.json # 区域分析
```
- **素材准备方式**:
- 从Figma手动导出图片素材到images目录
- 确保素材命名符合规范（icon_xxx.svg, image_xxx.png等）
- 推荐使用高分辨率素材（2x或3x）
### 步骤4: 递归还原子组件
对于识别出的子组件：
- 每个子组件重新执行步骤1-7的完整流程
- 创建独立的组件目录结构
- 确保组件间的依赖关系正确
- 优先还原基础组件，再还原复合组件
### 步骤5: 生成Vue组件代码
基于优化的JSON、准备的素材和制作的子组件生成代码：
- **技术栈要求**:
- Vue 3 Composition API
- TypeScript支持
- **优先使用flex布局，避免绝对定位**
- **代码结构**:
- 响应式设计
- 不需要语义化HTML结构
- **文件生成**:
- `index.vue`: 主组件文件
- `metadata.json`: 组件元数据（尺寸、描述等）
- **⭐ 组件自动注册**: Vue组件在项目中通过 `src/components/index.ts` 自动注册，无需检查注册相关代码
### 步骤6: 组件截图
使用工具进行高质量组件截图：
- **基本参数**:
- `componentName`: 组件名称
- `projectPath`: 项目根路径
- `port`: **⭐ 必须使用用户启动的服务器端口号**
- **⭐ 必须指定输出路径**:
- **outputPath**: **必须使用绝对路径到组件的results目录下的actual.png**
- **路径格式**: `/Users/yujie_wu/Documents/study/11111/figma-restoration-mcp-vue-tools/src/components/{ComponentName}/results/actual.png`
- **截图配置**:
- `snapDOMOptions`: 高质量截图配置
- `scale`: 3（高分辨率）
- **⭐ padding设置规则**:
- **无阴影组件**: `padding: 0` （精确裁切，提升还原度）
- `backgroundColor`: "transparent"
- `embedFonts`: true
### 步骤7: 还原度对比
使用工具进行像素级对比分析：
- **基本参数**:
- `componentName`: 组件名称
- `threshold`: 0.02（98%还原度要求）
- `generateReport`: true
- **⭐ 必须指定输出路径**:
- **必须与步骤6使用相同的results目录**
- **路径格式**: `/Users/yujie_wu/Documents/study/11111/figma-restoration-mcp-vue-tools/src/components/{ComponentName}/results`
- **⭐ 结果存储位置**:
- expected.png, actual.png, diff.png 存储在组件的results目录
- 分析报告存储在同一results目录下
- 分析对比结果，识别差异点
### 步骤8: 自我反思优化
如果还原度 < 98%：
- **问题分析**:
- 布局差异（位置、尺寸、对齐）
- 样式差异（颜色、字体、效果）
- 素材问题（缺失、错误、质量）
- **🆕 素材节点问题**: 检查是否正确识别了所有素材节点
- **优化策略**:
- 重新分析JSON结构（回到步骤2）
- **🆕 验证素材节点识别**: 确认所有 `ic`、`ic_`、`素材` 等关键词节点已正确处理
- 调整CSS样式和布局（**优先使用flex布局优化**）
- 重新准备或优化素材
- 修复子组件问题
- **迭代流程**:
- 最多迭代3次
- 每次迭代都要重新截图对比
- 记录改进点和剩余问题
## 🆕 路径配置最佳实践
### ⭐ 分类路径配置（推荐）
- **Figma数据savePath**: **必须使用绝对路径**到组件根目录
- **素材下载localPath**: **必须使用绝对路径**到组件的images目录
- **Figma预期截图**: **必须下载到results目录**（expected.png）
- **截图工具outputPath**: **必须使用绝对路径**到results目录下的actual.png
- **对比工具outputPath**: **必须使用绝对路径**到results目录
**路径格式**:
- **素材路径**: `/Users/yujie_wu/Documents/study/11111/figma-restoration-mcp-vue-tools/src/components/{ComponentName}/images`
- **结果路径**: `/Users/yujie_wu/Documents/study/11111/figma-restoration-mcp-vue-tools/src/components/{ComponentName}/results`
### 🎯 路径规则
- **Figma JSON savePath**: 组件根目录的绝对路径
- **素材下载**: images目录的绝对路径
- **截图对比**: results目录的绝对路径
- **必须分类存储**: 素材文件在images目录，结果文件在results目录
- **必须保持一致**: 截图和对比工具使用相同的results文件夹
## 质量标准
### 代码质量
- 遵循Vue 3最佳实践
- TypeScript支持
- **优先使用flex布局，避免绝对定位**
- **🆕 CSS盒模型规范**:
- **任何设置了padding的元素必须设置 `box-sizing: border-box`**
- 这遵循Figma的实现方式，确保元素尺寸包含padding
- 推荐在组件根元素设置通用规则：`.component, .component * { box-sizing: border-box; }`
- 响应式设计支持
- 无障碍访问性
- 性能优化
- 及时更新进度和状态
- 遇到问题时主动寻求帮助