macos-app-design
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesemacOS App Design & Development
macOS 应用设计与开发
Guide for designing and implementing native-feeling, "good Mac citizen" apps: fast, elegant, accessible, and deeply integrated with macOS workflows.
本指南用于设计和实现具备原生质感、拥有“优秀Mac应用特质”的应用：快速、优雅、易用，并与macOS工作流深度集成。
Two Rules That Beat Everything Else
两条核心准则
- Prefer system components and conventions over bespoke UI—fastest path to "feels right on Mac"
- If you customize bars, backgrounds, borders, or control chrome: stop and justify it
- 优先使用系统组件和约定而非自定义UI——这是实现“Mac原生质感”的最快路径
- 若要自定义栏、背景、边框或控件外观：请先暂停并说明其合理性
Quick Reference: Mac Citizen Checklist
快速参考：优秀Mac应用特质检查表
| Area | Requirement |
|---|---|
| Menu Bar | Standard layout (App/File/Edit/View/Window/Help), ⌘, for Settings |
| Keyboard | Every primary command reachable via keyboard, standard shortcuts work |
| Windows | Resize fluidly, support multiple windows, respect fullscreen/minimize |
| Sidebars | Top-level navigation, scannable items, content extends behind |
| Toolbars | Group by function/frequency, demote secondary to "more" menu |
| Text | Use system text components, standard editing behaviors |
| Accessibility | VoiceOver labels, full keyboard navigation, Reduced Motion support |
| 领域 | 要求 |
|---|---|
| 菜单栏 | 标准布局（应用/文件/编辑/视图/窗口/帮助），使用⌘, 打开设置 |
| 键盘 | 所有核心命令均可通过键盘访问，标准快捷键可正常使用 |
| 窗口 | 可流畅调整大小，支持多窗口，适配全屏/最小化功能 |
| 侧边栏 | 顶级导航，条目易于浏览，内容延伸至侧边栏后方 |
| 工具栏 | 按功能/使用频率分组，将次要功能移至“更多”菜单 |
| 文本 | 使用系统文本组件，遵循标准编辑行为 |
| 无障碍访问 | 支持VoiceOver标签、全键盘导航、减少动态效果 |
Liquid Glass Quick Rules
Liquid Glass 设计准则速览
Do:
- Use for navigation/controls layer (toolbars, sidebars, bars)
- Let system components provide built-in behaviors
Don't:
- Apply to content layer (tables, lists, document content)
- Stack "glass on glass"
建议：
- 用于导航/控件层（工具栏、侧边栏、各类栏）
- 由系统组件提供内置行为
禁止：
- 应用于内容层（表格、列表、文档内容）
- 叠加使用“玻璃效果”
App Archetypes
应用原型分类
Identify your app type first:
- Document-based: Files as primary units (open/save/duplicate)
- Library + editor: Sidebar lists items, detail in main area
- Utility: Single window, optional menu bar
- Menu-bar app: Lives in menu bar, minimal UI
- Pro tool: Dense, power-user workflows
首先确定你的应用类型：
- 文档型：以文件为核心单元（支持打开/保存/复制）
- 库+编辑器型：侧边栏列出项目，主区域显示详情
- 工具型：单窗口，可选菜单栏
- 菜单栏应用：常驻菜单栏，UI极简
- 专业工具型：界面紧凑，面向高级用户工作流
Deliverables Before Building
开发前需完成的交付物
- App archetype identified
- Information architecture (sidebar structure, navigation, window model)
- Command map (menus + keyboard shortcuts for every major feature)
- State + data model (persistence, undo/redo, concurrency)
- Accessibility plan (VoiceOver, keyboard, contrast, reduce motion)
- 已确定应用原型
- 完成信息架构设计（侧边栏结构、导航、窗口模型）
- 制定命令映射表（包含所有主要功能的菜单及键盘快捷键）
- 设计状态与数据模型（持久化、撤销/重做、并发处理）
- 制定无障碍访问计划（VoiceOver、键盘操作、对比度、减少动态效果）
Full Reference
完整参考资料
For complete design system details, Icon Composer workflow, SF Symbols guidance, evaluation rubrics, and Definition of Done checklist:
See: references/macos-design-guide.md
如需完整的设计系统细节、Icon Composer工作流、SF Symbols使用指南、评估标准及完成定义检查表，请查看：
references/macos-design-guide.md
Common Mistakes
常见错误
| Mistake | Fix |
|---|---|
| Missing menu bar commands | Every feature in menus with keyboard shortcuts |
| Settings outside App menu | Always ⌘, opening from App menu |
| Custom text components | Use system text for Mac editing ecosystem |
| Toolbar overload | Demote secondary actions, group by function |
| Glass on content | Reserve Liquid Glass for navigation layer only |
| Breaking standard shortcuts | Never override ⌘C, ⌘V, ⌘Z, etc. |
| Single-window only | Support multiple windows when it benefits workflows |
| 错误 | 修复方案 |
|---|---|
| 缺少菜单栏命令 | 所有功能均需在菜单中提供，并配备键盘快捷键 |
| 设置入口不在应用菜单内 | 始终通过应用菜单中的⌘, 打开设置 |
| 使用自定义文本组件 | 使用系统文本组件以适配Mac编辑生态 |
| 工具栏功能过载 | 将次要操作降级，按功能分组 |
| 内容层使用玻璃效果 | 仅在导航层使用Liquid Glass效果 |
| 破坏标准快捷键 | 绝不要覆盖⌘C、⌘V、⌘Z等标准快捷键 |
| 仅支持单窗口 | 当对工作流有益时，支持多窗口功能 |