ios-storyboard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iOS Storyboard Best Practices

iOS Storyboard 最佳实践

Legacy interoperability guidance for storyboard-heavy code that still exists in clinic projects. Not for new SwiftUI clinic feature development.

Comprehensive UI design and architecture guide for Xcode Storyboard and Interface Builder, focused on building maintainable, adaptive, and accessible iOS interfaces. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

针对诊所项目中仍存在的大量storyboard代码的遗留系统互操作性指南。不适用于新的SwiftUI诊所功能开发。

这是一份针对Xcode Storyboard和Interface Builder的全面UI设计与架构指南，专注于构建可维护、自适应且无障碍的iOS界面。包含8个类别下的45条规则，按影响优先级排序，为自动化重构和代码生成提供指导。

Clinic Architecture Contract (iOS 26 / Swift 6.2)

诊所架构规范（iOS 26 / Swift 6.2）

All guidance in this skill assumes the clinic modular MVVM-C architecture:

Feature modules import
```
Domain
```
+
```
DesignSystem
```
only (never
```
Data
```
, never sibling features)
App target is the convergence point and owns
```
DependencyContainer
```
, concrete coordinators, and Route Shell wiring
```
Domain
```
stays pure Swift and defines models plus repository,
```
*Coordinating
```
,
```
ErrorRouting
```
, and
```
AppError
```
contracts
```
Data
```
owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
ViewModels call repository protocols directly (no default use-case/interactor layer)

本技能中的所有指南均基于诊所模块化MVVM-C架构：

功能模块仅导入
```
Domain
```
+
```
DesignSystem
```
（绝不导入
```
Data
```
，绝不导入兄弟功能模块）
App目标是聚合点，负责
```
DependencyContainer
```
、具体协调器和Route Shell的连接
```
Domain
```
保持纯Swift实现，定义模型以及repository、
```
*Coordinating
```
、
```
ErrorRouting
```
和
```
AppError
```
规范
```
Data
```
模块负责SwiftData/网络/同步/重试/后台I/O，并实现Domain协议
读写流默认采用 stale-while-revalidate 读取策略和乐观队列写入策略
ViewModels直接调用repository协议（默认不使用用例/交互层）

When to Apply

适用场景

Reference these guidelines when:

Creating or modifying Storyboard scenes in Xcode Interface Builder
Setting up Auto Layout constraints for adaptive layouts
Designing navigation flows with segues and storyboard references
Configuring size classes and trait variations for universal apps
Reviewing storyboard XML diffs and resolving merge conflicts

在以下场景中参考本指南：

在Xcode Interface Builder中创建或修改Storyboard场景
为自适应布局设置Auto Layout约束
使用segues和storyboard引用设计导航流程
为通用应用配置尺寸类和特征变体
查看storyboard XML差异并解决合并冲突

Rule Categories by Priority

按优先级划分的规则类别


arch-
layout-
nav-
adapt-
view-
ally-
vcs-
debug-

Priority	Category	Impact	Prefix
1	Storyboard Architecture	CRITICAL	`arch-`
2	Auto Layout Constraints	CRITICAL	`layout-`
3	Navigation & Segues	HIGH	`nav-`
4	Adaptive Layout & Size Classes	HIGH	`adapt-`
5	View Hierarchy & Stack Views	MEDIUM-HIGH	`view-`
6	Accessibility & VoiceOver	MEDIUM	`ally-`
7	Version Control & Collaboration	MEDIUM	`vcs-`
8	Debugging & Inspection	LOW-MEDIUM	`debug-`


arch-
layout-
nav-
adapt-
view-
ally-
vcs-
debug-

优先级	类别	影响级别	前缀
1	Storyboard架构	关键	`arch-`
2	Auto Layout约束	关键	`layout-`
3	导航与Segues	高	`nav-`
4	自适应布局与尺寸类	高	`adapt-`
5	视图层级与栈视图	中高	`view-`
6	无障碍与VoiceOver	中	`ally-`
7	版本控制与协作	中	`vcs-`
8	调试与检查	中低	`debug-`

Quick Reference

快速参考

1. Storyboard Architecture (CRITICAL)

1. Storyboard架构（关键）

