axiom-hig-ref

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apple Human Interface Guidelines — Comprehensive Reference

Apple人机界面指南 — 全面参考资料

Overview

概述

The Human Interface Guidelines (HIG) define Apple's design philosophy and provide concrete guidance for creating intuitive, accessible, platform-appropriate experiences across all Apple devices.

人机界面指南（HIG）定义了Apple的设计理念，为在所有Apple设备上创建直观、无障碍、适配平台的体验提供具体指导。

Three Core Principles

三大核心原则

Every design decision should support these principles:

1. Clarity Content is paramount. Interface elements should defer to content, not compete with it. Every element has a purpose, unnecessary complexity is eliminated, and users should immediately know what they can do without extensive instructions.

2. Consistency Apps use standard UI elements and familiar patterns. Navigation follows platform conventions, gestures work as expected, and components appear in expected locations. This familiarity reduces cognitive load.

3. Deference The UI should not distract from essential content. Use subtle backgrounds, receding navigation when not needed, restrained branding, and let content be the hero.

From Apple HIG: "Deference makes an app beautiful by ensuring the content stands out while the surrounding visual elements do not compete with it."

每一个设计决策都应遵循以下原则：

1. 清晰性 内容是核心。界面元素应服务于内容，而非与之竞争。每个元素都有明确用途，剔除不必要的复杂性，用户无需复杂说明就能立即知晓可执行的操作。

2. 一致性 应用使用标准UI元素和熟悉的交互模式。导航遵循平台惯例，手势操作符合预期，组件出现在用户预期的位置。这种熟悉性能降低认知负担。

3. 依从性 UI不应分散用户对核心内容的注意力。使用柔和的背景、在不需要时隐藏导航、克制品牌展示，让内容成为焦点。

来自Apple HIG的表述： "依从性让应用更美观，确保内容脱颖而出，同时周围的视觉元素不会与之竞争。"

Design System Philosophy

设计系统理念

From WWDC25: "A systematic approach means designing with intention at every level, ensuring that all elements, from the tiniest control to the largest surface, are considered in relation to the whole."

来自WWDC25："系统化方法意味着在每个层面都有目的地进行设计，确保从最小的控件到最大的界面区域，所有元素都能与整体协调统一。"

Related Skills

Color System

颜色系统

Semantic Colors Explained

语义色详解

Instead of hardcoded color values, use semantic colors that describe the purpose of a color rather than its appearance. Semantic colors automatically adapt to light/dark mode and accessibility settings.

Key insight from WWDC19: "Think of Dark Mode as having the lights dimmed rather than everything being flipped inside out." Colors are NOT simply inverted—table row backgrounds are lighter in both modes.

不要使用硬编码的颜色值，应使用语义色——描述颜色的用途而非外观。语义色会自动适配浅色/深色模式和无障碍设置。

WWDC19的关键见解： "将深色模式视为调暗灯光，而非完全反转所有内容。"颜色并非简单反转——表格行背景在两种模式下都偏浅。

Label Colors (Foreground Content)

标签颜色（前景内容）

Use label colors for text and symbols:

swift

// Primary content (most prominent)
Text("Title")
    .foregroundStyle(.primary)
// Uses `label` color - black in Light Mode, white in Dark Mode

// Secondary content (subtitles, less prominent)
Text("Subtitle")
    .foregroundStyle(.secondary)
// Uses `secondaryLabel` - gray tone

// Tertiary content (placeholder text)
Text("Placeholder")
    .foregroundStyle(.tertiary)
// Uses `tertiaryLabel` - lighter gray

// Quaternary content (disabled text)
Text("Disabled")
    .foregroundStyle(.quaternary)
// Uses `quaternaryLabel` - very light gray

Hierarchy:

label

→

secondaryLabel

→

tertiaryLabel

→

quaternaryLabel

标签颜色用于文本和符号：

swift

// 主要内容（最突出）
Text("Title")
    .foregroundStyle(.primary)
// 使用`label`颜色——浅色模式下为黑色，深色模式下为白色

// 次要内容（副标题，不太突出）
Text("Subtitle")
    .foregroundStyle(.secondary)
// 使用`secondaryLabel`——灰色调

// 三级内容（占位文本）
Text("Placeholder")
    .foregroundStyle(.tertiary)
// 使用`tertiaryLabel`——浅灰色

// 四级内容（禁用文本）
Text("Disabled")
    .foregroundStyle(.quaternary)
// 使用`quaternaryLabel`——极浅灰色

层级关系：

label

→

secondaryLabel

→

tertiaryLabel

→

quaternaryLabel

Background Colors (Primary → Tertiary)

背景颜色（主→三级）

Background colors come in two sets: ungrouped and grouped.

背景颜色分为两组：非分组和分组。

Ungrouped Backgrounds

非分组背景

For standard lists and views:

swift

// Primary background (main background)
Color(.systemBackground)
// Pure white in Light Mode, pure black in Dark Mode

// Secondary background (information structure)
Color(.secondarySystemBackground)
// Light gray in Light Mode, dark gray in Dark Mode

// Tertiary background (further layering)
Color(.tertiarySystemBackground)
// Lighter than secondary, darker in Dark Mode

用于标准列表和视图：

swift

// 主背景（主要背景）
Color(.systemBackground)
// 浅色模式下为纯白色，深色模式下为纯黑色

// 次要背景（信息结构区分）
Color(.secondarySystemBackground)
// 浅色模式下为浅灰色，深色模式下为深灰色

// 三级背景（进一步分层）
Color(.tertiarySystemBackground)
// 比次要背景更浅，深色模式下更深

Grouped Backgrounds

分组背景

For grouped table views (iOS Settings style):

swift

// Primary grouped background
Color(.systemGroupedBackground)

// Secondary grouped background
Color(.secondarySystemGroupedBackground)

// Tertiary grouped background
Color(.tertiarySystemGroupedBackground)

Usage:

swift

// Standard list
List {
    Text("Item")
}
.background(Color(.systemBackground))

// Grouped list (Settings style)
List {
    Section("Section 1") {
        Text("Item")
    }
}
.listStyle(.grouped)

用于分组表格视图（iOS设置样式）：

swift

// 主分组背景
Color(.systemGroupedBackground)

// 次要分组背景
Color(.secondarySystemGroupedBackground)

// 三级分组背景
Color(.tertiarySystemGroupedBackground)

用法示例：

swift

// 标准列表
List {
    Text("Item")
}
.background(Color(.systemBackground))

// 分组列表（设置样式）
List {
    Section("Section 1") {
        Text("Item")
    }
}
.listStyle(.grouped)

Base vs Elevated Backgrounds

基础与提升级背景

There are actually two sets of background colors for layering interfaces:

Base set: Used for background apps/interfaces
Elevated set: Used for foreground apps/interfaces

Why this matters:

In Light Mode, simple drop shadows create visual separation. In Dark Mode, drop shadows are less effective, so the system uses lighter colors for elevated content.

Example: iPad multitasking:

Mail app alone → base color set
Contacts in slide-over → elevated colors (lighter, stands out)
Both side-by-side → both use elevated colors for contrast around splitter
Email compose sheet → elevated colors with overlay dimming

Critical: Some darker colors may not contrast well when elevated. Always test designs in elevated state. Semi-opaque fill and separator colors adapt gracefully.

实际上有两组背景颜色用于界面分层：

基础组： 用于后台应用/界面
提升级组： 用于前台应用/界面

重要性：

在浅色模式下，简单的阴影即可创建视觉区分。在深色模式下，阴影效果较差，因此系统会为提升级内容使用更浅的颜色。

示例：iPad多任务处理

仅打开邮件应用 → 使用基础颜色组
通讯录以侧滑方式打开 → 使用提升级颜色（更浅，更突出）
两者并排显示 → 为了分割线周围的对比度，都使用提升级颜色
邮件撰写面板 → 使用提升级颜色并叠加暗化效果

关键提示： 某些深色在提升状态下可能对比度不足。务必在提升状态下测试设计。半透明填充和分隔线颜色能灵活适配。

Tint Colors (Dynamic Adaptation)

色调颜色（动态适配）

Tint colors are dynamic - they have variants for Light and Dark modes:

swift

// Tint color automatically adapts
Button("Primary Action") {
    // action
}
.tint(.blue)
// Gets lighter in Dark Mode, darker in Light Mode

Custom tint colors: When creating custom tint colors, select colors that work well in both modes. Use a contrast calculator to aim for 4.5:1 or higher contrast ratio. Colors that work in Light Mode may have insufficient contrast in Dark Mode.

色调颜色是动态的——针对浅色和深色模式有不同变体：

swift

