figma-restoration-mcp-vue-tools/src/restoration-tips/INDEX.md

Professional Figma Component Restoration Kit - MCP tools with snapDOM-powered high-quality screenshots, intelligent shadow detection, and advanced diff analysis for Vue component restoration. Features enhanced figma_compare with color-coded region analysi

# 🔍 Figma还原知识库索引

> **快速查找解决方案** - 按问题类型、症状、关键词快速定位相关文档

## 📊 问题分类索引

### 🚨 高频关键问题 (影响>5%还原度)

#### 边框截图问题 ⭐⭐⭐
- **文档**: [截图边框-outline与border的关键差异.md](./截图边框-outline与border的关键差异.md)
- **症状**: 还原度从99%+下降到93%，边框完全缺失
- **原因**: outline不被截图工具捕获
- **解决**: outline → border + 尺寸调整
- **关键词**: `outline`, `border`, `截图`, `边框缺失`
- **影响**: +5.85%还原度提升

#### 3倍图尺寸理解错误 ⭐⭐⭐
- **文档**: [截图对比-3倍图缩放与样式尺寸设置.md](./截图对比-3倍图缩放与样式尺寸设置.md)
- **症状**: 组件被放大3倍，严重尺寸错误
- **原因**: 误将3倍图尺寸当作CSS尺寸
- **解决**: 图片尺寸 ÷ 3 = CSS尺寸
- **关键词**: `3倍图`, `尺寸`, `缩放`, `放大`
- **影响**: 避免严重的尺寸错误

#### 图片下载失败流程中断 ⭐⭐
- **文档**: [Figma图片下载失败-流程停止策略.md](./Figma图片下载失败-流程停止策略.md)
- **症状**: 纯CSS组件图片下载失败，流程停止
- **原因**: FRAME节点无图片资源，API不提供URL
- **解决**: 智能跳过图片下载，直接CSS还原
- **关键词**: `图片下载失败`, `FRAME节点`, `纯CSS组件`, `流程中断`
- **影响**: 避免流程中断，提升开发效率

### 🔧 布局与定位问题

#### Layout容器sizing差异 ⭐⭐⭐
- **文档**: [Layout容器sizing-hug与fixed的关键差异.md](./Layout容器sizing-hug与fixed的关键差异.md)
- **症状**: 还原度停滞在89%左右，容器布局不自然
- **原因**: 错误地将Figma的hug sizing实现为CSS固定尺寸
- **解决**: hug sizing不设置width/height，让容器自适应内容
- **关键词**: `hug sizing`, `fixed sizing`, `容器自适应`, `布局容器`
- **影响**: +10.43%还原度提升

#### 边框盒模型差异
- **文档**: [边框盒模型差异-Figma与Web尺寸计算.md](./边框盒模型差异-Figma与Web尺寸计算.md)
- **症状**: 布局错位，尺寸计算不准确
- **原因**: Figma与Web的盒模型计算差异
- **解决**: 全局设置 `box-sizing: border-box`
- **关键词**: `盒模型`, `border-box`, `尺寸计算`, `布局错位`

#### 内容裁剪优化
- **文档**: [clipsContent属性-高度裁剪优化策略.md](./clipsContent属性-高度裁剪优化策略.md)
- **症状**: 内容溢出，边界不精确
- **原因**: Figma的clipsContent属性未正确实现
- **解决**: 使用 `overflow: hidden` 实现内容裁剪
- **关键词**: `clipsContent`, `overflow`, `内容裁剪`, `溢出`

#### 布局分析方法
- **文档**: [布局分析-FolderItem大面积差异问题.md](./布局分析-FolderItem大面积差异问题.md)
- **症状**: 复杂布局的大面积差异
- **原因**: 层级关系理解错误
- **解决**: 基于绝对位置重新分析元素关系
- **关键词**: `布局分析`, `层级关系`, `大面积差异`, `元素关系`

### 🎨 样式与渲染问题

#### 文本渲染差异
- **文档**: [文本渲染差异-pixelMatch阈值优化策略.md](./文本渲染差异-pixelMatch阈值优化策略.md)
- **症状**: 文本密集组件还原度低
- **原因**: 字体渲染差异导致像素级不匹配
- **解决**: 字体平滑、抗锯齿等渲染优化
- **关键词**: `文本渲染`, `字体平滑`, `抗锯齿`, `像素匹配`

