Use when designing, scaffolding, or reviewing **native macOS** UX with **AppKit + SwiftUI**, especially for windows, menus, toolbars, sidebars, preferences, status bar apps, keyboard navigation, first-responder behavior, drag and drop, focus handling, and accessibility. Do not use for general Apple UI work that is not macOS-specific.
Purpose: Equip Claude Agents to scaffold, review, and generate native macOS apps that feel like Finder, Settings, and Mail — not iOS ports. This skill packages repeatable patterns for AppKit + SwiftUI hybrid architecture, window & toolbar design, menu bar, NavigationSplitView sidebars, preferences, status bar apps, drag & drop, keyboard navigation, first responder chain, focus rings, and accessibility.
Deliverables in this skill:
scripts/ — Python generators for project scaffolding, menus, toolbars, status bar extras, and multi-window managers.examples/ — Production-quality Swift files (AppKit, SwiftUI, and Hybrid).docs/ — Focused references: window management, menu design, toolbar patterns, AppKit↔SwiftUI bridge, keyboard navigation, and gotchas.templates/plist/ — Sample Info.plist and hardened runtime entitlements.SKILL.md — Detailed design guidance and usage.Native macOS apps reward precision: deep keyboard control, robust multi-window behavior, clear menus, unified toolbars, state restoration, and efficient data views. This skill teaches Claude to generate, critique, and evolve production-ready Mac apps with AppKit and SwiftUI in tandem, using battle-tested patterns seen in Finder (source list + toolbar + path bar), Settings (sidebar navigation, split views), and Mail (three-pane layout, message list with contextual menus).
Key outcomes
Use this skill when you need to:
NavigationSplitView, tabbed preferences, status bar extras, popovers/sheets.validateMenuItem, toolbar customization, accessibility, and localization.validateMenuItem, and predictable key equivalents.NavigationSplitView for clarity.macOS 26 introduces Liquid Glass, a new material system that replaces the classic vibrancy/blur effects with a refractive, adaptive surface. Liquid Glass bends and focuses light rather than merely scattering it, making UI elements float above busy backgrounds without sacrificing legibility. The system manages vibrancy, shadows, and tint automatically and provides grouping and morphing behaviors when multiple glass panes are near each other.
NSGlassEffectView is the primary AppKit API for Liquid Glass. You embed
your content in its contentView and set a cornerRadius and optional
tintColor. Multiple glass views should be wrapped in an
NSGlassEffectContainerView so the system can merge their surfaces and
perform a single sampling pass. Use the container to group adjacent
toolbars, sidebars, or palettes; when spacing is minimal the panes will
morph into one organic surface.
Liquid Glass automatically adopts the system’s Clear or Tinted
preference (System Settings → Appearance → Liquid Glass). Clear glass is
airy and highly translucent; Tinted increases opacity and contrast to
improve legibility. Do not hard‑code text colors on glass surfaces — rely
on the system’s vibrant colors or adjust tintColor for emphasis. When
Reduce Transparency or Increase Contrast are enabled in Accessibility
settings, fall back to solid backgrounds.
Toolbars can take full advantage of Liquid Glass by unifying with the
window title area (window.toolbarStyle = .unified) and by using
NSToolbarItem.style = .prominent for primary actions. A prominent
toolbar item renders with a tinted glass background; a plain item floats
subtly on clear glass. Group your toolbar with adjacent search fields or
palettes using an NSGlassEffectContainerView to ensure their surfaces
merge gracefully.
Sidebars are natural candidates for Liquid Glass. Wrap the sidebar list
in an NSGlassEffectView, match the corner radius to your window’s shape
for concentricity, and group the sidebar with neighboring panels in a
container. In SwiftUI, call .glassEffect on your list or sidebar
container. When a sidebar collapses or expands, keep it inside the same
container so the glass morphs rather than snaps.
Inspectors, HUDs, and floating tool palettes benefit from glass because
they appear light and unobtrusive. Use NSPanel with
isFloatingPanel = true and embed an NSGlassEffectView as its
contentView. For HUD windows, apply a tinted glass (tintColor) to
increase opacity over busy content. Always provide a close/dismiss
control and ensure the panel participates in the first responder chain.
On macOS 26, SwiftUI’s .sheet and .popover adopt Liquid Glass
automatically. In AppKit, embed your popover’s content in
NSGlassEffectView to achieve the same effect. Keep popovers concise and
prefer a prominent (tinted) glass style if the background competes
with your content. Provide keyboard dismissal (Esc) and avoid piling
toolbars on popovers.
SwiftUI gains the .glassEffect modifier and GlassEffectContainer to
build glass surfaces. Apply .glassEffect(.regular, in: someShape) to a
view to wrap it in Liquid Glass. Use GlassEffectContainer to group
adjacent glass elements so they morph and share sampling. Button styles
.glass and .glassProminent mirror the plain/prominent styles in AppKit.
Hybrid apps can bridge Liquid Glass across frameworks. Use
NSViewRepresentable to embed an NSGlassEffectView inside SwiftUI when
you need AppKit‑level control such as grouping or custom tinting. To
embed SwiftUI glass in AppKit, wrap a SwiftUI view that uses
.glassEffect in an NSHostingView or NSHostingController. This skill
includes examples in examples/hybrid demonstrating both directions.
Respect the system’s Clear vs Tinted preference. If your app previously exposed its own translucency toggle, remove it and allow the system to drive glass opacity. Always support Reduce Transparency, Reduce Motion and Increase Contrast accessibility options by falling back to solid surfaces and disabling glass flex animations.
For a full reference on AppKit APIs, SwiftUI patterns and migration
steps, see the dedicated documents in the docs/ folder:
liquid-glass-macos.md, appkit-glass-bridge.md and macos-26-migration.md.
.fullSizeContentView and .unified toolbar style for modern layouts.window.frameAutosaveName to persist geometry; implement restoration for critical windows.NSWindow.allowsAutomaticWindowTabbing and per-window tabbing modes.collectionBehavior, animationBehavior, and full‑screen support for each window.NSTitlebarAccessoryViewController for path controls or segmented filters in the title area.frameAutosaveName and encode/decode restorable state for custom positions, split ratios, and visibility.NSWindowTabGroup and manage default tab visibility.NSWindowDelegate to save on close, and to prevent accidental data loss or dead windows.WindowGroup, Settings, and MenuBarExtra scenes.Unified toolbars (.unified / .unifiedCompact) merge title and toolbar; reduces chrome, like Finder/Photos/iWork.
Customization. Use NSToolbar with allowed/default item sets; expose Customize Toolbar… if appropriate.
Validation. Implement NSToolbarItemValidation to enable/disable items via the responder chain.
Center items. Consider centeredItemIdentifier for prominent content controls (e.g., segmented filters).
Liquid Glass integration (macOS 26). When targeting macOS 26 or later, use
Liquid Glass for unified toolbars. Assign NSToolbarItem.style = .prominent to
primary actions and .plain to secondary actions, and set
backgroundTintColor for meaningful accent colors. Group your toolbar
with adjacent search fields or palettes using an NSGlassEffectContainerView
so their surfaces morph seamlessly. See the GlassToolbarWindow.swift
example for a complete pattern.
keyEquivalent with appropriate modifierMask; avoid collisions.validateMenuItem.Source lists. Use sidebars for navigation, not action overload. Keep items text‑first with familiar badges.
Split views. Pair sidebars with detail panes; use NavigationSplitView for adaptive SwiftUI patterns.
Selection semantics. Single selection by default; multi‑select only where it unlocks clear bulk actions.
Liquid Glass sidebars (macOS 26). Wrap your sidebar’s list in an
NSGlassEffectView or, in SwiftUI, apply .glassEffect to the sidebar.
Match the corner radius to your window’s geometry for concentricity and
group the sidebar with any adjacent panels in an NSGlassEffectContainerView.
When collapsing or expanding the sidebar, keep it inside the same
container to enable smooth morphing rather than abrupt snapping. See
GlassSidebarWindow.swift and GlassSidebarNavigation.swift in
examples/ for reference.
NSHostingView or embed AppKit lists in SwiftUI with NSViewRepresentable.Settings scene; for classic AppKit, provide a tabbed preferences window with a toolbar.MenuBarExtra for a lightweight menu or mini‑window experience.NSStatusItem for full control; ensure a Quit path when Dock icon is hidden; manage highlight states.Sheets: Use for blocking, focused tasks; keep concise and reversible.
Popovers: Use for transient tools and inspectors; anchor to controls; dismiss on focus loss when appropriate.
Materials: Prefer system materials; ensure proper arrow placement and escape-to-dismiss behavior.
Liquid Glass (macOS 26). On macOS 26, SwiftUI automatically applies
Liquid Glass to .popover and .sheet surfaces. In AppKit, embed your
popover’s content view in an NSGlassEffectView to achieve the same
effect. Prefer a prominent (tinted) glass style when the
underlying content is busy, and always respect Reduce Transparency by
falling back to solid backgrounds. See FloatingGlassPalette.swift for
a floating example.
NSDraggingDestination on views/lists; adopt pasteboards and promised files as needed.Transferable and onDrop for type‑safe payloads; bridge to AppKit where advanced behaviors are required.validateMenuItem to enable/disable contextually.validateMenuItem/validateUserInterfaceItem where actions vary by selection/context.drawFocusRingMask and noteFocusRingMaskChanged.Scenes. Use WindowGroup, Window, Settings, MenuBarExtra; coordinate with AppKit windows where needed.
Navigation. Prefer NavigationSplitView for Mac‑style sidebars; preserve selection and column state.
Bridging. Embed AppKit where SwiftUI is lacking (text inputs, complex lists, legacy views).
Liquid Glass (macOS 26). SwiftUI in macOS 26 introduces .glassEffect and
GlassEffectContainer. Use .glassEffect(_:, in:) on any view to wrap
it in Liquid Glass, specifying a shape (e.g. .capsule, RoundedRectangle).
Group adjacent glass elements with GlassEffectContainer to merge their
sampling region and enable morphing transitions. Button styles
.glass and .glassProminent mirror the plain/prominent styles in
AppKit. See SwiftUIGlassWindow.swift and other SwiftUI examples for
patterns.
SwiftUI → AppKit: NSViewRepresentable, NSViewControllerRepresentable.
AppKit → SwiftUI: NSHostingView, NSHostingController with sizing options.
Responder integration. Ensure hosted views participate in focus and responder chain correctly.
Liquid Glass bridging. To use Liquid Glass across frameworks, embed
NSGlassEffectView in SwiftUI via NSViewRepresentable when you need
AppKit‑level control (e.g. grouping, custom tint). Conversely, embed
SwiftUI views that use .glassEffect into AppKit using NSHostingView
or NSHostingController. This skill provides bridging examples in
examples/hybrid/AppKitGlassInSwiftUI.swift and
examples/hybrid/SwiftUIGlassInAppKit.swift.
Strategy. Keep windowing, menus, and toolbars in AppKit; implement content panes in SwiftUI for speed and consistency.
Data flow. Use ObservableObject and dependency injection for SwiftUI, and delegates/notifications bridging in AppKit.
Testing. Unit test reducers/view models; UI tests for menu validation and toolbar state.
Liquid Glass across frameworks. When combining AppKit and SwiftUI, unify
glass surfaces by grouping related views in NSGlassEffectContainerView or
GlassEffectContainer. Manage state in a shared model so both
frameworks update tints and visibility consistently. Use bridging
patterns to embed AppKit glass in SwiftUI and vice versa (see
examples/hybrid for details). Always respect system preferences for
Clear/Tinted and fall back to solid materials when accessibility
settings require it.
Settings scene to automatically wire the App menu → Settings… item.MenuBarExtra for menu‑only or window‑style extras; provide a Quit affordance.NSGlassEffectContainerView or GlassEffectContainer so they morph and sample together.NSWindow.allowsAutomaticWindowTabbing = false at launch.Settings scene on newer macOS versions supersedes legacy Preferences wiring.scripts/scaffold_macos_app.py — Generate a hybrid AppKit + SwiftUI project skeleton with unified toolbar, sidebar, and menus.scripts/menu_generator.py — Generate Swift Commands/NSMenu from JSON/YAML specs.scripts/toolbar_generator.py — Generate NSToolbar implementations from specs.scripts/statusbar_generator.py — Generate NSStatusItem and MenuBarExtra templates.scripts/window_manager_generator.py — Generate multi‑window orchestration and restoration code.Each tool supports --out to pick an output folder; see --help.
apple-macos-ux-full/
SKILL.md
scripts/
examples/
appkit/
swiftui/
hybrid/
docs/
visuals/
templates/
plist/
This skill encodes production patterns seen in Finder, Settings, and Mail while staying faithful to platform conventions.