figma-ios-vertical-layout-safearea

Figma 垂直布局与安全区识别规范

版本: v2.1 最后更新: 2026-04-20

---

⛔ 红线规则（最高优先级）

1. 禁止用宽度比例 scale 缩放垂直方向

// ❌ 严重错误：把宽度比例用在 y / height
let scale = /* host.utils.screen_width */ / 375.0
view.snp.makeConstraints { make in
    make.top.equalTo(...).offset(49 * scale)        // ❌
    make.height.equalTo(111 * scale)                 // ❌
    make.bottom.equalToSuperview().offset(-34 * scale) // ❌
}

垂直方向只允许以下三种写法：

场景	写法
相对相邻元素的固定 gap	make.top.equalTo(prev.snp.bottom).offset(figma_gap)
相对 safeArea	make.bottom.equalTo(view.safeAreaLayoutGuide.snp.bottom).offset(-figma_gap)
元素本身的 height/width	make.height.equalTo(figma_h)（直接用 Figma 实测值，不乘 scale）

理由：scale = 屏宽 / 375 仅反映横向像素缩放。如果把它用在 y / height，iPhone SE（375）和 iPhone 16 Pro Max（430）会产生 ~14% 的纵向偏差，严重时按钮会被吃掉、内容跑出 safeArea。设计稿的 y / height 是固定 pt，不应随屏宽缩放。

2. 禁止把 safeArea.top 当导航栏底

如果设计稿没有原生导航栏（直接是吸顶卡片），用 view.safeAreaLayoutGuide.snp.top 即可；如果有导航栏，用 host.json → utils.status_bar_nav_height 的表达式，不要混用。

3. 禁止凭空给容器加 padding/margin

任何 offset 都要能从 Figma frame.absolute / frame.relative 推出来，禁止"看着别扭加 12pt"。如果数据不对，先回 design.json 找根因，不要在代码里加补丁。

4. Scroll 容器的顶/底必须锚定邻居，禁止硬编码 y/height ⭐️

如果页面上存在 _role.is_sticky_top / is_sticky_bottom 节点（见 audit.json.sticky_keyword_hits，关键字：吸顶 / 吸底 / sticky_top / sticky_bottom），它们之间的 scroll 承载区必须把顶/底约束到这些 sticky 节点上：

// ❌ 错误：scroll 容器用绝对 y/height（已在 341:313 '垂直滚动' 事故中出现）
formScrollView.snp.makeConstraints { make in
    make.top.equalToSuperview().offset(195)
    make.height.equalTo(407)   // iPhone 8 上直接盖掉底部吸底按钮
}

// ✅ 正确：顶对 sticky_top.bottom，底对 sticky_bottom.top
formScrollView.snp.makeConstraints { make in
    make.leading.trailing.equalToSuperview()
    make.top.equalTo(stepStripContainer.snp.bottom).offset(figma_gap_top)
    make.bottom.equalTo(bottomBarContainer.snp.top).offset(-figma_gap_bottom)
}

判定依据：audit.json 里 sticky_keyword_hits[].sibling_rule 会明确列出本规则。

---

⚡ 核心原则