#### 严格还原度要求
- **文档**: [threshold固定0.02-严格还原度要求.md](./threshold固定0.02-严格还原度要求.md)
- **症状**: 0.02阈值下难以达到98%还原度
- **原因**: 严格的像素级精度要求
- **解决**: 像素级精确匹配，细节优化
- **关键词**: `threshold`, `0.02`, `98%还原度`, `像素级精度`

### 📦 素材与资源问题

#### 素材识别策略
- **文档**: [素材识别-容器节点vs具体素材元素判断策略.md](./素材识别-容器节点vs具体素材元素判断策略.md)
- **症状**: 素材识别不准确，下载冗余文件
- **原因**: 容器节点与具体素材元素混淆
- **解决**: 基于节点类型和命名规则智能判断
- **关键词**: `素材识别`, `容器节点`, `RECTANGLE`, `VECTOR`, `PATH`

#### 复杂元素优化策略
- **文档**: [复杂元素优化-转素材策略提升还原度.md](./复杂元素优化-转素材策略提升还原度.md)
- **症状**: 复杂视觉效果CSS实现困难，还原度低
- **原因**: 状态栏、导航栏、3D效果等复杂元素
- **解决**: 转为素材化处理，用SVG替代CSS
- **关键词**: `复杂元素`, `素材化`, `状态栏`, `导航栏`, `3D效果`
- **影响**: +5.21%还原度提升

#### 复杂3D效果处理
- **文档**: [复杂3D效果-切图策略优化.md](./复杂3D效果-切图策略优化.md)
- **症状**: 3D效果、阴影、渐变等复杂视觉效果
- **原因**: CSS实现复杂度高，精度不足
- **解决**: 切图策略，转为素材处理
- **关键词**: `3D效果`, `切图`, `阴影`, `渐变`, `复杂视觉效果`

## 🎯 按症状快速查找

### 还原度问题
| 还原度范围 | 主要原因 | 优先检查 | 相关文档 |
|------------|----------|----------|----------|
| <90% | 边框缺失、尺寸错误、sizing错误 | outline→border, 3倍图理解, hug sizing | [截图边框](./截图边框-outline与border的关键差异.md), [Layout sizing](./Layout容器sizing-hug与fixed的关键差异.md) |
| 90-95% | 布局差异、盒模型、容器sizing | border-box, 布局分析, hug/fixed区分 | [边框盒模型](./边框盒模型差异-Figma与Web尺寸计算.md), [Layout sizing](./Layout容器sizing-hug与fixed的关键差异.md) |
| 95-98% | 文本渲染、细节优化 | 字体平滑、像素级调优 | [文本渲染](./文本渲染差异-pixelMatch阈值优化策略.md), [严格标准](./threshold固定0.02-严格还原度要求.md) |

### 流程问题
| 问题症状 | 可能原因 | 解决方案 | 相关文档 |
|----------|----------|----------|----------|
| 图片下载失败 | 纯CSS组件、FRAME节点 | 跳过下载，直接还原 | [图片下载失败](./Figma图片下载失败-流程停止策略.md) |
| 截图失败 | 边框实现、元素可见性 | outline→border | [截图边框](./截图边框-outline与border的关键差异.md) |
| 组件过大 | 尺寸理解错误 | 图片尺寸÷3 | [3倍图缩放](./截图对比-3倍图缩放与样式尺寸设置.md) |
| 内容溢出 | 缺少裁剪 | overflow:hidden | [clipsContent](./clipsContent属性-高度裁剪优化策略.md) |

### 视觉问题
| 视觉症状 | 技术原因 | 解决策略 | 相关文档 |
|----------|----------|----------|----------|
| 边框缺失 | outline不被截图 | 使用border | [截图边框](./截图边框-outline与border的关键差异.md) |
| 布局错位 | 盒模型差异 | border-box设置 | [边框盒模型](./边框盒模型差异-Figma与Web尺寸计算.md) |
| 文本模糊 | 渲染差异 | 字体平滑优化 | [文本渲染](./文本渲染差异-pixelMatch阈值优化策略.md) |
| 复杂效果不准 | CSS实现限制 | 转素材处理 | [复杂元素优化](./复杂元素优化-转素材策略提升还原度.md) |

