MCPInstall

macos-settings-ui

by fayazaraFrontend & Design

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.

Installs
655
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/fayazara/macos-app-skills --skill macos-settings-ui
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads macos-settings-ui automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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:

  1. 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.

  2. 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).

  3. 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)
.scrollContentBackground(.hidden)
.contentMargins(.top, 8, for: .scrollContent)
  • .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

The sidebar List MUST have:

.listStyle(.sidebar)
.scrollEdgeEffectStyleSoftIfAvailable()  // macOS 26 progressive blur at scroll edges
.navigationTitle("Settings")

The NavigationSplitView MUST have:

NavigationSplitView(columnVisibility: .constant(.all))  // sidebar always visible
// ...
.navigationTitle("Settings")
.navigationSplitViewStyle(.balanced)

Reference Implementation

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:

enum SettingsTab: String, CaseIterable, Identifiable {
    case general
    case appearance
    case about

    var id: Self { self }

    var title: String {
        switch self {
        case .general: "General"
        case .appearance: "Appearance"
        case .about: "About"
        }
    }

    var systemImage: String {
        switch self {
        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:

import SwiftUI

struct GeneralSettingsPane: View {
    @AppStorage("someKey") private var someValue = false

    var body: some View {
        Form {
            Section("Section Name") {
                Toggle("Toggle label", isOn: $someValue)
            }
        }
        .formStyle(.grouped)
        .scrollContentBackground(.hidden)
        .contentMargins(.top, 8, for: .scrollContent)
    }
}

5. Open Settings from Your App

From a menu bar, button, or anywhere:

SettingsWindowController.show(tab: .general)

Do NOT use a SwiftUI Window scene. Do NOT use openWindow(id:). The window controller handles everything.

6. Remove Any SwiftUI Window Scene

If you previously had a Window("Settings", id: "SETTINGS") scene in your App struct, remove it entirely. The SettingsWindowController replaces it.

Common Control Patterns Inside Form Sections

Toggle with description:

Toggle(isOn: $value) {
    VStack(alignment: .leading, spacing: 2) {
        Text("Primary label")
        Text("Description text explaining what this does.")
            .font(.caption)
            .foregroundStyle(.secondary)
    }
}
.toggleStyle(.switch)

Picker (dropdown):

Picker("Label", selection: $value) {
    Text("Option A").tag(OptionEnum.a)
    Text("Option B").tag(OptionEnum.b)
}
.pickerStyle(.menu)

Picker (segmented):

Picker("Label", selection: $value) {
    ForEach(SomeEnum.allCases) { item in
        Text(item.title).tag(item)
    }
}
.pickerStyle(.segmented)

Slider with value label:

LabeledContent("Size") {
    HStack(spacing: 12) {
        Slider(value: $size, in: 24...96, step: 2)
            .frame(width: 180)
        Text("\(Int(size)) pt")
            .monospacedDigit()
            .foregroundStyle(.secondary)
            .frame(width: 46, alignment: .trailing)
    }
}

Button row:

HStack(spacing: 8) {
    Button("Action") { doSomething() }
        .controlSize(.small)
    Button("Reset") { reset() }
        .controlSize(.small)
        .disabled(isDefault)
}

Menu-Bar-Only Apps

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:

@MainActor
enum AppActivationPolicy {
    private static var count = 0

    static func enter() {
        count += 1
        NSApp.setActivationPolicy(.regular)
        NSApp.activate(ignoringOtherApps: true)
    }

    static func leave() {
        count = max(0, count - 1)
        guard count == 0 else { return }
        Task { @MainActor in
            NSApp.setActivationPolicy(.accessory)
        }
    }
}

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:

private extension View {
    @ViewBuilder
    func scrollEdgeEffectStyleSoftIfAvailable() -> some View {
        if #available(macOS 26.0, *) {
            scrollEdgeEffectStyle(.soft, for: .all)
        } else {
            self
        }
    }
}

The rest of the pattern (NSWindowController with .fullSizeContentView, grouped Form, NavigationSplitView) works on macOS 14+.

FAQ

What does the macos-settings-ui skill do?

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.

How do I install macos-settings-ui?

Run npx skills add https://github.com/fayazara/macos-app-skills --skill macos-settings-ui in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/macos-settings-ui/ (personal) or .claude/skills/macos-settings-ui/ (project).

Which AI agents can use macos-settings-ui?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is macos-settings-ui safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains macos-settings-ui?

It is published by fayazara in fayazara/macos-app-skills. It has 655 recorded installs.

More from fayazara/macos-app-skills

View all →

macos-patterns

fayazara/macos-app-skills

Essential native macOS development patterns that web developers don't know about. Use this skill whenever the user is building a macOS app and needs guidance on native patterns, or when they ask about menu bar apps, floating panels, window levels, keyboard shortcuts, file pickers, clipboard, drag and drop, screen capture, activation policy, Quick Look, launch at login, or any macOS-specific API. Also trigger when the user seems to be applying web development patterns to macOS (e.g., using z-index thinking for windows, expecting simple clipboard APIs, or not understanding focus/activation). This is the "how things actually work on macOS" reference that prevents the AI from generating confident but wrong code. Use this skill proactively whenever building any native macOS app.

Backend & APIs676 installs

macos-build

fayazara/macos-app-skills

Build a native macOS app using xcodebuild from the command line. Use this skill whenever the user asks to build, compile, or check if their macOS project compiles successfully. Also use it when the user asks to fix build errors, verify changes compile, or run a debug build. Trigger on phrases like "build the app", "does it compile", "run xcodebuild", "fix build errors", or even just "build".

Code Quality & Workflow614 installs

macos-release

fayazara/macos-app-skills

Release a native macOS app to GitHub with DMG packaging and Sparkle appcast updates. Use this skill whenever the user wants to publish a new version, create a release, ship an update, push a release to GitHub, or update the appcast. Also trigger when the user mentions DMG creation, Sparkle signing, notarization, archiving, or anything related to distributing a new version of their macOS app. This covers the full release pipeline: archive, notarize, export, create DMG, sign with Sparkle EdDSA, update appcast.xml, git push, and GitHub release creation.

Code Quality & Workflow587 installs

macos-auto-update

fayazara/macos-app-skills

Add Sparkle auto-update support to a native macOS app. Use this skill whenever the user wants to add auto-updates, implement Sparkle, set up an appcast feed, add "Check for Updates" to their app, or integrate automatic update checking. Also trigger when the user mentions Sparkle, appcast, SUFeedURL, EdDSA signing, or update notifications. This covers the full setup: adding the Sparkle SPM dependency, creating the UpdaterManager singleton, wiring it into the app delegate and UI, configuring Info.plist, and generating the initial appcast.xml.

Frontend & Design569 installs

macos-notch-ui

fayazara/macos-app-skills

Add a Dynamic Island-style notch UI to a macOS app. Use this skill whenever the user wants to create a notch overlay, notch extender, Dynamic Island for Mac, notch indicator, or any UI that extends from the MacBook notch area. Also trigger when the user mentions "notch shape", "notch window", "notch cutout", "notch panel", "recording indicator near the notch", "Dynamic Island style", or wants to show status/content that appears to emerge from the hardware notch. This covers the NSPanel setup, the NotchShape with concave Bezier ear curves, screen positioning math, spring animations, and show/hide choreography.

Frontend & Design566 installs

Popular frontend & design skills

View category →

setup-matt-pocock-skills

mattpocock/skills

Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

Frontend & Design1.1M installs

frontend-design

anthropics/skills

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

OfficialFrontend & Design1M installs

hyperframes-animation

heygen-com/hyperframes

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Frontend & Design1M installs

prototype

mattpocock/skills

Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

Frontend & Design999.2K installs

hyperframes-core

heygen-com/hyperframes

The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Frontend & Design930.5K installs

vercel-react-best-practices

vercel-labs/agent-skills

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

OfficialFrontend & Design843.1K installs