ios-design

Apple SwiftUI iOS 设计最佳实践

面向构建者的指南，介绍如何使用 SwiftUI 实现符合 Apple 品质标准的 iOS 界面。本指南以两部奠基性设计著作为基础：

• Ken Kocienda — Creative Selection（对用户的共情、代码编写的匠心、选择最佳方案的品味，以及通过迭代完善来打造演示的文化）
• John Edson — Design Like Apple（系统思维、产品就是营销、坦诚地呈现设计、坚定地进行设计）

本指南涵盖 8 个基于原则的类别，共 62 条规则。每条规则都会指出一个具体的反模式，依据明确命名的原则阐述修正方法，并提供正确的 iOS 26 / Swift 6.2 SwiftUI 实现。

适用范围与关联技能

此技能是构建与实现指南——指导你从零开始，使用符合 Apple 品质标准的模式构建新的 SwiftUI 界面。与 ios-ui-refactor（用于审查和重构现有 UI）一起加载时，此技能负责全新实现，之后由 ios-ui-refactor 进行审查。构建新屏幕时使用此技能；评估并改进现有屏幕时使用关联技能。

Clinic 架构约定（iOS 26 / Swift 6.2）

此技能中的所有指导均基于 Clinic 模块化 MVVM-C 架构：

• 功能模块只导入 Domain + DesignSystem（绝不导入 Data 或其他功能模块）
• App 目标是汇聚点，并负责管理 DependencyContainer、具体的协调器以及 Route Shell wiring
• Domain 保持纯 Swift，定义模型以及 repository、*Coordinating、ErrorRouting 和 AppError 契约
• Data 负责 SwiftData/网络/同步/重试/后台 I/O，并实现 Domain 协议
• 读写流程默认采用过期时后台重新验证的读取方式，以及乐观排队写入
• ViewModel 直接调用 repository 协议（默认不设用例/交互器层）

适用场景

在以下情况下可参考这些指南：

• 从零开始构建新的 SwiftUI 视图和屏幕
• 在语义化颜色、系统排版和间距网格之间进行选择（Edson 的系统思维）
• 使用 @State、@Binding、@Observable、@Environment 管理状态（Kocienda 的匠心）
• 选择合适的组件：List 还是 LazyVStack、Sheet 还是 FullScreenCover（Kocienda 的品味）
• 使用 @ViewBuilder、自定义修饰符和值类型组合视图（Kocienda 的创意选择）
• 使用 NavigationStack、TabView 和工作表实现导航（Edson 的对话）
• 使用堆栈、网格、框架和自适应布局安排内容（Edson 的坦诚呈现设计）
• 确保支持 VoiceOver、触控目标、深色模式和减少动态效果（Kocienda 的共情）
• 添加转场、加载状态和精致的动画（Edson 的产品就是营销）

按优先级排列的规则类别

优先级	类别	原则	影响	前缀	规则数
1	每个像素都体现共情	Kocienda「共情」· Edson「设计关乎人」	CRITICAL	empathy-	8
2	视觉系统	Edson「系统思维」· Kocienda「收敛」	CRITICAL	system-	8
3	匠心：状态是基础	Kocienda「匠心」	CRITICAL	craft-	7
4	创意组合	Kocienda「创意选择」	HIGH	compose-	6
5	品味：做出正确选择	Kocienda「品味」· Edson「坚定地进行设计」	HIGH	taste-	8
6	导航即对话	Edson「设计是一种对话」· Kocienda「演示」	HIGH	converse-	9
7	坦诚呈现设计：布局	Edson「坦诚呈现设计」· Kocienda「交汇」	HIGH	layout-	8
8	产品传达自身价值	Edson「产品就是营销」· Kocienda「演示文化」	MEDIUM	product-	8

快速参考

1. 每个像素都体现同理心（CRITICAL）

Kocienda：“同理心——试着从他人的视角看世界。” Edson：设计始于手持设备的人。

• empathy-semantic-colors - 使用语义颜色，绝不使用硬编码值
• empathy-dark-mode - 从第一天起就支持深色模式
• empathy-foreground-style - 使用 foregroundStyle，而非 foregroundColor
• empathy-safe-areas - 始终确保内容位于安全区域内
• empathy-voiceover-labels - 为每个交互元素添加 VoiceOver 标签
• empathy-touch-targets - 确保触控目标至少为 44x44 点
• empathy-reduce-motion - 始终提供减少动态效果的替代方案
• empathy-readable-width - 在 iPad 上将文本限制在易读宽度内

2. 视觉系统（CRITICAL）

Edson：“缩小视图，观察对象之间的关系。” Kocienda：融合——通过多个决策不断收敛，形成一个协调统一的整体。

