apply-macos-hig（apply macOS HIG 搜索）

macOS Human Interface Guidelines — Complete Design System Reference

Definitive reference for building native macOS applications. Backed by 21 exhaustively sourced reference documents totaling 13,286 lines — every claim traced to Apple HIG, AppKit API docs, SDK headers, WWDC sessions, or verified practitioner sources. Covers macOS Sequoia (15) through Tahoe (26) including Liquid Glass, Compositional Layout, SF Symbol effects, AutoFill/Passkeys, and window tiling.

The skill body below contains critical values you need constantly — spacing scale, typography sizes, component decision trees, and core patterns. For detailed specs, read the corresponding reference file from the Reference Index. Do not guess dimensions or behaviors — look them up.

1. The Three Laws of macOS UI

1. Every action must be in the menu bar. Toolbars can be hidden/customized. The menu bar is the source of truth for discoverability. Every toolbar action needs a menu bar equivalent.
2. Standard keyboard shortcuts are sacred. Cmd-Q quits, Cmd-W closes, Cmd-, opens Settings, Cmd-Z/X/C/V/A/S/F do what users expect. Breaking any of these is immediately noticed.
3. Settings take effect immediately. No Save/Cancel/Apply buttons in preferences. macOS settings are live.

2. Spacing Scale

macOS uses an 8pt baseline grid. All standard values are multiples or sub-multiples of 4pt.

The 20-8-6 rule: 20pt window margins, 8pt label-to-control gaps, 6pt minimum between stacked controls.

3. Typography Quick Reference

macOS text styles are 25-50% smaller than iOS equivalents for the same semantic name.

Critical: macOS body text is 13pt, not 17pt. Headline on macOS is Bold, not Semibold. SF Pro Text for sizes <= 19pt; SF Pro Display at >= 20pt.

4. Control Size Tiers

5. Component Decision Trees

Which Button Type?

Is it an action that executes immediately?
  YES -> Push button (.bordered / .borderedProminent)
    Is it the most likely action? -> Default button (Return key, accent fill)
    Is it destructive? -> .destructive role (system red, NOT the default)
    Does it open more UI? -> Add ellipsis: "Export..."
  NO -> Is it a binary on/off?
    YES -> Is it a major feature toggle taking effect immediately?
      YES -> NSSwitch / Toggle(.switch)
      NO -> Checkbox / Toggle(.checkbox)
    NO -> Is it one of 2-5 mutually exclusive options?
      YES -> Radio buttons (vertical preferred)
      NO -> Pop-up button (NSPopUpButton / Picker(.menu))

Which Container for Additional UI?

Blocks a critical operation? -> Alert (NSAlert) or Modal Sheet
Anchored to a control, brief and transient? -> Popover (.transient)
Persistent property editing alongside content? -> Inspector panel
Full-focus task, window still accessible? -> Sheet (beginSheetModal)
Inline expansion in current layout? -> DisclosureGroup / Disclosure triangle

Which Data Display Component?

Is the data hierarchical?
  YES -> Column-by-column navigation? -> NSBrowser
         Expandable tree? -> NSOutlineView
  NO -> Grid layout (equal-size items)? -> NSCollectionView / LazyVGrid
        List/rows?
          Need max performance (5000+ rows)? -> NSTableView (AppKit)
          Simple list (<1000 rows)? -> SwiftUI Table or List
          Sidebar navigation? -> NSOutlineView with .sourceList

Checkbox vs Toggle (NSSwitch)?

Major feature-level on/off, immediate effect, standalone? -> Toggle/Switch
Minor/detail setting, part of a form, or hierarchy of options? -> Checkbox
Already using checkboxes in same UI? -> Keep using checkboxes (consistency)
Deferred apply (Save/Submit button)? -> Checkbox

6. Window and Toolbar Patterns

Toolbar Styles (macOS 11+)

Toolbar Item Ordering

Leading: Sidebar toggle (anchored) -> App-specific items -> Center: Navigation -> Trailing: Search -> Share -> Inspector toggle

