figma-restoration-mcp-vue-tools/src/restoration-tips/素材识别-容器节点vs具体素材元素判断策略.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

# 素材识别：容器节点vs具体素材元素判断策略

## 问题描述
在Figma组件还原过程中，经常会遇到素材节点包含多个层级的情况。如果错误地下载了外层容器而非内部具体素材，会导致CSS尺寸设置与SVG实际内容不匹配，造成缩放变形和像素差异。

## 问题分析

### 典型场景：复选框组件
- **Figma结构**:
  ```
  "单选" (INSTANCE, 48×64px) - 外层容器
  └── "Rectangle 3464324" (RECTANGLE, 16×16px) - 实际矩形素材
  ```
- **错误做法**: 下载外层"单选"容器(48×64)，CSS设置为16×16 → 强制缩放变形
- **正确做法**: 下载内部"Rectangle"元素(16×16)，CSS设置为16×16 → 精确匹配

### 根本原因
1. **Figma设计逻辑**: 外层往往是语义化的组件容器，内层才是具体的视觉素材
2. **下载工具特性**: 默认下载指定nodeId的完整内容，包括容器和内部元素
3. **CSS实现需求**: 需要的是纯净的视觉素材，不需要额外的容器结构

## 解决方案

### 1. 基于Claude视觉分析判断
**核心方法**: 利用Claude直接分析expected.png中的视觉元素
- **观察实际需求**: 复选框在视觉上就是16×16的矩形，无48×64容器表现
- **确定真实尺寸**: 基于图片中实际显示的元素大小判断需要的素材尺寸
- **验证层级合理性**: 判断哪些Figma层级在视觉上是必要的

### 2. 基于节点名字判断
**判断规则**:
- **语义化名称** → 通常是组件容器
  - 示例: `"单选"`、`"按钮"`、`"图标组"`
  - 特征: 功能性描述、中文语义、组件类型名
- **具体形状名称** → 真正的视觉素材  
  - 示例: `"Rectangle 3464324"`、`"Vector 297"`、`"Path 123"`
  - 特征: 技术性描述、形状类型+数字编号

### 3. 基于节点类型判断
**优先级策略**:
1. **RECTANGLE/VECTOR/PATH** → 具体绘制元素，优先下载
2. **INSTANCE/COMPONENT** → 容器组件，需检查子元素
3. **GROUP/FRAME** → 布局容器，通常不是素材本身

### 4. 实际操作流程
```javascript
// 伪代码示例
function selectAssetNode(figmaNode) {
  // 1. 视觉驱动判断
  const visualRequirement = analyzeExpectedImage();
  
  // 2. 节点名字判断
  if (isSemanticName(node.name)) {
    // 检查子元素
    return findConcreteChildAsset(node.children);
  }
  
  // 3. 具体形状优先
  if (isConcreteShape(node.type, node.name)) {
    return node;
  }
}
```

## 代码示例

### 错误做法 ❌
```javascript
// 下载外层容器
nodeId: "4211:72485" // "单选" 48×64px容器

// CSS强制缩放
.checkbox {
  width: 16px;   // 强制缩放48×64 → 16×16
  height: 16px;  // 导致变形和像素差异
}
```

### 正确做法 ✅
```javascript
// 下载内部具体元素  
nodeId: "I4211:72485;924:63585" // "Rectangle 3464324" 16×16px

// CSS精确匹配
.checkbox {
  width: 16px;   // 精确匹配16×16
  height: 16px;  // 无缩放，保持精度
}
```

## 改进效果
- **还原度提升**: 91.28% → 91.60% (+0.32%)
- **区域匹配度**: 97.70% → 97.85% (+0.15%)  
- **消除缩放变形**: SVG不再被强制拉伸
- **像素精度提升**: 避免因缩放导致的抗锯齿差异

## 关键经验

### 1. 视觉驱动原则
**Claude的图像分析能力是判断素材需求的最佳工具**
- 直接观察expected.png中的实际视觉效果
- 确定真正需要还原的元素尺寸和样式
- 以视觉真实性为准，而非Figma技术结构

### 2. 层级选择策略  
**优先选择最具体的视觉实现层级**
- 跳过语义化的容器层
- 直接获取绘制形状层
- 避免不必要的嵌套结构

### 3. 尺寸精确匹配
**素材尺寸与CSS尺寸必须精确对应**
- SVG原始尺寸 = CSS设置尺寸
- 避免任何形式的缩放变换
- 保持viewBox与实际使用尺寸一致

## 注意事项

### 1. 复杂素材判断
- 某些图标可能确实需要容器背景，需要结合视觉分析判断
- 带阴影、背景的素材可能需要完整的容器结构
- 响应式图标可能有多种尺寸版本

### 2. 批量下载策略
- 可以先下载容器，分析结构后再决定是否重新下载内部元素
- 对于简单图标，优先尝试下载最内层的具体形状
- 对于复杂组件，可能需要保持一定的层级结构

### 3. 性能考虑
- 内部元素的SVG通常更简洁，文件更小
- 减少不必要的DOM层级有助于渲染性能
- 精确的尺寸匹配有助于浏览器优化

## 适用场景
- **简单图标素材**: 复选框、按钮图标、装饰元素
- **几何形状素材**: 矩形、圆形、多边形等基础形状  
- **线条图标**: 描边图标、简单矢量图形
- **单色图标**: 不涉及复杂颜色层次的图标

### 不适用场景
- **复杂插画**: 多层次、多颜色的复杂图形
- **带阴影素材**: 需要完整背景和效果的图标
- **响应式图标**: 需要保持容器结构以支持多尺寸适配