Cross Platform Adaptivity

Cross-Platform Adaptivity

One codebase, native everywhere — adapt to the device, don't just stretch to fit. A blown-up iPhone UI on iPad or Vision Pro reads as lazy. Share logic; specialize presentation. Pair with apple-design (HIG) and swiftui-micro-craft (polish).

> Principle: design for capabilities and size, not device names. Branch on size class / horizontal space, reserve #if os() for genuinely platform-specific APIs.

---

Adapt to size, not device

@Environment(\.horizontalSizeClass) private var hSize

var body: some View {
    if hSize == .compact {
        TabView { … }            // iPhone portrait, narrow windows
    } else {
        NavigationSplitView { … } // iPad, Mac, wide windows
    }
}

• Compact vs regular size classes matter more than iPhone-vs-iPad: an iPad multitasking slide-over is compact, and a Mac window can be resized to either. Respond to the class.
• Let layout flex with ViewThatFits (pick the first child that fits), adaptive Grid / LazyVGrid(columns: [.adaptive(minimum:)]), and .frame(maxWidth:) reading caps — not hard-coded widths.
• Avoid magic-number breakpoints; prefer the system's size classes and Dynamic Type.

---

Adaptive navigation

| Pattern | Compact | Regular | |---------|---------|---------| | NavigationStack | Push/pop column | Push/pop column | | NavigationSplitView | Collapses to a stack automatically | 2–3 column sidebar + content + detail | | TabView | Bottom tabs | Sidebar-adaptable tabs (.tabViewStyle) / top on tvOS |

NavigationSplitView is the workhorse for content apps: it gives a sidebar on iPad/Mac and automatically collapses to a navigation stack on iPhone. Drive selection with state so the same model works in both layouts.

---

Per-platform idioms (what "native" means on each)

• iPadOS — pointer/trackpad hover (.hoverEffect), keyboard shortcuts (.keyboardShortcut), multiple windows/scenes, drag & drop, Stage Manager resizing, sidebar. Support external keyboard and the menu bar.
• macOS — menu bar CommandMenu, Settings scene (⌘,), window management, .focusable, hover, right-click context menus, sensible min window sizes. Mac Catalyst vs native SwiftUI is a porting decision — native SwiftUI for new apps.
• visionOS — depth, glass materials, ornaments, .windowStyle(.volumetric), immersive spaces, eye/hand input (hover is gaze — generous hit targets). Don't assume a 2D plane; respect the spatial HIG.
• watchOS — glanceable, short sessions, the Digital Crown, complications; build for the wrist, not a shrunken phone screen.
• tvOS — the focus engine drives everything; design for a 10-foot distance and the Siri Remote. Focusable, not tappable.

---

Platform conditionals — use sparingly

#if os(iOS)
    .navigationBarTitleDisplayMode(.inline)   // doesn't exist on macOS
#endif

#if os(visionOS)
    .glassBackgroundEffect()
#endif

• #if os(iOS|macOS|watchOS|tvOS|visionOS) for compile-time API differences; #if targetEnvironment(macCatalyst) for Catalyst.
• Prefer runtime size-class/environment checks for layout (one binary adapts live as a window resizes); reserve #if for APIs that don't exist on a platform.
• Isolate platform code behind small wrappers / extensions so the shared view stays readable. Don't litter body with conditionals.

---

Structure for sharing

• One multiplatform target (or shared SwiftUI package) for models, view models, and most views; thin platform layers for the differences. Most SwiftUI views are already portable.
• Use @Environment-driven styling so components restyle themselves per platform instead of forking.
• Gate capabilities, not platforms: check for the feature (camera, UIApplication, push) rather than assuming from os().
• Keep assets/icons per platform in the asset catalog; verify each platform's icon set (see app-brand-identity).

---

Pre-ship checklist

• [ ] Works in both size classes (resize the iPad/Mac window; try slide-over).
• [ ] Navigation collapses sensibly compact↔regular (NavigationSplitView).
• [ ] No hard-coded widths that break on Mac resize or iPad multitasking.
• [ ] Each shipped platform uses its idioms (menus on Mac, focus on tvOS, depth on visionOS, Crown on watch).
• [ ] #if os() limited to true API gaps, not layout.
• [ ] Keyboard shortcuts & pointer hover on iPad/Mac; VoiceOver/focus verified per platform (see ios-accessibility).
• [ ] Each platform's app icon and launch experience set correctly.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: markdavidgan
• Source: markdavidgan/apple-dev-skills
• License: MIT

Install and usage instructions live in the source repository linked above.