• system-typography - 使用系统排版样式，绝不使用固定字号
• system-visual-hierarchy - 通过大小、字重和颜色建立清晰的视觉层级
• system-spacing-grid - 所有间距均使用 4pt 基准单位
• system-material-backgrounds - 使用材质背景营造景深和层次
• system-sf-symbols - 使用 SF Symbols，确保图标风格一致
• system-gradients - 使用渐变营造景深，而非单纯装饰
• system-standard-margins - 始终一致地使用系统标准边距
• system-stack-config - 明确配置堆栈对齐方式和间距

3. 精益求精：以状态为基础（CRITICAL）

Kocienda：“精益求精——运用技能，打造高品质成果。”

• craft-state-local - 对视图局部值类型使用 @State
• craft-state-binding - 对子视图的状态修改使用 @Binding
• craft-state-environment - 对应用范围内共享的数据使用 @Environment
• craft-state-observable - 对模型类使用 @Observable
• craft-avoid-body-state - 绝不在视图 body 内创建状态
• craft-minimize-scope - 尽量缩小状态作用域，减少重新渲染
• craft-state-bindable - 对 @Observable 绑定使用 @Bindable

4. 创意组合（HIGH）

Kocienda：“创造性选择——优秀的软件通过组合与重新组合而成。”

• compose-body-some-view - 从 body 返回 some View，绝不返回具体类型
• compose-custom-properties - 使用属性让视图可配置
• compose-modifier-order - 按正确顺序应用视图修饰符
• compose-viewbuilder - 使用 @ViewBuilder 实现灵活的插槽式组合
• compose-prefer-value-types - 视图数据优先使用值类型
• compose-prefer-composition - 视图复用优先采用组合，而非继承

5. 品味：做出正确选择（HIGH）

Kocienda：“品味——经过锤炼的判断力，也就是选择唯一正确方案的能力。” Edson：选定一种方案，并将其做到尽善尽美。

• taste-list-vs-lazyvstack - 系统功能选择 List，自定义布局选择 LazyVStack
• taste-sheet-vs-fullscreen - 任务选择 sheet，沉浸式体验选择 fullScreenCover
• taste-picker - 根据数据类型选择合适的选择器样式
• taste-grid-vs-lazygrid - 对齐数据选择 Grid，可滚动集合选择 LazyVGrid
• taste-button - 使用与操作重要性相匹配的按钮样式
• taste-textfield - 使用合适的键盘和内容类型配置文本输入
• taste-alerts - 仅在信息至关重要且会阻断操作时使用警告框
• taste-action-sheets - 使用确认对话框呈现与上下文相关的多选操作

6. 将导航视为对话（HIGH）

Edson：“设计是产品与使用者之间的对话。” Kocienda：演示是关于界面能否清晰表达的对话。

• converse-navigationstack - 使用 NavigationStack 实现可编程、类型安全的导航
• converse-tabview - 使用 TabView 组织应用分区，实现并行导航
• converse-sheet-item - 使用 item 绑定，根据数据呈现 sheet
• converse-dismiss - 使用环境中的 dismiss 关闭模态视图
• converse-toolbar - 将工具栏项放置在正确的语义位置
• converse-tab-bar - 使用标签栏进行顶层分区导航
• converse-nav-bar - 配置导航栏以传达上下文
• converse-hierarchy - 编写代码前设计清晰的导航层级
• converse-search - 使用 searchable 修饰符集成搜索

7. 直观呈现设计：布局（HIGH）

Edson：“直观呈现设计——不断制作原型，直到布局显得水到渠成。” Kocienda：技术与人文艺术的交汇点。

• layout-stacks - 使用堆栈代替手动定位
• layout-spacer - 使用 Spacer 灵活分配空间
• layout-frame-sizing - 使用 frame() 明确指定尺寸约束
• layout-zstack - 使用 ZStack 有目的地组合分层内容
• layout-grid - 使用 Grid 展示对齐且不滚动的表格内容
• layout-lazy-grids - 使用 LazyVGrid 构建可滚动的多列布局
• layout-adaptive - 使用自适应布局适配不同尺寸类别
• layout-scroll-indicators - 为较长的可滚动内容显示滚动指示器

8. 产品本身会说话（MEDIUM）

Edson：“产品本身就是营销。”Kocienda：每个动画和加载状态都经过精心设计，以经受 Steve Jobs 的审视。

• product-transitions - 为视图的显示使用语义化过渡
• product-loading-states - 显示真实的加载状态，而不是无限旋转的加载指示器
• product-with-animation - 使用 withAnimation 实现由状态明确驱动的动画
• product-matched-geometry - 使用 matchedGeometryEffect 实现具有上下文起点的过渡
• product-list-cells - 使用标准布局设计列表单元格
• product-content-unavailable - 使用 ContentUnavailableView 显示空状态和错误状态
• product-segmented - 使用分段控件呈现清晰可见、互斥的选项
• product-menus - 使用菜单呈现次要操作，避免界面杂乱

使用方法

阅读各个参考文件，了解详细说明和代码示例：

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

参考文件

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