swiftui-multiplatform-design-guide_skill

Overview

This skill provides a compact, practical design guide for building unified SwiftUI apps across iOS, iPadOS, macOS, and visionOS. It focuses on a state-driven architecture that respects per-scene state, spatial design principles, and platform-specific ergonomics. The guide emphasizes patterns that avoid singletons, embrace per-window dependency graphs, and treat UI as layered planes rather than flat pixels.

How this skill works

The guide inspects the lifecycle and scene types in SwiftUI—WindowGroup, DocumentGroup, and ImmersiveSpace—and prescribes where to scope state and navigation. It explains scene-phase management, make-before-break transitions for immersive spaces, window sizing strategies, and adaptive layout decisions (e.g., when to avoid NavigationSplitView as a root). The content maps spatial concepts (depth, focus, pass-through) to concrete implementation patterns and modifiers.

When to use it

• When building a single codebase that must run on iPhone, iPad, Mac, and Vision Pro.
• When you need per-window or per-scene independent state and navigation.
• When supporting document-based workflows and file integration across platforms.
• When implementing immersive visionOS experiences that must coordinate with standard windows.
• When optimizing performance based on ScenePhase and focus-driven rendering.

Best practices

• Scope state to the Scene: create per-window ViewModels or NavigationManagers injected at the window root.
• Use DocumentGroup for file-centric apps to leverage automatic system integration and file state handling.
• Apply the loading-window (make-before-break) pattern when switching ImmersiveSpaces to avoid zero-scene termination.
• Design UI as layered planes: plan for focus, parallax, and specular reaction rather than flat asset swaps.
• Respect .inactive ScenePhase: immediately suspend costly rendering or simulations when focus is lost.

Example use cases

• A notes app that supports multiple independent windows on macOS and iPad, with separate undo/history per window.
• A drawing app using DocumentGroup to open and edit multiple canvases as floating visionOS windows.
• A media player that adapts controls from touch, pointer, and gaze by exposing a single semantic action layer.
• A productivity suite that transitions between shared-space windows and a full ImmersiveSpace environment safely.
• An app that auto-adjusts layout and typography based on angular size and user distance in spatial displays.