# Apple Hig

> Apple Human Interface Guidelines 实战参考。涵盖 macOS/iOS 设计规范、System Colors、排版层级、控件规格、布局间距、Dark Mode 适配、辅助功能和平台差异。适用于开发 macOS 桌面应用（Electron/SwiftUI/AppKit）和 iOS 应用时的 UI 设计决策。

- Skill: `modbender/apple-hig` (Agent Skill)
- Install (CLI): `npx skillmds@latest add modbender/apple-hig`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modbender/apple-hig/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: modbender (https://skillmd.com/u/modbender)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/modbender/apple-hig

---


# Apple Human Interface Guidelines 实战参考

从 Apple 官方 HIG 和生产级桌面应用实战中提炼的设计规范速查。

## 适用场景

- macOS 桌面应用 UI 设计（Electron / SwiftUI / AppKit）
- iOS 应用 UI 设计
- 需要"原生感"的跨平台应用
- 审计现有 UI 是否符合 Apple 设计语言

## 不适用

- Android / Windows 应用（参考 Material Design / Fluent Design）
- Web 专属设计（不追求 native 感）

---

## 1. 核心设计原则

Apple HIG 的三大支柱：

| 原则 | 含义 | 实践 |
|------|------|------|
| **Clarity（清晰）** | 文字可读、图标清晰、功能一目了然 | 用 SF 字体、标准图标、足够对比度 |
| **Deference（顺从）** | UI 服务内容，不喧宾夺主 | 减少装饰、留白充足、动画克制 |
| **Depth（层次）** | 通过视觉层级传达结构 | 阴影、模糊、动画暗示前后关系 |

### 与其他平台的根本区别

```
Apple: 做减法，每一个像素都要有理由
Material: 做加法，用动效和色彩引导注意力
Fluent: 做透明，用 Acrylic/Mica 融入环境
```

---

## 2. 颜色系统

### Apple System Colors

这些颜色在 Light/Dark 模式下自动适配，**优先使用**：

| 颜色 | Light HEX | Dark HEX | 用途 |
|------|-----------|----------|------|
| Blue | `#007AFF` | `#0A84FF` | 主强调色、链接、可交互元素 |
| Green | `#34C759` | `#30D158` | 成功、确认 |
| Orange | `#FF9500` | `#FF9F0A` | 警告 |
| Red | `#FF3B30` | `#FF453A` | 错误、危险操作、删除 |
| Purple | `#AF52DE` | `#BF5AF2` | 辅助强调 |
| Teal | `#5AC8FA` | `#64D2FF` | 次要信息 |
| Yellow | `#FFCC00` | `#FFD60A` | 注意 |
| Pink | `#FF2D55` | `#FF375F` | 情感、收藏 |
| Indigo | `#5856D6` | `#5E5CE6` | 特殊强调 |

### 语义色

| 用途 | Light | Dark |
|------|-------|------|
| Label（主文字） | `#000000` | `#FFFFFF` |
| Secondary Label | `rgba(0,0,0,0.5)` | `rgba(255,255,255,0.55)` |
| Tertiary Label | `rgba(0,0,0,0.25)` | `rgba(255,255,255,0.25)` |
| Quaternary Label | `rgba(0,0,0,0.1)` | `rgba(255,255,255,0.1)` |
| Separator | `rgba(0,0,0,0.1)` | `rgba(255,255,255,0.1)` |
| Background（窗口） | `#FFFFFF` | `#1E1E1E` |
| Secondary BG | `#F5F5F5` | `#2C2C2E` |
| Tertiary BG | `#FFFFFF` | `#3A3A3C` |

### 使用原则

```
✅ 用 System Colors 做交互元素的强调色
✅ 用语义色做文字、背景、分隔线
❌ 不要硬编码 #007AFF — 在 Dark Mode 下它应该变成 #0A84FF
❌ 不要用 System Colors 做静态数据展示（如参数值 "0.3"、"18s"）
```

**铁律**：主强调色严格保留给**强交互元素**（按钮、Checkbox 选中、Slider 填充段、Focus Ring），不用于静态文字/数值。

---

## 3. 排版

### 字体栈

```css
font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Text', system-ui, sans-serif;
```

macOS 上会自动使用 SF Pro，iOS 上使用 SF。不要手动指定 SF Pro 的 TTF 文件。

### 字号层级（macOS）

| 层级 | 字号 | 字重 | 颜色 | 用途 |
|------|------|------|------|------|
| Large Title | 26px | Bold | Label | 页面大标题（iOS 常用，macOS 少用） |
| Title 1 | 22px | Regular | Label | 区块标题 |
| Title 2 | 17px | Regular | Label | 次要标题 |
| Title 3 / Headline | 15px | Semibold | Label | 工具栏标题、卡片标题 |
| Body | 13px | Regular | Label | 正文、控件默认 |
| Callout | 12px | Regular | Label | 注释文字 |
| Subheadline | 11px | Regular | Secondary Label | 辅助说明 |
| Footnote | 10px | Regular | Tertiary Label | 脚注、时间戳 |
| Caption 1 | 10px | Regular | Tertiary Label | 图片说明 |
| Caption 2 | 10px | Medium | Tertiary Label | 表格表头 |

### 字号层级（iOS）

| 层级 | 字号 | 字重 |
|------|------|------|
| Large Title | 34px | Bold |
| Title 1 | 28px | Regular |
| Title 2 | 22px | Regular |
| Title 3 | 20px | Regular |
| Headline | 17px | Semibold |
| Body | 17px | Regular |
| Callout | 16px | Regular |
| Subheadline | 15px | Regular |
| Footnote | 13px | Regular |
| Caption 1 | 12px | Regular |
| Caption 2 | 11px | Regular |

### 实战要点

- **macOS 默认正文 13px**，iOS 默认正文 17px — 差异大，不要混用
- Section 标题用 `11px font-medium text-black/40` 降噪（macOS），**禁止** `uppercase tracking-wide font-bold`
- 静态数值（Slider 值、时间）用 `12px font-mono text-black/50`
- 辅助说明 `10-11px font-normal text-black/25~30`

---

## 4. 控件规格

### macOS 标准控件尺寸

| 控件 | 高度 | 内边距 | 圆角 |
|------|------|--------|------|
| Button（Regular） | 22px | 12px 水平 | 5px |
| Button（Large） | 28px | 16px 水平 | 7px |
| TextField | 22px | 4px 内 | 5px |
| Checkbox | 14×14px | — | 3px |
| Radio | 16×16px（circle） | — | 50% |
| Switch（macOS Ventura+） | 20×34px | — | 10px |
| Slider | 4px 轨道高 | — | 2px |
| Segmented Control | 22px | 6px 水平 | 5px |
| Popup Button | 22px | 内含箭头 | 5px |

### iOS 标准控件

| 控件 | 最小高度 | 触控目标 |
|------|----------|---------|
| Button | 44px | 44×44px |
| TextField | 44px | — |
| Navigation Bar | 44px | — |
| Tab Bar | 49px | — |
| Table Row | 44px | 全宽 |

### ⚠️ 触控目标铁律

```
最小触控目标：44×44pt（iOS） / 24×24px（macOS 鼠标）
```

即使视觉上更小，可点击区域也必须达到最小尺寸。

### Segmented Control（macOS 仿真规格）

| 属性 | 值 |
|------|-----|
| 底座色 | `#e8e8ed` |
| 底座内距 | `p-[3px]` |
| 底座圆角 | `rounded-lg` |
| 选中药丸 | `bg-white rounded-[7px]` |
| 药丸阴影 | `0 1px 3px rgba(0,0,0,0.08), 0 0.5px 1px rgba(0,0,0,0.12)` |
| 文字 | `text-[13px] font-medium` |
| 选中文字 | `text-[#1d1d1f]` |
| 未选中文字 | `text-black/50` |
| 布局 | `flex-1` 平分等宽 |

**不要替换为 Tabs 或 RadioGroup** — Segmented Control 是 2-5 个选项的切换专用控件。

---

## 5. 布局与间距

### macOS 间距系统

| 间距 | 值 | 用途 |
|------|-----|------|
| 最小间距 | 4px | 相关元素间 |
| 控件间距 | 8px | 按钮组、表单字段间 |
| 区块间距 | 12-16px | 功能区块间 |
| 大区块间距 | 20-24px | 页面 section 间 |
| 窗口内边距 | 20px | 窗口内容边距 |

### 窗口

| 属性 | macOS | iOS |
|------|-------|-----|
| 最小宽度 | 400px | — |
| 标题栏高度 | 22px（标准）/ 52px（工具栏） | — |
| Sidebar 宽度 | 200-260px（标准） | — |
| Safe Area | 无 | 顶部/底部刘海 |

### 容器层级

```
✅ 平铺式布局 — 内容直接放在白底上，用间距和微弱分隔线区分
❌ 框套框 — Card 里面套 Card，增加视觉噪音
```

**实战规则**：
- 配置参数直接平铺，不要用 border + padding 整体包裹
- 列表 Header 可用极弱底纹（`bg-[#f5f5f7]/50`）产生软分隔
- 去掉灰色嵌套面板（`bg-s-bg-subtle` Card 套 Card）

---

## 6. 图标

### SF Symbols

Apple 提供 5000+ 个 SF Symbols 图标，与 SF 字体匹配。

```
使用场景：macOS / iOS 原生应用
替代方案：Lucide Icons（Web/Electron，风格接近 SF Symbols）
```

### 图标规格

| 场景 | 尺寸 | 线宽 |
|------|------|------|
| 工具栏 | 16×16px | 1.5px |
| 导航项 | 20×20px | 1.5px |
| Tab Bar（iOS） | 25×25px | — |
| 空状态 | 48-64px | 1px |

### 颜色规则

```
✅ 可交互图标：System Blue（或当前 accent color）
✅ 信息图标：Secondary Label 色
✅ 状态图标：对应 System Color（Green=成功, Red=错误）
❌ 禁止给信息图标上彩色 — 只有可交互/状态图标用色
```

---

## 7. 动画与过渡

### 标准时长

| 类型 | 时长 | 缓动 |
|------|------|------|
| 微交互（hover, press） | 100-200ms | ease-out |
| 状态切换 | 200-300ms | ease-in-out |
| 页面转场 | 300-500ms | ease-in-out |
| 弹窗出现 | 200ms | ease-out |
| 弹窗消失 | 150ms | ease-in |

### Apple 标准缓动

```css
/* macOS 标准 */
--apple-ease: cubic-bezier(0.25, 0.1, 0.25, 1);

/* Spring-like（弹性） */
--apple-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
```

### 动画原则

```
✅ 动画要有目的 — 引导注意力、暗示关系
✅ 支持 prefers-reduced-motion — 简化或禁用动画
❌ 不要为了炫技加动画 — Apple 的动画是"感觉到但说不出"的
❌ 不要用 linear 缓动 — 感觉机械
```

---

## 8. Dark Mode

### 设计原则

```
Dark Mode ≠ 反转颜色
Dark Mode = 重新设计的配色方案
```

| 原则 | 实践 |
|------|------|
| 用语义色 | 不硬编码 `#FFFFFF` / `#000000` |
| 降低饱和度 | Dark 模式中高饱和度色块刺眼 |
| 提高对比度 | 文字/图标的对比度要求更严格 |
| 阴影不可见 | Dark 模式中阴影效果弱，改用微弱边框或高光 |

### macOS Dark Mode 特殊处理

```css
/* Light: 阴影分层 */
box-shadow: 0 1px 3px rgba(0,0,0,0.08);

/* Dark: 阴影无效，改用微弱边框 */
border: 1px solid rgba(255,255,255,0.06);
```

### 适配检查

```
✅ 所有文字在 Dark 背景上对比度 ≥ 4.5:1
✅ 分隔线/边框在两种模式下都可见
✅ 图标在两种模式下都清晰
✅ 品牌色在 Dark 模式下略微提亮
```

---

## 9. 辅助功能（Accessibility）

### WCAG 对比度

| 级别 | 正文 | 大字体（≥18px bold / ≥24px） |
|------|------|---------------------------|
| AA | ≥ 4.5:1 | ≥ 3:1 |
| AAA | ≥ 7:1 | ≥ 4.5:1 |

### Apple 特有要求

```
✅ 支持 Dynamic Type（iOS）— 用户可全局调整字体大小
✅ 支持 VoiceOver — 所有可交互元素有 aria-label
✅ 支持 Reduce Motion — 简化动画
✅ 支持 Increase Contrast — 提高边框/文字对比度
✅ 支持键盘导航（macOS）— Tab 遍历所有控件
```

### Focus Ring

```css
/* macOS 标准 Focus Ring */
outline: none;
box-shadow: 0 0 0 3px rgba(0, 122, 255, 0.3);

/* 或用 Tailwind */
ring-[var(--color-primary)]/30  /* 不带 ring-offset */
```

所有可聚焦控件统一此规则。

---

## 10. macOS vs iOS 差异速查

| 差异点 | macOS | iOS |
|--------|-------|-----|
| 正文字号 | 13px | 17px |
| 最小交互目标 | 24px | 44px |
| 导航模式 | Sidebar + Tab | Tab Bar + Navigation Stack |
| 窗口管理 | 多窗口 | 单窗口全屏 |
| 输入方式 | 鼠标 + 键盘 | 手指触控 |
| Hover 状态 | 必须有 | 没有（无鼠标） |
| Right-click | 上下文菜单 | 长按菜单 |
| 滚动条 | 自动隐藏 / 始终显示 | 始终自动隐藏 |
| 标题栏 | 红黄绿三按钮（左上角） | 无 |
| 通知 | 右上角通知中心 | 顶部横幅 |

### 跨平台设计策略

```
如果是 Electron 桌面应用：
  → macOS: 追求 native 感，使用 Segmented Control、Sidebar
  → Windows: 可以偏 Fluent，也可以保持统一（大多数 Electron 应用选后者）

如果是 React Native / Flutter：
  → 每个平台用对应的组件库（iOS: Cupertino / Android: Material）
  → 或用自定义设计语言统一（如 Notion、Figma 的做法）
```

---

## 11. HIG 审计 Checklist

### 设计审计五维度

**D1 — 容器层级与分组**
- [ ] 无框套框（Card 套 Card）
- [ ] 配置参数平铺，不过度包裹
- [ ] 列表 Header 用弱底纹分隔，非强边框

**D2 — 排版降噪**
- [ ] Section 标题用 `11px font-medium text-black/40`（macOS）
- [ ] 禁止 `uppercase tracking-wider font-bold`
- [ ] Card header 高度适当（macOS: ~40px）

**D3 — 控件选择**
- [ ] 2-5 选项切换用 Segmented Control
- [ ] 数值显示用纯文字 `font-mono text-black/50`
- [ ] 主按钮用 accent color，不用品牌色

**D4 — 交互反馈**
- [ ] 所有可交互元素有 hover 状态（macOS）
- [ ] Focus Ring 统一使用 accent color /30
- [ ] 动画时长 100-300ms，缓动用 ease-out

**D5 — 状态表达**
- [ ] 日志/状态用纯文字颜色区分（Apple System Colors）
- [ ] 时间戳 `text-black/20 text-[10px]`
- [ ] 空状态克制：浅灰图标 + 简短文字
- [ ] Loading 用 skeleton / spinner，不留空白

### 通用审计

- [ ] 所有文字对比度 ≥ 4.5:1
- [ ] 触控目标 ≥ 44pt（iOS）/ 24px（macOS）
- [ ] 支持 prefers-reduced-motion
- [ ] 支持 prefers-color-scheme（Dark Mode）
- [ ] 键盘可导航所有控件（macOS）

---

## 12. 快速参考卡片

### 色彩

```
主强调: #007AFF (Light) / #0A84FF (Dark)
成功:   #34C759 / #30D158
警告:   #FF9500 / #FF9F0A
错误:   #FF3B30 / #FF453A
```

### 字体

```
macOS 正文: 13px Regular
iOS 正文:   17px Regular
字体栈:     -apple-system, BlinkMacSystemFont, 'SF Pro Text', system-ui
```

### 间距

```
最小: 4px | 控件间: 8px | 区块间: 16px | 窗口边距: 20px
```

### 动画

```
微交互: 150ms ease-out
状态切换: 250ms ease-in-out
标准缓动: cubic-bezier(0.25, 0.1, 0.25, 1)
```

---

## 来源

Apple Human Interface Guidelines (developer.apple.com/design/human-interface-guidelines) + 生产级 macOS Electron 应用实战中的像素级校准经验。