axiom-hig-ref

Name: axiom-hig-ref
Author: charleswiltgen

github.com/charleswiltgen设计与 UI1.2k207 次安装今天更新

代码仓库

关于 axiom-hig-ref

面向 Apple 平台设计者与开发者的 Human Interface Guidelines 参考技能，涵盖界面原则、色彩、排版、形状与材质，帮助制定平台适配的设计决策。

主要功能

01Clarity、Consistency 与 Deference 原则
02语义色彩与明暗模式建议
03系统字体和 Dynamic Type 指引
04形状、几何与材质参考

适用场景

01检查界面是否遵循 Apple 设计原则
02为明暗模式选择语义颜色
03规划支持 Dynamic Type 的排版
04设计嵌套界面的形状与材质

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/charleswiltgen/axiom --skill axiom-hig-ref

安装后在 Claude Code 中输入/axiom-hig-ref确认已加载。

详细介绍

Apple Human Interface Guidelines — 综合参考

概述

Human Interface Guidelines（HIG）阐述了 Apple 的设计理念，并为如何在所有 Apple 设备上打造直观、易用且符合平台特性的体验提供了具体指导。

三大核心原则

每项设计决策都应体现以下原则：

1. 清晰

内容至关重要。界面元素应衬托内容，而不是与之争抢注意力。每个元素都有其用途，不必要的复杂性应予以消除；用户无需阅读冗长说明，就应能立即了解自己可以做什么。

2. 一致

应用应使用标准 UI 元素和用户熟悉的模式。导航遵循平台惯例，手势符合预期，组件出现在用户预期的位置。这种熟悉感可以降低认知负担。

3. 克制

UI 不应分散用户对核心内容的注意力。使用低调的背景，在不需要导航时让其退至次要位置，克制地展现品牌，并让内容成为主角。

来自 Apple HIG：“克制能让应用更美观，因为它确保内容脱颖而出，而周围的视觉元素不会与之争抢注意力。”

设计系统理念

来自 WWDC25：“系统化的方法意味着在每个层面都经过深思熟虑地进行设计，确保所有元素——从最小的控件到最大的表面——都能从整体角度加以考量。”

颜色系统

语义颜色说明

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

来自 WWDC19 的关键见解：“不妨把深色模式想成调暗灯光，而不是把所有东西里外翻转。”颜色并非简单地反转——表格行背景在两种模式下都会更亮。

标签颜色（前景内容）

文本和符号有四个语义标签级别，显眼程度依次递减：

样式	语义颜色	用途
`.primary`	`label`	标题、最醒目的文本
`.secondary`	`secondaryLabel`	副标题、不太醒目的文本
`.tertiary`	`tertiaryLabel`	占位文本
`.quaternary`	`quaternaryLabel`	禁用状态的文本

Text("Title").foregroundStyle(.primary)    // Black in Light, white in Dark
Text("Subtitle").foregroundStyle(.secondary)

背景颜色（主要 → 第三层级）

背景颜色分为两组——非分组（标准列表）和分组（iOS 设置样式）：

级别	非分组	分组
主要	`.systemBackground`	`.systemGroupedBackground`
次要	`.secondarySystemBackground`	`.secondarySystemGroupedBackground`
第三层级	`.tertiarySystemBackground`	`.tertiarySystemGroupedBackground`

非分组：浅色模式下为纯白色，深色模式下为纯黑色。分组：浅色模式下为浅灰色，深色模式下为深灰色。

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

// Settings-style list → grouped backgrounds
List { Section("Section") { Text("Item") } }
    .listStyle(.grouped)

基础与凸起背景

实际上，界面分层时有两组背景颜色：

基础组： 用于背景中的应用／界面
凸起组： 用于前景中的应用／界面

为何这很重要：

在浅色模式下，简单的投影即可形成视觉分隔。在深色模式下，投影效果较弱，因此系统会为凸起的内容使用更亮的颜色。