Sidebar Specs

7. Dialog and Alert Rules

Button Placement (macOS Convention)

[Destructive]     [Cancel]     [Default Action]
  <- left           middle       right (Return) ->

• Default button: trailing (rightmost), accent-colored, bound to Return
• Cancel: second from right, bound to Escape
• Never make a destructive button the default
• Use specific verbs ("Delete", "Erase"), not "OK" or "Yes"/"No"

Alert Text

• messageText (bold, larger): State the specific action — "Delete 'Project Alpha'?"
• informativeText (regular, smaller): State consequences — "You can't undo this."

8. Menu Bar Requirements

Standard menus in order: App Menu -> File -> Edit -> View -> [App-specific] -> Window -> Help

• "Settings..." (not "Preferences..." on macOS 13+) with Cmd-,
• Ellipsis only when further input required (Open..., Save As...) — NOT for About, Quit
• Toggle titles describe the action: "Show Toolbar" / "Hide Toolbar"
• Modifier glyph order: Fn -> Ctrl -> Opt -> Shift -> Cmd
• Help menu always contains a search field at top (system-provided)

9. Color System Essentials

Label Hierarchy (auto-adapts light/dark)

• Use semantic colors, never hardcoded hex — they auto-adapt to light/dark/high-contrast
• controlAccentColor follows the user's system accent color choice
• CALayer does NOT auto-adapt — refresh in viewDidChangeEffectiveAppearance()
• Asset catalog colors support 4 slots: Any, Dark, High Contrast, High Contrast Dark

10. Materials and Vibrancy

Critical: Title bar material MUST use .withinWindow. Sidebar uses .behindWindow (requires window.isOpaque = false).

Liquid Glass (macOS 26)

• API: NSGlassEffectView (AppKit) / .glassEffect() (SwiftUI)
• Variants: Regular (adaptive) and Clear (needs dimming overlay)
• Glass on control layer only (toolbars, sidebars) — never content
• No .state property — appearance depends on key window status

11. Motion and Animation

Use no-bounce or near-zero bounce springs on macOS. Always check accessibilityReduceMotion — substitute .opacity for spatial transitions.

12. Accessibility Non-Negotiables

• Every interactive element needs accessibilityLabel (unless visible text serves as label)
• Every custom NSView control must adopt a role-specific protocol (NSAccessibilityButton, etc.)
• Decorative images: .accessibilityHidden(true) / setAccessibilityElement(false)
• Test with VoiceOver (Cmd-F5) and Full Keyboard Access

13. SwiftUI vs AppKit

Practitioner consensus: SwiftUI implements HIG for you on iOS; on macOS, it fights you at every turn. Use SwiftUI for layout, fall back to AppKit via NSViewRepresentable for complex controls.

14. Common Mistakes

1. Treating macOS as a big iPad — No bottom tab bars, no full-screen sheets
2. Save/Cancel/Apply in Settings — Settings changes are immediate
3. Missing standard keyboard shortcuts — Cmd-, Cmd-W Cmd-Q Cmd-Z/X/C/V/A/S/F
4. Missing menu bar items — Every action needs a menu equivalent
5. iOS body text size (17pt) — macOS body is 13pt
6. iOS row heights (44pt) — macOS default is 22pt
7. Custom dark mode toggle — Respect NSAppearance
8. SwiftUI List/Table for large datasets — Falls apart past ~1000 rows
9. Missing Services menu — Text apps must support NSServicesMenuRequestor
10. Hardcoded colors — Use semantic NSColor tokens or asset catalog names

Reference Index

Read these files for detailed specs. Each contains exact values, API examples, and do's/don'ts.

Foundations

Components

Platform Patterns

Technologies

Context

Using References

When implementing a component or pattern:

1. Identify the reference file from the index above
2. Read it for exact dimensions, API examples, states, and do's/don'ts
3. Cross-reference practitioner insights for real-world gotchas
4. Check accessibility requirements in the accessibility reference

Do not rely on memory alone — the references are authoritative.