figma-ios-hierarchy-preservation

Figma 层级结构保持规则

职责边界（与 figma-ios-snapkit-layout 的分工）

• 本 Skill 负责：Figma 节点 → UIView 层级映射（建哪些容器、addSubview 顺序、坐标系转换）
• 不负责：约束写法语法（SnapKit make.* 写法）→ 见 figma-ios-snapkit-layout

两者协作：本 Skill 确定"建什么容器、父子关系"，snapkit-layout 确定"如何写约束值"。

---

⚡ QUICK_REF（Agent 优先读此处）

核心规则：每个 Figma <frame> / <group> 必须对应一个 UIView，不得拍平。

Figma 节点类型	iOS 对应	说明
<frame>	UIView 容器	保持层级，设置 clipsToBounds 按 clipsContent
<group>	UIView 容器	通常透明，仅作分组
<rectangle>	UIView 或 UIImageView	看填充类型
<text>	UILabel	直接
<instance> (iconfont)	UILabel	见 figma-ios-iconfont-mapping

坐标转换核心规则：

• 数据包 design.json[node].frame.relative.{x,y} 是相对直接父容器的坐标，直接用作 SnapKit offset
• 如需绝对坐标，读 frame.absolute.{x,y}（已由数据包预计算）
• 禁止跨层累加坐标（会双重计算）

Figma: <frame id="A" x="16" y="100">
           <frame id="B" x="0" y="0">
               <rect id="C" x="45" y="10" />

Swift:
A.snp: leading=16, top=100  ← 用 A 自己的 x/y
B.snp: leading=0, top=0     ← 用 B 自己的 x/y（相对A）
C.snp: leading=45, top=10   ← 用 C 自己的 x/y（相对B）

详细规则、坐标转换公式、addSubview 顺序规范见下文。

---

目标

确保生成的 Swift/UIKit 代码完整保留 Figma 的层级结构，避免将嵌套的容器"拍平"成扁平结构。

---

核心原则

✅ 原则 1：每个 Frame/Group 都对应一个 UIView 容器

Figma 中的每个 <frame> 或 <group> 节点，在代码中都应该有对应的 UIView 容器。

Figma:

<frame id="1:305" name="编组">
  <frame id="1:309" name="编组 6">
    <rectangle id="1:310" name="图片A" />
    <rectangle id="1:325" name="图片B" />
  </frame>
</frame>

Swift:

// ✅ 正确：保持层级
private lazy var groupContainer: UIView = { ... }()
private lazy var group6Container: UIView = { ... }()
private lazy var imageA: UIImageView = { ... }()
private lazy var imageB: UIImageView = { ... }()

// setupUI
groupContainer.addSubview(group6Container)
group6Container.addSubview(imageA)
group6Container.addSubview(imageB)

// ❌ 错误：拍平层级
private lazy var groupContainer: UIView = { ... }()
private lazy var imageA: UIImageView = { ... }()
private lazy var imageB: UIImageView = { ... }()

// setupUI
groupContainer.addSubview(imageA)  // 缺少中间容器
groupContainer.addSubview(imageB)