示例： iPad 多任务处理：

单独使用 Mail 应用 → 基础颜色组
以侧拉方式显示 Contacts → 凸起颜色（更亮、更醒目）
两个应用并排显示 → 两者都使用凸起颜色，以便在分隔条周围形成对比
撰写电子邮件的工作表 → 凸起颜色，并叠加变暗效果

重要： 某些较暗的颜色在凸起状态下可能对比度不足。请务必在凸起状态下测试设计。半不透明填充色和分隔线颜色能够平滑适配。

色调颜色（动态适配）

色调颜色是动态的——在浅色和深色模式下各有对应变体：

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

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

填充颜色（半透明）

填充颜色具有半透明效果，能与各种背景形成良好对比：

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

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

分隔线颜色

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

// Opaque separator
Color(.opaqueSeparator)

当透明度会造成不理想的效果时（例如，在相交的网格线中，重叠的半透明颜色会产生视觉错觉），请使用不透明分隔线。

何时使用永久深色背景

Apple 的明确指导：

“在极少数情况下，可以考虑在界面中仅使用深色外观。例如，对于支持沉浸式媒体观看的应用，永久使用深色外观是合理的，因为这可以让 UI 退居次要位置，帮助人们专注于媒体内容。”

Apple 应用示例：

应用	背景	原因
Music	深色	专辑封面应成为视觉焦点
Photos	深色	图片是主要内容
Clock	深色	适合夜间使用，具有仪表感
Stocks	深色	数据可视化、图表
Camera	深色	拍摄时减少干扰

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

创建自定义颜色

需要自定义颜色时：

打开 Assets.xcassets
添加 Color Set
配置变体：
- 浅色模式颜色
- 深色模式颜色
- 高对比度浅色（可选，但建议设置）
- 高对比度深色（可选，但建议设置）

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

排版

系统字体

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

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

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

两者都提供可变字体，可实现平滑的字重过渡。

字重建议

来自 Apple HIG：“避免使用较细的字重。优先使用 Regular、Medium、Semibold 或 Bold，而不是 Ultralight、Thin 或 Light。”

原因： 较细的字重可读性较差，尤其是在字号较小、光线明亮或用户有视力障碍时。

层级：

// 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)

用于构建层级的文本样式

使用内置文本样式，自动构建层级并支持动态字体：

.font(.largeTitle)  .font(.title)       .font(.title2)
.font(.title3)      .font(.headline)    .font(.body)
.font(.callout)     .font(.subheadline) .font(.footnote)
.font(.caption)     .font(.caption2)

所有文本样式都会随动态字体自动缩放。

动态字体支持

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

实现：

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

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

布局注意事项：

在较大字号下减少多列布局
尽量减少文本截断
大字号下使用堆叠布局，而不是行内布局
无论字号如何变化，都要保持信息层级一致

并非所有内容都应同比例缩放： 优先考虑用户真正关注的内容。标签页标题等次要元素的放大幅度不应超过主要内容。

自定义字体

使用自定义字体时：

确保在不同距离和环境下都清晰易读
实现动态字体支持
响应“粗体文本”辅助功能设置
测试所有字号
确保辅助功能行为与系统字体一致

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

行距

宽松行距： 适用于宽栏（更容易找到下一行） 紧凑行距： 适用于高度受限的情况（避免用于 3 行及以上的文本）

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

形状与几何

三种形状类型（iOS 26）

来自 WWDC25：“我们的形状之间有一种微妙的几何关系，由同心性驱动。通过围绕共享中心对齐半径和边距，形状可以自然地嵌套在彼此之中。”

1. 固定形状

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

RoundedRectangle(cornerRadius: 12)

适用场景： 需要特定且固定的圆角半径时。

2. 胶囊形

半径为容器高度的一半：

Capsule()

适用场景： 希望形状能适应内容，同时保持圆润的两端。非常适合按钮、胶囊形控件和控制项。

