apple-hig-settings
Skill11 starsChanged 3 months agoMITView on GitHub
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.
In this repository39 other files it gives its agents.
- agent-starter-packSkill
- agent-state-machineSkill
- local-ai-ollamaSkill
- apple-hig-command-paletteSkill
- apple-hig-empty-statesSkill
- apple-hig-feedback-statusSkill
- apple-hig-inspectorsSkill
- apple-hig-macos-window-layoutSkill
- apple-hig-search-filteringSkill
- apple-hig-sf-symbolsSkill
- apple-hig-sidebarsSkill
- apple-hig-toolbarsSkill
- apple-hig-typographySkill
- blog-post-publishingSkill
- social-post-kitSkill
- color-principlesSkill
- kika-design-systemSkill
- emergency-switch-appSkill
- product-hunt-polish-reviewSkill
- docs-updateSkill
- project-folder-cleanupSkill
- between-runs-auditSkill
- explain-new-projectSkill
- new-project-gateSkill
- old-project-auditSkill
- project-catch-upSkill
- project-workflowSkill
- project-worth-my-timeSkill
- butterfly-effectSkill
- spreadSkill
- tilSkill
- apple-app-intentsSkill
- macos-app-distribution-dmgSkill
- macos-clipboard-pasteboardSkill
- macos-global-shortcutsSkill
- macos-launch-at-loginSkill
- macos-menubar-swiftuiSkill
- macos-notificationsSkill
- macos-permissions-privacySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 13 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Use this skill when designing, reviewing, or implementing Settings/Preferences for Apple-platform apps.
- Distinctive: line 35
Do not put these in Settings:
- Very specific: line 178
Use @AppStorage for simple preferences:
- Distinctive: line 187
Use a settings service or model for:
- Distinctive: line 197
Use Keychain for secrets.
- Very specific: line 199
Do not store API keys in plain UserDefaults.
- Very specific: line 203
Use SMAppService where appropriate.
- Distinctive: line 228
Add Reveal in Finder.
- Distinctive: line 229
Add Reset to Default.
- Distinctive: line 241
Use ellipsis for actions needing confirmation.
- Distinctive: line 246
Keep each section focused.
- Distinctive: line 247
Put advanced/debug settings last.
- Distinctive: line 249
Use footer/help text sparingly.
- Distinctive: line 250
Do not use huge cards.
- Distinctive: line 251
Do not make settings look like a dashboard.
- Distinctive: line 252
Use native controls: Toggle, Picker, TextField, Button.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
AboutFor 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 diagnosticsSwiftUI macOS Settings scene
@main
struct MyApp: App {
var body: some Scene {
MenuBarExtra("My App", systemImage: "sparkles") {
AppMenuView()
}
Settings {
SettingsView()
}
}
}Settings view template
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
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
NumbersUse a settings service or model for:
API keys
Folder bookmarks
Secure tokens
Complex JSON
Per-project preferencesUse Keychain for secrets.
Do not store API keys in plain UserDefaults.
Launch at Login
Use SMAppService where appropriate.
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 literalCommon 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 workPrompt 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.Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