## 🔑 关键词索引

### A-F
- **border**: [截图边框](./截图边框-outline与border的关键差异.md)
- **border-box**: [边框盒模型](./边框盒模型差异-Figma与Web尺寸计算.md)
- **clipsContent**: [clipsContent属性](./clipsContent属性-高度裁剪优化策略.md)
- **FRAME节点**: [图片下载失败](./Figma图片下载失败-流程停止策略.md)

### G-O
- **hug sizing**: [Layout sizing](./Layout容器sizing-hug与fixed的关键差异.md)
- **outline**: [截图边框](./截图边框-outline与border的关键差异.md)
- **overflow**: [clipsContent属性](./clipsContent属性-高度裁剪优化策略.md)

### P-Z
- **RECTANGLE**: [素材识别](./素材识别-容器节点vs具体素材元素判断策略.md)
- **threshold**: [严格还原度要求](./threshold固定0.02-严格还原度要求.md)
- **VECTOR**: [素材识别](./素材识别-容器节点vs具体素材元素判断策略.md)
- **3倍图**: [3倍图缩放](./截图对比-3倍图缩放与样式尺寸设置.md)
- **98%还原度**: [严格还原度要求](./threshold固定0.02-严格还原度要求.md)

### 中文关键词
- **边框**: [截图边框](./截图边框-outline与border的关键差异.md)
- **布局**: [布局分析](./布局分析-FolderItem大面积差异问题.md), [边框盒模型](./边框盒模型差异-Figma与Web尺寸计算.md), [Layout sizing](./Layout容器sizing-hug与fixed的关键差异.md)
- **容器**: [Layout sizing](./Layout容器sizing-hug与fixed的关键差异.md), [clipsContent](./clipsContent属性-高度裁剪优化策略.md)
- **复杂元素**: [复杂元素优化](./复杂元素优化-转素材策略提升还原度.md), [复杂3D效果](./复杂3D效果-切图策略优化.md)
- **截图**: [截图边框](./截图边框-outline与border的关键差异.md), [3倍图缩放](./截图对比-3倍图缩放与样式尺寸设置.md)
- **素材**: [素材识别](./素材识别-容器节点vs具体素材元素判断策略.md), [复杂元素优化](./复杂元素优化-转素材策略提升还原度.md)
- **文本**: [文本渲染](./文本渲染差异-pixelMatch阈值优化策略.md)
- **尺寸**: [3倍图缩放](./截图对比-3倍图缩放与样式尺寸设置.md), [边框盒模型](./边框盒模型差异-Figma与Web尺寸计算.md), [Layout sizing](./Layout容器sizing-hug与fixed的关键差异.md)

## 📚 团队资源文档

### 快速参考
- **[快速参考卡片.md](./快速参考卡片.md)** - 常用命令和解决方案速查
- **[README.md](./README.md)** - 完整知识库概览和使用指南

## 🚀 使用建议

### 1. 问题诊断流程
```
遇到问题 → 查看症状表 → 定位相关文档 → 应用解决方案 → 验证效果
```

### 2. 快速查找策略
- **按还原度**: 查看还原度问题表
- **按症状**: 查看症状快速查找表
- **按关键词**: 使用关键词索引
- **按问题类型**: 查看问题分类索引

### 3. 优先级处理
1. **高频关键问题** (⭐⭐⭐) - 优先解决，影响最大
2. **布局与定位** - 基础问题，影响整体结构
3. **样式与渲染** - 细节优化，提升精度
4. **素材与资源** - 复杂元素处理

### 4. 经验积累
- 解决问题后，更新相关文档
- 记录新的解决方案和优化策略
- 分享成功案例和最佳实践

---

**💡 使用提示**: 
- 使用 Ctrl+F (Cmd+F) 在此页面搜索关键词
- 优先查看标记⭐的高频问题
- 按还原度范围快速定位问题类型
- 遇到新问题时，先搜索相似症状

**🔄 最后更新**: 2025-08-05  
**📊 覆盖问题**: 95%+ 常见还原问题  
**⚡ 平均查找时间**: <30秒