ios-ui-refactor

Apple HIG SwiftUI iOS 26 / Swift 6.2 最佳实践

从首席设计师的视角，依据 Rams、Segall 和 Edson 的理念，以 Apple 级标准评估和重构 SwiftUI 界面。包含 8 个类别中的 51 条规则，每条规则都基于三部奠基性设计著作中的具体原则：

• Dieter Rams — Ten Principles for Good Design（“少即是多”，“设计应当诚实”）
• Ken Segall — Insanely Simple（简约是打造直观、美观产品的核心原则）
• John Edson — Design Like Apple（以设计为核心的文化、通过原型打磨至完美、产品就是营销）

类别按照视觉审查流程排序：先考虑要移除什么，再考虑要阐明什么、如何做到诚实、不可见、系统化、面面俱到、历久弥新，最后再考虑如何精益求精。

范围与相关技能

这项技能是重构与审查视角——用于评估现有 UI，并找出需要修正的视觉反模式。与 ios-design（构建新 UI）、ios-hig（符合 HIG）或 swift-refactor（代码级重构）一起加载时，这项技能会以更详尽的“错误 -> 正确”转换方式和“何时不适用”指导，取代重叠规则。使用这项技能审查和改进现有屏幕；从零开始实现时则使用相关技能。

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

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

• 功能模块仅导入 Domain + DesignSystem（绝不导入 Data，也不导入其他功能模块）
• App target 是汇合点，负责管理 DependencyContainer、具体协调器和 Route Shell 接线
• Domain 保持纯 Swift，并定义模型，以及 repository、*Coordinating、ErrorRouting 和 AppError 契约
• Data 负责管理 SwiftData/网络/同步/重试/后台 I/O，并实现 Domain 协议
• 读写流程默认采用“过时数据优先、后台重新验证”的读取方式，以及乐观排队写入
• ViewModel 直接调用 repository 协议（不设置默认的 use case/interactor 层）

何时使用

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

• 审查现有 SwiftUI 屏幕的视觉质量问题
• 检查屏幕上的每个元素是否都有存在的价值（Rams #10）
• 评估界面是否无需工具提示即可自我说明（Rams #4）
• 检查颜色、状态和层级是否如实传达信息（Rams #6）
• 确保动画和材质不可察觉，而非装饰性元素（Rams #5）
• 验证间距、圆角和颜色是否构成连贯的系统（Edson“系统思维”）
• 确认已处理边缘情况——减少动态效果、触控目标、安全区域（Rams #8）
• 采用能够改进此前无法实现的交互的 iOS 26 / Swift 6.2 API（Edson“直言设计”）

规则类别优先级

优先级	类别	原则	影响	前缀	规则数
1	少即是多	Rams #10 + Segall“极简思维”	严重	less-	7
2	不言自明的设计	Rams #4 + Segall“以人为本”	严重	evident-	6
3	诚实的界面	Rams #6 + Segall“直言不讳”	严重	honest-	6
4	不可察觉的设计	Rams #5 + Edson“产品就是营销”	高	invisible-	6
5	系统，而非零件	Edson“系统思维” + Rams #8	高	system-	6
6	细节也要面面俱到	Rams #8 + Rams #2	高	thorough-	7
7	历久弥新，而非追逐潮流	Rams #7 + Edson“坚定设计”	中高	enduring-	5
8	通过迭代精益求精	Edson“直言设计” + Rams #1/#3	中	refined-	8

快速参考

1. 少即是多（关键）

Rams 第 10 条：“优秀的设计，应尽可能少。”Segall：Apple 的成功，源于对一千件事说“不”。

• less-single-focal - 每个屏幕只有一个主要焦点
• less-type-restraint - 每个屏幕的不同字体样式不超过 3-4 种
• less-one-typeface - 每个应用只使用一种字体，通过字重和字号来区分
• less-color-restraint - 将高饱和度颜色留给小型交互元素
• less-one-color-purpose - 每种语义颜色只用于一种目的
• less-purposeful-motion - 每个动画都必须传达状态变化或提供反馈
• less-fewer-controls - 移除不服务于核心任务的控件

2. 一目了然的设计（关键）

Rams 第 4 条：“优秀的设计让产品易于理解。”Segall：界面必须使用人们能理解的语言。

