PixelPilot: Instructions file for GitHub Copilot

Spatial UI & 3D Web Experiences

Flat is dead. The web is going spatial. This file covers WebGPU, Three.js, 3D product viewers, depth-layered interfaces, and parallax that actually impresses — not the 2015 "background moves slower" kind.

---

CRITICAL RULES

1. Performance first — 3D must not tank mobile. Use LOD (level of detail), lazy-load models.
2. Graceful degradation — Always provide 2D fallback for unsupported browsers.
3. Accessibility — 3D viewers need keyboard controls, alt descriptions, reduced-motion fallback.
4. Design tokens — All colors, shadows, and UI overlays use tokens.

---

WHEN TO USE SPATIAL UI

Use Case	Recommended Approach
Product viewer (e-commerce)	Three.js + GLB model
Hero visual impact	CSS 3D transforms + depth layers
Data visualization	Three.js or WebGPU for large datasets
Interactive storytelling	Scroll-linked 3D scenes
Gaming/immersive	WebGPU (modern) or Three.js

Never use 3D for:

• Navigation menus
• Form inputs
• Text content
• Anything that needs to be accessible by default

---

THREE.JS PRODUCT VIEWER

// ProductViewer.tsx — React + Three.js + React Three Fiber
import { Canvas, useFrame } from '@react-three/fiber';
import { OrbitControls, useGLTF, Environment, ContactShadows } from '@react-three/drei';
import { Suspense, useRef } from 'react';

function Model({ url }: { url: string }) {
  const { scene } = useGLTF(url);
  const ref = useRef<THREE.Group>(null);
  
  // Respect reduced motion
  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
  
  useFrame((state) => {
    if (ref.current && !prefersReducedMotion) {
      // Subtle idle rotation
      ref.current.rotation.y = Math.sin(state.clock.elapsedTime * 0.3) * 0.1;
    }
  });

  return <primitive ref={ref} object={scene} scale={1} />;
}

function LoadingFallback() {
  return (
    <mesh>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color="var(--surface-2)" wireframe />
    </mesh>
  );
}

export function ProductViewer({ modelUrl, fallbackImage }: Props) {
  const supportsWebGL = !!document.createElement('canvas').getContext('webgl2');

  if (!supportsWebGL) {
    return (
      <div className="product-viewer-fallback">
        <img src={fallbackImage} alt="Product view" loading="lazy" />
        <p className="text-muted">3D view not supported in this browser</p>
      </div>
    );
  }

  return (
    <div className="product-viewer" role="img" aria-label="Interactive 3D product viewer. Use mouse to rotate, scroll to zoom.">
      <Canvas
        camera={{ position: [0, 0, 4], fov: 45 }}
        dpr={[1, 2]} // Limit pixel ratio for performance
      >
        <ambientLight intensity={0.5} />
        <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} />
        
        <Suspense fallback={<LoadingFallback />}>
          <Model url={modelUrl} />
          <Environment preset="studio" />
          <ContactShadows position={[0, -1, 0]} opacity={0.4} blur={2} />
        </Suspense>
        
        <OrbitControls 
          enablePan={false}
          minDistance={2}
          maxDistance={8}
          minPolarAngle={Math.PI / 4}
          maxPolarAngle={Math.PI / 2}
        />
      </Canvas>
      
      {/* Keyboard instructions for accessibility */}
      <div className="sr-only" aria-live="polite">
        Use arrow keys to rotate. Plus and minus to zoom.
      </div>
    </div>
  );
}