macos-hig-designer
# macOS HIG Designer
Design native macOS applications following Apple's Human Interface Guidelines with macOS Tahoe's Liquid Glass design system.
## Workflow Decision Tree
```
User Request
│
├─► "Review my macOS UI code"
│ └─► Run HIG Compliance Check (Section 11)
│ └─► Report violations with fixes
│
├─► "Modernize this macOS code"
│ └─► Identify deprecated APIs
│ └─► Apply Modern API Replacements (Section 10)
│
└─► "Build [feature] for macOS"
└─► Design with HIG principles first
└─► Implement with modern SwiftUI patterns
```
## 1. Design Principles (macOS Tahoe)
### Three Core Tenets
| Principle | Description | Implementation |
|-----------|-------------|----------------|
| **Hierarchy** | Visual layers through Liquid Glass translucency | Use `.glassEffect()`, materials, and depth |
| **Harmony** | Concentric alignment between hardware/software | Round corners, consistent radii, flowing shapes |
| **Consistency** | Platform conventions that adapt to context | Follow standard patterns, respect user preferences |
### Liquid Glass Philosophy
Liquid Glass combines transparency, reflection, refraction, and fluidity with a frosted aesthetic:
```swift
// macOS Tahoe Liquid Glass effect
.glassEffect() // Primary Liquid Glass material
.glassEffect(.regular.tinted) // Tinted variant (26.1+)
// Pre-Tahoe fallback
.background(.ultraThinMaterial)
.background(.regularMaterial)
.background(.thickMaterial)
```
**When to use Liquid Glass:**
- Sidebars, toolbars, and navigation chrome
- Floating panels and popovers
- Dock and widget backgrounds
- System-level UI elements
**When NOT to use:**
- Primary content areas (documents, media)
- Dense data displays (tables, lists with many items)
- Text-heavy interfaces where readability is critical
## 2. Navigation Patterns
### NavigationSplitView (Primary Pattern)
Three-column layout for document-based and content-heavy apps:
```swift
struct ContentView: View {
@State private var selection: Item.ID?
@State private var columnVisibility: NavigationSplitViewVisibility = .all
var body: some View {
NavigationSplitView(columnVisibility: $columnVisibility) {
// Sidebar (source list)
List(items, selection: $selection) { item in
NavigationLink(value: item) {
Label(item.title, systemImage: item.icon)
}
}
.navigationSplitViewColumnWidth(min: 180, ideal: 220, max: 300)
} content: {
// Content column (optional middle)
ContentListView(selection: selection)
} detail: {
// Detail view
DetailView(item: selectedItem)
}
}
}
```
### Sidebar Patterns
```swift
// Source list with sections
List(selection: $selection) {
Section("Library") {
ForEach(libraryItems) { item in
Label(item.name, systemImage: item.icon)
.tag(item)
}
}
Section("Collections") {
ForEach(collections) { collection in
Label(collection.name, systemImage: "folder")
.tag(collection)
.badge(collection.count)
}
}
}
.listStyle(.sidebar)
```
### Inspector Panel (Trailing Sidebar)
```swift
struct DocumentView: View {
@State private var showInspector = true
var body: some View {
MainContentView()
.inspector(isPresented: $showInspector) {
InspectorView()
.inspectorColumnWidth(min: 200, ideal: 250, max: 400)
}
.toolbar {
ToolbarItem {
Button {
showInspector.toggle()
} label: {
Label("Inspector", systemImage: "sidebar.trailing")
}
}
}
}
}
```
## 3. Window Management
### Window Configuration
```swift
@main
struct MyApp: App {
var body: some Scene {
// Main document window
WindowGroup {
ContentView()
}
.windowStyle(.automatic)
.windowToolbarStyle(.unified)
.defaultSize(width: 900, height: 600)
.defaultPosition(.center)
// Settings window
Settings {
SettingsView()
}
// Utility window
Window("Inspector", id: "inspector") {
InspectorWindow()
}
.windowStyle(.plain)
.windowResizability(.contentSize)
.defaultPosition(.topTrailing)
// Menu bar extra
MenuBarExtra("Status", systemImage: "circle.fill") {
StatusMenu()
}
.menuBarExtraStyle(.window)
}
}
```
### Window Styles
| Style | Use Case |
|-------|----------|
| `.automatic` | Standard app windows |
| `.hiddenTitleBar` | Content-focused (media players) |
| `.plain` | Utility windows, panels |
| `.unified` | Integrated toolbar appearance |
| `.unifiedCompact` | Compact toolbar height |
### Window State Restoration
```swift
WindowGroup {
ContentView()
}
.handlesExternalEvents(matching: Set(arrayLiteral: "main"))
.commands {
CommandGroup(replacing: .newItem) {
Button("New Document") {
// Handle new document
}
.keyboardShortcut("n")
}
}
```
### Document-Based Apps
```swift
@main
struct DocumentApp: App {
var body: some Scene {
DocumentGroup(newDocument: MyDocument()) { file in
DocumentView(document: file.$document)
}
.commands {
CommandGroup(after: .saveItem) {
Button("Export...") { }
.keyboardShortcut("e", modifiers: [.command, .shift])
}
}
}
}
struct MyDocument: FileDocument {
static var readableContentTypes: [UTType] { [.plainText] }
init(configuration: ReadConfiguration) throws { }
func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper { }
}
```
## 4. Toolbar & Menu Bar
### Toolbar Configuration
```swift
.toolbar {
// Leading items (macOS places these before title)
ToolbarItem(placement: .navigation) {
Button(action: goBack) {
Label("Back", systemImage: "chevron.left")
}
}
// Principal (centered)
ToolbarItem(placement: .principal) {
Picker("View Mode", selection: $viewMode) {
Label("Icons", systemImage: "square.grid.2x2").tag(ViewMode.icons)
Label("List", systemImage: "list.bullet").tag(ViewMode.list)
}
.pickerStyle(.segmented)
}
// Trailing items
ToolbarItemGroup(placement: .primaryAction) {
Button(action: share) {
Label("Share", systemImage: "square.and.arrow.up")
}
Button(action: toggleInspector) {
Label("Inspector", systemImage: "sidebar.trailing")
}
}
}
.toolbarRole(.editor) // or .browser, .automatic
```
### Custom Menu Bar
```swift
.commands {
// Replace existing menu group
CommandGroup(replacing: .newItem) {
Button("New Project") { }
.keyboardShortcut("n")
Button("New from Template...") { }
.keyboardShortcut("n", modifiers: [.command, .shift])
}
// Add to existing group
CommandGroup(after: .sidebar) {
Button("Toggle Inspector") { }
.keyboardShortcut("i", modifiers: [.command, .option])
}
// Custom menu
CommandMenu("Canvas") {
Button("Zoom In") { }
.keyboardShortcut("+")
Button("Zoom Out") { }
.keyboardShortcut("-")
Divider()
Button("Fit to Window") { }
.keyboardShortcut("0")
}
}
```
### Menu Bar Apps
```swift
MenuBarExtra("App Status", systemImage: statusIcon) {
VStack(alignment: .leading, spacing: 8) {
Text("Status: \(status)")
.font(.headline)
Divider()
Button("Open Main Window") {
openWindow(id: "main")
}
Button("Quit") {
NSApplication.shared.terminate(nil)
}
.keyboardShortcut("q")
}
.padding()
}
.menuBarExtraStyle(.window) // or .menu for simple dropdown
```
## 5. Keyboard Shortcuts
### Standard macOS Shortcuts
Always implement these when applicable:
| Action | Shortcut | Implementation |
|--------|----------|----------------|
| New | ⌘N | `.keyboardShortcut("n")` |
| Open | ⌘O | `.keyboardShortcut("o")` |
| Save | ⌘S | `.keyboardShortcut("s")` |
| Close | ⌘W | `.keyboardShortcut("w")` |
| Undo | ⌘Z | `.keyboardShortcut("z")` |
| Redo | ⇧⌘Z | `.keyboardShortcut("z", modifiers: [.command, .shift])` |
| Cut | ⌘X | `.keyboardShortcut("x")` |
| Copy | ⌘C | `.keyboardShortcut("c")` |
| Paste | ⌘V | `.keyboardShortcut("v")` |
| Select All | ⌘A | `.keyboardShortcut("a")` |
| Find | ⌘F | `.keyboardShortcut("f")` |
| Preferences | ⌘, | `.keyboardShortcut(",")` |
| Hide | ⌘H | System handled |
| Quit | ⌘Q | System handled |
### Custom Shortcuts
```swift
Button("Toggle Sidebar") {
toggleSidebar()
}
.keyboardShortcut("s", modifiers: [.command, .control])
// Function keys
Button("Refresh") { }
.keyboardShortcut(KeyEquivalent.init(Character(UnicodeScalar(NSF5FunctionKey)!)))
// Arrow keys
Button("Next") { }
.keyboardShortcut(.rightArrow)
```
## 6. Components with Liquid Glass
### Control Sizing
| Size | Shape | Use Case |
|------|-------|----------|
| Mini | Rounded rect | Compact toolbars, dense UIs |
| Small | Rounded rect | Secondary controls, sidebars |
| Regular | Rounded rect | Primary controls (default) |
| Large | Capsule | Prominent actions |
| Extra Large | Capsule + Glass | Hero CTAs, onboarding |
```swift
// Size modifiers
Button("Action") { }
.controlSize(.mini) // Smallest
.controlSize(.small) // Compact
.controlSize(.regular) // Default
.controlSize(.large) // Prominent
.controlSize(.extraLarge) // Hero (macOS 15+)
```
### Buttons
```swift
// Primary action (prominent)
Button("Save Changes") { }
.buttonStyle(.borderedProminent)
.controlSize(.large)
// Secondary action
Button("Cancel") { }
.buttonStyle(.bordered)
// Tertiary/link style
Button("Learn More") { }
.buttonStyle(.plain)
.foregroundStyle(.link)
// Destructive
Button("Delete", role: .destructive) { }
.buttonStyle(.bordered)
// Toolbar button
Button { } label: {
Label("Add", systemImage: "plus")
}
.buttonStyle(.borderless)
```
### Text Fields
```swift
// Standard text field
TextField("Search", text: $query)
.textFieldStyle(.roundedBorder)
// Search field with tokens
TextField("Search", text: $query)
.searchable(text: $query, tokens: $tokens) { token in
Label(token.name, systemImage: token.icon)
}
// Secure field
SecureField("Password", text: $password)
.textFieldStyle(.roundedBorder)
```
### Tables
```swift
Table(items, selection: $selection) {
TableColumn("Name", value: \.name)
.width(min: 100, ideal: 150)
TableColumn("Date") { item in
Text(item.date, format: .dateTime)
}
.width(100)
TableColumn("Status") { item in
StatusBadge(status: item.status)
}
.width(80)
}
.tableStyle(.inset(alternatesRowBackgrounds: true))
.contextMenu(forSelectionType: Item.ID.self) { selection in
Button("Open") { }
Button("Delete", role: .destructive) { }
}
```
### Popovers and Sheets
```swift
// Popover
Button("Info") {
showPopover = true
}
.popover(isPresented: $showPopover, arrowEdge: .bottom) {
InfoView()
.frame(width: 300, height: 200)
.padding()
}
// Sheet
.sheet(isPresented: $showSheet) {
SheetContent()
.frame(minWidth: 400, minHeight: 300)
}
// Alert
.alert("Delete Item?", isPresented: $showAlert) {
Button("Cancel", role: .cancel) { }
Button("Delete", role: .destructive) {
deleteItem()
}
} message: {
Text("This action cannot be undone.")
}
```
## 7. Typography & Colors
### System Typography
```swift
// Semantic styles (preferred)
Text("Title").font(.largeTitle) // 26pt bold
Text("Headline").font(.headline) // 13pt semibold
Text("Subheadline").font(.subheadline) // 11pt regular
Text("Body").font(.body) // 13pt regular
Text("Callout").font(.callout) // 12pt regular
Text("Caption").font(.caption) // 10pt regular
Text("Caption 2").font(.caption2) // 10pt regular
// Monospaced for code
Text("let x = 1").font(.system(.body, design: .monospaced))
```
### Semantic Colors
```swift
// Foreground
.foregroundStyle(.primary) // Primary text
.foregroundStyle(.secondary) // Secondary text
.foregroundStyle(.tertiary) // Tertiary text
.foregroundStyle(.quaternary) // Quaternary text
// Backgrounds
.background(.background) // Window background
.background(.regularMaterial) // Translucent material
// Accent colors
.tint(.accentColor) // App accent color
.foregroundStyle(.link) // Clickable links
// Semantic colors
Color.red // System red (adapts to light/dark)
Color.blue // System blue
```
### Vibrancy and Materials
```swift
// Materials (adapt to background content)
.background(.ultraThinMaterial) // Most transparent
.background(.thinMaterial)
.background(.regularMaterial) // Default
.background(.thickMaterial)
.background(.ultraThickMaterial) // Least transparent
// Vibrancy in sidebars
List { }
.listStyle(.sidebar)
.scrollContentBackground(.hidden)
.background(.ultraThinMaterial)
```
## 8. Spacing & Layout
### 8-Point Grid System
```swift
// Standard spacing values
VStack(spacing: 8) { } // Standard
VStack(spacing: 16) { } // Section spacing
VStack(spacing: 20) { } // Group spacing
// Padding
.padding(8) // Tight
.padding(12) // Standard
.padding(16) // Comfortable
.padding(20) // Spacious
// Content margins
.contentMargins(16) // Uniform margins
.contentMargins(.horizontal, 20) // Horizontal only
```
### Safe Areas
```swift
// Respect toolbar safe area
.safeAreaInset(edge: .top) {
ToolbarContent()
}
// Ignore safe area for backgrounds
.ignoresSafeArea(.container, edges: .top)
// Content that should avoid toolbar
.safeAreaPadding(.top)
```
### Minimum Touch/Click Targets
```swift
// Minimum 44x44 points for clickable elements
Button { } label: {
Image(systemName: "gear")
}
.frame(minWidth: 44, minHeight: 44)
// Use contentShape for larger hit areas
RoundedRectangle(cornerRadius: 8)
.frame(width: 200, height: 100)
.contentShape(Rectangle())
.onTapGesture { }
```
### Adaptive Layouts
```swift
// Responsive to window size
GeometryReader { geometry in
if geometry.size.width > 600 {
HStack { content }
} else {
VStack { content }
}
}
// Grid that adapts
LazyVGrid(columns: [
GridItem(.adaptive(minimum: 150, maximum: 250))
], spacing: 16) {
ForEach(items) { ItemView(item: $0) }
}
```
## 9. Accessibility
### VoiceOver
```swift
// Labels and hints
Button { } label: {
Image(systemName: "plus")
}
.accessibilityLabel("Add item")
.accessibilityHint("Creates a new item in your library")
// Grouping related elements
VStack {
Text(item.title)
Text(item.subtitle)
}
.accessibilityElement(children: .combine)
// Custom actions
.accessibilityAction(named: "Delete") {
deleteItem()
}
```
### Keyboard Navigation
```swift
// Focus management
@FocusState private var focusedField: Field?
TextField("Name", text: $name)
.focused($focusedField, equals: .name)
.onSubmit {
focusedField = .email
}
// Focusable custom views
.focusable()
.onMoveCommand { direction in
handleArrowKey(direction)
}
```
### Dynamic Type
```swift
// Scales with user preference
Text("Content")
.dynamicTypeSize(.large ... .accessibility3)
// Fixed size when necessary (use sparingly)
Text("Fixed")
.dynamicTypeSize(.large)
```
### Reduce Motion
```swift
@Environment(\.accessibilityReduceMotion) var reduceMotion
.animation(reduceMotion ? .none : .spring(), value: isExpanded)
// Alternative non-animated transitions
.transaction { transaction in
if reduceMotion {
transaction.animation = nil
}
}
```
### High Contrast
```swift
@Environment(\.colorSchemeContrast) var contrast
// Increase contrast when needed
.foregroundStyle(contrast == .increased ? .primary : .secondary)
```
## 10. Modern API Replacements
### Deprecated → Modern
| Deprecated | Modern | Notes |
|------------|--------|-------|
| `NavigationView` | `NavigationSplitView` / `NavigationStack` | Split for macOS, Stack for simple flows |
| `.navigationViewStyle(.columns)` | `NavigationSplitView` | Built-in column support |
| `List { }.listStyle(.sidebar)` with `NavigationLink` | `NavigationSplitView` sidebar | Proper split view behavior |
| `.toolbar { ToolbarItem(...) }` in detail | `.toolbar` on NavigationSplitView | Toolbar applies to correct scope |
| `NSWindowController` | `WindowGroup` / `Window` | Pure SwiftUI window management |
| `NSMenu` / `NSMenuItem` | `.commands { }` / `CommandMenu` | Declarative menus |
| `NSToolbar` | `.toolbar { }` | SwiftUI toolbar API |
| `NSTouchBar` | `.touchBar { }` | SwiftUI Touch Bar |
| `NSOpenPanel.begin()` | `.fileImporter()` | SwiftUI file dialog |
| `NSSavePanel.begin()` | `.fileExporter()` | SwiftUI save dialog |
| `.background(Color.clear)` for materials | `.background(.regularMaterial)` | Proper material support |
| Custom blur effects | `.glassEffect()` (Tahoe) | Native Liquid Glass |
### AppKit Interop (When Needed)
```swift
// Wrap AppKit view
struct NSViewWrapper: NSViewRepresentable {
func makeNSView(context: Context) -> NSView {
// Create and configure NSView
}
func updateNSView(_ nsView: NSView, context: Context) {
// Update when SwiftUI state changes
}
}
// Access NSWindow
.background(WindowAccessor { window in
window?.titlebarAppearsTransparent = true
})
```
## 11. Review Checklist
### Liquid Glass & Materials
- [ ] Sidebars use `.glassEffect()` or appropriate material
- [ ] Toolbars have translucent appearance
- [ ] Content areas remain clear (not overly translucent)
- [ ] Materials adapt properly to light/dark mode
- [ ] Fallback materials provided for pre-Tahoe
### Navigation & Windows
- [ ] `NavigationSplitView` used for multi-column layouts
- [ ] Sidebar has proper min/max width constraints
- [ ] Inspector panel available for detail/properties
- [ ] Window restoration configured
- [ ] Document-based apps use `DocumentGroup`
- [ ] Multiple window sizes tested
### Controls & Interaction
- [ ] Control sizes appropriate for context
- [ ] Primary actions use `.borderedProminent`
- [ ] Destructive actions properly marked with `.destructive` role
- [ ] Tables have context menus
- [ ] Popovers have appropriate sizing
### Keyboard & Shortcuts
- [ ] Standard shortcuts implemented (⌘N, ⌘S, ⌘W, etc.)
- [ ] Custom shortcuts don't conflict with system
- [ ] All interactive elements keyboard accessible
- [ ] Focus order logical
- [ ] Menu bar commands have shortcuts
### Accessibility
- [ ] All images have accessibility labels
- [ ] Custom controls have proper roles
- [ ] VoiceOver tested
- [ ] Keyboard navigation complete
- [ ] Reduce Motion respected
- [ ] High Contrast mode tested
### Platform Conventions
- [ ] App uses system appearance (not custom chrome)
- [ ] Settings in Preferences window (not separate)
- [ ] File dialogs use system sheets
- [ ] Drag and drop supported where expected
- [ ] Services menu integration (if applicable)
### Visual Polish
- [ ] 8-point grid alignment
- [ ] Consistent spacing throughout
- [ ] Semantic colors used (adapts to themes)
- [ ] Typography follows SF Pro guidelines
- [ ] Minimum 44pt touch targets
## Quick Reference: Control Shapes by Size
```
┌─────────────────────────────────────────────────────┐
│ Mini/Small/Medium │ Large/XLarge │
│ ┌──────────────────┐ │ ╭──────────────────╮ │
│ │ Rounded Rect │ │ │ Capsule │ │
│ └──────────────────┘ │ ╰──────────────────╯ │
│ │ │
│ Compact layouts │ Hero actions │
│ Toolbars, sidebars │ Onboarding, CTAs │
└─────────────────────────────────────────────────────┘
```
## Quick Reference: Window Styles
```
┌─────────────────────────────────────────────────────┐
│ .automatic Standard window with titlebar │
│ .hiddenTitleBar Full content, titlebar hidden │
│ .plain No chrome, utility panels │
│ .unified Toolbar merges with titlebar │
│ .unifiedCompact Compact unified toolbar │
└─────────────────────────────────────────────────────┘
```
## Quick Reference: Navigation Patterns
```
┌─────────────┬───────────────┬─────────────────────┐
│ Sidebar │ Content │ Detail │
│ │ │ │
│ Source │ List or │ Selected item │
│ List │ Grid │ properties │
│ │ │ │
│ Collections│ Items │ Inspector panel │
│ Folders │ Browse │ Edit view │
│ │ │ │
│ Min: 180 │ Flexible │ Min: 300 │
│ Max: 300 │ │ Ideal: 400+ │
└─────────────┴───────────────┴─────────────────────┘
NavigationSplitView (three-column)
```
标签
skill
ai
