| name | apple-hig |
| description | Apple Human Interface Guidelines 实战参考。涵盖 macOS/iOS 设计规范、System Colors、排版层级、控件规格、布局间距、Dark Mode 适配、辅助功能和平台差异。适用于开发 macOS 桌面应用（Electron/SwiftUI/AppKit）和 iOS 应用时的 UI 设计决策。 |
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. 排版
字体栈
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 标准缓动
--apple-ease: cubic-bezier(0.25, 0.1, 0.25, 1);
--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 特殊处理
box-shadow: 0 1px 3px rgba(0,0,0,0.08);
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
outline: none;
box-shadow: 0 0 0 3px rgba(0, 122, 255, 0.3);
ring-[var(--color-primary)]/30
所有可聚焦控件统一此规则。
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 — 容器层级与分组
D2 — 排版降噪
D3 — 控件选择
D4 — 交互反馈
D5 — 状态表达
通用审计
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 应用实战中的像素级校准经验。
