window-management

name	window-management
description	Customize macOS SwiftUI windows and scene behavior. Use when tuning window chrome, drag regions, placement, restoration, launch behavior, or borderless windows.

Window Management

Overview

Use this skill to tailor each SwiftUI window to its job. Start by identifying which scene owns the window (Window, WindowGroup, or a dedicated utility scene), then customize the toolbar/title area, background material, resize and restoration behavior, and initial or zoomed placement.

Prefer scene and window modifiers over ad hoc AppKit bridges when SwiftUI offers the behavior directly. Keep each window purpose-built: a main browser window, an About window, and a media player window usually want different chrome, resizability, restoration, and placement rules.

These APIs are macOS 15+ SwiftUI window/scene customizations. For older deployment targets, expect to use more AppKit bridging or availability guards.

Workflow

1. Inspect the relevant scene declaration and classify the window role: main app navigation, inspector/detail utility, About/support window, media playback window, welcome window, or a borderless custom surface.
2. Adjust toolbar and title presentation to match the content.
3. If the toolbar background or entire toolbar is hidden, make sure the window still has a usable drag region.
4. Refine window behavior for that role: minimize availability, restoration, resize expectations, and whether the window should appear at launch.
5. Set default placement for newly opened windows and ideal placement for zoom behavior when content and display size matter.
6. Build and launch the app with build-run-debug to verify the result in a real foreground .app bundle.
7. If SwiftUI scene/window modifiers are not enough, switch to appkit-interop for a narrow NSWindow bridge rather than spreading AppKit through the view tree.