Apple HIG visionOS Spatial Computing (Eye and Hand Gestures / Immersion Spectrum / Comfort Science / Spatial UI / SharePlay)

The design of Apple Vision Pro differs from all 2D platforms — it adds eyes, gestures, depth, and real space as four new dimensions. A core tension runs through the entire document:immersion vs comfort (motion sickness prevention),virtual vs reality (integration). Many dynamic effects are presented as videos (local.mov files); this wiki explains the underlying principles thoroughly.

1. Eye Input Eyes (the most unique interaction)

When a user looks at a virtual object, the system identifies it as an interactive target and displays a hover effect to confirm.Ironclad privacy rule: before the user taps, the system does not tell the app where the user is looking (so you cannot listen for hover events; you can only define a "normal state" and a "gazed-at state" for the system to switch between automatically, and you cannot directly trigger functions from gaze alone).

· Comfort: Place content directly in the center of the forward field of view (turning the neck left/right is easier than up/down; for large canvases, choose width over height); keep interactions and content at the same depth as much as possible (the eyes can only focus at one distance at a time; frequent focal changes cause fatigue — that is why pop-ups dim the parent window behind them instead of floating on top, the opposite of mobile behavior). · Easy to focus: Use circles / capsules / rounded rectangles (sharp corners draw the eyes outward and reduce center accuracy); keep designs flat (thick strokes and shadows draw eyes to edges); leave ample internal padding and center content. · Response:Dynamic scaling (windows grow larger when far and smaller when near, opposite to "closer looks bigger, farther looks smaller", to keep target area consistent); all interactive elements must have a highlight state, with subtle, universal effects (eye movement is fast). · Intent: Sustained gaze = interest → show more information (tool names / button descriptions / gazing at the microphone triggers voice search); focus also supports accessibility (gaze selection avoids the need for hand taps). · Look to Scroll: Gazing at the edge triggers automatic scrolling; suitable for reading/browsing (Safari/TV),not suitable for Settings (quickly scanning for options easily causes accidental triggers); not enabled by default, requires active opt-in; scroll areas fill the full window width/height.

2. Hover Interaction Hover (3 types)

All hover animations start from a visible element (do not make things pop out of empty space);provide anchor elements (keep titles stationary as a reference);avoid unexpected motion (Safari tab close button: fades in semi-transparently when looking at the tab, only becomes fully visible when looking at the button itself, otherwise accidental taps close tabs). Effects should be small and restrained (use default system highlights for high-frequency areas like toolbars).

Persistent controls: UI that auto-hides after a delay (video playback controls / FaceTime hang up / meditation pause),do not disappear as long as the user is still gazing at them, and only hide when gaze returns to content (system video controls handle this automatically, no code required).

3. Gestures Gestures + Haptics

· System gestures (users already know them, no extra equipment needed, usable in any space): single tap (gaze + two-finger tap), double tap, pinch-drag (direct/indirect manipulation), pinch-and-hold (activate + move to control direction and force), two-hand gestures (zoom, rotate). Combinable (simultaneously select, move, adjust, rotate, as in satellite view). · Eye + hand combination: When starting a hand action, the zoom origin is the point the eyes are focused on at that moment; looking at another part of the canvas and tapping jumps the cursor there (precisely covers large canvases). · Direct vs indirect touch: Direct touch is suitable for ① close-up inspection / hand-moved assembly ② mimicking real-world actions (muscle memory) ③ experiences centered on physical activity; otherwise prioritize indirect gestures (no need to reach into the field of view, less tiring). · Compensation for lack of haptics: visionOS has no haptic feedback, so compensate with audio and visuals — raised buttons, hover highlights, proximity brightening as you approach, rapid state changes at the moment of contact + spatial audio, to provide a sense of "touch, reliability, and satisfaction".

4. Comfort Science Comfort (hard constraints for motion sickness prevention)

Movement science: Self-motion perception is produced jointly by the visual system + the vestibular system (inner ear balance canals).When visual motion conflicts with vestibular information → motion sickness (dizziness/nausea).

· Movement: When large objects covering most of the field of view move, the brain thinks "I am moving" → use translucency to reduce conflict;avoid head-locked content (if you must use it, make it a small window, place it at the center of gaze, and keep it far away); prioritize world-locked content; camera movement should be slow and predictable, aligned to the horizon, avoid fast turns/pure rotation (use fast fade-outs + instantaneous direction changes);avoid oscillations around 0.2Hz (once every 5 seconds) (if you must use them, keep amplitude low + use translucency); avoid large objects quickly passing by at close range. · Depth: Depth cues (perspective/shadow/color/size/blur/motion) must be consistent;conflicts cause discomfort (contradictions between relative size vs occlusion); prevent ghosting from repeating patterns (two eyes locking onto different objects) → use small patterns or break up patterns. · Visual parameters: For long reading sessions, place content beyond arm's length for maximum comfort, slightly below center of gaze; reserve near distances only for brief or direct interactions; transition gradually from dark scenes to bright ones (give eyes time to adapt); eyes are most comfortable turning downward/left/right; provide rest points for long sessions.

5. Spatial UI and Layout

