apple-design

Apple 设计系统与人机界面指南（HIG）

此技能让 AI 编码 Agent 掌握 Apple 人机界面指南（HIG） 中为 iOS、iPadOS、macOS、watchOS、visionOS 及现代 Apple 级 Web UI 定义的精确原则、视觉规范、组件架构、字体排版指标、颜色令牌、动态曲线和自动化合规审计。

---

🎯 操作模式

模式 1 — 从头开始设计与构建

接到以 Apple 风格创建新屏幕、应用或 Web 界面的任务时：

1. 选择平台原生的导航范式（例如：iOS 的底部标签栏、macOS/iPad 的侧边栏、visionOS 的装饰控件）。
2. 建立 8pt 空间网格和连续的圆角超椭圆曲率（G2 continuity）。
3. 应用 SF Pro / New York 字体比例和视觉校正字距规则。
4. 实现语义化动态颜色（浅色与 OLED 深色模式）和液态磨砂玻璃材质。
5. 应用 Apple 弹簧物理效果（cubic-bezier(0.25, 1, 0.5, 1)）和触感式主动反馈（scale(0.97)）。

模式 2 — Apple HIG 合规性审计与评分

审查现有代码库、模型图或组件时：

1. 运行审计工具 node skills/apple-design/scripts/audit-apple-design.mjs，进行自动化静态扫描，并按照 0–100 分评分标准评分。
2. 进行精确的数学 WCAG 对比度检查，并验证 44×44pt 触控目标。
3. 按照 5 个核心支柱填写 Apple HIG 审计评分卡。
4. 提供按优先级排序的发现，并标注 置信度：
   • 🟢 工具已验证：通过 CLI 工具进行统计测量（例如，对比度、按钮尺寸、静态 CSS 规则）。
   • 🟡 需要设备测试：需要硬件交互（例如，300% 动态字体、切换降低透明度、VoiceOver 语音层级）。
   • 🔴 推测：情境化的设计权衡或主观审美评估。

---

🛠️ Apple HIG 合规性 CLI 引擎

内置审计引擎（skills/apple-design/scripts/audit-apple-design.mjs）提供四个子命令：

# 1. Full Codebase Static Scan with 0-100 Scorecard (Default)
npm run audit
# or: node skills/apple-design/scripts/audit-apple-design.mjs [path]

# 2. WCAG Relative Luminance Contrast Ratio Check
node skills/apple-design/scripts/audit-apple-design.mjs contrast "#8E8E93" "#FFFFFF"
# -> Contrast Ratio: 3.26:1 [🔴 FAILED - Needs >= 4.5:1]

# 3. Tap Target Sizing Validation (44x44 pt minimum)
node skills/apple-design/scripts/audit-apple-design.mjs target 32 32
# -> Tap Target: 32x32 pt [🔴 FAILED - Minimum 44x44 pt]

# 4. Batch JSON Automated Verification
node skills/apple-design/scripts/audit-apple-design.mjs batch audit.json

审计评分标准：

• 基础分：100 分。
• 扣分：每项违规扣 10 分。
• 评分卡分类：
  • 🟢 90 – 100 分：可发布（已做好发布准备） — 达到卓越标准。
  • 🟡 70 – 89 分：发布前需修复 — 上架 App Store / 投入生产环境前需要修复。
  • 🔴 < 70 分：需要系统性重新设计 — 严重违反架构或无障碍设计要求。

---

1. 核心设计理念

Apple 界面建立在三大支柱之上：

1. 清晰：

   • 文本在各种尺寸下都清晰易读；图标精准、易于区分且广为人知。
   • 装饰元素含蓄且恰到好处。内容始终比装饰性界面元素更具视觉优先级。
   • 负空间（留白）提供呼吸空间，并理清视觉层级。

2. 谦让：

   • 流畅的动态效果、半透明材质和清晰的字体排版能够提升内容，而不会与内容争夺注意力。
   • 背景应衬托内容；当用户专注于主要任务时，界面元素应淡出。

3. 深度：

   • 不同的视觉层次、真实的光照、镜面高光和真实的弹簧物理效果，共同传达空间层级和触感真实感。
   • 立体效果和材质能够传达交互暗示，无需使用生硬的投影或刺眼的轮廓线。

---

2. Apple 通用设计原则与关键规则

🚫 禁止的反模式（绝不要这样做）