// 色调颜色自动适配
Button("Primary Action") {
    // 操作逻辑
}
.tint(.blue)
// 深色模式下变浅，浅色模式下变深

自定义色调颜色： 创建自定义色调颜色时，选择在两种模式下都表现良好的颜色。使用对比度计算器，目标对比度比至少达到4.5:1。在浅色模式下表现良好的颜色，在深色模式下可能对比度不足。

Fill Colors (Semi-Transparent)

填充颜色（半透明）

Fill colors are semi-transparent to contrast well against variable backgrounds:

swift

// System fill colors
Color(.systemFill)
Color(.secondarySystemFill)
Color(.tertiarySystemFill)
Color(.quaternarySystemFill)

When to use: Controls, buttons, and interactive elements that need to appear above dynamic backgrounds.

填充颜色为半透明，以便在多变的背景上形成良好对比度：

swift

// 系统填充颜色
Color(.systemFill)
Color(.secondarySystemFill)
Color(.tertiarySystemFill)
Color(.quaternarySystemFill)

适用场景： 需要显示在动态背景上方的控件、按钮和交互元素。

Separator Colors

分隔线颜色

swift

// Standard separator (semi-transparent)
Color(.separator)

// Opaque separator
Color(.opaqueSeparator)

Opaque separators are used when transparency would create undesirable results (e.g., intersecting grid lines where overlapping semi-transparent colors create optical illusions).

swift

// 标准分隔线（半透明）
Color(.separator)

// 不透明分隔线
Color(.opaqueSeparator)

不透明分隔线用于当透明度会产生不良效果的场景（例如，交叉网格线中，重叠的半透明颜色会产生视觉错觉）。

When to Use Permanent Dark Backgrounds

何时使用永久深色背景

Apple's explicit guidance:

"In rare cases, consider using only a dark appearance in the interface. For example, it can make sense for an app that enables immersive media viewing to use a permanently dark appearance that lets the UI recede and helps people focus on the media."

Examples from Apple's apps:

App	Background	Rationale
Music	Dark	Album art should be visual focus
Photos	Dark	Images are hero content
Clock	Dark	Nighttime use, instrument feel
Stocks	Dark	Data visualization, charts
Camera	Dark	Reduces distraction during capture

For all other apps: Support both Light and Dark modes via system backgrounds.

Apple明确指导：

"在极少数情况下，可以考虑在界面中仅使用深色外观。例如，对于支持沉浸式媒体观看的应用，使用永久深色外观可以让UI弱化，帮助用户专注于媒体内容。"

Apple应用示例：

应用	背景	理由
音乐	深色	专辑封面应为视觉焦点
照片	深色	图片是核心内容
时钟	深色	适配夜间使用，营造工具感
股市	深色	适配数据可视化、图表展示
相机	深色	减少拍摄时的干扰

其他所有应用： 通过系统背景支持浅色和深色两种模式。

Creating Custom Colors

创建自定义颜色

When you need custom colors:

Open Assets.xcassets
Add Color Set
Configure variants:
- Light mode color
- Dark mode color
- High Contrast Light (optional but recommended)
- High Contrast Dark (optional but recommended)

swift

// Use custom color from asset catalog
Color("BrandAccent")
// Automatically uses correct variant

当需要自定义颜色时：

打开Assets.xcassets
添加颜色集
配置变体：
- 浅色模式颜色
- 深色模式颜色
- 高对比度浅色（可选但推荐）
- 高对比度深色（可选但推荐）

swift

// 使用资源目录中的自定义颜色
Color("BrandAccent")
// 自动使用对应变体

Typography

排版

System Fonts

系统字体

San Francisco (SF): The system sans-serif font family.

SF Pro: General use
SF Compact: watchOS and space-constrained layouts
SF Mono: Code and monospaced text
SF Rounded: Softer, friendlier feel
Weights: Ultralight, Thin, Light, Regular, Medium, Semibold, Bold, Heavy, Black

New York (NY): System serif font family for editorial content.

Both available as variable fonts with seamless weight transitions.

San Francisco (SF)： 系统无衬线字体家族。

SF Pro：通用场景使用
SF Compact：watchOS和空间受限的布局使用
SF Mono：代码和等宽文本使用
SF Rounded：更柔和、友好的风格
字重：Ultralight、Thin、Light、Regular、Medium、Semibold、Bold、Heavy、Black

New York (NY)： 用于编辑类内容的系统衬线字体家族。

两者均为可变字体，支持无缝字重过渡。

Font Weight Recommendations

字重推荐

From Apple HIG: "Avoid light font weights. Prefer Regular, Medium, Semibold, or Bold weights instead of Ultralight, Thin, or Light."

Why: Light weights have legibility issues, especially at small sizes, in bright lighting, or for users with visual impairments.

Hierarchy:

swift

// Headers - Bold weight for prominence
Text("Header")
    .font(.title.weight(.bold))

// Subheaders - Semibold
Text("Subheader")
    .font(.title2.weight(.semibold))

// Body - Regular or Medium
Text("Body text")
    .font(.body)

// Captions - Regular (never Light)
Text("Caption")
    .font(.caption)

来自Apple HIG： "避免使用轻量字重。优先选择Regular、Medium、Semibold或Bold字重，而非Ultralight、Thin或Light。"

原因： 轻量字重在小字号、明亮光线或视觉障碍用户使用时，可读性较差。

层级示例：

swift

// 标题 - 使用Bold字重以突出
Text("Header")
    .font(.title.weight(.bold))

// 副标题 - 使用Semibold
Text("Subheader")
    .font(.title2.weight(.semibold))

// 正文 - 使用Regular或Medium
Text("Body text")
    .font(.body)

// 说明文字 - 使用Regular（绝不要用Light）
Text("Caption")
    .font(.caption)

Text Styles for Hierarchy

用于层级的文本样式

Use built-in text styles for automatic hierarchy and Dynamic Type support:

swift

.font(.largeTitle)    // Largest
.font(.title)         // Page titles
.font(.title2)        // Section headers
.font(.title3)        // Sub-section headers
.font(.headline)      // Emphasized body
.font(.body)          // Default body text
.font(.callout)       // Slightly emphasized
.font(.subheadline)   // Less prominent
.font(.footnote)      // Auxiliary info
.font(.caption)       // Minimal emphasis
.font(.caption2)      // Smallest

使用内置文本样式，自动实现层级关系并支持Dynamic Type：

swift

.font(.largeTitle)    // 最大字号
.font(.title)         // 页面标题
.font(.title2)        // 章节标题
.font(.title3)        // 子章节标题
.font(.headline)      // 强调型正文
.font(.body)          // 默认正文
.font(.callout)       // 轻微强调
.font(.subheadline)   // 次要内容
.font(.footnote)      // 辅助信息
.font(.caption)       // 最低强调
.font(.caption2)      // 最小字号

Dynamic Type Support

Dynamic Type支持

Requirement: Apps must support text scaling of at least 200% (iOS, iPadOS) or 140% (watchOS).

Implementation:

swift

// ✅ CORRECT - Scales automatically
Text("Hello")
    .font(.body)

// ❌ WRONG - Fixed size, doesn't scale
Text("Hello")
    .font(.system(size: 17))

Layout considerations:

Reduce multicolumn layouts at larger sizes
Minimize text truncation
Use stacked layouts instead of inline at large sizes
Maintain consistent information hierarchy regardless of size

Not all content scales equally: Prioritize what users actually care about. Secondary elements like tab titles shouldn't grow as much as primary content.

要求： 应用必须支持至少200%的文本缩放（iOS、iPadOS）或140%（watchOS）。

实现方式：

swift

// ✅ 正确用法 - 自动缩放
Text("Hello")
    .font(.body)

// ❌ 错误用法 - 固定字号，无法缩放
Text("Hello")
    .font(.system(size: 17))

布局注意事项：

大字号下减少多列布局
尽量减少文本截断
大字号下使用堆叠布局而非行内布局
无论字号大小，保持一致的信息层级

并非所有内容都需同等缩放： 优先考虑用户真正关注的内容。标签栏标题等次要元素的缩放比例不应与主要内容相同。

Custom Fonts

自定义字体

When using custom fonts:

Ensure legibility at various distances and conditions
Implement Dynamic Type support
Respond to Bold Text accessibility setting
Test at all text sizes
Match system font behaviors for accessibility

If your custom font is thin: Increase size by ~2 points when pairing with uppercase Latin text.

使用自定义字体时：

确保在不同距离和环境下的可读性
实现Dynamic Type支持
响应粗体文本无障碍设置
在所有文本字号下进行测试
匹配系统字体的无障碍行为

如果自定义字体偏细： 搭配大写拉丁文本时，字号增加约2磅。

Leading (Line Spacing)

行间距

