ios-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apple SwiftUI iOS Design Best Practices

Apple SwiftUI iOS 设计最佳实践

Comprehensive guide for building Apple-quality iOS UIs with SwiftUI. Contains 62 rules across 8 categories covering design systems, state management, layout, view composition, navigation, components, accessibility, and animation polish.

这是一份使用SwiftUI构建Apple级iOS UI的综合指南，包含8个类别共62条规则，覆盖设计系统、状态管理、布局、视图组合、导航、组件、无障碍访问和动画优化。

When to Apply

适用场景

Reference these guidelines when:

Building new SwiftUI views and screens
Implementing design systems with semantic colors, typography, and spacing
Managing state with @State, @Binding, @Observable, @Environment
Laying out content with stacks, grids, and adaptive layouts
Composing views with @ViewBuilder and custom modifiers
Implementing navigation with NavigationStack, TabView, sheets
Choosing and configuring SwiftUI components
Ensuring VoiceOver support, touch targets, and reduce motion
Adding semantic transitions and loading state animations

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

构建新的SwiftUI视图和屏幕
实现包含语义化颜色、排版和间距的设计系统
使用@State、@Binding、@Observable、@Environment管理状态
使用栈、网格和自适应布局排布内容
使用@ViewBuilder和自定义修饰符组合视图
使用NavigationStack、TabView、sheets实现导航
选择和配置SwiftUI组件
确保VoiceOver支持、触摸目标适配和减少动画适配
添加语义化过渡和加载状态动画

Rule Categories by Priority

按优先级划分的规则类别


design-
state-
layout-
view-
nav-
comp-
access-
anim-

Priority	Category	Impact	Prefix
1	Design System	CRITICAL	`design-`
2	State & Data Flow	CRITICAL	`state-`
3	Layout & Sizing	HIGH	`layout-`
4	View Composition	HIGH	`view-`
5	Navigation	HIGH	`nav-`
6	Components & Controls	HIGH	`comp-`
7	Accessibility	HIGH	`access-`
8	Animation & Polish	MEDIUM	`anim-`


design-
state-
layout-
view-
nav-
comp-
access-
anim-

优先级	类别	影响级别	前缀
1	设计系统	关键	`design-`
2	状态与数据流	关键	`state-`
3	布局与尺寸	高	`layout-`
4	视图组合	高	`view-`
5	导航	高	`nav-`
6	组件与控件	高	`comp-`
7	无障碍访问	高	`access-`
8	动画与优化	中	`anim-`

Quick Reference

快速参考

1. Design System (CRITICAL)

1. 设计系统（关键）

```
design-semantic-colors
```
- Use semantic and system colors
```
design-typography
```
- Use system typography styles
```
design-visual-hierarchy
```
- Establish clear visual hierarchy
```
design-dark-mode
```
- Support Dark Mode from day one
```
design-material-backgrounds
```
- Use material backgrounds for depth
```
design-sf-symbols
```
- Use SF Symbols for consistent iconography
```
design-safe-areas
```
- Respect safe areas for content layout
```
design-gradients
```
- Apply gradients for visual depth
```
design-foreground-style
```
- Use foregroundStyle over foregroundColor

```
design-semantic-colors
```
- 使用语义化和系统颜色
```
design-typography
```
- 使用系统排版样式
```
design-visual-hierarchy
```
- 建立清晰的视觉层级
```
design-dark-mode
```
- 从一开始就支持深色模式
```
design-material-backgrounds
```
- 使用材质背景增加层次感
```
design-sf-symbols
```
- 使用SF Symbols实现一致的图标系统
```
design-safe-areas
```
- 内容布局时遵循安全区域规则
```
design-gradients
```
- 应用渐变增加视觉深度
```
design-foreground-style
```
- 使用foregroundStyle替代foregroundColor

2. State & Data Flow (CRITICAL)

2. 状态与数据流（关键）