```
arch-split-storyboards
```
- Split Monolithic Storyboards into Feature Modules
```
arch-storyboard-references
```
- Use Storyboard References for Cross-Module Navigation
```
arch-one-scene-per-flow
```
- Limit Each Storyboard to a Single User Flow
```
arch-initial-view-controller
```
- Set Initial View Controller Explicitly in Every Storyboard
```
arch-avoid-hardcoded-identifiers
```
- Avoid Hardcoded Storyboard and Cell Identifiers
```
arch-scene-naming
```
- Use Descriptive Scene Labels in Document Outline
```
arch-modular-xibs
```
- Extract Reusable Views into Separate XIB Files

```
arch-split-storyboards
```
- 将单体Storyboard拆分为功能模块
```
arch-storyboard-references
```
- 使用Storyboard引用实现跨模块导航
```
arch-one-scene-per-flow
```
- 每个Storyboard仅对应单个用户流程
```
arch-initial-view-controller
```
- 为每个Storyboard显式设置初始视图控制器
```
arch-avoid-hardcoded-identifiers
```
- 避免硬编码Storyboard和Cell标识符
```
arch-scene-naming
```
- 在文档大纲中使用描述性的场景标签
```
arch-modular-xibs
```
- 将可复用视图提取到独立的XIB文件中

2. Auto Layout Constraints (CRITICAL)

2. Auto Layout约束（关键）

```
layout-avoid-fixed-dimensions
```
- Avoid Fixed Width and Height Constraints
```
layout-leading-trailing
```
- Use Leading and Trailing Instead of Left and Right
```
layout-safe-area
```
- Constrain Views to Safe Area Guides
```
layout-content-hugging
```
- Set Content Hugging and Compression Resistance Priorities
```
layout-constraint-nearest-neighbor
```
- Constrain to Nearest Neighbor Views
```
layout-avoid-constant-offsets
```
- Use Layout Margins Instead of Constant Offsets
```
layout-inequality-constraints
```
- Use Inequality Constraints for Flexible Minimums and Maximums
```
layout-constraint-priorities
```
- Assign Distinct Priorities to Optional Constraints

```
layout-avoid-fixed-dimensions
```
- 避免固定宽度和高度约束
```
layout-leading-trailing
```
- 使用Leading和Trailing替代Left和Right
```
layout-safe-area
```
- 将视图约束到安全区域指南
```
layout-content-hugging
```
- 设置内容拥抱和压缩阻力优先级
```
layout-constraint-nearest-neighbor
```
- 将视图约束到最近的相邻视图
```
layout-avoid-constant-offsets
```
- 使用布局边距替代固定偏移量
```
layout-inequality-constraints
```
- 使用不等式约束实现灵活的最小值和最大值
```
layout-constraint-priorities
```
- 为可选约束分配不同的优先级

3. Navigation & Segues (HIGH)

3. 导航与Segues（高）

```
nav-prepare-for-segue
```
- Pass Data via prepare(for:sender:) Instead of Direct Property Access
```
nav-unwind-segues
```
- Use Unwind Segues to Navigate Backward
```
nav-avoid-mixed-navigation
```
- Avoid Mixing Segue and Programmatic Navigation
```
nav-adaptive-segues
```
- Use Show and Show Detail Instead of Push and Modal
```
nav-perform-segue-validation
```
- Validate Segue Conditions with shouldPerformSegue
```
nav-container-view-controllers
```
- Use Container Views for Embedded Child View Controllers

```
nav-prepare-for-segue
```
- 通过prepare(for:sender:)传递数据，而非直接访问属性
```
nav-unwind-segues
```
- 使用Unwind Segues实现向后导航
```
nav-avoid-mixed-navigation
```
- 避免混合使用Segue和程序化导航
```
nav-adaptive-segues
```
- 使用Show和Show Detail替代Push和Modal
```
nav-perform-segue-validation
```
- 使用shouldPerformSegue验证Segue触发条件
```
nav-container-view-controllers
```
- 使用容器视图嵌入子视图控制器

4. Adaptive Layout & Size Classes (HIGH)

4. 自适应布局与尺寸类（高）

```
adapt-size-classes
```
- Configure Constraints per Size Class Using Vary for Traits
```
adapt-trait-variations
```
- Use Trait Variations for Font and Spacing Adjustments
```
adapt-safe-area-all-devices
```
- Test Adaptive Layouts on All Device Size Classes
```
adapt-readable-content-guide
```
- Use Readable Content Guide for Text on Large Screens
```
adapt-dynamic-type
```
- Support Dynamic Type for All Text Labels

