ios-ui-refactor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apple HIG SwiftUI iOS 26 / Swift 6.2 Best Practices

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

A principal designer's lens for evaluating and refactoring SwiftUI interfaces to Apple-quality standards, grounded in Rams, Segall, and Edson. Contains 51 rules across 8 categories, each grounded in specific principles from three foundational design texts:

Dieter Rams — Ten Principles for Good Design ("less, but better," "design should be honest")
Ken Segall — Insanely Simple (simplicity as a core principle for intuitive, beautiful products)
John Edson — Design Like Apple (design-focused culture, prototyping to perfection, the product is the marketing)

Categories are ordered by a visual review process: start with what to remove, then what to clarify, then what to make honest, invisible, systematic, thorough, enduring, and finally what to refine.

这是一套以资深设计师视角打造的指南，基于Rams、Segall和Edson的设计原则，用于评估和重构SwiftUI界面，使其达到苹果品质标准。指南包含8个类别共51条规则，每条规则均源自三本经典设计著作中的特定原则：

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

类别按视觉评审流程排序：先梳理需移除的元素，再明确需清晰化的内容，接着打造诚实、无形、系统化、精细化、持久化的设计，最后完成细节优化。

Scope & Relationship to Sibling Skills

适用范围与关联技能的关系

This skill is the refactoring and review lens — it evaluates existing UI and identifies visual anti-patterns to fix. When loaded alongside

ios-design

(building new UI),

ios-hig

(HIG compliance), or

swift-refactor

(code-level refactoring), this skill supersedes overlapping rules with more detailed "incorrect -> correct" transformations and "When NOT to apply" guidance. Use this skill for auditing and improving existing screens; use the siblings for greenfield implementation.

本技能是重构与评审视角——用于评估现有UI并识别需修复的视觉反模式。当与

ios-design

（构建新UI）、

ios-hig

（HIG合规性）或

swift-refactor

（代码级重构）同时使用时，本技能会以更详细的“错误→正确”转换方案及“何时不适用”指导覆盖重叠规则。本技能适用于审核和优化现有界面；关联技能则适用于全新项目的实现。

Clinic Architecture Contract (iOS 26 / Swift 6.2)

Clinic架构约定（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)

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

功能模块仅导入
```
Domain
```
+
```
DesignSystem
```
（绝不导入
```
Data
```
或兄弟功能模块）
App目标是整合点，负责
```
DependencyContainer
```
、具体协调器及Route Shell的配置
```
Domain
```
为纯Swift代码，定义模型及repository、
```
*Coordinating
```
、
```
ErrorRouting
```
和
```
AppError
```
协议
```
Data
```
模块负责SwiftData/网络/同步/重试/后台I/O，并实现Domain层协议
读写流程默认采用“过时数据优先读取+后台刷新”的读取策略，以及乐观队列式写入策略
ViewModel直接调用repository协议（默认不使用用例/交互器层）

When to Apply

适用场景

Reference these guidelines when:

