Spatial SwiftUI Developer

Quick Start

1. If the task is really about surface choice, scene ownership, or file

structure, switch to spatial-app-architecture first.

1. If the task is about Chart3D, SurfacePlot, 3D chart marks, or

Chart3DPose, switch to $swiftui-chart3d-developer.

1. Pick the rendering track: Model3D for simple asset display, RealityView

for custom entity graphs and attachments.

1. Load only the matching reference files.
2. Keep loading async and keep RealityKit mutations inside its intended entry

points.

1. Route build, launch, simulator, and test problems to build-run-debug.

Load References When

Workflow

1. Confirm the architecture and scene ownership are already settled.
2. Choose the rendering surface: Model3D, RealityView, window, volume, or

immersive scene.

1. Load only the matching reference files.
2. Implement the smallest viable scene and keep mutations in the right layer.
3. Summarize the chosen SwiftUI-to-RealityKit integration path.

Guardrails

• Every visible button gets an explicit .buttonBorderShape(...) (.capsule

for labeled actions, .circle for icon-only, .roundedRectangle(radius:) matching the background for card-like buttons - on visionOS this is also what shapes the button's hover highlight). Non-button hover surfaces pair .hoverEffect() with a matching .contentShape(.hoverEffect, ...). Load [buttons-and-controls.md](references/buttons-and-controls.md) before writing any control code - this applies even when buttons are incidental to a larger task.

• Keep RealityKit loads async; do not block the main actor with asset or entity loading.
• Mutate RealityKit content in RealityView make or update closures or in a

system, not in SwiftUI body code.

• Use Model3D only when you need simple display and layout, not a custom ECS graph.
• Treat ImmersiveSpace as a separate scene with its own lifecycle and environment actions.
• Use defaultSize as an initial hint only; the system can clamp or restore geometry.
• Use $swiftui-chart3d-developer for Chart3D and spatial data visualization.
• Switch to build-run-debug when the question is about launch, build,

simulator, codesign, or debugging workflow.

• Use spatial-app-architecture when the question is about scene boundaries,

ownership, or feature decomposition rather than API usage.

• visionOS 27 SwiftUI adds no new scene, volume, or immersion APIs; the

guidance here is current for visionOS 27. New in 27: gesture inputKinds: filtering (see interaction.md) plus cross-platform toolbar and navigation refinements that also apply on visionOS.

Output Expectations

Provide:

• the chosen rendering and scene path
• which references were used
• the API surface involved (Model3D, RealityView, windowing, interaction,

or layout)

• the main implementation constraint or pitfall
• routing back to architecture, Chart3D, or build/debug if needed