immersive-interactive-architect

name

immersive-interactive-architect

description

Specialized architect for building augmented reality, 3D, and immersive shopping experiences — across ANY output format (React JSX, standalone HTML/CSS/JS, WordPress/WooCommerce PHP, Python backends, or any other language). Use this skill whenever the user mentions: 3D product viewers, virtual try-on, AR fitting rooms, immersive brand showrooms, 3D collection environments, interactive drop pages, Three.js, React Three Fiber, A-Frame, model-viewer, WebXR, GSAP cinematic scroll, Lottie animations, spatial UI, parallax 3D scenes, or any request to make shopping feel like an experience rather than a webpage. Always use this skill even if the request seems simple — immersive experiences require specialized architecture that generic frontend patterns cannot match. This skill extends frontend-design with deep 3D and AR expertise; load frontend-design alongside it for complete visual design guidance.

Immersive Interactive Architect

This skill governs the design and implementation of AR, 3D, and immersive commerce experiences — spatial interfaces where products live in three-dimensional space, motion tells the story, and every interaction deepens the emotional connection between brand and customer.

Before coding, always read the frontend-design SKILL.md for visual design principles. This skill handles the spatial architecture layer on top of it.

---

Immersive Design Philosophy

Fashion is emotional. Immersive experiences must feel like entering a world, not browsing a store. Every build answers:

1. The World: What is the spatial metaphor? (underground vault, rose garden at midnight, elevated rooftop, fractured mirror dimension)
2. The Journey: How does the customer move through it? (scroll-driven, click-to-explore, gesture-controlled, camera-tracked)
3. The Reveal: When does the product become the hero, and how is it presented?
4. The Emotion: What should the visitor feel 10 seconds in — awe, mystery, hunger, belonging?
5. The Exit: What action do they take? (add to cart, join waitlist, share, save)

CRITICAL PRINCIPLE: Never build a 3D experience that is slower, harder, or less emotional than a good 2D page. Immersive = purposeful. Every Three.js mesh, every GSAP timeline, every WebGL shader must earn its render cost.

---

Technology Stack — Decision Matrix

Select based on the experience type and output target:

Experience	Primary Tech	Supporting
3D Product Viewer (spin/zoom/inspect)	model-viewer or Three.js	GSAP for entrance animations
Brand Showroom / 3D Environment	Three.js or React Three Fiber	GSAP ScrollTrigger, custom shaders
Collection Drop / Launch Page	GSAP + Lottie + CSS 3D	Three.js particle systems (optional)
Virtual Try-On / AR Overlay	WebXR + model-viewer AR mode	MediaPipe (body/face tracking)
Cinematic Scroll Experience	GSAP ScrollTrigger + CSS Transforms	Three.js for accent effects
WordPress/WooCommerce Integration	Standalone HTML embed + PHP wrapper	REST API for product data

Library CDN References (always use exact versions for stability)

Three.js r169 requires ESM import maps — the legacy UMD three.min.js bundle is no longer the recommended path. Use the module build with an importmap:

<!-- Import map — place before any <script type="module"> -->
<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.169.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.169.0/examples/jsm/"
  }
}
</script>

<!-- Then in your module script: -->
<script type="module">
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader }    from 'three/addons/loaders/GLTFLoader.js';
// CapsuleGeometry, WebGPURenderer — all available in r169
const capsule = new THREE.CapsuleGeometry(0.5, 1, 4, 8);
</script>

For WebGPU renderer (r169+):

<script type="importmap">
{
  "imports": {
    "three":        "https://cdn.jsdelivr.net/npm/three@0.169.0/build/three.webgpu.js",
    "three/webgpu": "https://cdn.jsdelivr.net/npm/three@0.169.0/build/three.webgpu.js",
    "three/tsl":    "https://cdn.jsdelivr.net/npm/three@0.169.0/build/three.tsl.js",
    "three/addons/":"https://cdn.jsdelivr.net/npm/three@0.169.0/examples/jsm/"
  }
}
</script>

GSAP 3.12:        https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js
GSAP ScrollTrigger: https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/ScrollTrigger.min.js
A-Frame 1.4:      https://aframe.io/releases/1.4.0/aframe.min.js
model-viewer:     https://ajax.googleapis.com/ajax/libs/model-viewer/3.3.0/model-viewer.min.js
Lottie Web:       https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js

---

Output Format Patterns

React / JSX (Claude.ai Artifacts)

