SkillHub

apple-hig

v1.0.0

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

Sourced from ClawHub, Authored by BingFoon

Installation

Please help me install the skill `apple-hig` from SkillHub official store. npx skills add bingfoon/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. 排版

字体栈

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 标准缓动

/* 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 特殊处理

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

/* 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 应用实战中的像素级校准经验。