macos-design

---
name: macos-design
license: MIT
description: "设计、实现、改进或审查 SwiftUI / AppKit 原生 macOS 应用界面，依据项目规范处理多窗口、分栏、菜单栏、快捷键、系统组件、排版密度、材质、鼠标键盘交互与无障碍。适用于效率工具、文档、数据管理、编辑器、设置窗口及菜单栏轻应用；网页或跨平台桌面应用仅在明确要求 Mac 风格或平台差异分析时使用。"
---

# MacOS-design

清晰、克制、高密度但不拥挤。围绕持续工作与精确操作组织窗口，让对象、属性和命令易于发现，支持窗口调整及工作状态恢复。

## 使用方式

先明确任务对象、窗口角色、命令作用范围、现有实现平台与最低部署版本；能从项目和用户上下文确定的信息直接沿用。按任务读取相关参考章节，再完成设计、实现或审查。

| 当前问题 | 参考文件与章节 |
| --- | --- |
| 设计层级、窗口角色、标题栏、Sidebar、Toolbar、分栏缩放 | [基础与窗口](references/foundations-windows.md)，导言与第 1–2 章 |
| 字体、标题、间距、表单对齐、列宽、滚动与安全区域 | [排版与布局](references/typography-layout.md)，第 3–4 章 |
| 控件尺寸、按钮、Checkbox、Table、Outline、Sheet、Panel、设置与状态 | [原生组件](references/native-components.md)，第 5 章 |
| 功能入口、系统菜单栏、快捷键、搜索范围、右键与 Hover | [命令与搜索](references/commands-search.md)，第 6 章 |
| SF Symbols、图标或文字、Tooltip、Help、应用与状态图标 | [图标与文案](references/icons-writing.md)，第 7 章 |
| 语义色、系统强调色、Vibrancy、Glass、滚动边缘、圆角与模糊 | [材质与交互](references/materials-interaction.md)，第 8 章 |
| 动效、指针、选择、拖放、键盘焦点、无障碍与持续反馈 | [材质与交互](references/materials-interaction.md)，第 9 章 |
| 效率工具、三栏、编辑器、设置、菜单栏应用及 Mac/iOS/Web 差异 | [布局模式与平台差异](references/patterns-platform.md)，第 10.1–10.6 节 |
| Apple 官方依据、系统版本、API 可用性、第三方观察 | [资料出处](references/sources.md)，第 10.7–10.8 节 |

参考内容来自项目《macOS 原生应用设计规范》2026 年 10 月深度研究版，沿用原章节号与文献标识：

- **〔Apple〕**：原规范引用的系统原则、样式、数值或交互约定。
- **〔建议〕**：统一设计语言的推荐起点，随信息密度、任务和可用空间调整。
- **〔条件〕**：满足对应应用类型、窗口尺寸或系统设置时使用。

版本专属条目，尤其 macOS 26/27、WWDC 2026、控件尺寸与 Glass 行为，结合目标 SDK 和当前 Apple 官方文档核对 API 及可用性，并为最低部署版本保留适配路径。联网核对聚焦当前决策需要的来源；第三方观察用于辅助判断。

## 核心设计决策

### 窗口和工作区

- 按任务选单栏、Sidebar + Content、Sidebar + List + Detail、Canvas + Inspector，或菜单栏轻应用。内容与属性需要并行参照时使用常驻分栏或独立窗口。
- 使用原生窗口、标题栏与交通灯控制，保留拖动、缩放、最小化、全屏和跨屏行为。保留系统窗口外缘与圆角，工具栏避让系统窗口按钮。
- 可调整分栏宽度、隐藏侧边栏或检查器，缩小时按任务优先级折叠次要区域；折叠后保留恢复入口。断点由栏位所需宽度推导。
- 恢复适用的窗口位置、尺寸、当前对象、滚动位置及工作区状态，尊重用户调整。菜单命令与输入作用于当前焦点和对象；涉及浮动面板或多窗口时区分主窗口与 Key 窗口。
- 标题表达文档、对象或工作区身份；内容已有清楚身份时保持标题简洁。主要动作放在 Toolbar、内容顶部或对象附近，窗口底边适合状态和有其他入口的辅助控制。

### 命令、菜单和键盘

- 系统菜单栏覆盖应用命令，遵循 App、File、Edit、View、Window、Help 等熟悉结构。工具栏提供高频动作，右键和 Hover 提供对象级快捷入口。
- 工具栏可隐藏或定制，其命令在菜单栏中仍可发现；重要操作始终保留可见或菜单入口。菜单动作依据焦点、选中对象和当前任务启用。
- 沿用适用的 ⌘N、⌘O、⌘S、⌘W、⌘Q、⌘,、⌘F、⌘Z 及复制粘贴惯例；⌘W 关闭当前窗口，⌘Q 退出应用。快捷键与菜单使用相同命令及状态来源。
- 全局设置通过 App 菜单和 ⌘, 打开独立设置窗口；任务内参数放在相关内容或 Inspector。默认用 Checkbox 表达普通设置，重要状态按语义选择 Switch。
- 搜索位置表达范围：跨列搜索放 Toolbar 尾端，集合过滤放列表顶部，侧边栏筛选放侧边栏顶部，文档查找使用文档内查找条。
- 键盘焦点顺序跟随视觉顺序，选中态与焦点态清楚区分；Tab、Shift-Tab 和 Esc 按上下文工作。Hover 中的必要信息也能通过键盘焦点获得。