• Use import * as THREE from 'three' (r169 — full ESM, all modern geometry available)
• Use useEffect + useRef for Three.js canvas lifecycle
• THREE.CapsuleGeometry is available natively — new THREE.CapsuleGeometry(radius, length, capSegments, radialSegments)
• GSAP via CDN script tag injected dynamically, or use CSS animations
• State management: useState/useReducer for experience phases (loading → explore → selected → cart)

Standalone HTML/CSS/JS

• Single-file unless complexity demands otherwise
• All CDN libs loaded in <head> with defer
• Canvas element as full-viewport layer, UI elements as absolute-positioned HTML overlay
• Use CSS custom properties for brand theming
• Mobile-first: touch events alongside mouse events always

WordPress / WooCommerce

• Deliver as a self-contained shortcode embed — PHP wrapper + enqueued scripts
• Use WooCommerce REST API (/wp-json/wc/v3/products) for live product data
• Inject product data as window.SKYYROSE_PRODUCT_DATA = <?php echo json_encode($product_data); ?>
• NEVER block the WordPress render thread — all 3D init must be async/deferred
• Provide both: (a) the shortcode PHP snippet, (b) the full HTML/JS embed file

For the SkyyRose flagship theme specifically, the CDN/importmap pattern above does NOT apply. That theme's real loading contract — three.js from jsdelivr via /+esm with NO importmap (a late importmap is rejected once the page has run a module script), self-hosted Draco decoder only, window.THREE gated behind a three-ready event — is documented and load-bearing in .claude/skills/skyyrose-wp-platform/reference/threejs-immersive.md. Read that file before writing any three.js code targeting this theme; it overrides this section. The wp-immersive agent owns the four template-immersive-*.php pages (Black Rose, Love Hurts, Signature, Kids Capsule) — route work there rather than duplicating scene logic here.

Any Other Language / Stack

• Identify the runtime, then output the canonical pattern for that environment
• Python (Flask/Django): Jinja2 templates + static JS bundles
• Vue/Svelte/Next.js: Component-based with the same Three.js lifecycle patterns
• Always document environment assumptions at the top of the file

---

Experience Type: 3D Product Viewer

Goal: Customer inspects the product from every angle before buying. Eliminates return anxiety. Builds confidence.

Architecture:

Canvas (Three.js WebGLRenderer)
├── Scene
│   ├── AmbientLight + DirectionalLight (3-point studio setup)
│   ├── ProductMesh (GLTF/OBJ/procedural geometry)
│   ├── EnvironmentMap (HDR or solid gradient)
│   └── ReflectionPlane (optional — adds luxury feel)
├── Camera (PerspectiveCamera, FOV 35-45 for product shots)
├── Controls (OrbitControls or custom drag handler)
└── UI Overlay (HTML)
    ├── Hotspot labels (position projected from 3D to 2D)
    ├── Color/variant switcher
    └── Add to Cart CTA

Lighting Setup for Fashion/Apparel:

// Studio 3-point lighting
const keyLight = new THREE.DirectionalLight(0xffffff, 1.2);
keyLight.position.set(5, 8, 5);

const fillLight = new THREE.DirectionalLight(0xB76E79, 0.4); // rose gold fill
fillLight.position.set(-5, 3, 2);

const rimLight = new THREE.DirectionalLight(0xffffff, 0.8);
rimLight.position.set(0, -3, -5); // backlight for fabric edge glow

const ambient = new THREE.AmbientLight(0x111111, 0.6);

Mobile Handling: Always implement touch-drag controls with touchstart/touchmove alongside mouse. Pinch-to-zoom via touchmove with two-finger distance delta.

---

Experience Type: Brand Showroom / 3D Environment

Goal: Customer enters a spatial world that IS the brand. Products are discovered, not listed.

Architecture Pattern:

Scene Graph
├── Environment (skybox or procedural background)
│   ├── Fog (THREE.FogExp2 for depth)
│   └── Background particles / atmospheric effects
├── Collection Zones (spatial groupings)
│   ├── Zone: BLACK ROSE → dark marble surfaces, moody spotlights
│   ├── Zone: LOVE HURTS → deep reds, cracked texture, emotional lighting
│   └── Zone: SIGNATURE → clean planes, neutral tones, editorial
├── Product Objects (instanced meshes for performance)
├── Navigation (raycasting on click/tap, camera lerp to target)
└── UI Layer
    ├── Minimap (optional for large environments)
    └── Product detail panel (slides in on selection)

Camera Movement:

// Smooth cinematic camera lerp — NEVER teleport, always glide
function lerpCamera(targetPosition, targetLookAt, duration = 1.2) {
  gsap.to(camera.position, {
    x: targetPosition.x,
    y: targetPosition.y,
    z: targetPosition.z,
    duration,
    ease: "power2.inOut",
    onUpdate: () => camera.lookAt(currentLookAt)
  });
}