Loose leading: Wide columns (easier to track to next line) Tight leading: Constrained height (avoid for 3+ lines)

swift

// Adjust leading for specific layouts
Text("Long content...")
    .lineSpacing(8) // Add space between lines

宽松行间距： 宽列布局（便于换行阅读） 紧凑行间距： 高度受限的布局（避免用于3行以上文本）

swift

// 为特定布局调整行间距
Text("Long content...")
    .lineSpacing(8) // 增加行间距

Shapes & Geometry

形状与几何

Three Shape Types (iOS 26)

三种形状类型（iOS 26）

From WWDC25: "There's a quiet geometry to how our shapes fit together, driven by concentricity. By aligning radii and margins around a shared center, shapes can comfortably nest within each other."

来自WWDC25："我们的形状组合遵循一种隐性的几何规则，由同心性驱动。通过围绕共同中心对齐半径和边距，形状可以自然地嵌套在一起。"

1. Fixed Shapes

1. 固定形状

Constant corner radius regardless of size:

swift

RoundedRectangle(cornerRadius: 12)

Use when: You need a specific, unchanging corner radius.

无论尺寸如何，圆角半径保持不变：

swift

RoundedRectangle(cornerRadius: 12)

适用场景： 需要特定、固定圆角半径的情况。

2. Capsules

2. 胶囊形

Radius is half the container's height:

swift

Capsule()

Use when: You want shapes that adapt to content while maintaining rounded ends. Perfect for buttons, pills, and controls.

Found throughout iOS 26: Sliders, switches, grouped table views, tab bars, navigation bars.

半径为容器高度的一半：

swift

Capsule()

适用场景： 希望形状适配内容同时保持圆角末端的情况。非常适合按钮、药丸状控件和操作项。

iOS 26中的常见应用： 滑块、开关、分组表格视图、标签栏、导航栏。

3. Concentric Shapes

3. 同心形状

Calculate radius by subtracting padding from parent's radius:

swift

.containerRelativeShape(.roundedRectangle)

Use when: Nesting shapes within containers to maintain visual harmony.

通过从父容器半径中减去内边距来计算半径：

swift

.containerRelativeShape(.roundedRectangle)

适用场景： 在容器内嵌套形状以保持视觉协调性的情况。

Concentricity Principle

同心性原则

Hardware ↔ Software harmony: Apple's hardware features consistent bezel curvature. The same precision now guides UI, with curvature, size, and proportion aligning to create unified rhythm between what you hold and what you see.

Example of concentricity:

Window (rounded corners)
  ├─ Sheet (concentric to window)
  │   ├─ Card (concentric to sheet)
  │   │   └─ Button (concentric to card)

硬件与软件的协调性： Apple硬件具有一致的边框曲率。这种精度现在也指导UI设计，曲率、尺寸和比例保持一致，让用户握持的设备与看到的界面形成统一的韵律。

同心性示例：

窗口（圆角）
  ├─ 面板（与窗口同心）
  │   ├─ 卡片（与面板同心）
  │   │   └─ 按钮（与卡片同心）

Platform-Specific Guidance

平台特定指导

iOS:

Capsules for buttons, switches, grouped lists
Creates hierarchy and focus in touch-friendly layouts

macOS:

Mini, Small, Medium controls → Rounded rectangles (dense layouts, inspector panels)
Large, X-Large controls → Capsules (spacious areas, emphasis via Liquid Glass)

iOS：

按钮、开关、分组列表使用胶囊形
在触控友好的布局中创建层级和焦点

macOS：

小型、微型、中型控件 → 圆角矩形（密集布局、检查器面板）
大型、超大型控件 → 胶囊形（宽敞区域，通过Liquid Glass强调）

Optical Centering

视觉居中

To preserve optical balance, views are:

Mathematically centered when it makes sense
Subtly offset when optical weight requires it

Example: Asymmetric icons may need padding adjustments for optical centering rather than geometric centering.

为了保持视觉平衡，视图：

在合理情况下进行数学居中
当视觉重量需要时，进行细微偏移

示例： 不对称图标可能需要调整内边距以实现视觉居中，而非几何居中。

Materials & Depth

材质与深度

Standard Materials

标准材质

Materials allow background content to show through, creating visual depth and hierarchy.

材质允许背景内容透显，创建视觉深度和层级。

Four Thickness Options

四种厚度选项

Ultra-thin — Minimal separation, content clearly visible
Thin — Lighter-weight interactions
Regular — Default, works well in most circumstances
Thick — Most separation from background

Choosing thickness:

Content needs more contrast → thicker material
Simpler content → thin/ultra-thin material

swift

// Apply material
.background(.ultraThinMaterial)
.background(.thinMaterial)
.background(.regularMaterial)
.background(.thickMaterial)

超薄 — 最小程度的分离，内容清晰可见
薄 — 轻量化交互场景
常规 — 默认选项，适用于大多数场景
厚 — 与背景的分离度最高

厚度选择：

内容需要更高对比度 → 使用更厚的材质
内容简单 → 使用薄/超薄材质

swift

// 应用材质
.background(.ultraThinMaterial)
.background(.thinMaterial)
.background(.regularMaterial)
.background(.thickMaterial)

Vibrancy with Materials

材质与活力效果

Key principle: Use vibrant colors on top of materials for legibility. Solid colors can get muddy depending on background context. Vibrancy maintains contrast regardless of background.

swift

// Vibrant text on material
VStack {
    Text("Primary")
        .foregroundStyle(.primary) // Vibrant
    Text("Secondary")
        .foregroundStyle(.secondary) // Vibrant
}
.background(.regularMaterial)

核心原则： 在材质上方使用活力色以保证可读性。纯色在不同背景环境下可能显得浑浊，而活力色无论背景如何都能保持对比度。

swift

// 材质上的活力文本
VStack {
    Text("Primary")
        .foregroundStyle(.primary) // 活力色
    Text("Secondary")
        .foregroundStyle(.secondary) // 活力色
}
.background(.regularMaterial)

Liquid Glass (iOS 26+)

Liquid Glass（iOS 26+）

Purpose: Creates a distinct functional layer for controls and navigation, floating above content.

Two variants:

Regular Liquid Glass
- Default, use in 95% of cases
- Full visual and adaptive effects
- Provides legibility regardless of context
- Works over any background
Clear Liquid Glass
- Highly translucent
- No adaptive behaviors
- Only use for components over visually rich backgrounds (photos, videos)
- Requires dimming layer for legibility

Cross-reference: See

axiom-liquid-glass

skill for implementation details and

axiom-liquid-glass-ref

for comprehensive adoption guide.

用途： 为控件和导航创建独特的功能层，悬浮于内容上方。

两种变体：

常规Liquid Glass
- 默认选项，95%的场景使用
- 完整的视觉和自适应效果
- 无论上下文如何都能保证可读性
- 适用于任何背景
透明Liquid Glass
- 高度半透明
- 无自适应行为
- 仅用于视觉丰富的背景（照片、视频）上的组件
- 需要暗化层以保证可读性

交叉参考： 实现细节请查看

axiom-liquid-glass

技能，全面采用指南请查看

axiom-liquid-glass-ref

。

Layout Principles

布局原则

Visual Hierarchy

视觉层级

Place items to convey their relative importance:

Important content → top and leading side
Secondary content → below or trailing
Tertiary content → separate views or progressive disclosure

From Apple HIG: "Make essential information easy to find by giving it sufficient space and avoid obscuring it with nonessential details."

通过位置传达相对重要性：

重要内容 → 顶部和左侧
次要内容 → 下方或右侧
三级内容 → 单独视图或渐进式展示

来自Apple HIG： "通过给予足够空间让关键信息易于查找，避免用非必要细节遮挡关键信息。"

Grouping & Organization

分组与组织

Group related items using:

Negative space (whitespace)
Colors and materials
Separator lines

Ensure content and controls remain clearly distinct through Liquid Glass material and scroll edge effects.

使用以下方式对相关内容进行分组：

负空间（留白）
颜色和材质
分隔线

确保内容和控件通过Liquid Glass材质和滚动边缘效果保持清晰区分。

Content Extension to Edges

内容延伸至边缘

"Extend content to fill the screen or window" with backgrounds and artwork reaching display edges.

Background extension views: Use when content doesn't naturally span the full window.

swift

// Content extends to edges
VStack {
    FullWidthImage()
        .ignoresSafeArea() // Extends to screen edges
}

"让内容填充屏幕或窗口"，背景和艺术作品延伸至显示边缘。

背景延伸视图： 当内容无法自然铺满整个窗口时使用。

swift

// 内容延伸至边缘
VStack {
    FullWidthImage()
        .ignoresSafeArea() // 延伸至屏幕边缘
}