广泛用于 iOS 26： 滑块、开关、分组表格视图、标签栏、导航栏。

3. 同心形状

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

.containerRelativeShape(.roundedRectangle)

适用场景： 将形状嵌套在容器中，以保持视觉协调。

同心性原则

硬件 ↔ 软件的协调： Apple 的硬件具有一致的边框曲率。如今，同样的精确度也应用于 UI，曲率、尺寸和比例相互协调，让手中所持与眼前所见形成统一的节奏。

同心性示例：

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

平台特定指南

iOS：

按钮、开关、分组列表使用胶囊形
在适合触控的布局中营造层次感并突出重点

macOS：

迷你、小、中号控制项 → 圆角矩形（适用于密集布局、检查器面板）
大号、超大号控制项 → 胶囊形（适用于宽敞区域，通过 Liquid Glass 突出重点）

视觉居中

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

在合适时进行数学居中
在视觉重量需要时进行细微偏移

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

材质与深度

标准材质

材质可以让背景内容透显出来，从而营造视觉深度和层次感。

四种厚度选项

超薄 — 分隔效果极弱，内容清晰可见
薄 — 适用于较轻量的交互
常规 — 默认选项，适用于大多数情况
厚 — 与背景的分隔效果最强

选择厚度：

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

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

材质与鲜明度

关键原则： 在材质上方使用鲜明色彩，以确保易读性。纯色可能会受背景环境影响而显得浑浊。无论背景如何，鲜明度都能保持对比度。

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

Liquid Glass（iOS 26+）

用途： 为控制项和导航创建独立的功能层，使其悬浮于内容之上。

两种变体：

常规 Liquid Glass
- 默认选项，适用于 95% 的情况
- 具备完整的视觉效果和自适应效果
- 无论环境如何，都能保证易读性
- 适用于任何背景
透明 Liquid Glass
- 具有很高的透明度
- 不具备自适应行为
- 仅用于视觉内容丰富的背景上的组件（照片、视频）
- 需要添加调暗层以确保易读性

模态框与工作表（iOS 26+）： 使用 Xcode 26 时，工作表、警告框和弹出框会自动采用 Liquid Glass — 移除自定义的 .presentationBackground() 或 UIBlurEffect 背景。系统会处理材质、同心圆角半径和形变过渡。模态内容背景应使用具有抬升效果的语义颜色，而不要在工作表主体上使用 Liquid Glass。

交叉参考： 有关 Liquid Glass 的完整实现模式（工作表、警告框、弹出框、形变过渡），请参阅 axiom-liquid-glass-ref。有关决策树，请参阅 axiom-liquid-glass。

布局原则

视觉层次

通过元素的位置传达其相对重要性：

重要内容 → 顶部和前导侧
次要内容 → 下方或尾随侧
第三级内容 → 独立视图或渐进式呈现

摘自 Apple HIG：“为重要信息提供充足空间，避免被非必要细节遮挡，让用户能够轻松找到这些信息。”

分组与组织

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

留白
颜色与材质
分隔线

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

将内容延伸至边缘

通过让背景和艺术作品延伸至显示屏边缘，“扩展内容以填满屏幕或窗口”。

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

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

安全区域与布局参考线

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

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

布局参考线： 定义用于定位内容和设置间距的矩形区域，包括：

预定义边距
优化文本宽度
阅读宽度限制

核心原则：“尊重各平台的关键显示区域和系统特征。”

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

对齐组件

“将组件彼此对齐，使其更易于浏览。”

网格对齐：

文本基线对齐
控件按统一网格对齐
间距保持一致且有节奏

适应性要求

设计布局时应：

“在适应上下文变化的同时，保持一致且易于识别”
支持 Dynamic Type 字号调整
适用于多种设备、屏幕方向和本地化设置
考虑不同的屏幕尺寸、分辨率和系统特征

辅助功能

视觉辅助功能

文本与易读性