Performance Budget:

• Max 50k triangles total scene for mobile
• Max 150k triangles for desktop
• Use THREE.InstancedMesh for repeated objects (particles, floor tiles)
• Texture atlasing: combine small textures into one 2048×2048 atlas
• Disable shadows on mobile: renderer.shadowMap.enabled = isMobile ? false : true

---

Experience Type: Virtual Try-On / AR Overlay

Goal: Customer sees the product on themselves or in their environment using the device camera.

Implementation Tiers (choose based on scope):

Tier 1: model-viewer AR Mode (simplest, iOS + Android)

<model-viewer
  src="product.glb"
  ar
  ar-modes="webxr scene-viewer quick-look"
  camera-controls
  auto-rotate
  shadow-intensity="1"
  environment-image="neutral"
  style="width:100%; height:500px;">
  <button slot="ar-button" class="ar-cta">View in Your Space</button>
</model-viewer>

Tier 2: WebXR Hit-Test (full AR placement)

• Requires HTTPS + WebXR-capable browser (Chrome Android, Safari 16+)
• Use navigator.xr.requestSession('immersive-ar', { requiredFeatures: ['hit-test'] })
• Render overlay anchored to real-world surface via hit-test matrix
• Always include a graceful fallback to Tier 1 or 3D viewer

Tier 3: MediaPipe Body Segmentation (garment overlay)

• Advanced: use @mediapipe/selfie_segmentation to isolate body
• Overlay product texture on segmented person silhouette
• GPU-accelerated via WebGL — frame rate critical, target 24fps minimum
• Provide detailed instructions: see references/ar-mediapipe.md

AR Trigger UX: Always show a clear "View in AR" CTA that feature-detects before launching:

async function checkARSupport() {
  if (!navigator.xr) return 'unsupported';
  const supported = await navigator.xr.isSessionSupported('immersive-ar');
  return supported ? 'webxr' : 'model-viewer-fallback';
}

---

Experience Type: Cinematic Collection Drop / Launch Page

Goal: A product drop feels like a movie premiere. Scroll = timeline. Every frame is intentional.

GSAP ScrollTrigger Architecture:

// Phase 1: Hero — product emerges from darkness
gsap.timeline({
  scrollTrigger: { trigger: "#hero", start: "top top", end: "+=100%", scrub: 1.5 }
})
.from(".product-hero", { scale: 0.6, opacity: 0, duration: 1 })
.from(".collection-name", { y: 120, opacity: 0, duration: 0.8 }, "-=0.4")
.from(".hero-particles", { opacity: 0, duration: 1.2 }, "-=0.6");

// Phase 2: Collection reveal — products stagger in
gsap.timeline({
  scrollTrigger: { trigger: "#collection", start: "top 80%", toggleActions: "play none none reverse" }
})
.from(".product-card", {
  y: 80, opacity: 0, stagger: 0.15, ease: "power3.out", : 
});


 and staggered character animations

Lottie Integration:

const anim = lottie.loadAnimation({
  container: document.getElementById('lottie-container'),
  renderer: 'svg',
  loop: false,
  autoplay: false,
  path: 'animation.json'
});
// Sync Lottie frame to scroll progress
ScrollTrigger.create({
  trigger: "#lottie-section",
  start: "top center",
  end: "bottom center",
  onUpdate: (self) => {
    anim.goToAndStop(self.progress * anim.totalFrames, true);
  }
});

---

SkyyRose Brand Integration

When building for SkyyRose, always:

Load: skyyrose-market:skyyrose-brand-dna SKILL.md alongside this skill for full brand context.

Pre-screened patterns: docs/design/visual-pattern-shortlist.md has 176 animation/visual patterns already cross-checked against this brand system, including a dedicated set tagged "Immersive Worlds scene work." Check there before improvising a pattern from scratch.

CDN loading: this is theme-dependent, not a blanket zero-CDN policy — the flagship WordPress theme actually loads three.js from jsdelivr (see the WordPress/WooCommerce section above and threejs-immersive.md); only the Draco decoder is self-hosted there. For other output targets, self-host under SKYYROSE_ASSETS_URI where the platform supports it. Don't assume either policy — check the target.

Spatial Brand Palette (canonical tokens — locked, do not invent alternates):