Safe Areas & Layout Guides

安全区域与布局指南

Safe Areas: Rectangular regions unobstructed by:

Status bar
Navigation bar
Tab bar
Toolbar
Device features (Dynamic Island, notch, home indicator)

Layout Guides: Define rectangular regions for positioning and spacing content with:

Predefined margins
Text width optimization
Reading width constraints

Key principle: "Respect key display and system features in each platform."

swift

// Respect safe areas
VStack {
    Text("Content")
}
.safeAreaInset(edge: .bottom) {
    BottomBar()
}

安全区域： 不受以下元素遮挡的矩形区域：

状态栏
导航栏
标签栏
工具栏
设备特性（灵动岛、刘海、主屏幕指示器）

布局指南： 定义矩形区域，用于定位和间距内容，具备：

预定义边距
文本宽度优化
阅读宽度约束

核心原则： "尊重每个平台的关键显示和系统特性。"

swift

// 尊重安全区域
VStack {
    Text("Content")
}
.safeAreaInset(edge: .bottom) {
    BottomBar()
}

Align Components

组件对齐

"Align components with one another to make them easier to scan."

Grid alignment:

Text baselines align
Controls align on common grid
Spacing is consistent and rhythmic

"让组件彼此对齐，便于用户扫描阅读。"

网格对齐：

文本基线对齐
控件对齐到通用网格
间距一致且有韵律

Adaptability Requirements

适配性要求

Design layouts that:

"Adapt gracefully to context changes while remaining recognizably consistent"
Support Dynamic Type text-size changes
Work across multiple devices, orientations, and localizations
Account for different screen sizes, resolutions, and system features

设计的布局应：

"在上下文变化时灵活适配，同时保持可识别的一致性"
支持Dynamic Type文本大小变化
在多种设备、方向和本地化环境下正常工作
考虑不同的屏幕尺寸、分辨率和系统特性

Accessibility

无障碍设计

Vision Accessibility

视觉无障碍

Text & Legibility

文本与可读性

Requirements:

Support text enlargement of at least 200% (140% for watchOS)
Implement Dynamic Type for systemwide text adjustment
Use font weights that enhance readability (avoid Light weights with custom fonts)

要求：

支持至少**200%**的文本放大（watchOS为140%）
实现Dynamic Type以支持系统级文本调整
使用增强可读性的字重（自定义字体避免使用轻量字重）

Color Contrast

颜色对比度

WCAG Level AA standards:

Normal text (14pt+): 4.5:1 minimum
Small text (<14pt): 7:1 recommended
Large text (18pt+ regular, 14pt+ bold): 3:1 acceptable

Implementation:

swift

// ✅ Use semantic colors (automatic contrast)
Text("Label").foregroundStyle(.primary)

// ❌ Custom colors may fail contrast
Text("Label").foregroundStyle(.gray) // Check with calculator

High contrast mode: Provide higher contrast color schemes when "Increase Contrast" accessibility setting is enabled.

Test in both Light and Dark modes.

WCAG AA级标准：

常规文本（14磅及以上）：最低4.5:1
小文本（小于14磅）：建议7:1
大文本（18磅及以上常规字重、14磅及以上粗体）：3:1可接受

实现方式：

swift

// ✅ 使用语义色（自动满足对比度）
Text("Label").foregroundStyle(.primary)

// ❌ 自定义颜色可能不满足对比度
Text("Label").foregroundStyle(.gray) // 使用计算器检查

高对比度模式： 当"增加对比度"无障碍设置启用时，提供更高对比度的配色方案。

务必在浅色和深色模式下都进行测试。

Color Considerations

颜色使用注意事项

Critical: "Convey information with more than color alone" to support colorblind users.

Solutions:

Use distinct shapes or icons alongside color
Add text labels
Employ system-defined colors with accessible variants
Test with Color Blindness simulators

Example:

swift

// ❌ Only color indicates status
Circle().fill(isActive ? .green : .red)

// ✅ Shape + color
HStack {
    Image(systemName: isActive ? "checkmark.circle.fill" : "xmark.circle.fill")
    Text(isActive ? "Active" : "Inactive")
}
.foregroundStyle(isActive ? .green : .red)

关键提示： "不要仅通过颜色传达信息"，以支持色盲用户。

解决方案：

结合颜色使用独特的形状或图标
添加文本标签
使用具有无障碍变体的系统定义颜色
使用色盲模拟器进行测试

示例：

swift

// ❌ 仅通过颜色指示状态
Circle().fill(isActive ? .green : .red)

// ✅ 形状+颜色
HStack {
    Image(systemName: isActive ? "checkmark.circle.fill" : "xmark.circle.fill")
    Text(isActive ? "Active" : "Inactive")
}
.foregroundStyle(isActive ? .green : .red)

Screen Readers

屏幕阅读器

Describe interface and content for VoiceOver accessibility:

swift

Button {
    share()
} label: {
    Image(systemName: "square.and.arrow.up")
}
.accessibilityLabel("Share")

为VoiceOver无障碍功能描述界面和内容：

swift

Button {
    share()
} label: {
    Image(systemName: "square.and.arrow.up")
}
.accessibilityLabel("Share")

Hearing Accessibility

听觉无障碍

Media Alternatives

媒体替代方案

For video/audio content, provide:

Captions for dialogue
Subtitles
Audio descriptions for visual-only information
Transcripts for longer-form media

对于视频/音频内容，提供：

对话字幕
字幕翻译
仅视觉信息的音频描述
长格式媒体的文字记录

Audio Cues

音频提示

Pair audio signals with:

Haptic feedback
Visual indicators

音频信号需搭配：

触觉反馈
视觉指示器

Mobility Accessibility

行动无障碍

Touch targets:

Minimum: 44x44 points
Spacing: 12-24 points padding around controls

Gestures:

Use simple gestures
Offer alternatives (buttons alongside gestures)
Support Voice Control
Enable keyboard navigation

Assistive technologies:

VoiceOver
Switch Control
Full Keyboard Access

触控目标：

最小尺寸：44x44点
间距：控件周围保留12-24点的内边距

手势：

使用简单手势
提供替代方式（手势搭配按钮）
支持语音控制
启用键盘导航

辅助技术：

VoiceOver
切换控制
全键盘访问

Cognitive Accessibility

认知无障碍

Interaction Design

交互设计

"Keep actions simple and intuitive"
Avoid time-based auto-dismissing views
Prevent autoplay of audio/video without controls

"保持操作简单直观"
避免基于时间的自动关闭视图
无控制情况下，禁止音频/视频自动播放

Motion & Visual Effects

动效与视觉效果

Respect "Reduce Motion":

Minimize animations
Avoid excessive flashing lights
Support "Dim Flashing Lights"
Reduce bounce effects
Minimize z-axis depth changes

swift

// Check Reduce Motion setting
@Environment(\.accessibilityReduceMotion) var reduceMotion

var body: some View {
    content
        .animation(reduceMotion ? nil : .spring(), value: isExpanded)
}

尊重"减少动态效果"设置：

尽量减少动画
避免过度闪烁的灯光
支持"减弱闪烁灯光"
减少弹跳效果
尽量减少Z轴深度变化

swift

// 检查减少动态效果设置
@Environment(\.accessibilityReduceMotion) var reduceMotion

var body: some View {
    content
        .animation(reduceMotion ? nil : .spring(), value: isExpanded)
}

Game Accommodations

游戏适配

Offer adjustable difficulty levels.

提供可调整的难度级别。

visionOS Specific

visionOS特定要求

Prioritize comfort:

Maintain horizontal layouts
Reduce animation speed
Avoid head-anchored content (prevents assistive technology use)

优先考虑舒适性：

保持水平布局
降低动画速度
避免头部锚定内容（防止辅助技术无法使用）

Motion & Animation

动效与动画

Core Principles

核心原则

Purposeful Animation: "Add motion purposefully, supporting the experience without overshadowing it."

Avoid gratuitous animations that distract or cause discomfort. Motion should enhance rather than dominate the interface.

有目的的动画： "有目的地添加动效，为体验提供支持而非喧宾夺主。"

避免无意义的动画，以免分散注意力或引起不适。动效应增强而非主导界面。

Accessibility First

无障碍优先

Make motion optional. Supplement visual feedback with haptics and audio to communicate important information, ensuring all users can understand your interface regardless of motion preferences.

让动效成为可选项。补充触觉反馈和音频反馈以传达重要信息，确保所有用户无论动效偏好如何都能理解界面。

Best Practices for Feedback

反馈最佳实践

Realistic Motion

真实感动效

Design animations aligned with user expectations and gestures. Feedback should be:

"Brief and precise"
Lightweight
Effectively conveying information without distraction