要求：

支持至少 200% 的文本放大（watchOS 为 140%）
实现 Dynamic Type，以便在整个系统中调整文本
使用有助于提升可读性的字体粗细（自定义字体避免使用 Light 字重）

色彩对比度

WCAG AA 级标准：

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

实现：

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

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

高对比度模式： 启用“增强对比度”辅助功能设置时，提供对比度更高的配色方案。

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

色彩注意事项

关键：“传达信息时不能仅依赖颜色”，以便色盲用户也能理解。

解决方案：

在颜色之外使用不同的形状或图标
添加文本标签
使用带有无障碍变体的系统定义颜色
使用色盲模拟器进行测试

示例：

// ❌ 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)

屏幕阅读器

为 VoiceOver 辅助功能描述界面和内容：

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

听觉辅助功能

媒体替代方案

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

对话字幕
字幕
针对纯视觉信息的音频描述
较长媒体内容的文字稿

音频提示

音频信号应搭配：

触觉反馈
视觉指示器

行动辅助功能

触控目标：

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

手势：

使用简单手势
提供替代操作方式（手势之外也提供按钮）
支持语音控制
启用键盘导航

辅助技术：

VoiceOver
切换控制
全键盘控制

认知辅助功能

交互设计

“让操作简单直观”
避免使用会按时间自动消失的视图
避免在没有控件的情况下自动播放音频/视频

动效与视觉效果

遵循“减少动态效果”设置：

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

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

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

游戏辅助选项

提供可调整的难度等级。

visionOS 专项

优先考虑舒适度：

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

动效与动画

核心原则

有目的地使用动画：“有目的地添加动态效果，在支持体验的同时不喧宾夺主。”

避免无谓的动画，以免分散注意力或造成不适。动态效果应增强界面，而不是主导界面。

无障碍优先

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

反馈最佳实践

真实自然的动态效果

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

“简短而精准”
轻巧
有效传达信息，且不造成干扰

频率方面的考量

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

用户控制

“让用户能够取消动态效果”，不要强迫他们等待动画完成后才能继续，尤其是在重复交互时。

// ✅ 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

特定平台指南

visionOS

避免在周边视野边缘使用动态效果 — 这会造成不适
移动对象位置时使用淡入淡出，而不是明显的移动效果
保持静止的参照框架
避免持续振荡（尤其是频率为 0.2 Hz 时）
防止虚拟世界旋转（这会破坏稳定感）

watchOS

SwiftUI 提供动画功能；WatchKit 提供 WKInterfaceImage，用于布局动画和动画序列。

图标与符号

SF Symbols

6,900 多个矢量符号，与 San Francisco 字体相匹配，可随动态字体大小缩放，并自动适配粗体文本和深色模式。提供 9 种字重、3 种尺寸、4 种渲染模式和 12 种以上动画效果。

如需全面了解渲染模式（单色、分层、调色板、多色）、符号效果（弹跳、脉冲、摆动、绘制显示/隐藏）和自定义符号创作，请参阅 axiom-sf-symbols（决策树）和 axiom-sf-symbols-ref（完整 API）。

自定义界面图标

设计原则： 采用易于识别、简化且使用熟悉视觉隐喻的设计。保持尺寸、细节程度、线条粗细和透视效果统一。图标的视觉粗细应与相邻文本匹配。如果视觉重量不对称，应调整内边距以实现视觉居中。

格式： 使用 PDF 或 SVG 实现自动缩放。系统组件会自动处理选中状态。

何时使用图标，何时使用文本

引自 WWDC25：“铅笔可能表示注释，勾号可能看起来像确认——因此，‘选择’或‘编辑’之类的操作很容易被误解。如果没有明确简洁的表达方式，文本标签始终是更好的选择。”

在以下情况下使用图标：

符号含义清晰且普遍通用（分享、删除、设置）
空间有限
图标有助于快速浏览

在以下情况下使用文本：

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