### 原生组件、内容和反馈

- 优先 SwiftUI / AppKit 原生窗口、分栏、Toolbar、List、Table、Outline、Form、Picker 和标准文件面板，沿用项目已有能力。系统控件采用自身 `controlSize`、内在尺寸和平台行为。
- 按数据结构选择 List、Table 或 Outline。适用时支持列排序、列宽调整、复制、⌘ 多选、Shift 连续选择，以及清楚的持续选中态。
- 编辑任务保留撤销、重做、文本选择、复制粘贴与文件操作习惯；任务涉及文件拖放时，支持 Finder 拖入并展示目标、预览和复制/移动语义。
- Popover 承载锚定控件的少量临时内容；Sheet 承载当前父窗口的短任务；Panel / Inspector 承载反复参照修改；独立窗口承载完整流程。Sheet 的阻断范围限定在父窗口。
- 表单保留可见标签。宽窗口使用对齐的标签与控件列，窄窗口或长标签改为上下排列。设置窗格保留导航位置并更新当前标题。
- 空状态说明下一步；加载保持布局稳定；已知进度展示真实数量、比例或阶段。错误贴近受影响对象并给出补救，成功反馈以局部状态和自然内容更新为主。

### 排版、图标和材质

- macOS 正文优先语义 Body，默认 13pt / 16pt 行高，辅助文字通常 11–12pt。系统字体、控件和行高随用户设置适配，自定义容器支持文字增长。
- 文本使用 leading/trailing，表单标签与控件基线对齐；可比较数值对齐，必要时采用等宽数字。阅读列约束行长，表格、时间线和画布根据内容使用空间。
- 通过空间、字号、对齐和语义色组织层级；明确需要独立容器的内容再使用面板。普通列表保留紧凑且连续的扫描节奏。
- 标准 Toolbar 动作可用单图标与简短 Tooltip，并提供无障碍名称；Sidebar 保留文字，陌生业务动作和风险操作使用具体动作文字。必要规则就地常显，说明只补充结果、前提和后果。
- 使用系统动态色和用户 Accent Color，兼顾浅色、深色、选中与失焦状态。在目标系统支持时，Glass 用于导航与交互层，内容使用标准背景或语义 Material / Vibrancy。
- 在目标系统与 SDK 支持时，滚动内容经过固定栏下方采用系统 Scroll Edge Effect，默认 Automatic，分栏边缘保持协调；较早版本保留其系统边界处理。Gaussian / 渐进模糊用于媒体视觉处理，系统材质由相应原生能力承载。
- 采用系统动效，自定义运动表达状态或空间关系；支持 VoiceOver、完整键盘访问、文字缩放、增加对比度、Reduce Motion、Reduce Transparency 及目标系统支持的边框偏好。

## 自定义布局的常用起点

以下数值用于初步方案或自定义区域，随内容与用户设置调整。系统组件保留系统尺寸；详细表见基础与窗口的快速参数索引及相应主题章节。

| 项目 | 起点 |
| --- | --- |
| 主内容水平边距 | 20–24pt；紧凑工具 16–20pt |
| 间距 | 4pt 主节奏，允许 2pt 微调；组内 8–12pt，组间 20–32pt |
| 字体 | Body 13pt；辅助 11–12pt；局部标题 15–17pt |
| Sidebar / Inspector 初始宽度 | 220–280pt / 260–340pt，可调整与折叠 |
| 阅读列最大宽度 | 620–820pt，表格与画布另按内容布局 |
| 自定义常规图标按钮 | 点击区约 28–32pt，工具栏符号视觉大小约 14–18pt |
| 自定义普通列表行 | 30–38pt；双行内容约 48–60pt |
| 自定义动画 | 微反馈约 100–180ms，区域切换约 180–260ms |

## 交付与检查

设计任务交付窗口结构、命令入口、组件选择、状态行为和必要视觉参数；实现任务在现有项目中完成修改；审查任务给出具体位置、体验影响和可执行建议。

围绕当前改动复核最小窗口和分栏折叠、命令目标和快捷键、键盘焦点及文字增长、选中和失焦表现、相关状态恢复、深色模式和辅助功能。按代码改动完成必要的编译、类型或业务验证。UI 交互和最终体验交由用户人工验收，自动化点击或页面走查须由用户明确要求。

用户选择网页、Electron 或其他跨平台技术栈时，保留其实现平台；明确需要 Mac 风格时按平台差异章节转换窗口、路由、输入、菜单和无障碍语义，并区分实际系统能力与视觉模拟。

• LICENSE 1 KB
• SKILL.md 9 KB
• agents/openai.yaml 1 KB
• references/commands-search.md 5 KB
• references/foundations-windows.md 12 KB
• references/icons-writing.md 4 KB
• references/materials-interaction.md 8 KB
• references/native-components.md 8 KB
• references/patterns-platform.md 7 KB
• references/sources.md 6 KB
• references/typography-layout.md 8 KB