```
state-local
```
- Use @State for view-local value types
```
state-binding
```
- Use @Binding for child view mutations
```
state-environment
```
- Use @Environment for shared app data
```
state-observable
```
- Use @Observable for model classes
```
state-avoid-in-body
```
- Avoid creating state inside view body
```
state-minimize-scope
```
- Minimize state scope to reduce re-renders
```
state-bindable
```
- Use @Bindable for @Observable bindings

```
state-local
```
- 对视图本地值类型使用@State
```
state-binding
```
- 对子视图修改使用@Binding
```
state-environment
```
- 对共享应用数据使用@Environment
```
state-observable
```
- 对模型类使用@Observable
```
state-avoid-in-body
```
- 避免在视图body内部创建状态
```
state-minimize-scope
```
- 最小化作用域以减少重渲染
```
state-bindable
```
- 对@Observable绑定使用@Bindable

3. Layout & Sizing (HIGH)

3. 布局与尺寸（高）

```
layout-8pt-grid
```
- Use 8pt grid for spacing
```
layout-readable-width
```
- Constrain text to readable width on iPad
```
layout-adaptive
```
- Use adaptive layouts for different size classes
```
layout-standard-margins
```
- Use system standard margins
```
layout-scroll-indicators
```
- Show scroll indicators for long content
```
layout-stacks
```
- Use stacks instead of manual positioning
```
layout-stack-config
```
- Configure stack alignment and spacing
```
layout-spacer
```
- Use Spacer for flexible distribution
```
layout-frame-sizing
```
- Use frame() for explicit size constraints
```
layout-zstack
```
- Use ZStack for layered view composition
```
layout-grid
```
- Use Grid for aligned tabular layouts
```
layout-lazy-grids
```
- Use LazyVGrid for scrollable grid layouts

```
layout-8pt-grid
```
- 使用8pt网格规范设置间距
```
layout-readable-width
```
- 在iPad上限制文本为可读宽度
```
layout-adaptive
```
- 针对不同尺寸类使用自适应布局
```
layout-standard-margins
```
- 使用系统标准边距
```
layout-scroll-indicators
```
- 长内容时显示滚动指示器
```
layout-stacks
```
- 使用栈而非手动定位
```
layout-stack-config
```
- 配置栈的对齐方式和间距
```
layout-spacer
```
- 使用Spacer实现灵活分布
```
layout-frame-sizing
```
- 使用frame()设置显式尺寸约束
```
layout-zstack
```
- 使用ZStack实现分层视图组合
```
layout-grid
```
- 使用Grid实现对齐的表格布局
```
layout-lazy-grids
```
- 使用LazyVGrid实现可滚动网格布局

4. View Composition (HIGH)

4. 视图组合（高）

```
view-body-some-view
```
- Return some View from body property
```
view-custom-properties
```
- Use properties to make views configurable
```
view-modifier-order
```
- Apply modifiers in correct order
```
view-viewbuilder
```
- Use @ViewBuilder for flexible composition
```
view-prefer-value-types
```
- Prefer value types for view data
```
view-prefer-composition
```
- Prefer composition over inheritance

```
view-body-some-view
```
- 从body属性返回some View
```
view-custom-properties
```
- 使用属性让视图可配置
```
view-modifier-order
```
- 按正确顺序应用修饰符
```
view-viewbuilder
```
- 使用@ViewBuilder实现灵活组合
```
view-prefer-value-types
```
- 优先使用值类型存储视图数据
```
view-prefer-composition
```
- 优先使用组合而非继承

5. Navigation (HIGH)

5. 导航（高）

```
nav-navigationstack
```
- Use NavigationStack for modern navigation
```
nav-tabview
```
- Organize app sections with TabView
```
nav-sheet-item
```
- Use item binding for sheet presentation
```
nav-dismiss
```
- Use environment dismiss for modal closure
```
nav-toolbar
```
- Place toolbar items correctly
```
nav-tab-bar
```
- Use tab bar for top-level navigation
```
nav-bar
```
- Configure navigation bar
```
nav-hierarchy
```
- Design clear navigation hierarchy
```
nav-search
```
- Integrate search using searchable modifier