设计符合用户预期和手势的动画。反馈应：

"简洁精准"
轻量化
有效传达信息而不分散注意力

Frequency Considerations

频率考虑

Avoid animating frequent UI interactions. Standard system elements already include subtle animations, so custom elements shouldn't add unnecessary motion to common actions.

避免为频繁的UI交互添加动画。标准系统元素已包含细微动画，因此自定义元素不应为常见操作添加不必要的动效。

User Control

用户控制

"Let people cancel motion" by not forcing them to wait for animations to complete before proceeding, especially for repeated interactions.

swift

// ✅ Allow immediate tap, don't block on animation
Button("Next") {
    withAnimation(.easeOut(duration: 0.2)) {
        showNext = true
    }
}
// User can tap again immediately, not forced to wait

"让用户可以取消动效"，不要强迫用户等待动画完成才能继续操作，尤其是重复交互时。

swift

// ✅ 允许立即点击，不被动画阻塞
Button("Next") {
    withAnimation(.easeOut(duration: 0.2)) {
        showNext = true
    }
}
// 用户可以立即再次点击，无需等待动画完成

Platform-Specific Guidance

平台特定指导

visionOS

Avoid motion at peripheral vision edges — causes discomfort
Use fades when relocating objects rather than visible movement
Maintain stationary frames of reference
Avoid sustained oscillations (especially at 0.2 Hz frequency)
Prevent virtual world rotation (disrupts stability)

避免在周边视觉边缘添加动效——会引起不适
移动对象时使用淡入淡出而非可见的移动
保持静止的参考框架
避免持续振荡（尤其是0.2Hz频率）
防止虚拟世界旋转（破坏稳定性）

watchOS

SwiftUI provides animation capabilities; WatchKit offers

WKInterfaceImage

for layout animations and sequences.

SwiftUI提供动画功能；WatchKit提供

WKInterfaceImage

用于布局动画和序列。

Icons & Symbols

图标与符号

SF Symbols

Advantages:

5,000+ symbols included with system (SF Symbols 5)
Match San Francisco font visual characteristics
Can be typed inline with text
Embedded baseline values for proper vertical alignment
Small, medium, and large-scale variants
Nine weights matching SF font
Vector-based — scale with text and Dynamic Type
Become bolder when Bold Text accessibility enabled
Automatic light/dark adaptation

Usage:

swift

Label("Settings", systemImage: "gear")

Image(systemName: "star.fill")
    .font(.title) // Scales with text size

优势：

系统内置5000+符号（SF Symbols 5）
匹配San Francisco字体的视觉特征
可与文本内联显示
嵌入基线值以实现正确的垂直对齐
提供小、中、大尺寸变体
九种字重匹配SF字体
基于矢量——随文本和Dynamic Type缩放
启用粗体文本无障碍设置时自动加粗
自动适配浅色/深色模式

用法示例：

swift

Label("Settings", systemImage: "gear")

Image(systemName: "star.fill")
    .font(.title) // 随文本字号缩放

Custom Interface Icons

自定义界面图标

Key design principles:

Simplification & Recognition: Create "recognizable, axiom-highly simplified design[s]" to avoid confusion. Icons work best with familiar visual metaphors directly connected to their actions or content.

Visual Consistency: Maintain uniform:

Size
Detail level
Stroke thickness
Perspective across all interface icons

Weight Matching: Align interface icon weights with adjacent text for consistent emphasis unless deliberately emphasizing one element.

Optical Alignment: Asymmetric icons may need padding adjustments for optical centering rather than geometric centering, particularly when visual weight concentrates on one area.

核心设计原则：

简化与辨识度： 创建"易于识别、axiom高度简化的设计"，避免混淆。图标使用与操作或内容直接相关的熟悉视觉隐喻时效果最佳。

视觉一致性： 保持统一的：

尺寸
细节程度
描边粗细
所有界面图标的透视效果

字重匹配： 界面图标的字重应与相邻文本一致，除非刻意强调其中一个元素。

视觉对齐： 不对称图标可能需要调整内边距以实现视觉居中，而非几何居中，尤其是当视觉重量集中在一侧时。

Format & Implementation

格式与实现

Vector formats required: Use PDF or SVG for custom interface icons to enable automatic scaling across display resolutions. PNG requires multiple versions for each icon.

Selected states: System components (toolbars, tab bars, buttons) automatically handle selected appearances—custom versions aren't necessary.

必须使用矢量格式： 使用PDF或SVG作为自定义界面图标，以支持跨显示分辨率的自动缩放。PNG需要为每个图标提供多个版本。

选中状态： 系统组件（工具栏、标签栏、按钮）会自动处理选中状态的外观——无需自定义版本。

When to Use Icons vs Text

何时使用图标 vs 文本

From WWDC25: "A pencil might suggest annotate, and a checkmark can look like confirm—making actions like Select or Edit easy to misread. When there's no clear shorthand, a text label is always the better choice."

Use icons when:

Symbol has clear, universal meaning (share, trash, settings)
Space is constrained
Icon aids quick scanning

Use text when:

Action has no clear symbol
Multiple similar actions exist
Clarity is more important than space

来自WWDC25："铅笔可能暗示注释功能，而对勾看起来像确认——这会让选择或编辑等操作容易被误解。当没有明确的简写符号时，文本标签始终是更好的选择。"

使用图标场景：

符号具有清晰、通用的含义（分享、删除、设置）
空间受限
图标有助于快速扫描

使用文本场景：

操作没有明确的对应符号
存在多个相似操作
清晰度比空间更重要

Accessibility

无障碍设计

Always provide alternative text labels enabling VoiceOver descriptions:

swift

Image(systemName: "star.fill")
    .accessibilityLabel("Favorite")

始终提供替代文本标签，以便VoiceOver进行描述：

swift

Image(systemName: "star.fill")
    .accessibilityLabel("Favorite")

Gestures & Input

手势与输入

Core Gesture Design Principles

核心手势设计原则

Consistency and Familiarity: "People expect most gestures to work the same regardless of their current context." Standard gestures like tap, swipe, and drag should perform their expected functions across platforms.

Responsive Feedback: "Handle gestures as responsively as possible" and provide immediate feedback during gesture performance so users can predict outcomes.

一致性与熟悉度： "用户期望大多数手势在任何上下文下都能以相同方式工作。"点击、滑动和拖动等标准手势应在各平台上执行预期功能。

响应式反馈： "尽可能响应式地处理手势"，在手势执行过程中提供即时反馈，让用户可以预测结果。

Standard Gestures

标准手势

Basic gestures supported across all platforms (though precise movements vary by device):

Tap
Swipe
Drag
Pinch
Rotate (iOS/iPadOS)
Long press

所有平台支持的基本手势（具体操作因设备而异）：

点击
滑动
拖动
捏合
旋转（iOS/iPadOS）
长按

Touch Target Requirements

触控目标要求

Minimum touch target sizes:

Platform	Minimum Size	Spacing
iOS/iPadOS	44x44 points	12-24pt padding
macOS	Varies by control	System spacing
watchOS	System controls	Optimized for small screen
tvOS	Large (focus model)	60pt+ spacing

swift

// ✅ Adequate touch target
Button("Tap") { }
    .frame(minWidth: 44, minHeight: 44)

// ❌ Too small
Button("Tap") { }
    .frame(width: 20, height: 20) // Fails accessibility

最小触控目标尺寸：

平台	最小尺寸	间距
iOS/iPadOS	44x44点	12-24点内边距
macOS	因控件而异	系统间距
watchOS	系统控件	针对小屏幕优化
tvOS	大尺寸（聚焦模型）	60点以上间距

swift

// ✅ 足够的触控目标
Button("Tap") { }
    .frame(minWidth: 44, minHeight: 44)

// ❌ 尺寸过小
Button("Tap") { }
    .frame(width: 20, height: 20) // 不符合无障碍要求

Custom Gesture Guidelines

自定义手势指南

Custom gestures should only be implemented when necessary and must be:

Discoverable — Users can find them
Straightforward to perform — Easy to execute
Distinct from other gestures — No conflicts
Never the only method — Provide alternatives for important actions

Warning: Don't replace standard gestures with custom ones. Shortcuts should supplement, not replace, familiar interactions.

仅在必要时实现自定义手势，且必须满足：

可发现性——用户能够找到
易于执行——操作简单
与其他手势区分——无冲突
绝非唯一方式——为重要操作提供替代方案

警告： 不要用自定义手势替代标准手势。快捷方式应作为熟悉交互的补充，而非替代。

Accessibility

无障碍设计

Critical: "Give people more than one way to interact with your app." Never assume users can perform specific gestures.

Provide alternatives:

Voice control
Keyboard navigation
Button alternatives to gestures