• 深色主题中禁止使用紫色／紫罗兰色：绝不要在深色背景上使用紫色字体或紫罗兰色强调按钮。请使用 Apple System Blue（#0A84FF）或语义化系统色调。
• 禁止使用生硬的投影：绝不要使用浓重、未经柔化的黑色盒状阴影（box-shadow: 0 4px 10px rgba(0,0,0,0.5)）。请使用多层环境漫射效果（box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08), 0 1px 2px rgba(0, 0, 0, 0.04)）。
• 禁止使用尖锐／几何形状的圆角：交互控件、卡片或输入框的圆角绝不能设为 0px，也不能使用任意的非连续圆角。
• 禁止使用未经字距调整的大字号字体：绝不要在没有紧凑字距（-0.02em 至 -0.03em／-0.5px 至 -1.2px）的情况下渲染大标题（>24px）。
• 禁止使用非标准触控目标：绝不要创建小于 44×44 pt（iOS 标准）或 28×28 pt（macOS 紧凑指针）的可点击元素。
• 禁止使用普通的静态 CSS 过渡：物理交互效果绝不要使用 ease-in-out；始终使用流畅的弹簧物理效果或 Apple 缓动曲线。

---

3. 视觉基础

A. 字体系统（San Francisco 与 New York）

• 主要界面字体：SF Pro（-apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", "Helvetica Neue", sans-serif）
• 等宽字体：SF Mono（ui-monospace, "SF Mono", Menlo, Monaco, Consolas, monospace）
• 衬线字体：New York（"New York", ui-serif, Georgia, Cambria, serif）

字体比例与光学尺寸规则：

样式	大小（pt/px）	字重	行高	字距／字母间距
大标题	34px	粗体（700）	41px	-0.022em (-0.75px)
标题 1	28px	粗体／半粗体	34px	-0.020em (-0.56px)
标题 2	22px	粗体／半粗体	28px	-0.018em (-0.40px)
标题 3	20px	半粗体（600）	25px	-0.015em (-0.30px)
主标题	17px	半粗体（600）	22px	-0.012em (-0.20px)
正文	17px	常规（400）	22px	-0.010em (-0.17px)
提示文字	16px	常规（400）	21px	-0.008em (-0.13px)
副标题	15px	常规（400）	20px	-0.005em (-0.08px)
脚注	13px	常规（400）	18px	0.000em (0.00px)
说明文字 1	12px	常规（400）	16px	0.005em (+0.06px)
说明文字 2	11px	常规／中等	13px	0.010em (+0.11px)

---

4. 材质、半透明效果与镜面玻璃

Apple 材质会模糊底层内容，在保持鲜艳感的同时营造视觉上的稳定感：

/* Authentic Apple Ultra-Thin Frosted Glass Material */
.apple-material-ultrathin {
  background: rgba(255, 255, 255, 0.72);
  backdrop-filter: blur(20px) saturate(190%);
  -webkit-backdrop-filter: blur(20px) saturate(190%);
  border: 1px solid rgba(255, 255, 255, 0.45);
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.04), 0 1px 2px rgba(0, 0, 0, 0.02);
}

@media (prefers-color-scheme: dark), [data-theme="dark"] {
  .apple-material-ultrathin {
    background: rgba(28, 28, 30, 0.75);
    backdrop-filter: blur(25px) saturate(190%);
    -webkit-backdrop-filter: blur(25px) saturate(190%);
    border: 1px solid rgba(255, 255, 255, 0.12);
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.35), 0 1px 3px rgba(255, 255, 255, 0.05) inset;
  }
}

---

5. 动画物理效果（Apple 弹簧曲线）

交互式 UI 绝不要使用线性或标准缓动曲线。请使用真实的 Apple 弹簧物理效果：

弹簧参数参考：

• 交互／点击反馈：mass: 1, stiffness: 350, damping: 35（CSS 近似值：cubic-bezier(0.25, 1, 0.5, 1)）
• 面板呈现／模态框滑动：mass: 1.2, stiffness: 280, damping: 28（CSS 近似值：cubic-bezier(0.32, 0.72, 0, 1)）
• 灵敏的开关／切换：mass: 0.8, stiffness: 450, damping: 30

/* Apple Native Motion Classes */
.apple-spring-interactive {
  transition: transform 0.35s cubic-bezier(0.25, 1, 0.5, 1),
              opacity 0.25s ease;
}

.apple-spring-interactive:active {
  transform: scale(0.965);
}

---

6. 捆绑资源与完整 Apple HIG 文档库

• Apple HIG 文档主目录 (skills/apple-design/references/INDEX.md)：包含全部 172 个指南主题的完整可搜索索引。
• Apple HIG 审核评分卡模板：标准的五大支柱评估评分卡。
• 资源与预设：
  • skills/apple-design/assets/apple-tokens.css：完整的 CSS 变量设计令牌样式表。
  • skills/apple-design/assets/apple-components.css：可直接使用的 CSS 组件（按钮、玻璃卡片、分段控件、表单）。
  • skills/apple-design/assets/tailwind.preset.apple.js：Tailwind 配置预设。
  • skills/apple-design/assets/swiftui-cheat-sheet.md：符合 SwiftUI 惯用风格的模式。
• CLI 自动化工具：
  • npm run audit：扫描代码库中的 Apple HIG 违规项，并生成 0–100 分的评分。
  • npm run fetch-hig：从 Apple CDN 获取并更新完整的 Apple HIG 文档和插图。