spatial-design

Spatial Design (visionOS)

The design rules that make a visionOS app comfortable instead of exhausting — distilled from Apple's spatial-design sessions (WWDC23–26). Widget-specific rules live in visionos/widgets; custom immersive-environment production and budgets live in immersive-environments.md.

When This Skill Activates

• Designing or reviewing a visionOS app, window, volume, or immersive space
• "Users say it's tiring / uncomfortable / hard to hit controls"
• Porting an iPad app and deciding what should become spatial
• Adding hover effects, custom gestures, environments, or spatial audio
• Choosing a video experience format (spatial, 180°, 360°, wide-FOV, Apple Immersive)

The prime directive: find the key moment

Don't window a 2D app. Identify the one thing only possible on visionOS — the "key moment" — and build around it. Immersion has three approaches, and full immersion is not mandatory: full environments · integration with real surroundings (scene sensing) · meaningful audio.

Layout & ergonomics

• Wide beats tall — layouts match the human field of view; turning the head left/right is easier than up/down. Center = primary content; edges = secondary, infrequent actions.
• Default placement sits along the natural line of sight, a bit further than arm's reach; extended reading goes farther out, centered and slightly below eye line.
• Design in points, not meters — dynamic scale keeps windows legible at any distance (they scale up as they move away). Never fixed scale for UI; keep custom UI facing the viewer.
• Depth is hierarchy, used sparingly — "prefer subtle depth" (a modal pushes its parent back). Keep text flat; 3D text is hard to read at an angle.
• Glass, never solid window backgrounds — solid colors block the world, don't adapt to lighting, and "can feel constricting." Elements on glass use vibrancy + white text/symbols; system colors over custom (they're calibrated for legibility). Brand color goes in backgrounds or whole buttons, not glyphs.
• Typography runs heavier than iOS: body = medium (vs regular), titles = bold (vs semibold), slightly increased tracking. Avoid small/lightweight custom fonts.
• Component specs: vertical tab bar fixed left, ≤6 items, expands on gaze · ornaments overlap the window's bottom edge by 20pt, borderless buttons inside · sheets appear centered at the parent's Z while the parent dims and pushes back · nested corners concentric (outer radius = inner + padding).
• SwiftUI spatial layout: stacks default to .back depth alignment — switch to .front when content should read toward the viewer; rotation3DLayout (not rotation3DEffect) when rotation must affect layout; SpatialContainer/spatialOverlay for shared 3D space; scaledToFit3D() for models.