SwiftUI Multiplatform Design Guide

What this skill does

# Unified Architectures in SwiftUI: A Comprehensive Design Strategy for iOS, iPadOS, macOS, and visionOS

## 1. Introduction: The Convergence of Spatial and Flat Computing

The contemporary landscape of Apple software development is defined by a
radical convergence of interaction paradigms. Historically, the
demarcation lines between platforms were rigid: iOS was governed by the
touch target and the direct manipulation of glass; macOS was the domain
of the precise cursor and the indirect abstraction of the mouse; and
iPadOS occupied a liminal space, attempting to bridge the two. The
introduction of visionOS, however, has fundamentally disrupted this
tiered architecture. It has necessitated a new design language that is
not merely responsive in terms of screen size, but adaptive in terms of
physical dimension, input modality, and user intent.

This report provides an exhaustive analysis of the architectural
strategies required to build truly multiplatform applications using
SwiftUI. It moves beyond the superficial concept of \"cross-platform\"
code sharing---often synonymous with the \"lowest common denominator\"
approach---and instead advocates for a unified state-driven architecture
that respects the distinct ergonomics of each device. We will explore
the \"Liquid Glass\" metaphor that now underpins Apple's visual
language, the complex hierarchy of scenes and windows, and the unified
input models that allow a single semantic action to be triggered by a
tap, a click, or a gaze-driven pinch.

### 1.1 The Evolution of Human Interface Guidelines

The Apple Human Interface Guidelines (HIG) have evolved from static sets
of rules for distinct platforms into a fluid, overarching philosophy of
design. The core pillars of this philosophy---Space, Immersion,
Passthrough, and Spatial Audio---are no longer exclusive to the
headset.^1^ They represent a shift toward \"Spatial Computing\" that
influences even flat interfaces. For instance, the layering and depth
effects found in visionOS icons are conceptually linked to the parallax
effects on tvOS and the fluid animations of iOS.^2^

A critical insight from this evolution is the concept of
\"Pass-through\" design, not just in the optical sense of seeing the
real world, but in the interface sense of minimizing obstruction. On
iOS, this manifests as translucent materials and sheets; on visionOS, it
is literal transparency. Designing for this requires a \"content-first\"
approach where the \"chrome\" (interface elements) recedes. The HIG
explicitly advises using windows for UI-centric experiences while
reserving immersion for distinctive moments, a pattern that mirrors the
modal presentations on iOS.^1^

### 1.2 The Role of App Icons in Multiplatform Identity

The entry point to any application, the app icon, serves as the first
lesson in multiplatform adaptation. While often overlooked as a mere
asset, the icon's behavior dictates user expectations. On iOS, icons are
flattened super-ellipses that respond to home screen layout shifts. On
macOS, they act as uniform \"chicklets\" with drop shadows to imply a
desktop metaphor. However, on tvOS and visionOS, the icon becomes a
layered, three-dimensional object.

Research into the construction of these icons reveals a \"Liquid Glass\"
aesthetic where layers coalesce to create dimensionality. On visionOS,
an icon typically consists of a background layer and one or two
foreground layers. When the user gazes at the icon, the system applies
specular highlights and a parallax effect, physically lifting the
foreground layers to meet the user\'s eye.^2^ This is not merely
cosmetic; it acts as a primer for the user, teaching them that
\"looking\" is an interactive act. An effective multiplatform
architecture must therefore extend this layered thinking into the app
itself, treating UI elements not as flat pixels, but as planes floating
in a hierarchy, ready to react to the \"focus\" of the eye or the
pointer.

## 2. The Hierarchy of Scenes: Windows, Volumes, and Spaces

In the SwiftUI lifecycle, the Scene protocol has supplanted the View as
the fundamental unit of application structure. While the View defines
what the user sees, the Scene defines how the operating system manages
that content\'s existence, persistence, and lifecycle. A mastery of
Scene types---specifically WindowGroup, DocumentGroup, and
ImmersiveSpace---is the prerequisite for building apps that scale from
the iPhone SE to the Vision Pro.

### 2.1 The WindowGroup Paradigm and Lifecycle Management

The WindowGroup is the workhorse of SwiftUI. It defines a template for
the application\'s primary interface. However, its behavior is radically
polymorphic depending on the host platform. On iPhone, it generally
instantiates a single, persistent window. On iPadOS and macOS, it serves
as a factory for creating multiple, concurrent windows.^4^

This polymorphism introduces significant architectural complexity
regarding state management. A common anti-pattern in early SwiftUI
development was the reliance on a singleton AppState object injected at
the App level. While functional on a single-window iPhone, this
architecture collapses on iPadOS and macOS. If a user opens two windows
of the same application to compare data, a singleton architecture forces
both windows to share the same navigation path and selection state.
Navigating in Window A inadvertently drives navigation in Window B,
breaking the user\'s mental model of independent workspaces.

To address this, modern multiplatform architecture demands that state be
scoped to the Scene. Each time a WindowGroup instantiates a new window,
it must effectively spin up a fresh dependency graph for that window\'s
view hierarchy. This often involves creating a per-window ViewModel or
NavigationManager that is injected into the environment of the window\'s
root view, rather than the app\'s root.^6^

#### 2.1.1 Window Resizability and Geometry

The concept of a \"Window\" varies by physics. On macOS, a window is a
rect confined by the screen bezel, fully resizable by the user. On
visionOS, a window is a planar surface floating in 3D space, also
resizable, but with constraints dictated by legibility and the field of
view.

SwiftUI provides the .windowResizability and .defaultSize modifiers to
control this.

- **Content Size Strategy:** Using .windowResizability(.contentSize)
  allows the window to shrink-wrap its SwiftUI content. This is ideal
  for settings panels or utility dialogs.^4^

- **Automatic Strategy:** The system determines the size. On visionOS,
  this interacts with the user\'s distance. A window that appears
  \"small\" (in angular dimension) when far away might technically be
  rendering at the same pixel resolution as a \"large\" window close up.
  The system automatically scales content to maintain legibility
  (dynamic type), meaning developers must layout for \"points\" rather
  than pixels to avoid microscopic text in spatial environments.^1^

### 2.2 The DocumentGroup and File-Based Workflows

For productivity applications, the DocumentGroup scene type is
indispensable. It provides out-of-the-box integration with the
platform\'s file system (Finder on macOS, Files on iOS/iPadOS). More
importantly, it automates the complex \"Dirty State\" management and
file locking mechanisms required for desktop-class applications.^8^

When a DocumentGroup is deployed, SwiftUI automatically bridges the
application\'s document model (conforming to FileDocument) to the
system\'s standard menu commands. The \"File \> Open,\" \"File \>
Save,\" and \"File \> Duplicate\" menu items on macOS are automatically
wired to the active document scene. This is a crucial \"free\" feature
of SwiftUI that replicates hundreds of lines of AppKit boilerplate.

However, transitioning a standard app to a DocumentGroup app requires a
fundamental shift in data flow. The source of truth becomes the file on
disk, not a cloud database or a local cache. This has implications for
visionOS, where file ma