· Size: Interactive elements require ≥60pt tap targets (=2.5° viewing angle, ~4.4cm at 1 meter); ≥8pt of empty space around buttons to meet the 60pt target; stacked button spacing ≥16pt; mini 28pt buttons are still easy to tap when surrounded by 60pt of space;Concentric formula: nested element corner radius + margin = outer container corner radius. · Ergonomics: Keep UI within the field of view, not too high or too low; windows can be moved/closed/resized, and always face the user when moved; for large canvases choose width over height. · Windows sized to content: Safari is tall (to see more of a webpage), Keynote is wide (full-size presentations); multiple windows side by side (slides + presenter view); separate controls from content (navigation bar separate from webpages). · Ornaments: Floating attachments; in visionOS they sit slightly in front of the window bottom; borderless buttons (glass containers); overlap the bottom by 20pt for a fused look; can expand and have their own navigation hierarchy. · Menus / popovers / Sheets: Can extend outside the window, centered by default (appear at the gaze point); modals share the same Z-axis as the parent window, parent window recedes and dims; use white background with black marks for selected states (no arrows needed); close + back buttons are both in the top-left corner. · Materials: Glass material has no light/dark mode (renders automatically with ambient light); dark materials separate sections (sidebars), light materials emphasize interaction (buttons), dark materials increase contrast (input fields); do not stack light materials (reduces readability);text defaults to white, with increased font weight + letter spacing for contrast (body text is medium weight in visionOS, titles are bold); vibrancy keeps foreground content updated in real time to maintain readability. · Icons: Three-dimensional and realistic, ≤3 layers (background + 2 foreground layers), 1024px square with transparent foreground and opaque background; the system adds a glass layer + highlights + a circular shadow mask.

6. Immersion Spectrum

graph LR
  A["共享空间<br/>Shared Space<br/>多 App 并存"] --> B["调暗 Dim<br/>突出主内容<br/>(Keynote 放幻灯片)"]
  B --> C["全空间 Full Space<br/>独占,带你到新地方<br/>(Keynote 剧院排练)"]
  C --> D["完全沉浸<br/>360° 自定义环境<br/>替代透视"]

· Supports dynamic transitions (smoothly switches based on user position); dimming is the simplest focus tool (does not leave the current page); Full Space requires more room; blends with reality (e.g., "hello" casts a shadow on the desk). · Basic techniques: Guide attention (motion + spatial audio + color, e.g., Mindfulness flower); soft edges blend with reality; subtle animations feel "alive" (water ripples/clouds);less is more (subtle light reflections on cinema floors and ceilings are enough); smooth, predictable transitions preserve comfort. · Building realism / sense of space: Focus on "key moments that can only be experienced in space"; use light and shadow to add depth (small nearby elements matter more than large distant objects, glowing objects cast reflections);keep text flat (3D text is hard to read and distracts attention); use scale to convey emphasis (small objects feel personal, large objects feel impressive; shopping apps use real-world scale).

7. Spatial Widgets (visionOS exclusive "proximity awareness")

Widgets become 3D objects, placed on walls/tables (permanently reside in that room, locked in position, slightly tilted on tables + cast shadows); they can only attach to physical surfaces (cannot attach to virtual environments); always appear behind virtual content.Fixed physical size (look like they "naturally belong in that space" on walls or tables; adjustable from 75%–125%, use high-resolution assets).

· Inset styles: Elevated (floating, like a hung picture, emphasizes presence, works vertically and horizontally) / Recessed (sunken, immersive feeling of a wall being carved out, vertical surfaces only); 14 system color schemes, 5 levels of border thickness. · Proximity awareness (most unique): far = Simplified state (only shows team name and score), near = Default state (full content); like a "spatial version of responsive design".

8. SharePlay Shared Space (multi-user sync)

· Window mode (can use other apps simultaneously, windows marked "shared / not shared" and draggable) vs Full Space mode (more immersive but limits multitasking). · 3 Full Space sub-modes:Side-by-Side (like a movie theater, viewing the same content from the same angle, good for watching videos) / Surround (like sitting around a conference table, each person views the center from their own angle, good for discussion and collaboration) / Conversational (chatting around the app, content acts as background, good for socializing). · Shared context + spatial audio (sound positions are consistent for everyone); personal settings (volume/subtitles) do not affect others; personal windows can sync with the main view.

9. Narrative Interaction + Core Spatial Strategies

· Narrative interaction (Encounter Dinosaurs): clear instructions are mandatory; the initial interaction sets the tone (butterfly guide lands on the hand); spatial characters use eye contact + approach + hand interaction (dinosaur Izzy sniffs the hand and can be petted); spatial audio brings them to life. · Spatial audio: Simulates real-world sound propagation (sensors recognize room size and materials + reverb); randomization avoids monotony (frog pitch/volume + push away + random timing); layered foreground + background. · Core spatial strategies: Find the app's key moments (only possible on visionOS, e.g., Mindfulness pulsing flower);constantly iterate with prototypes (Loona "built many prototypes to find the best experience"); build complementary experiences (Lowe's vision immersive kitchen design + iPad product purchasing = complete journey); minimize physical movement (Fruit Ninja does not require walking around); infinite canvas but keep interface coherent; visual comfort (glass material + hover feedback).

Sourced from visionOS VR (17 articles). Spatial motion effects are in the original document .mov Video (view locally in Obsidian). For eye tracking/gesture input, see also Apple HIG Inputs (13 types · Touch/Gestures/Keyboard/Pointer/Pencil/Digital Crown/Eye Tracking/Remote/Game Controller); for immersive experience/spatial layout basics, see Apple HIG Visual Foundations (Color/Typography/Layout/Materials/Motion/Dark Mode/Icons/SF Symbols/Branding).