Reviewing existing SwiftUI screens for visual quality issues
Auditing whether every element on screen earns its place (Rams #10)
Evaluating if the interface is self-explanatory without tooltips (Rams #4)
Checking that colors, states, and hierarchy tell the truth (Rams #6)
Ensuring animations and materials are invisible, not decorative (Rams #5)
Verifying spacing, radii, and colors form a coherent system (Edson "Systems Thinking")
Confirming edge cases — reduce motion, touch targets, safe areas — are handled (Rams #8)
Adopting iOS 26 / Swift 6.2 APIs that refine previously impossible interactions (Edson "Design Out Loud")

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

评审现有SwiftUI界面的视觉质量问题
审核界面上的每个元素是否有存在的必要（Rams第10条原则）
评估界面是否无需提示即可自行理解（Rams第4条原则）
检查颜色、状态和层级是否真实传达信息（Rams第6条原则）
确保动画和材质是功能性的而非装饰性的（Rams第5条原则）
验证间距、圆角和颜色是否构成连贯的系统（Edson“系统思维”）
确认边缘场景——减少动画、触控目标、安全区域——已被妥善处理（Rams第8条原则）
采用iOS 26 / Swift 6.2 API实现此前无法完成的交互优化（Edson“公开设计”）

Rule Categories by Priority

按优先级排序的规则类别


less-
evident-
honest-
invisible-
system-
thorough-
enduring-
refined-

Priority	Category	Principle	Impact	Prefix	Rules
1	Less, But Better	Rams #10 + Segall "Think Minimal"	CRITICAL	`less-`	7
2	Self-Evident Design	Rams #4 + Segall "Think Human"	CRITICAL	`evident-`	6
3	Honest Interfaces	Rams #6 + Segall "Think Brutal"	CRITICAL	`honest-`	6
4	Invisible Design	Rams #5 + Edson "Product Is Marketing"	HIGH	`invisible-`	6
5	Systems, Not Pieces	Edson "Systems Thinking" + Rams #8	HIGH	`system-`	6
6	Thorough to the Last Detail	Rams #8 + Rams #2	HIGH	`thorough-`	7
7	Enduring Over Trendy	Rams #7 + Edson "Design With Conviction"	MEDIUM-HIGH	`enduring-`	5
8	Refined Through Iteration	Edson "Design Out Loud" + Rams #1/#3	MEDIUM	`refined-`	8


less-
evident-
honest-
invisible-
system-
thorough-
enduring-
refined-

优先级	类别	原则	影响级别	前缀	规则数量
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

Quick Reference

快速参考

1. Less, But Better (CRITICAL)

1. 少即是好（关键）

Rams #10: "Good design is as little design as possible." Segall: Apple succeeded by saying no to a thousand things.

```
less-single-focal
```
- One primary focal point per screen
```
less-type-restraint
```
- Limit to 3-4 distinct type treatments per screen
```
less-one-typeface
```
- One typeface per app, differentiate with weight and size
```
less-color-restraint
```
- Reserve saturated colors for small interactive elements
```
less-one-color-purpose
```
- Each semantic color serves exactly one purpose
```
less-purposeful-motion
```
- Every animation must communicate state change or provide feedback
```
less-fewer-controls
```
- Remove controls that do not serve the core task

Rams第10条：“好的设计是尽可能少的设计。”Segall：苹果的成功源于对上千种说“不”。

```
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. Self-Evident Design (CRITICAL)

2. 自明式设计（关键）

Rams #4: "Good design makes a product understandable." Segall: interfaces must speak in terms people understand.

```
evident-visual-weight
```
- Combine size, weight, and contrast for hierarchy
```
evident-whitespace-grouping
```
- Use whitespace to separate conceptual groups
```
evident-progressive-disclosure
```
- Use progressive disclosure for dense information
```
evident-reading-order
```
- Align visual weight with logical reading order
```
evident-navigation-intent
```
- Sheets for tasks and creation, push for drill-down hierarchy
```
evident-label-clarity
```
- Use clear labels over ambiguous icons

Rams第4条：“好的设计让产品易于理解。”Segall：界面必须用用户能理解的语言表达。

```
evident-visual-weight
```
- 结合尺寸、字重和对比度构建层级
```
evident-whitespace-grouping
```
- 使用留白分隔概念组
```
evident-progressive-disclosure
```
- 对密集信息采用渐进式展示
```
evident-reading-order
```
- 视觉权重与逻辑阅读顺序保持一致
```
evident-navigation-intent
```
- 使用弹窗（Sheet）处理任务与创建流程，使用推送（Push）处理层级钻取
```
evident-label-clarity
```
- 使用清晰标签而非模糊图标

3. Honest Interfaces (CRITICAL)

3. 诚实界面（关键）

Rams #6: "Good design is honest." Segall: clarity without sugar-coating.

```
honest-semantic-colors
```
- Use semantic colors, never hard-coded black or white
```
honest-contrast
```
- Ensure WCAG AA contrast ratios
```
honest-dark-mode
```
- Define light and dark variants for every custom color
```
honest-foreground-style
```
- Use foregroundStyle over foregroundColor
```
honest-depth-cues
```
- Use materials for layering, not drop shadows for depth
```
honest-loading-states
```
- Show real progress, not indefinite spinners

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

```
honest-semantic-colors
```
- 使用语义颜色，绝不硬编码黑色或白色
```
honest-contrast
```
- 确保符合WCAG AA对比度标准
```
honest-dark-mode
```
- 为每个自定义颜色定义亮色和暗色变体
```
honest-foreground-style
```
- 使用foregroundStyle而非foregroundColor
```
honest-depth-cues
```
- 使用材质实现分层，而非阴影营造深度
```
honest-loading-states
```
- 展示真实进度，而非无限加载的 spinner

4. Invisible Design (HIGH)

4. 无形设计（高）

Rams #5: "Good design is unobtrusive." Edson: the product itself is the marketing.

```
invisible-spring-physics
```
- Default to spring animations for all UI transitions
```
invisible-spring-presets
```
- Use .smooth for routine, .snappy for interactive, .bouncy for delight
```
invisible-no-easing
```
- Prefer springs over linear and easeInOut for UI elements
```
invisible-system-materials
```
- Use system materials, not custom semi-transparent backgrounds
```
invisible-symbol-effects
```
- Use built-in symbolEffect, not manual symbol animation
```
invisible-content-transitions
```
- Use contentTransition for changing text and numbers

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. Systems, Not Pieces (HIGH)

5. 系统化而非碎片化（高）

Edson: "Design is systems thinking." Rams #8: nothing must be arbitrary or left to chance.

```
system-spacing-grid
```
- Use a 4pt base unit for all spacing
```
system-consistent-padding
```
- Use consistent padding across all screens
```
system-corner-radii
```
- Standardize corner radii per component type
```
system-alignment
```
- Consistent alignment per content type within a screen
```
system-color-naming
```
- Name custom colors by role, not hue
```
system-brand-integration
```
- Map brand palette onto iOS semantic color roles

Edson：“设计是系统思维。”Rams第8条：任何元素都不能是随意或偶然的。

```
system-spacing-grid
```
- 所有间距使用4pt作为基础单位
```
system-consistent-padding
```
- 所有界面使用统一的内边距
```
system-corner-radii
```
- 按组件类型标准化圆角半径
```
system-alignment
```
- 同一界面内的同类内容保持一致对齐方式
```
system-color-naming
```
- 按功能而非色调命名自定义颜色
```
system-brand-integration
```
- 将品牌色映射到iOS语义颜色角色

6. Thorough to the Last Detail (HIGH)

6. 细节至臻完善（高）

Rams #8: "Care and accuracy in the design process show respect for the user." Rams #2: if the user cannot reliably use it, the product has failed.

```
thorough-reduce-motion
```
- Always provide reduce motion fallback
```
thorough-touch-targets
```
- All interactive elements at least 44x44 points
```
thorough-safe-areas
```
- Always respect safe areas
```
thorough-readable-weights
```
- Avoid light font weights for body text
```
thorough-vibrancy-levels
```
- Match vibrancy level to content importance
```
thorough-material-thickness
```
- Choose material thickness by contrast needs
```
thorough-background-interaction
```
- Enable background interaction for peek-style sheets

Rams第8条：“设计过程中的用心和精准是对用户的尊重。”Rams第2条：如果用户无法可靠使用产品，那么产品就是失败的。

```
thorough-reduce-motion
```
- 始终提供减少动画的 fallback 方案
```
thorough-touch-targets
```
- 所有交互元素尺寸至少为44x44点
```
thorough-safe-areas
```
- 始终遵循安全区域规范
```
thorough-readable-weights
```
- 正文文本避免使用轻量字重
```
thorough-vibrancy-levels
```
- 根据内容重要性匹配活力级别
```
thorough-material-thickness
```
- 根据对比度需求选择材质厚度
```
thorough-background-interaction
```
- 为预览式弹窗启用背景交互

7. Enduring Over Trendy (MEDIUM-HIGH)

7. 持久而非跟风（中高）

Rams #7: "Good design is long-lasting." Edson: commit to a voice that persists across product generations.

```
enduring-system-text-styles
```
- Use Apple text styles, never fixed font sizes
```
enduring-weight-not-caps
```
- Use weight for emphasis, not ALL CAPS
```
enduring-swipe-back
```
- Never break the system back-swipe gesture
```
enduring-zoom-navigation
```
- Use zoom transitions for collection-to-detail navigation
```
enduring-card-modularity
```
- Use self-contained cards for dashboard layouts

Rams第7条：“好的设计是持久的。”Edson：坚持能跨产品世代延续的设计风格。

```
enduring-system-text-styles
```
- 使用Apple文本样式，绝不使用固定字体大小
```
enduring-weight-not-caps
```
- 使用字重强调内容，而非全大写
```
enduring-swipe-back
```
- 绝不破坏系统侧滑返回手势
```
enduring-zoom-navigation
```
- 集合视图到详情页的导航使用缩放转场
```
enduring-card-modularity
```
- 仪表盘布局使用独立卡片组件

8. Refined Through Iteration (MEDIUM)

8. 迭代优化（中）

Edson: "Design out loud" — prototype relentlessly until every interaction feels inevitable. Rams #1: innovation serves genuine purpose.

```
refined-scroll-transitions
```
- Use scrollTransition for scroll-position visual effects
```
refined-phase-animator
```
- Use PhaseAnimator for multi-step animation sequences
```
refined-mesh-gradients
```
- Use MeshGradient for premium dynamic backgrounds
```
refined-text-renderer
```
- Use TextRenderer for hero text animations only
```
refined-inspector
```
- Use inspector for trailing-edge detail panels
```
refined-multi-detent
```
- Provide multiple sheet detents with drag indicator
```
refined-matched-geometry
```
- Use matchedGeometryEffect for contextual origin transitions
```
refined-no-hard-cuts
```
- Always animate between states, even minimally

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
```
- 状态切换时始终添加动画，哪怕是最基础的动画

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

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

阅读单个参考文件获取详细说明及代码示例：

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

Reference Files

参考文件

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

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