:root {
  --sr-void: #0A0A0A;          /* scene background / Dark */
  --sr-charcoal: #1C1C1C;      /* surfaces */
  --sr-smoke: #2D2D2D;         /* secondary surfaces */
  --sr-rose-gold: #B76E79;     /* accent lights, UI highlights — global + Kids Capsule */
  --sr-silver: #C0C0C0;        /* BLACK ROSE collection accent */
  --sr-crimson: #DC143C;       /* LOVE HURTS collection energy */
  --sr-gold: #D4AF37;          /* SIGNATURE collection accent */
  --sr-white: #F5F5F0;         /* typography, clean surfaces */
}

Per-Collection 3D Environments:

Collection	Environment	Light Color	Fog	Particle Effect
BLACK ROSE	Dark marble vault	#B76E79 rose gold key, #C0C0C0 silver rim	Dense black fog	Gold dust particles
LOVE HURTS	Fractured red glass space	#DC143C crimson fill, white backlight	Red mist	Ember/ash particles
SIGNATURE	Editorial white studio	#D4AF37 gold key, neutral 3-point	None	None
KIDS CAPSULE	Playful, launch-mode	#B76E79 rose gold (shared global accent)	None	Physics-based bouncing elements, not ambient particles

Product Interaction Sound Design (optional but impactful):

• Use Web Audio API for subtle UI sounds (no autoplay — always user-triggered)
• Soft chime on product selection, tactile click on variant switch

---

Performance Standards

Every immersive experience MUST meet these before delivery:

Metric	Target	Hard Limit
Initial load (3G)	< 4s to first render	< 8s
FPS (mobile)	30fps stable	Never drop below 20fps
FPS (desktop)	60fps stable	Never drop below 45fps
JS bundle (gzipped)	< 400KB	< 800KB
Texture memory	< 50MB	< 100MB
Lighthouse Performance	> 70	> 55

Optimization Checklist:

• Progressive loading: show 2D placeholder while 3D initializes
• renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)) — cap DPR
• Frustum culling enabled (default in Three.js, verify not disabled)
• geometry.dispose() + material.dispose() on unmount (React) or scene clear
• Texture compression: use .basis or .ktx2 for production GLTFs
• Use requestAnimationFrame loop only when canvas is visible (IntersectionObserver pause)

---

Accessibility & Fallback Architecture

Immersive experiences must be inclusive:

Experience Tiers:
1. Full 3D/AR       → WebGL + WebXR capable browsers
2. CSS 3D Fallback  → Modern browsers without WebGL (rare but real)
3. Static Fallback  → Accessible, screen-reader-friendly product page

Always implement:

• <noscript> block with product images and description
• aria-label on canvas: <canvas aria-label="Interactive 3D product viewer. Use arrow keys to rotate.">
• Keyboard controls for 3D rotation (arrow keys)
• Prefers-reduced-motion media query: disable all animations, show static scene

const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
if (prefersReduced) {
  // Skip GSAP timelines, show static scene
  gsap.globalTimeline.pause();
}

---

File Delivery Format

When delivering an immersive experience, always provide:

1. The primary file — fully functional, self-contained when possible
2. Integration notes — clear comments for WordPress shortcode, npm install, etc.
3. Asset checklist — what GLB/GLTF/texture files the developer needs to supply
4. Demo data — if no real assets provided, use procedural geometry + placeholder textures so the experience is fully runnable

For WordPress delivery, output two code blocks:

• experience.html — the full standalone experience
• functions.php snippet — enqueue + shortcode registration

---

Reference Files

Load these when you need deeper guidance on specific topics:

• references/three-js-patterns.md — Three.js boilerplate, geometry patterns, shader snippets
• references/gsap-scroll-patterns.md — ScrollTrigger timelines, SplitText, Lottie sync
• references/ar-mediapipe.md — MediaPipe body tracking integration guide
• references/woocommerce-3d-embed.md — WordPress/WooCommerce integration patterns

---

Quick-Start Templates

For common requests, scaffold from these mental templates:

"Build a 3D product viewer" → Three.js canvas + OrbitControls + studio lighting + HTML overlay CTA

"Create an immersive collection page" → GSAP ScrollTrigger multi-phase timeline + Three.js particle background + product cards with 3D entrance animations

"AR try-on for mobile" → model-viewer with ar attribute + WebXR hit-test upgrade path + graceful feature detection

"Brand showroom / 3D store" → Three.js environment + raycasting navigation + collection zone spatial layout + camera lerp transitions

"Drop launch page" → Cinematic GSAP countdown + particle burst on reveal + product hero with Three.js depth-of-field effect

Always begin with: What emotion should hit the visitor in the first 3 seconds? Then build backward from that feeling.