```
adapt-size-classes
```
- 使用Vary for Traits为不同尺寸类配置约束
```
adapt-trait-variations
```
- 使用特征变体调整字体和间距
```
adapt-safe-area-all-devices
```
- 在所有设备尺寸类上测试自适应布局
```
adapt-readable-content-guide
```
- 为大屏幕文本使用可读内容指南
```
adapt-dynamic-type
```
- 为所有文本标签支持动态类型

5. View Hierarchy & Stack Views (MEDIUM-HIGH)

5. 视图层级与栈视图（中高）

```
view-prefer-stack-views
```
- Use Stack Views Instead of Manual Constraints for Linear Layouts
```
view-avoid-deep-nesting
```
- Avoid Deeply Nested Stack Views Beyond Two Levels
```
view-intrinsic-content-size
```
- Rely on Intrinsic Content Size for Standard UIKit Controls
```
view-placeholder-intrinsic-size
```
- Use Placeholder Intrinsic Size for Custom Views in Storyboard
```
view-clip-to-bounds
```
- Enable Clip to Bounds for Views with Corner Radius
```
view-content-mode
```
- Set Correct Content Mode for UIImageView in Storyboard

```
view-prefer-stack-views
```
- 对于线性布局，优先使用栈视图而非手动约束
```
view-avoid-deep-nesting
```
- 避免栈视图嵌套超过两层
```
view-intrinsic-content-size
```
- 依赖标准UIKit控件的固有内容尺寸
```
view-placeholder-intrinsic-size
```
- 为Storyboard中的自定义视图设置占位符固有尺寸
```
view-clip-to-bounds
```
- 为带圆角的视图启用Clip to Bounds
```
view-content-mode
```
- 在Storyboard中为UIImageView设置正确的内容模式

6. Accessibility & VoiceOver (MEDIUM)

6. 无障碍与VoiceOver（中）

```
ally-labels
```
- Set Accessibility Labels for All Interactive Elements
```
ally-traits
```
- Assign Correct Accessibility Traits in Interface Builder
```
ally-grouping
```
- Group Related Elements for VoiceOver Navigation
```
ally-identifiers
```
- Set Accessibility Identifiers for UI Testing
```
ally-dynamic-labels
```
- Update Accessibility Labels for Dynamic Content

```
ally-labels
```
- 为所有交互元素设置无障碍标签
```
ally-traits
```
- 在Interface Builder中分配正确的无障碍特征
```
ally-grouping
```
- 为VoiceOver导航分组相关元素
```
ally-identifiers
```
- 设置无障碍标识符用于UI测试
```
ally-dynamic-labels
```
- 为动态内容更新无障碍标签

7. Version Control & Collaboration (MEDIUM)

7. 版本控制与协作（中）

```
vcs-one-scene-per-developer
```
- Assign Storyboard Scenes to Individual Developers
```
vcs-open-as-source
```
- Review Storyboard Diffs as Source Code Before Committing
```
vcs-lock-storyboard-files
```
- Use Git File Locking for Active Storyboard Edits
```
vcs-gitattributes-merge
```
- Configure .gitattributes to Use Union Merge for Storyboards

```
vcs-one-scene-per-developer
```
- 为每个开发人员分配单个Storyboard场景
```
vcs-open-as-source
```
- 提交前以源代码形式查看Storyboard差异
```
vcs-lock-storyboard-files
```
- 对正在编辑的Storyboard文件使用Git文件锁定
```
vcs-gitattributes-merge
```
- 配置.gitattributes为Storyboards使用Union Merge

8. Debugging & Inspection (LOW-MEDIUM)

8. 调试与检查（中低）

```
debug-view-hierarchy
```
- Use Debug View Hierarchy to Inspect Layout Issues
```
debug-ambiguous-layout
```
- Use hasAmbiguousLayout to Detect Constraint Problems at Runtime
```
debug-constraint-identifier
```
- Assign Identifiers to Constraints for Readable Logs
```
debug-stale-outlets
```
- Remove Stale Outlet Connections to Prevent Crashes

```
debug-view-hierarchy
```
- 使用调试视图层级检查布局问题
```
debug-ambiguous-layout
```
- 使用hasAmbiguousLayout在运行时检测约束问题
```
debug-constraint-identifier
```
- 为约束分配标识符以生成易读的日志
```
debug-stale-outlets
```
- 移除失效的Outlet连接以防止崩溃

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

查看单个参考文件获取详细说明和代码示例：

章节定义 - 类别结构和影响级别
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息