无障碍

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

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

手势与输入

手势设计核心原则

保持一致且熟悉：“人们期望大多数手势无论当前情境如何，都能以相同方式运作。”点按、轻扫和拖移等标准手势应在各个平台上执行用户预期的功能。

及时响应：“尽可能及时地处理手势”，并在执行手势时立即提供反馈，以便用户预测操作结果。

标准手势

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

点按
轻扫
拖移
捏合
旋转（iOS/iPadOS）
长按

触控目标要求

触控目标最小尺寸：

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

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

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

自定义手势指南

仅在必要时才应实现自定义手势，并且必须满足以下条件：

易于发现 — 用户能够找到这些手势
易于执行 — 操作简单
与其他手势有明显区别 — 不会产生冲突
绝不能是唯一操作方式 — 为重要操作提供替代方式

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

无障碍

至关重要：“为用户提供多种与应用交互的方式。”绝不要假设用户能够执行特定手势。

提供替代方式：

语音控制
键盘导航
使用按钮替代手势

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

启动与引导

启动屏幕

必须用于： iOS、iPadOS、tvOS
不需要用于： macOS、axiom-visionOS、watchOS

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

最佳实践

尽量减少品牌元素：

避免使用徽标
不要使用启动画面
不添加装饰性元素
目的：让用户感觉启动迅速，而非展示品牌

不使用文字：

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

保持一致的外观：

遵循设备方向
适配浅色/深色模式

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

引导

引导是启动阶段之后的独立体验。它会“概述应用或游戏的主要内容”，并可根据需要加入启动画面。

**适用时机：**仅在需要向新用户传达有意义的信息时使用。

引导内容可以包括：

品牌元素和启动画面
教育内容
权限请求
账户设置

时间线：

启动 — 系统显示启动屏幕，然后过渡到首个屏幕
引导（可选）— 可以包含品牌介绍和教学内容
持续使用 — “在应用重启时恢复之前的状态，让用户能够从上次离开的地方继续使用”

平台专属指南

iOS

标签栏指南：

iPhone 上最多显示 5 个标签（第 6 个及之后的标签会自动放入“更多”）
每个标签都必须同时包含图标和文字标签 — 仅使用图标不符合 HIG
始终可见 — 在标签内导航时不要隐藏标签栏
标签顺序应反映使用频率（最常用的放在左侧）
保持标签状态：切换标签时保留滚动位置和导航状态
iOS 26：自动采用 Liquid Glass — 不要添加自定义模糊/材质背景
iPad：横屏时将标签栏转换为侧边栏；使用 TabView 和 Tab 实现适配

导航栏指南：

始终使用系统返回按钮（箭头符号）— 不要替换为自定义的“X”
标题应描述当前视图的内容，而非应用名称
仅在顶层视图使用大标题（prefersLargeTitles）；推入的视图使用行内标题
工具栏操作最多 1-3 个；更多操作请使用 ... 菜单
iOS 26：使用 Liquid Glass，工具栏会在视图之间变形

**系统集成：**小组件、主屏幕快捷操作、Spotlight、快捷指令、活动视图

iPadOS

在 iOS 的基础上扩展了更大的显示屏、侧边栏导航、分屏视图、指针/触控板和任意窗口（iOS 26+）。不要只是放大 iOS 布局 — 应充分利用侧边栏和分屏视图。

macOS

以指针操作为主，以键盘操作为核心。布局更紧凑，控件比 iOS 更小。多窗口、菜单栏、上下文菜单和键盘快捷键都至关重要。控件尺寸：迷你/小/中 → 圆角矩形；大/特大 → 胶囊形。

watchOS

显示屏非常小，适合一瞥即读、尽量减少交互。内容铺满屏幕，尽量减少内边距；支持 Digital Crown 交互，并为表盘提供复杂功能。还需考虑常亮显示。