swift

// ✅ Swipe action + button alternative
.swipeActions {
    Button("Delete", role: .destructive) {
        delete()
    }
}
.contextMenu {
    Button("Delete", role: .destructive) {
        delete()
    }
}

关键提示： "为用户提供多种与应用交互的方式。"不要假设用户能够执行特定手势。

提供替代方式：

语音控制
键盘导航
手势的按钮替代方案

swift

// ✅ 滑动操作 + 按钮替代方案
.swipeActions {
    Button("Delete", role: .destructive) {
        delete()
    }
}
.contextMenu {
    Button("Delete", role: .destructive) {
        delete()
    }
}

Launch & Onboarding

启动与引导

Launch Screens

启动屏幕

Mandatory for: iOS, iPadOS, tvOS Not required for: macOS, axiom-visionOS, watchOS

Design principle: "Design a launch screen that's nearly identical to the first screen of your app or game" to avoid jarring visual transitions.

强制要求： iOS、iPadOS、tvOS 无需： macOS、axiom-visionOS、watchOS

设计原则： "设计与应用或游戏首屏几乎完全一致的启动屏幕"，以避免突兀的视觉过渡。

Best Practices

最佳实践

Minimize branding:

Avoid logos
No splash screens
No artistic flourishes
Purpose: Enhance perception of quick startup, not showcase brand

No text:

Launch screen content cannot be localized
Avoid text entirely

Match appearance:

Respect device orientation
Adapt to light/dark mode

swift

// Launch screen matches first screen
// Transitions smoothly without flash

最小化品牌展示：

避免使用Logo
不要使用闪屏
不要添加艺术装饰
目的：提升快速启动的感知，而非展示品牌

不要包含文本：

启动屏幕内容无法本地化
完全避免使用文本

匹配外观：

尊重设备方向
适配浅色/深色模式

swift

// 启动屏幕与首屏匹配
// 平滑过渡，无闪烁

Onboarding

引导流程

Onboarding is a separate experience that follows the launch phase. Provides "a high-level view of your app or game" and can include a splash screen if needed.

When to use: Only when you have meaningful context to communicate to new users.

What onboarding can include:

Branding and splash screens
Educational content
Permission requests
Account setup

Timeline:

Launch — System displays launch screen, transitions to first screen
Onboarding (optional) — Can include branding and education
Continued use — "Restore the previous state when your app restarts so people can continue where they left off"

引导流程是启动阶段之后的独立体验。提供"应用或游戏的概览"，必要时可包含闪屏。

使用场景： 仅当需要向新用户传达有意义的上下文时使用。

引导流程可包含：

品牌展示和闪屏
教育内容
权限请求
账户设置

时间线：

启动 — 系统显示启动屏幕，过渡到首屏
引导流程（可选） — 可包含品牌展示和教育内容
持续使用 — "应用重启时恢复之前的状态，让用户可以从上次中断的地方继续"

Platform-Specific Guidance

平台特定指导

iOS

Device characteristics:

Medium-size, axiom-high-resolution display
One or two-handed interaction
Portrait/landscape switching
Viewing distance: 1-2 feet

Input methods:

Multi-Touch gestures
Virtual keyboards
Voice control
Gyroscope/accelerometer
Spatial interactions

Design patterns:

Swiping for back navigation
List actions positioned in middle or bottom areas
Multiple simultaneous apps
Frequent app switching

Content hierarchy:

"Limit the number of onscreen controls while making secondary details and actions discoverable with minimal interaction"

System integration:

Widgets
Home Screen quick actions
Spotlight search
Shortcuts
Activity views

设备特性：

中等尺寸、axiom高分辨率显示屏
单手握持或双手握持交互
支持横竖屏切换
观看距离：1-2英尺

输入方式：

多点触控手势
虚拟键盘
语音控制
陀螺仪/加速计
空间交互

设计模式：

滑动返回导航
列表操作位于中部或底部区域
支持多应用同时运行
频繁切换应用

内容层级：

"限制屏幕上的控件数量，同时让次要细节和操作通过最少交互即可被发现"

系统集成：

小组件
主屏幕快速操作
Spotlight搜索
快捷指令
活动视图

iPadOS

Extends iOS with:

Larger display (more content simultaneously)
Sidebar-adaptable layouts
Split view multitasking
Pointer/trackpad support
Arbitrary window sizing (iOS 26+)
Menu bar (swiping down from top)

Design considerations:

Don't just scale iOS layouts
Leverage sidebars for navigation
Support split view
Optimize for pointer interactions

在iOS基础上扩展：

更大的显示屏（可同时显示更多内容）
可适配侧边栏的布局
分屏多任务处理
指针/触控板支持
任意窗口大小（iOS 26+）
菜单栏（从顶部向下滑动呼出）

设计注意事项：

不要简单缩放iOS布局
利用侧边栏进行导航
支持分屏视图
针对指针交互进行优化

macOS

Characteristics:

Large, axiom-high-resolution display
Pointer-first interactions
Keyboard-centric workflows
Multiple windows
Menu bar for commands

Design patterns:

Dense layouts acceptable
Smaller controls (vs iOS)
Window chrome and controls
Contextual menus expected
Keyboard shortcuts essential

Control sizes:

Mini, Small, Medium → Rounded rectangles
Large, X-Large → Capsules (iOS 26+)

特性：

大尺寸、axiom高分辨率显示屏
指针优先的交互
以键盘为中心的工作流
多窗口支持
菜单栏用于执行命令

设计模式：

允许密集布局
控件比iOS更小
窗口边框和控件
上下文菜单是预期功能
键盘快捷键至关重要

控件尺寸：

微型、小型、中型 → 圆角矩形
大型、超大型 → 胶囊形（iOS 26+）

watchOS

Constraints:

Very small display
Glanceable interfaces
Minimal interaction time
Always-on consideration

Design principles:

Full-bleed content
Minimal padding
Digital Crown interactions
Complications for watch faces

限制：

非常小的显示屏
一瞥即得的界面
交互时间极短
始终显示的考虑

设计原则：

全屏内容
最小内边距
数码表冠交互
表盘复杂功能

tvOS

Characteristics:

Large display
10-foot viewing distance
Focus-based navigation
Gestural remote

Design requirements:

Large touch targets
Focus states clear and prominent
Limited text input
Spatial navigation (up/down/left/right)

特性：

大尺寸显示屏
10英尺观看距离
基于焦点的导航
手势遥控器

设计要求：

大触控目标
焦点状态清晰突出
文本输入受限
空间导航（上下左右）

visionOS

Unique aspects:

Spatial computing
Glass materials
3D layouts
Depth and layering

Design principles:

Comfortable viewing depth
Avoid head-anchored content
Center important content in field of view
Use depth deliberately for large, important elements

独特之处：

空间计算
玻璃材质
3D布局
深度与分层

设计原则：

舒适的观看深度
避免头部锚定内容
重要内容位于视野中心
为大型重要元素刻意使用深度

Inclusive Design

包容性设计

Language & Communication

语言与沟通

Welcoming language requirements:

Use plain, direct, and respectful tone
Don't suggest exclusivity based on education level
Address people directly with "you/your" rather than "the user"
Define specialized or technical terms when necessary
Replace culture-specific expressions with plain alternatives

Avoid phrases with oppressive origins (e.g., "peanut gallery").

Exercise caution with humor — it's subjective and difficult to translate across cultures.

友好语言要求：

使用简洁、直接、尊重的语气
不要暗示基于教育水平的排他性
使用"你/您"直接称呼用户，而非"用户"
必要时定义专业或技术术语
用平实的表达替代特定文化的习语

避免使用带有压迫性起源的短语（例如："peanut gallery"）。

谨慎使用幽默——幽默具有主观性，跨文化翻译难度大。

Visual Representation

视觉呈现

Portraying human diversity:

Feature people demonstrating range of racial backgrounds, body types, ages, physical capabilities
Avoid stereotypical representations in occupations and behaviors

Avoiding assumptions:

Don't assume narrow definitions of family structures
Don't assume universal experiences
Replace culture-specific security questions with more universal experiences

展现人类多样性：

展示不同种族背景、体型、年龄、身体能力的人
避免职业和行为中的刻板印象

避免假设：

不要假设家庭结构的狭隘定义
不要假设普遍的体验
用更具普遍性的问题替代特定文化的安全问题

Gender Identity & Pronouns

性别认同与代词

Best practices:

Avoid unnecessary gender references in copy
Provide inclusive options: "nonbinary," "self-identify," "decline to state"
Use nongendered imagery
Allow customization of avatars and characters

最佳实践：

文案中避免不必要的性别提及
提供包容性选项："非二元性别"、"自我认同"、"拒绝说明"
使用无性别意象
允许自定义头像和角色