• evident-visual-weight - 结合大小、字重和对比度来构建层级
• evident-whitespace-grouping - 使用留白分隔概念分组
• evident-progressive-disclosure - 对密集信息采用渐进式呈现
• evident-reading-order - 让视觉权重与逻辑阅读顺序保持一致
• evident-navigation-intent - 任务和创建使用模态表单，层级下钻使用推入式导航
• evident-label-clarity - 使用清晰标签，而不是含糊不清的图标

3. 诚实的界面（关键）

Rams 第 6 条：“优秀的设计是诚实的。”Segall：不加粉饰，清晰直白。

• honest-semantic-colors - 使用语义颜色，绝不硬编码黑色或白色
• honest-contrast - 确保符合 WCAG AA 对比度要求
• honest-dark-mode - 为每种自定义颜色定义浅色和深色变体
• honest-foreground-style - 使用 foregroundStyle，而不是 foregroundColor
• honest-depth-cues - 使用材质实现分层，而不是用投影营造深度
• honest-loading-states - 显示真实进度，而不是无限旋转的加载图标

4. 隐形的设计（高）

Rams 第 5 条：“优秀的设计不突兀。”Edson：产品本身就是营销。

• invisible-spring-physics - 所有 UI 转场默认使用弹簧动画
• invisible-spring-presets - 常规场景使用 .smooth，交互场景使用 .snappy，营造愉悦感时使用 .bouncy
• invisible-no-easing - UI 元素优先使用弹簧动画，而不是线性动画和 easeInOut
• invisible-system-materials - 使用系统材质，而不是自定义半透明背景
• invisible-symbol-effects - 使用内置的 symbolEffect，而不是手动制作符号动画
• invisible-content-transitions - 使用 contentTransition 实现文本和数字变化

5. 系统，而非零散部分（HIGH）

Edson：“设计就是系统思维。” Rams #8：任何事情都不应随意或听天由命。

• system-spacing-grid - 所有间距均使用 4pt 基础单位
• system-consistent-padding - 所有屏幕均使用一致的内边距
• system-corner-radii - 按组件类型统一圆角半径
• system-alignment - 同一屏幕内，相同内容类型保持对齐一致
• system-color-naming - 根据用途而非色调命名自定义颜色
• system-brand-integration - 将品牌调色板映射到 iOS 语义颜色角色

6. 注重每一处细节（HIGH）

Rams #8：“设计过程中的细致与准确，体现了对用户的尊重。” Rams #2：如果用户无法可靠地使用产品，产品就失败了。

• thorough-reduce-motion - 始终提供减少动态效果时的替代方案
• thorough-touch-targets - 所有交互元素至少为 44x44 点
• thorough-safe-areas - 始终遵循安全区域
• thorough-readable-weights - 正文避免使用过细的字体字重
• thorough-vibrancy-levels - 根据内容的重要性匹配鲜明度级别
• thorough-material-thickness - 根据对比度需求选择材质厚度
• thorough-background-interaction - 为窥视式工作表启用背景交互

7. 经久耐用，而非追逐潮流（MEDIUM-HIGH）

Rams #7：“好设计经久不衰。” Edson：坚持一种能够贯穿多代产品的风格。

• enduring-system-text-styles - 使用 Apple 文本样式，绝不使用固定字号
• enduring-weight-not-caps - 使用字重强调，而非全大写
• enduring-swipe-back - 绝不破坏系统的返回滑动手势
• enduring-zoom-navigation - 使用缩放转场实现从集合到详情的导航
• enduring-card-modularity - 使用独立封装的卡片构建仪表板布局

8. 通过迭代不断打磨（MEDIUM）

Edson：“让设计充分呈现”——不断制作原型，直到每次交互都恰到好处。Rams #1：创新应服务于真正的目的。

• refined-scroll-transitions - 使用 scrollTransition 实现滚动位置的视觉效果
• refined-phase-animator - 使用 PhaseAnimator 实现多步骤动画序列
• refined-mesh-gradients - 使用 MeshGradient 构建高品质动态背景
• refined-text-renderer - 仅将 TextRenderer 用于主视觉文本动画
• refined-inspector - 使用 inspector 显示尾端详情面板
• refined-multi-detent - 提供多个工作表停靠位置，并显示拖动指示器
• refined-matched-geometry - 使用 matchedGeometryEffect 实现具有上下文来源的转场
• refined-no-hard-cuts - 状态切换时始终添加动画，即使效果很轻微

使用方法

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

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

参考文件

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