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
- 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.
- Adjust toolbar and title presentation to match the content.
- If the toolbar background or entire toolbar is hidden, make sure the window
still has a usable drag region.
- Refine window behavior for that role: minimize availability, restoration,
resize expectations, and whether the window should appear at launch.
- Set default placement for newly opened windows and ideal placement for zoom
behavior when content and display size matter.
- Build and launch the app with
build-run-debug to verify the result in
a real foreground .app bundle.
- 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.
Toolbar And Title
- Use
.toolbar(removing: .title) when the window title should stay associated
with the window for accessibility and menus, but not be visibly drawn in the
title bar.
- Use
.toolbarBackgroundVisibility(.hidden, for: .windowToolbar) when large
media or hero content should visually extend to the top edge of the window.
- If the window still needs close/minimize/full-screen controls, remove only the
title and toolbar background. If the toolbar should disappear entirely, use
.toolbarVisibility(.hidden, for: .windowToolbar) instead.
- Remove custom toolbar backgrounds and manually painted titlebar fills before
layering new SwiftUI toolbar APIs on top.
- Keep the window's logical title meaningful even if hidden; the system can
still use it for accessibility and menu items. These are visual changes only.
Drag Regions
- If a toolbar background is hidden or the toolbar is removed entirely, use
WindowDragGesture() to extend the draggable area into your content.
- Attach the gesture to a transparent overlay or non-interactive header region
that does not steal gestures from real controls.
- For a media player with custom playback controls, insert the drag overlay
between the video content and the controls so AVKit or transport controls keep
receiving input.
- Pair the drag gesture with
.allowsWindowActivationEvents(true) so clicking
and immediately dragging a background window still activates and moves it.
Background And Materials
- Use
.containerBackground(.thickMaterial, for: .window) when a utility window
or About window should replace the default window background with a subtle
frosted material.
- Prefer system materials for stylized windows instead of hardcoded translucent
colors.
- Use this especially for fixed-content utility windows where a softer backdrop
is part of the design.
Window Behavior
- Use
.windowMinimizeBehavior(.disabled) for always-reachable utility windows
such as a custom About window where minimizing adds little value.
- Disable the green zoom control through fixed sizing or window constraints when
the window's content has one intended size.
- Use
.restorationBehavior(.disabled) for windows that should not reopen on
next launch, such as About panels, transient support/info windows, or
first-run welcome surfaces.
- Keep state restoration enabled for primary document or navigation windows when
reopening prior size and position is desirable.
- By default, SwiftUI respects the user's system-wide macOS state restoration
setting. Use
restorationBehavior(...) only when a specific window should
intentionally opt into or out of that system behavior.
- Use
.defaultLaunchBehavior(.presented) for windows that should appear first
on launch, such as a welcome window, and choose that behavior intentionally
rather than relying on side effects from scene creation order.
Window Placement
- Use
.defaultWindowPlacement { content, context in ... } to control the
initial size and optional position of newly opened windows.
- Inside the placement closure, call
content.sizeThatFits(.unspecified) to get
the content's ideal size.
- Read
context.defaultDisplay.visibleRect to get the display's usable region
after accounting for the menu bar and Dock.
- Return
WindowPlacement(size: size) with a size clamped to the visible rect
when media or document content may be larger than the display. If no position
is provided, the window is centered by default.
- Use
.windowIdealPlacement { content, context in ... } to control what
happens when the user chooses Zoom from the Window menu or Option-clicks the
green toolbar button. For media windows, preserve aspect ratio and grow to the
largest size that fits the display.
- Treat default placement and ideal placement as separate policies:
- default placement controls where a new window first appears,
- ideal placement controls how large a zoomed window should become.
- Always consider external displays and rotated/narrow screens when sizing
player windows or document windows from content dimensions.
Borderless And Specialized Windows
- Use
.windowStyle(.plain) for borderless or highly custom chrome windows, but
make sure the content still provides a clear drag/move affordance and visible
context.
- For a borderless player, HUD, or welcome window, decide upfront whether losing
standard titlebar affordances is worth the custom presentation.
- Keep one clear path back to regular window management if the plain style makes
the window feel invisible or hard to move.
For concrete window modifier examples, read references/api-snippets.md.
Review Checklist
- The scene type matches the window's role and lifecycle.
- Hidden titles still leave a meaningful logical title for accessibility and
menus.
- Toolbar background removal is intentional and does not hurt titlebar legibility
or window control placement.
- Windows with hidden or removed toolbars still have a reliable drag region and
support click-then-drag activation from the background.
- Utility windows have restoration/minimize behavior that matches their purpose.
- Restoration overrides are used only when a scene should intentionally differ
from the user's system-wide setting.
- Default and ideal placement use
content.sizeThatFits(.unspecified) and
context.defaultDisplay.visibleRect when content/display size matters.
- Media windows preserve aspect ratio and fit on small or rotated displays.
- Borderless windows still have a usable move/drag affordance.
Guardrails
- Do not use
.toolbar(removing: .title) just to hide a title you forgot to set.
Keep the underlying window title meaningful.
- Do not hide the toolbar background or the whole toolbar without replacing the
lost drag affordance.
- Do not disable restoration on the main document/navigation window unless the
user explicitly wants a fresh-start app every launch.
- Do not hardcode one monitor size or assume a single-display setup when sizing
player windows.
- Do not reach for
NSWindow mutation before checking whether
.windowMinimizeBehavior, .restorationBehavior, .defaultWindowPlacement,
.windowIdealPlacement, .windowStyle, or .defaultLaunchBehavior already
solve the problem.
- Do not leave a plain borderless window without any obvious drag or close path.
When To Use Other Skills
- Use
swiftui-patterns for broader scene, commands, settings, sidebar,
and inspector architecture.
- Use
liquid-glass when the main question is modern macOS visual treatment,
Liquid Glass, or system material adoption.
- Use
appkit-interop if a custom window behavior truly requires NSWindow,
NSPanel, or responder-chain control.
- Use
build-run-debug to launch and verify the resulting windows.
1---2name: window-management3description: Customize macOS SwiftUI windows and scene behavior. Use when tuning window chrome, drag regions, placement, restoration, launch behavior, or borderless windows.4metadata:5 source: https://skillmd.com/skills/concertonotes/window-management6---78# Window Management910## Overview1112Use this skill to tailor each SwiftUI window to its job. Start by identifying13which scene owns the window (`Window`, `WindowGroup`, or a dedicated utility14scene), then customize the toolbar/title area, background material, resize and15restoration behavior, and initial or zoomed placement.1617Prefer scene and window modifiers over ad hoc AppKit bridges when SwiftUI offers18the behavior directly. Keep each window purpose-built: a main browser window, an19About window, and a media player window usually want different chrome,20resizability, restoration, and placement rules.2122These APIs are macOS 15+ SwiftUI window/scene customizations. For older23deployment targets, expect to use more AppKit bridging or availability guards.2425## Workflow26271. Inspect the relevant scene declaration and classify the window role:28 main app navigation, inspector/detail utility, About/support window, media29 playback window, welcome window, or a borderless custom surface.302. Adjust toolbar and title presentation to match the content.313. If the toolbar background or entire toolbar is hidden, make sure the window32 still has a usable drag region.334. Refine window behavior for that role: minimize availability, restoration,34 resize expectations, and whether the window should appear at launch.355. Set default placement for newly opened windows and ideal placement for zoom36 behavior when content and display size matter.376. Build and launch the app with `build-run-debug` to verify the result in38 a real foreground `.app` bundle.397. If SwiftUI scene/window modifiers are not enough, switch to `appkit-interop`40 for a narrow `NSWindow` bridge rather than spreading AppKit through the view41 tree.4243## Toolbar And Title4445- Use `.toolbar(removing: .title)` when the window title should stay associated46 with the window for accessibility and menus, but not be visibly drawn in the47 title bar.48- Use `.toolbarBackgroundVisibility(.hidden, for: .windowToolbar)` when large49 media or hero content should visually extend to the top edge of the window.50- If the window still needs close/minimize/full-screen controls, remove only the51 title and toolbar background. If the toolbar should disappear entirely, use52 `.toolbarVisibility(.hidden, for: .windowToolbar)` instead.53- Remove custom toolbar backgrounds and manually painted titlebar fills before54 layering new SwiftUI toolbar APIs on top.55- Keep the window's logical title meaningful even if hidden; the system can56 still use it for accessibility and menu items. These are visual changes only.5758## Drag Regions5960- If a toolbar background is hidden or the toolbar is removed entirely, use61 `WindowDragGesture()` to extend the draggable area into your content.62- Attach the gesture to a transparent overlay or non-interactive header region63 that does not steal gestures from real controls.64- For a media player with custom playback controls, insert the drag overlay65 between the video content and the controls so AVKit or transport controls keep66 receiving input.67- Pair the drag gesture with `.allowsWindowActivationEvents(true)` so clicking68 and immediately dragging a background window still activates and moves it.6970## Background And Materials7172- Use `.containerBackground(.thickMaterial, for: .window)` when a utility window73 or About window should replace the default window background with a subtle74 frosted material.75- Prefer system materials for stylized windows instead of hardcoded translucent76 colors.77- Use this especially for fixed-content utility windows where a softer backdrop78 is part of the design.7980## Window Behavior8182- Use `.windowMinimizeBehavior(.disabled)` for always-reachable utility windows83 such as a custom About window where minimizing adds little value.84- Disable the green zoom control through fixed sizing or window constraints when85 the window's content has one intended size.86- Use `.restorationBehavior(.disabled)` for windows that should not reopen on87 next launch, such as About panels, transient support/info windows, or88 first-run welcome surfaces.89- Keep state restoration enabled for primary document or navigation windows when90 reopening prior size and position is desirable.91- By default, SwiftUI respects the user's system-wide macOS state restoration92 setting. Use `restorationBehavior(...)` only when a specific window should93 intentionally opt into or out of that system behavior.94- Use `.defaultLaunchBehavior(.presented)` for windows that should appear first95 on launch, such as a welcome window, and choose that behavior intentionally96 rather than relying on side effects from scene creation order.9798## Window Placement99100- Use `.defaultWindowPlacement { content, context in ... }` to control the101 initial size and optional position of newly opened windows.102- Inside the placement closure, call `content.sizeThatFits(.unspecified)` to get103 the content's ideal size.104- Read `context.defaultDisplay.visibleRect` to get the display's usable region105 after accounting for the menu bar and Dock.106- Return `WindowPlacement(size: size)` with a size clamped to the visible rect107 when media or document content may be larger than the display. If no position108 is provided, the window is centered by default.109- Use `.windowIdealPlacement { content, context in ... }` to control what110 happens when the user chooses Zoom from the Window menu or Option-clicks the111 green toolbar button. For media windows, preserve aspect ratio and grow to the112 largest size that fits the display.113- Treat default placement and ideal placement as separate policies:114 - default placement controls where a new window first appears,115 - ideal placement controls how large a zoomed window should become.116- Always consider external displays and rotated/narrow screens when sizing117 player windows or document windows from content dimensions.118119## Borderless And Specialized Windows120121- Use `.windowStyle(.plain)` for borderless or highly custom chrome windows, but122 make sure the content still provides a clear drag/move affordance and visible123 context.124- For a borderless player, HUD, or welcome window, decide upfront whether losing125 standard titlebar affordances is worth the custom presentation.126- Keep one clear path back to regular window management if the plain style makes127 the window feel invisible or hard to move.128129For concrete window modifier examples, read `references/api-snippets.md`.130131## Review Checklist132133- The scene type matches the window's role and lifecycle.134- Hidden titles still leave a meaningful logical title for accessibility and135 menus.136- Toolbar background removal is intentional and does not hurt titlebar legibility137 or window control placement.138- Windows with hidden or removed toolbars still have a reliable drag region and139 support click-then-drag activation from the background.140- Utility windows have restoration/minimize behavior that matches their purpose.141- Restoration overrides are used only when a scene should intentionally differ142 from the user's system-wide setting.143- Default and ideal placement use `content.sizeThatFits(.unspecified)` and144 `context.defaultDisplay.visibleRect` when content/display size matters.145- Media windows preserve aspect ratio and fit on small or rotated displays.146- Borderless windows still have a usable move/drag affordance.147148## Guardrails149150- Do not use `.toolbar(removing: .title)` just to hide a title you forgot to set.151 Keep the underlying window title meaningful.152- Do not hide the toolbar background or the whole toolbar without replacing the153 lost drag affordance.154- Do not disable restoration on the main document/navigation window unless the155 user explicitly wants a fresh-start app every launch.156- Do not hardcode one monitor size or assume a single-display setup when sizing157 player windows.158- Do not reach for `NSWindow` mutation before checking whether159 `.windowMinimizeBehavior`, `.restorationBehavior`, `.defaultWindowPlacement`,160 `.windowIdealPlacement`, `.windowStyle`, or `.defaultLaunchBehavior` already161 solve the problem.162- Do not leave a plain borderless window without any obvious drag or close path.163164## When To Use Other Skills165166- Use `swiftui-patterns` for broader scene, commands, settings, sidebar,167 and inspector architecture.168- Use `liquid-glass` when the main question is modern macOS visual treatment,169 Liquid Glass, or system material adoption.170- Use `appkit-interop` if a custom window behavior truly requires `NSWindow`,171 `NSPanel`, or responder-chain control.172- Use `build-run-debug` to launch and verify the resulting windows.