/design-ar-overlay

description: "Design an AR overlay interface — anchor strategy, world tracking UI, scan states, confirmation overlays, and occlusion handling."
argument-hint: "[use case: navigation|instructions|product-viz|social] [platform: arkit|webxr|snap|meta]"
allowed-tools: ["Read", "Write", "mcp__*"]

/design-ar-overlay

You are designing a complete AR overlay interface spec. Your output is a single structured document covering anchor strategy, world tracking UI, instruction card patterns, scan state designs, confirmation overlays, and occlusion handling — all calibrated to the parsed use case and platform.

Input

Arguments: **$ARGUMENTS**

Parse the following from `$ARGUMENTS`:

• **Use case**: navigation / instructions / product visualization / social (default: instructions)
• **Platform**: ARKit / WebXR / Snap / Meta (default: ARKit)

---

Step 1: Load Knowledge Base

Read `${CLAUDE_PLUGIN_ROOT}/skills/design/references/spatial-designer.md` to apply the full Spatial Designer knowledge base to every section below.

**MCP Fallback**: If the file cannot be read, proceed using inline knowledge. The inline knowledge for this command covers: spatial anchoring types (world-locked: fixed in physical space; image-tracked: tied to a recognized image marker; surface-detected: placed on detected plane; face-tracked: follows detected face); AR session requirements from W3C WebXR spec (hit-test is a separate capability module — design graceful fallbacks for devices without it); distance-size formula for AR typography (recommended_size = 44pt × distance_m; minimum 18pt at 0.5m); minimum interactive targets (44×44pt at all distances); comfort rules (no automatic camera movement, stable horizon, vignette during transitions); occlusion depth ordering (real-world objects can occlude or be occluded by AR elements depending on depth buffer rendering order); edge indicators for off-screen AR objects (directional arrow at visible cone edge); confirmation overlays anchored above AR object at 1m distance.

---

Step 2: Generate the Spec

Produce all six sections below as a single continuous output. Do not pause or ask for confirmation between sections.

---

Section 1: Anchor Strategy

Select the appropriate anchor type for the parsed use case and platform. Specify persistence and recovery behavior.

**Anchor type reference:**

| Anchor Type | Behavior | Best For | |-------------|----------|----------| | **World-locked** | Fixed in physical space relative to detected surfaces or spatial origin | Navigation waypoints, persistent spatial annotations, furniture placement | | **Image-tracked** | Tied to a recognized image marker (product packaging, QR code, poster) | Product visualization, instructions on physical products, marketing activations | | **Surface-detected** | Placed on a detected horizontal or vertical plane | Object placement, surface-anchored instructions, measurement tools | | **Face-tracked** | Follows the detected face position and orientation | Social filters, avatar overlays, face-specific instructions |

**For the parsed use case, specify:**

• **Anchor type**: [Select the most appropriate type from the table above, with rationale]
• **Platform capability note**: For WebXR — hit-test is a separate capability module from basic `immersive-ar` session establishment. Design graceful fallback for devices that support `immersive-ar` but not `hit-test`. For ARKit — use `ARWorldTrackingConfiguration` for world/surface anchors; `ARImageTrackingConfiguration` for image targets.
• **Persistence**: Session-only (anchor lost when app closes) vs. persistent across app launches (requires ARKit persistent world map or equivalent). Specify which is appropriate and why.
• **Recovery behavior when tracking is lost**: Define what the UI shows and what the app does when the anchor is lost mid-session (see Section 2 for tracking UI states).

---

Section 2: World Tracking UI

Three tracking states with complete UI spec for each. These states apply to the initial surface/object detection phase and to any mid-session tracking loss.

State 1: Searching

The device is actively scanning for the target surface, image, or anchor point.

| Element | Spec | |---------|------| | **Visual treatment** | Animated scan ring: circular ring, 120px diameter, 2px stroke, primary accent color, rotating 360° at 1.5s per revolution | | **Instructional text** | [Derive from use case: e.g., navigation → "Point your camera at the floor to begin"; instructions → "Move your phone to scan the surface"; product-viz → "Point your camera at the product"; social → "Center your face in the frame"] | | **Text spec** | 18pt minimum (per distance-size guidelines at ~0.5m arm's length reading distance); Medium weight (500); centered below scan ring; max 2 lines | | **Haptic pattern** | Continuous light pulse (CHHapticPattern: transient, 0.3 intensity, 0.5s interval) — communicates active scanning without demanding attention | | **Background treatment** | Dim non-target areas with 30% dark vignette overlay to guide focus toward scan ring |

State 2: Tracking Acquired

The anchor has been successfully established.

| Element | Spec | |---------|------| | **Visual treatment** | Success animation: scan ring completes to solid circle, 200ms ease-out scale from 100% → 120% → 100%; color transitions to success green (#34C759 for iOS; equivalent success color for other platforms) | | **Confidence indicator** | Brief pulse on the anchor point (subtle glow, 1.5s duration) confirming tracking lock | | **Confirmation copy** | "Found" label, 16pt, appears below animation for 1.2s then fades; or use platform-native success haptic (UINotificationFeedbackGenerator .success / equivalent) | | **Transition** | Fade scan ring out over 0.3s; immediately surface AR content layer | | **Haptic** | Single success impact (medium weight) on acquisition |

State 3: Tracking Lost

The anchor has been lost mid-session — due to low light, occluded