Accessibility & Disability

无障碍与残疾

Recognize:

Disabilities exist on spectrums
Temporary/situational disabilities affect everyone

Include:

People with disabilities in diversity representations
Adopt people-first approach in writing ("person with disability" vs "disabled person")

认知：

残疾存在于连续谱上
临时/情境性残疾影响每个人

包含：

在多样性呈现中包含残疾人
在写作中采用以人为本的表述（"残疾人" vs "有残疾的人"）

Localization & Global Considerations

本地化与全球考量

Prepare software for:

Internationalization
Translation into multiple languages

Cultural color awareness:

Colors carry culture-specific meanings
White represents death in some cultures, purity in others
Red signifies danger in some cultures, positive meanings elsewhere

Use plain language and avoid stereotypes to facilitate smoother localization.

为软件做好准备：

国际化
翻译成多种语言

文化颜色认知：

颜色具有特定文化含义
白色在某些文化中代表死亡，在其他文化中代表纯洁
红色在某些文化中表示危险，在其他文化中具有积极含义

使用平实语言，避免刻板印象，以促进更顺畅的本地化。

Branding

品牌展示

Core Principles

核心原则

Voice & Tone: Maintain consistent brand personality through written communication.

Visual Elements:

Consider accent color for UI components
Custom font if strongly associated with brand (but system fonts work better for body copy due to legibility)

语气与语调： 通过书面沟通保持一致的品牌个性。

视觉元素：

考虑将品牌强调色用作UI组件的色调
如果品牌与自定义字体强关联，可使用自定义字体（但系统字体因可读性更适合正文）

Key Restraint Guidelines

关键克制准则

Most critical guidance — restraint:

Defer to content: "Using screen space for an element that does nothing but display a brand asset can mean there's less room for the content people care about."

Logo minimalism: "Resist the temptation to display your logo throughout your app or game unless it's essential for providing context."

Familiar patterns: Maintain standard UI behaviors and component placement even with stylized designs to keep interfaces approachable.

Launch screen caution: Avoid using launch screens for branding since they disappear too quickly; consider onboarding screens instead for brand integration.

最重要的指导原则——克制：

服务于内容： "将屏幕空间用于仅显示品牌资产的元素，意味着用户关心的内容可用空间更少。"

Logo最小化： "除非为了提供上下文必不可少，否则不要在应用或游戏中频繁展示Logo。"

熟悉的模式： 即使采用风格化设计，也要保持标准UI行为和组件位置，让界面易于使用。

启动屏幕注意事项： 避免将启动屏幕用于品牌展示，因为它消失太快；可考虑在引导流程屏幕中融入品牌。

Appropriate Branding

合适的品牌展示

Do:

Use your brand's accent color as app tint color
Include branding in onboarding (not launch screen)
Use brand voice in copy
Feature brand in content, not chrome

Don't:

Display logo in navigation bar
Override system backgrounds with brand colors
Add splash screens
Make branding compete with content

建议做法：

将品牌强调色用作应用色调
在引导流程中加入品牌展示（而非启动屏幕）
文案使用品牌语气
在内容中突出品牌，而非界面框架中

避免做法：

在导航栏中显示Logo
用品牌颜色覆盖系统背景
添加闪屏
让品牌展示与内容竞争

Legal Consideration

法律考量

Apple trademarks cannot appear in your app name or images—consult Apple's official trademark guidelines.

Apple商标不得出现在应用名称或图片中——请查阅Apple官方商标指南。

Troubleshooting Common HIG Issues

常见HIG问题排查

Color Contrast Failures

颜色对比度不达标

Symptom: App Store rejection for accessibility violations, or colors don't meet WCAG standards.

Diagnosis:

Test with Xcode Accessibility Inspector
Use online contrast calculators
Check in both Light and Dark modes
Test with Increase Contrast enabled

Solution:

swift

// ❌ PROBLEM: Custom gray fails contrast
Text("Label").foregroundStyle(.gray) // May fail 4.5:1 requirement

// ✅ SOLUTION 1: Use semantic colors (automatic compliance)
Text("Label").foregroundStyle(.secondary)

// ✅ SOLUTION 2: Use darker custom color with verified contrast
Text("Label").foregroundStyle(Color(red: 0.25, green: 0.25, blue: 0.25))
// This achieves ~8:1 contrast on white background (WCAG AAA)

症状： 因无障碍违规被App Store拒绝，或颜色不符合WCAG标准。

诊断方法：

使用Xcode无障碍检查器测试
使用在线对比度计算器
在浅色和深色模式下都进行检查
启用"增加对比度"设置进行测试

解决方案：

swift

// ❌ 问题：自定义灰色对比度不达标
Text("Label").foregroundStyle(.gray) // 可能不满足4.5:1要求

// ✅ 解决方案1：使用语义色（自动符合标准）
Text("Label").foregroundStyle(.secondary)

// ✅ 解决方案2：使用经过验证的深色自定义颜色
Text("Label").foregroundStyle(Color(red: 0.25, green: 0.25, blue: 0.25))
// 在白色背景上实现约8:1的对比度（WCAG AAA级）

Touch Targets Too Small

触控目标过小

Symptom: Users report difficult tapping, App Store accessibility rejection.

Diagnosis:

swift

// Check button size
Button("Tap") { }
    .frame(width: 30, height: 30) // ❌ Too small

Solution:

swift

// ✅ Expand touch target to minimum 44x44
Button("Tap") { }
    .frame(minWidth: 44, minHeight: 44)

// ✅ Alternative: Add padding
Button("Tap") { }
    .padding() // System adds appropriate padding

症状： 用户反馈点击困难，因无障碍问题被App Store拒绝。

诊断方法：

swift

// 检查按钮尺寸
Button("Tap") { }
    .frame(width: 30, height: 30) // ❌ 尺寸过小

解决方案：

swift

// ✅ 将触控目标扩展至最小44x44
Button("Tap") { }
    .frame(minWidth: 44, minHeight: 44)

// ✅ 替代方案：添加内边距
Button("Tap") { }
    .padding() // 系统添加合适的内边距

Dark Mode Issues

深色模式问题

Symptom: Colors look wrong in Dark Mode, insufficient contrast.

Diagnosis:

Hardcoded colors that don't adapt
Custom colors without dark variants
Not testing in both appearance modes

Solution:

swift

// ❌ PROBLEM: Hardcoded white text
Text("Label").foregroundStyle(.white)
// Invisible in Light Mode

// ✅ SOLUTION: Semantic color
Text("Label").foregroundStyle(.primary)
// Black in Light, white in Dark

// ✅ ALTERNATIVE: Asset catalog color with variants
Text("Label").foregroundStyle(Color("BrandText"))
// Define in Assets.xcassets with Light/Dark variants

症状： 深色模式下颜色显示异常，对比度不足。

诊断方法：

使用硬编码颜色，无法适配
自定义颜色没有深色变体
未在两种外观模式下测试

解决方案：

swift

// ❌ 问题：硬编码白色文本
Text("Label").foregroundStyle(.white)
// 浅色模式下不可见

// ✅ 解决方案：使用语义色
Text("Label").foregroundStyle(.primary)
// 浅色模式下为黑色，深色模式下为白色

// ✅ 替代方案：使用资源目录中的多变体颜色
Text("Label").foregroundStyle(Color("BrandText"))
// 在Assets.xcassets中定义浅色/深色变体

Light Font Weight Legibility

轻量字重可读性差

Symptom: Text hard to read, especially at small sizes or in bright lighting.

Diagnosis:

swift

Text("Headline")
    .font(.system(size: 17, weight: .ultralight)) // ❌ Too light

Solution:

swift

// ✅ Use Regular minimum
Text("Headline")
    .font(.system(size: 17, weight: .regular))

// ✅ Better: Use system text styles
Text("Headline")
    .font(.headline) // Automatically uses appropriate weight

症状： 文本难以阅读，尤其是小字号或明亮环境下。

诊断方法：

swift

Text("Headline")
    .font(.system(size: 17, weight: .ultralight)) // ❌ 字重过轻

解决方案：

swift

// ✅ 至少使用Regular字重
Text("Headline")
    .font(.system(size: 17, weight: .regular))

// ✅ 更好的做法：使用系统文本样式
Text("Headline")
    .font(.headline) // 自动使用合适的字重

Dynamic Type Not Working

Dynamic Type无法工作

Symptom: Text doesn't scale when user increases text size in Settings.

Diagnosis:

swift

// ❌ Fixed size doesn't scale
Text("Label").font(.system(size: 17))

Solution:

swift

// ✅ Use text styles for automatic scaling
Text("Label").font(.body)

