---
name: apple-hig-settings
description: Use when designing, reviewing, or implementing Settings/Preferences for Apple-platform apps — what belongs in Settings vs Inspector/Toolbar, grouped forms, native controls, secure storage, launch at login, and destructive actions.
---

# Apple HIG Settings

Use this skill when designing, reviewing, or implementing Settings/Preferences for Apple-platform apps. It covers macOS `Settings`, iOS Settings screens, app preferences, model configuration, shortcuts, launch at login, folders, privacy, accounts, appearance, and advanced options.

## Core rule

```
Settings are for persistent preferences, not one-time actions or navigation.
```

## When to use this skill

Use for:

- Default model
- API keys
- Ollama URL
- Project folder
- Launch at Login
- Theme / appearance
- Keyboard shortcuts
- Notification preferences
- Privacy and local-only controls
- Data retention
- Export/import settings
- Advanced debug settings

## When not to use this skill

Do not put these in Settings:

- Current selected item metadata; use Inspector
- Main app navigation; use Sidebar
- Current-screen actions; use Toolbar
- One-time commands; use Command Palette or menu
- Full dashboards

## Recommended settings sections

```
General
Models
Projects
Keyboard
Notifications
Privacy
Appearance
Advanced
About
```

For an agent-driven app:

```
General
- Launch at Login
- Show Dock icon
- Start hidden

Models
- Provider: Ollama / OpenAI / Other
- Ollama Base URL
- Default model
- Test connection

Projects
- Default projects folder
- Open folder after create
- Include skills by default

Keyboard
- Command Palette shortcut
- Quick Capture shortcut
- Toggle Inspector shortcut

Notifications
- Notify when the agent finishes
- Notify on failure
- Quiet hours

Privacy
- Local-only mode
- Allowed folders
- Clear local history

Appearance
- System / Light / Dark
- Compact mode
- Show advanced metadata

Advanced
- Debug logs
- Reset app state
- Export diagnostics
```

## SwiftUI macOS Settings scene

```swift
@main
struct MyApp: App {
    var body: some Scene {
        MenuBarExtra("My App", systemImage: "sparkles") {
            AppMenuView()
        }

        Settings {
            SettingsView()
        }
    }
}
```

## Settings view template

```swift
import SwiftUI

struct SettingsView: View {
    @AppStorage("launchAtLogin") private var launchAtLogin = false
    @AppStorage("defaultModel") private var defaultModel = "llama3.1:8b"
    @AppStorage("ollamaBaseURL") private var ollamaBaseURL = "http://127.0.0.1:11434"
    @AppStorage("appearance") private var appearance = "system"

    var body: some View {
        TabView {
            GeneralSettingsView(launchAtLogin: $launchAtLogin)
                .tabItem { Label("General", systemImage: "gearshape") }

            ModelSettingsView(defaultModel: $defaultModel, ollamaBaseURL: $ollamaBaseURL)
                .tabItem { Label("Models", systemImage: "brain") }

            AppearanceSettingsView(appearance: $appearance)
                .tabItem { Label("Appearance", systemImage: "paintbrush") }
        }
        .frame(width: 560, height: 420)
    }
}
```

## Form section pattern

```swift
struct ModelSettingsView: View {
    @Binding var defaultModel: String
    @Binding var ollamaBaseURL: String

    var body: some View {
        Form {
            Section("Provider") {
                TextField("Ollama URL", text: $ollamaBaseURL)
                TextField("Default Model", text: $defaultModel)
                Button("Test Connection") {
                    testConnection()
                }
            }

            Section("Behavior") {
                Toggle("Prefer local models", isOn: .constant(true))
                Toggle("Fallback to cloud model", isOn: .constant(false))
            }
        }
        .formStyle(.grouped)
        .padding()
    }

    private func testConnection() {}
}
```

## Storage rules

Use `@AppStorage` for simple preferences:

```
Booleans
Strings
Small enum-like values
Numbers
```

Use a settings service or model for:

```
API keys
Folder bookmarks
Secure tokens
Complex JSON
Per-project preferences
```

Use Keychain for secrets.

Do not store API keys in plain `UserDefaults`.

## Launch at Login

Use `SMAppService` where appropriate.

```swift
import ServiceManagement

func setLaunchAtLogin(_ enabled: Bool) {
    do {
        if enabled {
            try SMAppService.mainApp.register()
        } else {
            try SMAppService.mainApp.unregister()
        }
    } catch {
        print("Failed to update launch at login: \(error)")
    }
}
```

## Folder permissions

For folder settings:

- Use a picker.
- Store security-scoped bookmarks if needed.
- Show current path.
- Add Reveal in Finder.
- Add Reset to Default.

## Destructive settings

Dangerous settings must be separated and confirmed:

```
Clear Local History…
Reset All Settings…
Delete All Cached Runs…
```

Use ellipsis for actions needing confirmation.

## Design rules

- Use grouped forms.
- Keep each section focused.
- Put advanced/debug settings last.
- Avoid long paragraphs.
- Use footer/help text sparingly.
- Do not use huge cards.
- Do not make settings look like a dashboard.
- Use native controls: Toggle, Picker, TextField, Button.

## Review checklist

```
[ ] Settings are persistent preferences
[ ] Settings are grouped clearly
[ ] App-wide settings are not in Inspector
[ ] Current-screen actions are not in Settings
[ ] Secrets are stored securely
[ ] Folder permissions are handled safely
[ ] Destructive options require confirmation
[ ] Launch at Login handles errors
[ ] Settings window has appropriate size
[ ] Labels are clear and literal
```

## Common mistakes

```
Using Settings for navigation
Putting selected item details in Settings
Storing API keys in UserDefaults
No confirmation for reset/delete actions
Too many advanced options visible by default
Long explanations everywhere
Custom controls where native controls work
```

## Prompt template

Drop this into any coding agent (Claude Code, Codex, Cursor, …) to apply the skill:

```
Use the apple-hig-settings skill to create or improve app settings.

Rules:
- Settings are for persistent app preferences.
- Use Settings scene on macOS.
- Use grouped Form sections.
- Use native controls.
- Store simple preferences in AppStorage.
- Store secrets in Keychain, not UserDefaults.
- Keep selected-item details in Inspector, not Settings.
- Keep current-screen actions in Toolbar, not Settings.
- Put advanced and destructive actions last.
- Require confirmation for destructive actions.

After coding:
1. List settings added.
2. Explain storage choices.
3. Explain security for secrets.
4. Explain destructive safeguards.
5. Give manual test steps.
```