Build a proper macOS settings/preferences window with liquid glass support for macOS 26 (Tahoe). Use this skill whenever the user asks to create a settings window, preferences UI, settings view, or preferences pane for a macOS app. Also trigger when the user mentions "liquid glass settings", "NavigationSplitView settings", "grouped Form settings", "macOS settings layout", or wants to add/fix/rebuild a settings screen in any native macOS SwiftUI app. This includes phrases like "add settings to my app", "create a preferences window", "my settings look wrong", "fix my settings UI", or even just "I need a settings view". If the user is building a macOS app and mentions settings or preferences in any context, use this skill.
Build a proper macOS settings/preferences window with liquid glass support for macOS 26 (Tahoe). Use this skill whenever the user asks to create a settings window, preferences UI, settings view, or preferences pane for a macOS app. Also trigger when the user mentions "liquid glass settings", "NavigationSplitView settings", "grouped Form settings", "macOS settings layout", or wants to add/fix/rebuild a settings screen in any native macOS SwiftUI app. This includes phrases like "add settings to my app", "create a preferences window", "my settings look wrong", "fix my settings UI", or even just "I need a settings view". If the user is building a macOS app and mentions settings or preferences in any context, use this skill.
macOS Settings UI with Liquid Glass
This skill produces a native macOS settings window that follows Apple's macOS 26 design guidelines. The result is a sidebar + detail NavigationSplitView with liquid glass window chrome, back/forward toolbar navigation, grouped Form sections with transparent backgrounds, and proper scroll edge effects.
Architecture Overview
The settings UI is composed of 3 layers:
Window Controller (SettingsWindowController.swift) — An NSWindowController that creates the NSWindow programmatically with .fullSizeContentView. This is what gives the window rounded liquid glass corners. You cannot get this effect from a SwiftUI Window scene.
Root View (SettingsView.swift) — A NavigationSplitView with a sidebar list and detail pane. Includes back/forward navigation history in the toolbar, which also forces the creation of an NSToolbar (required for the liquid glass title bar treatment).
Detail Panes (one file per tab) — Each pane uses Form { Section(...) { ... } }.formStyle(.grouped).scrollContentBackground(.hidden).
Why NSWindowController Instead of SwiftUI Window Scene
SwiftUI's declarative Window scene does not expose the NSWindow style mask. The .fullSizeContentView flag must be set at window creation time for macOS 26 to render the liquid glass chrome (rounded corners, translucent sidebar, blurred title bar). Trying to inject it later via NSViewRepresentable is unreliable because SwiftUI resets the window's configuration.
The NSWindowController approach also lets you control the toolbar style, frame autosave, minimum size, and delegate lifecycle directly.
Critical Modifiers
Every detail pane MUST have these three modifiers on its Form:
.formStyle(.grouped) — gives the native inset rounded-rect section appearance
.scrollContentBackground(.hidden) — makes the form background transparent so the liquid glass window chrome shows through. Without this, you get an opaque white/dark background that breaks the glass effect.
.contentMargins(.top, 8) — adds breathing room between the toolbar and the first section
Read the reference files for complete, working code:
references/SettingsWindowController.swift — The window controller (copy as-is, adapt the activation policy calls to your app)
references/SettingsView.swift — The root view with sidebar, detail routing, and navigation history
references/ExampleDetailPane.swift — A template detail pane showing common control patterns (Toggle, Picker, Slider, LabeledContent)
Step-by-Step: Adding Settings to a New App
1. Create the Tab Enum
Define your settings categories. Each case needs a title and SF Symbol icon:
enumSettingsTab: String, CaseIterable, Identifiable {
case general
case appearance
case about
var id: Self { self }
var title: String {
switchself {
case .general: "General"case .appearance: "Appearance"case .about: "About"
}
}
var systemImage: String {
switchself {
case .general: "gearshape"case .appearance: "paintbrush"case .about: "info.circle"
}
}
}
2. Create the Window Controller
Copy references/SettingsWindowController.swift into your project. Adapt:
The initial contentRect size (default 700x540 is good for most apps)
The minSize (default 620x460)
The activation policy calls (AppActivationPolicy.enter()/leave()) — if your app isn't a menu-bar-only app, remove these
3. Create the Root Settings View
Copy references/SettingsView.swift. Adapt:
The SettingsTab enum cases to match your categories
The SettingsDetailView switch to return your panes
4. Create Detail Panes
For each tab, create a pane file. Use this template:
If your app uses NSApp.setActivationPolicy(.accessory) (no Dock icon), you need activation policy management so the settings window brings the app to the foreground. The reference SettingsWindowController calls AppActivationPolicy.enter() on show and .leave() on close. Implement this as a simple reference-counting wrapper:
If your app always shows in the Dock, remove the AppActivationPolicy calls from the window controller and just use NSApp.activate(ignoringOtherApps: true) in showWindow.
macOS Version Compatibility
The scrollEdgeEffectStyle(.soft) API is macOS 26+ only. Always wrap it in an availability check:
