macos-window-architect

macOS Window Architect

Use SwiftUI scene/window modifiers first; switch to macos-appkit-bridge only when SwiftUI cannot express the behavior.

Workflow

1. Classify the window role: main navigation, inspector/detail, About/support, media, welcome, or borderless custom surface.
2. Adjust toolbar/title/background for that role.
3. If toolbar chrome is hidden, add a reliable drag region.
4. Set minimize, restoration, resize, launch, default placement, and ideal zoom behavior.
5. Build/launch with macos-runtime-debugger.

Patterns

• Hidden title but meaningful logical title:

  WindowGroup("Destination Video") {
    CatalogView()
      .toolbar(removing: .title)
      .toolbarBackgroundVisibility(.hidden, for: .windowToolbar)
  }
  

• Utility/About material window:

  Window("About", id: "about") {
    AboutView()
      .toolbar(removing: .title)
      .toolbarBackgroundVisibility(.hidden, for: .windowToolbar)
      .containerBackground(.thickMaterial, for: .window)
  }
  .windowMinimizeBehavior(.disabled)
  .restorationBehavior(.disabled)
  

• Placement from content/display:

  WindowGroup("Player", for: Video.self) { $video in
    PlayerView(video: video)
  }
  .defaultWindowPlacement { content, context in
    WindowPlacement(size: clampToDisplay(content.sizeThatFits(.unspecified),
                                         displayBounds: context.defaultDisplay.visibleRect))
  }
  .windowIdealPlacement { content, context in
    let size = zoomToFit(content.sizeThatFits(.unspecified),
                         displayBounds: context.defaultDisplay.visibleRect)
    return WindowPlacement(centeredPosition(for: size, in: context.defaultDisplay.visibleRect), size: size)
  }
  

• Drag region after hidden toolbar:

  Color.clear
    .frame(height: 48)
    .contentShape(Rectangle())
    .gesture(WindowDragGesture())
    .allowsWindowActivationEvents(true)
  

• Borderless/welcome:

  Window("Welcome", id: "welcome") { WelcomeView() }
    .windowStyle(.plain)
    .defaultLaunchBehavior(.presented)