**从 iPad/iOS 适配：**将侧边栏替换为基于页面的流程。将滑动/捏合操作转换为 Digital Crown 旋转。使用不透明度/间距来建立层级（不使用材质/Liquid Glass）。用复杂功能替代仪表板。@State/@Environment 可以很好地复用；视图层级则必须重写。

tvOS

适用于 10 英尺的观看距离，采用基于焦点的导航和手势遥控器。触控目标要大，焦点状态要醒目，尽量减少文本输入，并支持方向导航。

Focus Engine：tvOS 使用 UIKit Focus Engine 进行硬件导航，并与 SwiftUI 的 @FocusState 并存。Focus Engine 具有最终决定权——如果 Focus Engine 认为某个视图不可聚焦，就会忽略 @FocusState 赋值。使用 UIFocusGuide 填补相互孤立的视图之间的导航断点。

TVUIKit：tvOS 专属组件——TVPosterView（视差焦点效果）、TVDigitEntryViewController（PIN 输入）。没有对应的 SwiftUI 实现；可通过 UIViewRepresentable 桥接。

文本输入：标准文本字段会触发全屏系统键盘。若要获得更好的用户体验，请使用影子输入模式（Button UI + 隐藏的 CocoaTextField）。实现细节请参见 axiom-tvos。

存储：没有持久化的本地存储。所有本地文件都是缓存，系统会将其删除。数据策略请参见 axiom-tvos。

visionOS

空间计算采用玻璃材质、3D 布局和深度效果。确保观看深度舒适，避免将内容锚定在头部，并将内容置于视野中央。

包容性设计

语言与沟通

友善包容的语言要求：

使用通俗、直接且尊重他人的语气
不要暗示某些人会因教育程度而被排斥
直接称呼他人为“你”，而不是“用户”
必要时解释专业或技术术语
将特定文化的表达替换为通俗的说法

避免使用源自压迫性语境的短语（例如，“peanut gallery”）。

谨慎使用幽默——幽默因人而异，也难以跨文化翻译。

视觉呈现

展现人类多样性：

展现不同种族背景、体型、年龄和身体能力的人
避免在职业和行为方面采用刻板印象式的呈现

避免先入为主：

不要假设家庭结构只有狭隘的定义
不要假设所有人都有相同的经历
将特定文化的安全问题替换为更普遍的经历

性别认同与代词

最佳实践：

避免在文案中不必要地提及性别
提供包容性选项：“非二元性别”“自行填写”“不愿透露”
使用不体现性别的图像
允许用户自定义头像和角色

无障碍与残障

请认识到：

残障存在不同程度
暂时性/情境性残障会影响每个人

请纳入：

在多样性呈现中包含残障人士
书写时采用以人为本的方式（使用“残障人士”，而非“残疾人”）

本地化与全球化考量

为软件做好以下准备：

国际化
翻译成多种语言

了解色彩的文化差异：

色彩承载着特定文化含义
白色在某些文化中代表死亡，在另一些文化中代表纯洁
红色在某些文化中象征危险，在其他文化中则有积极含义

使用通俗易懂的语言，并避免刻板印象，以便更顺利地进行本地化。

品牌塑造

核心原则

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

视觉元素：

考虑为 UI 组件采用强调色
如果某种自定义字体与品牌紧密关联，可考虑使用（但正文使用系统字体通常更易阅读）

品牌使用克制指南

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

内容优先：“为一个仅用于展示品牌素材的元素占用屏幕空间，意味着用户关心的内容可用空间会减少。”

Logo 极简：“除非对于提供上下文至关重要，否则不要在应用或游戏中到处展示 Logo。”

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

**谨慎使用启动屏幕：**避免将启动屏幕用于品牌宣传，因为它消失得太快；可以考虑使用引导屏幕来融入品牌元素。

合理的品牌展示

应该：

将品牌的点缀色用作应用色调
在引导过程中融入品牌元素（而非启动屏幕）
在文案中使用品牌语调
在内容中展现品牌，而非界面装饰