// ✅ Custom font with scaling
Text("Label").font(.custom("CustomFont", size: 17, relativeTo: .body))

症状： 用户在设置中增大文本字号时，文本不缩放。

诊断方法：

swift

// ❌ 固定字号无法缩放
Text("Label").font(.system(size: 17))

解决方案：

swift

// ✅ 使用文本样式实现自动缩放
Text("Label").font(.body)

// ✅ 支持缩放的自定义字体
Text("Label").font(.custom("CustomFont", size: 17, relativeTo: .body))

Reduce Motion Not Respected

未尊重减少动态效果设置

Symptom: Users with motion sensitivity experience discomfort.

Diagnosis:

Animations always play regardless of setting
No alternative for motion-sensitive users

Solution:

swift

// ✅ Check Reduce Motion setting
@Environment(\.accessibilityReduceMotion) var reduceMotion

var body: some View {
    content
        .animation(reduceMotion ? nil : .spring(), value: isExpanded)
}

// ✅ Alternative: Simpler animation
.animation(reduceMotion ? .linear(duration: 0.1) : .spring(), value: isExpanded)

症状： 对动效敏感的用户感到不适。

诊断方法：

无论设置如何，动画始终播放
未为对动效敏感的用户提供替代方案

解决方案：

swift

// ✅ 检查减少动态效果设置
@Environment(\.accessibilityReduceMotion) var reduceMotion

var body: some View {
    content
        .animation(reduceMotion ? nil : .spring(), value: isExpanded)
}

// ✅ 替代方案：使用更简单的动画
.animation(reduceMotion ? .linear(duration: 0.1) : .spring(), value: isExpanded)

VoiceOver Labels Missing

VoiceOver标签缺失

Symptom: VoiceOver announces unhelpful information like "Button" instead of action.

Diagnosis:

swift

// ❌ Image button without label
Button {
    share()
} label: {
    Image(systemName: "square.and.arrow.up")
}
// VoiceOver says: "Button"

Solution:

swift

// ✅ Add accessibility label
Button {
    share()
} label: {
    Image(systemName: "square.and.arrow.up")
}
.accessibilityLabel("Share")
// VoiceOver says: "Share, Button"

症状： VoiceOver仅播报"按钮"等无帮助信息，而非操作内容。

诊断方法：

swift

// ❌ 无标签的图片按钮
Button {
    share()
} label: {
    Image(systemName: "square.and.arrow.up")
}
// VoiceOver播报："Button"

解决方案：

swift

// ✅ 添加无障碍标签
Button {
    share()
} label: {
    Image(systemName: "square.and.arrow.up")
}
.accessibilityLabel("Share")
// VoiceOver播报："Share, Button"

Information Only Conveyed by Color

仅通过颜色传达信息

Symptom: Colorblind users can't distinguish status.

Diagnosis:

swift

// ❌ Only color indicates state
Circle()
    .fill(isComplete ? .green : .red)

Solution:

swift

// ✅ Use shape + color + text
HStack {
    Image(systemName: isComplete ? "checkmark.circle.fill" : "xmark.circle.fill")
    Text(isComplete ? "Complete" : "Incomplete")
}
.foregroundStyle(isComplete ? .green : .red)

症状： 色盲用户无法区分状态。

诊断方法：

swift

// ❌ 仅通过颜色指示状态
Circle()
    .fill(isComplete ? .green : .red)

解决方案：

swift

// ✅ 使用形状+颜色+文本
HStack {
    Image(systemName: isComplete ? "checkmark.circle.fill" : "xmark.circle.fill")
    Text(isComplete ? "Complete" : "Incomplete")
}
.foregroundStyle(isComplete ? .green : .red)

Launch Screen Branding Rejection

启动屏幕品牌展示被拒

Symptom: App Store rejects launch screen with logo or text.

Diagnosis:

Launch screen contains branding elements
Launch screen has text that can't be localized

Solution:

swift

// ❌ Launch screen with logo (rejected)
// Launch.storyboard contains app logo

// ✅ Launch screen matches first screen (approved)
// Launch.storyboard shows same background/layout as first screen
// No text, no logos, minimal branding

// Move branding to onboarding screen instead

症状： 因启动屏幕包含Logo或文本被App Store拒绝。

诊断方法：

启动屏幕包含品牌元素
启动屏幕包含无法本地化的文本

解决方案：

swift

// ❌ 包含Logo的启动屏幕（会被拒）
// Launch.storyboard包含应用Logo

// ✅ 与首屏匹配的启动屏幕（可通过）
// Launch.storyboard显示与首屏相同的背景/布局
// 无文本、无Logo、品牌展示最少

// 改为在引导流程屏幕中加入品牌展示

Custom Appearance Toggle Issues

自定义外观切换问题

Symptom: Users confused by app-specific dark mode setting, double settings.

Diagnosis:

App has its own Light/Dark toggle
Conflicts with system Settings → Display & Brightness

Solution:

swift

// ❌ App-specific appearance toggle
.preferredColorScheme(userPreference == .dark ? .dark : .light)

// ✅ Respect system preference
// Remove custom toggle, use system preference
// Let iOS Settings control appearance

症状： 用户对应用专属的深色模式设置感到困惑，出现双重设置。

诊断方法：

应用有自己的浅色/深色切换开关
与系统设置→显示与亮度冲突

解决方案：

swift

// ❌ 应用专属外观切换
.preferredColorScheme(userPreference == .dark ? .dark : .light)

// ✅ 尊重系统偏好设置
// 移除自定义切换开关，使用系统偏好
// 让iOS设置控制外观

Resources

资源

WWDC: 356, 2019-808

Docs: /design/human-interface-guidelines, /design/human-interface-guidelines/color, /design/human-interface-guidelines/dark-mode, /design/human-interface-guidelines/materials, /design/human-interface-guidelines/typography, /design/human-interface-guidelines/layout, /design/human-interface-guidelines/accessibility, /design/human-interface-guidelines/icons

Skills: axiom-hig, axiom-liquid-glass, axiom-liquid-glass-ref, axiom-swiftui-layout-ref, axiom-accessibility-diag

Last Updated: Based on Apple HIG (2024-2025), WWDC25-356, WWDC19-808 Skill Type: Reference (Comprehensive guide with code examples)

WWDC: 356, 2019-808

文档: /design/human-interface-guidelines, /design/human-interface-guidelines/color, /design/human-interface-guidelines/dark-mode, /design/human-interface-guidelines/materials, /design/human-interface-guidelines/typography, /design/human-interface-guidelines/layout, /design/human-interface-guidelines/accessibility, /design/human-interface-guidelines/icons

技能: axiom-hig, axiom-liquid-glass, axiom-liquid-glass-ref, axiom-swiftui-layout-ref, axiom-accessibility-diag

最后更新: 基于Apple HIG (2024-2025), WWDC25-356, WWDC19-808 技能类型: 参考资料（含代码示例的全面指南）

axiom-hig-ref

Original

Translation

Apple Human Interface Guidelines — Comprehensive Reference

Apple人机界面指南 — 全面参考资料

Overview

概述

Three Core Principles

三大核心原则

Design System Philosophy

设计系统理念

Related Skills

相关技能

Color System

颜色系统

Semantic Colors Explained

语义色详解

Label Colors (Foreground Content)

标签颜色（前景内容）

Background Colors (Primary → Tertiary)

背景颜色（主→三级）

Ungrouped Backgrounds

非分组背景

Grouped Backgrounds

分组背景

Base vs Elevated Backgrounds

基础与提升级背景

Tint Colors (Dynamic Adaptation)

色调颜色（动态适配）

Fill Colors (Semi-Transparent)

填充颜色（半透明）

Separator Colors

分隔线颜色

When to Use Permanent Dark Backgrounds

何时使用永久深色背景

Creating Custom Colors

创建自定义颜色

Typography

排版

System Fonts

系统字体

Font Weight Recommendations

字重推荐

Text Styles for Hierarchy

用于层级的文本样式

Dynamic Type Support

Dynamic Type支持

Custom Fonts

自定义字体

Leading (Line Spacing)

行间距

Shapes & Geometry

形状与几何

Three Shape Types (iOS 26)

三种形状类型（iOS 26）

1. Fixed Shapes

1. 固定形状

2. Capsules

2. 胶囊形

3. Concentric Shapes

3. 同心形状

Concentricity Principle

同心性原则

Platform-Specific Guidance

平台特定指导

Optical Centering

视觉居中

Materials & Depth

材质与深度

Standard Materials

标准材质

Four Thickness Options

四种厚度选项

Vibrancy with Materials

材质与活力效果

Liquid Glass (iOS 26+)

Liquid Glass（iOS 26+）

Layout Principles

布局原则

Visual Hierarchy