```
nav-navigationstack
```
- 使用NavigationStack实现现代导航
```
nav-tabview
```
- 使用TabView组织应用板块
```
nav-sheet-item
```
- 使用item绑定呈现sheet
```
nav-dismiss
```
- 使用环境dismiss关闭模态视图
```
nav-toolbar
```
- 正确放置工具栏项目
```
nav-tab-bar
```
- 使用标签栏实现顶级导航
```
nav-bar
```
- 配置导航栏
```
nav-hierarchy
```
- 设计清晰的导航层级
```
nav-search
```
- 使用searchable修饰符集成搜索

6. Components & Controls (HIGH)

6. 组件与控件（高）

```
comp-list-vs-lazyvstack
```
- Choose List vs LazyVStack by feature needs
```
comp-sheet-vs-fullscreen
```
- Choose sheet vs fullScreenCover
```
comp-picker
```
- Choose the right picker style
```
comp-grid-vs-lazygrid
```
- Choose Grid vs LazyVGrid by data size
```
comp-textfield
```
- Configure text input components
```
comp-button
```
- Use appropriate button styles
```
comp-list-cells
```
- Design list cells with standard layouts
```
comp-alerts
```
- Use alerts sparingly for critical information
```
comp-action-sheets
```
- Use action sheets for contextual choices
```
comp-segmented
```
- Use segmented controls for exclusive options
```
comp-menus
```
- Use menus for secondary actions
```
comp-content-unavailable
```
- Use ContentUnavailableView for empty states

```
comp-list-vs-lazyvstack
```
- 根据功能需求选择List或LazyVStack
```
comp-sheet-vs-fullscreen
```
- 选择sheet或fullScreenCover
```
comp-picker
```
- 选择合适的选择器样式
```
comp-grid-vs-lazygrid
```
- 根据数据量选择Grid或LazyVGrid
```
comp-textfield
```
- 配置文本输入组件
```
comp-button
```
- 使用合适的按钮样式
```
comp-list-cells
```
- 使用标准布局设计列表单元格
```
comp-alerts
```
- 仅在关键信息场景下使用提醒
```
comp-action-sheets
```
- 使用操作表处理上下文选项
```
comp-segmented
```
- 使用分段控件处理互斥选项
```
comp-menus
```
- 使用菜单处理次要操作
```
comp-content-unavailable
```
- 使用ContentUnavailableView处理空状态

7. Accessibility (HIGH)

7. 无障碍访问（高）

```
access-voiceover-labels
```
- Add VoiceOver labels to interactive elements
```
access-touch-targets
```
- Ensure minimum 44pt touch targets
```
access-reduce-motion
```
- Respect reduce motion preference

```
access-voiceover-labels
```
- 为交互元素添加VoiceOver标签
```
access-touch-targets
```
- 确保最小44pt的触摸目标
```
access-reduce-motion
```
- 遵循减少动画的偏好设置

8. Animation & Polish (MEDIUM)

8. 动画与优化（中）

```
anim-transitions
```
- Use semantic transitions for appearing views
```
anim-loading-states
```
- Animate loading and empty states
```
anim-with-animation
```
- Use withAnimation for explicit state changes
```
anim-matched-geometry
```
- Use matchedGeometryEffect for smooth view transitions

```
anim-transitions
```
- 为出现的视图使用语义化过渡
```
anim-loading-states
```
- 为加载和空状态添加动画
```
anim-with-animation
```
- 使用withAnimation处理显式状态变更
```
anim-matched-geometry
```
- 使用matchedGeometryEffect实现平滑视图过渡

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

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

Section definitions - 类别结构和影响级别说明
Rule template - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板