不应该：

在导航栏中显示 Logo
用品牌颜色覆盖系统背景
添加启动画面
让品牌展示与内容争抢关注

法律注意事项

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

常见 HIG 问题排查

颜色对比度不合格

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

**诊断：**使用 Accessibility Inspector 和对比度计算器进行测试，并在浅色和深色模式下，以及启用“增强对比度”时进行测试。有关对比度要求，请参阅上文“无障碍 > 视觉”部分。

解决方案：

// ❌ Custom gray may fail contrast
Text("Label").foregroundStyle(.gray)

// ✅ Semantic colors (automatic compliance)
Text("Label").foregroundStyle(.secondary)

// ✅ Verified custom color (~8:1 on white, WCAG AAA)
Text("Label").foregroundStyle(Color(red: 0.25, green: 0.25, blue: 0.25))

触控目标太小

**症状：**用户反映难以点击，或因无障碍问题被 App Store 拒绝。

诊断：

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

解决方案：

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

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

深色模式问题

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

诊断：

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

解决方案：

// ❌ 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

浅色字重的可读性

**症状：**文本难以阅读，尤其是在小字号或强光环境下。

诊断：

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

解决方案：

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

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

动态字体无法生效

**症状：**用户在“设置”中更改文本大小后，文本没有随之缩放。

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

// ✅ Text styles scale automatically
Text("Label").font(.body)

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

未遵循“减弱动态效果”设置

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

诊断：

无论设置如何，动画都会播放
没有为对动态效果敏感的用户提供替代方案

解决方案：

// ✅ 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)

缺少 VoiceOver 标签

**症状：**VoiceOver 播报“按钮”等无用信息，而非具体操作。

诊断：

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

解决方案：

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

仅通过颜色传达信息

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

诊断：

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

解决方案：

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

启动屏幕品牌展示导致审核被拒

**症状：**App Store 因启动屏幕包含 Logo 或文本而拒绝应用。

诊断：

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

解决方案：

// ❌ 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

自定义外观切换问题

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

诊断：

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

解决方案：

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

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

资源

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、axiom-tvos

最后更新：基于 Apple HIG（2024-2025）、WWDC25-356、WWDC19-808 技能类型：参考（含代码示例的综合指南）

支持 Markdown

登录后评论

axiom-hig-ref

关于 axiom-hig-ref

主要功能

适用场景

安装

详细介绍

Apple Human Interface Guidelines — 综合参考

概述

三大核心原则

设计系统理念

相关技能

颜色系统

语义颜色说明

标签颜色（前景内容）

背景颜色（主要 → 第三层级）

基础与凸起背景

色调颜色（动态适配）

填充颜色（半透明）

分隔线颜色

何时使用永久深色背景

创建自定义颜色

排版

系统字体

字重建议

用于构建层级的文本样式

动态字体支持

自定义字体

行距

形状与几何

三种形状类型（iOS 26）

1. 固定形状

2. 胶囊形

3. 同心形状

同心性原则

平台特定指南

视觉居中

材质与深度

标准材质

四种厚度选项

材质与鲜明度

Liquid Glass（iOS 26+）

布局原则

视觉层次

分组与组织

将内容延伸至边缘

安全区域与布局参考线

对齐组件

适应性要求

辅助功能

视觉辅助功能

文本与易读性

色彩对比度

色彩注意事项

屏幕阅读器

听觉辅助功能

媒体替代方案

音频提示

行动辅助功能

认知辅助功能

交互设计

动效与视觉效果

游戏辅助选项

visionOS 专项

动效与动画

核心原则

无障碍优先

反馈最佳实践

真实自然的动态效果

频率方面的考量

用户控制

特定平台指南

visionOS

watchOS

图标与符号

SF Symbols

自定义界面图标

何时使用图标，何时使用文本

无障碍

手势与输入

手势设计核心原则