Three.js Implementation Architect

Overview

Production-grade Three.js implementation skill for a professional development company. Designs and builds high-quality 3D experiences across client projects — configurators, scroll animations, viewers, hero scenes, visualizations — with clean architecture, cross-device performance, and modular code that integrates into existing production codebases.

Core priorities: Performance, maintainability, modular architecture, cross-device compatibility, production-ready code.

Critical rule: Never generate .md files for implementation or architecture. All output must be real code files. Never skip discovery or architecture phases before coding.

Workflow

Phase 0  ·  CODEBASE SCAN        →  Analyze project stack + existing 3D usage
Phase 1  ·  FEASIBILITY           →  Determine if Three.js is the right tool
Phase 2  ·  REQUIREMENTS          →  Interactive questions about the 3D feature
Phase 3  ·  ARCHITECTURE DESIGN   →  Design scene architecture before coding
Phase 4  ·  BUILD CONFIRMATION    →  Get approval before generating code
Phase 5  ·  CODE GENERATION       →  Produce modular, production-ready code
Phase 6  ·  REVIEW + LEARN        →  Capture feedback, update templates

---

Phase 0 — Codebase Scanner

Before doing anything, inspect the project. Use Glob/Grep/Read to detect:

Output a structured analysis:

 ──────────────────────────────────────────────────────────
  Phase 0  ·  PROJECT ANALYSIS
 ──────────────────────────────────────────────────────────
  Framework         :  [detected]
  Build system      :  [detected]
  Rendering         :  [SSR / SSG / CSR]
  Animation libs    :  [detected or none]
  State management  :  [detected or none]
  Mobile needs      :  [yes / no + details]
  SEO constraints   :  [yes / no + details]
  Existing Three.js :  [yes / no + details]
  Integration level :  [easy / moderate / complex]
 ──────────────────────────────────────────────────────────

---

Phase 1 — Feasibility Engine

Determine whether Three.js is the correct solution. Evaluate:

• Scene complexity + polygon count estimates
• GPU cost on desktop and mobile
• Bundle size impact (~150KB min for three.js core)
• SEO impact (canvas elements are not crawlable)
• Whether CSS/Canvas/Lottie/video would achieve the same result

Return one verdict:

If BETTER_ALTERNATIVE, suggest the specific alternative and why.

---

Phase 2 — Interactive Requirements

Use AskUserQuestion to gather requirements. Load with ToolSearch → select:AskUserQuestion first.

Question 1 — Feature type:

AskUserQuestion({
  questions: [
    {
      question: 'What type of 3D feature are we building?',
      header: '3D Feature Type',
      multiSelect: false,
      options: [
        {
          label: 'Product configurator',
          description: 'Users customize materials, parts, or options on a 3D model',
        },
        {
          label: 'Scroll animation',
          description: 'Camera or objects animate as the user scrolls the page',
        },
        {
          label: 'Interactive 3D viewer',
          description: 'Users orbit, zoom, and inspect a 3D model',
        },
        { label: 'Landing page hero', description: 'Animated 3D scene as a visual centerpiece' },
        {
          label: 'Data visualization',
          description: '3D charts, graphs, or spatial data rendering',
        },
        { label: 'Other', description: 'Architecture rendering, simulation, or custom 3D UI' },
      ],
    },
  ],
})

Question 2 — Adaptive follow-ups (ask in one batch, skip confirmed answers):

AskUserQuestion({
  questions: [
    {
      question: 'Will users interact with the 3D model?',
      header: 'Interaction',
      multiSelect: false,
      options: [
        {
          label: 'Yes — orbit, click, drag',
          description: 'Users control camera or select objects',
        },
        {
          label: 'Scroll-driven only',
          description: 'Animation tied to scroll position, no direct interaction',
        },
        { label: 'View only', description: 'Passive display, no user interaction' },
      ],
    },
    {
      question: 'Do 3D models already exist?',
      header: 'Assets',
      multiSelect: false,
      options: [
        { label: 'Yes — GLB/glTF', description: 'Optimized format, ready to load' },
        { label: 'Yes — FBX/OBJ', description: 'Need conversion to GLB for web' },
        {
          label: 'No models yet',
          description: 'Geometry will be created in code or models need to be sourced',
        },
      ],
    },
    {
      question: 'What lighting style?',
      header: 'Lighting',
      multiSelect: false,
      options: [
        { label: 'Realistic / PBR', description: 'Environment maps, physically-based materials' },
        { label: 'Stylized / artistic', description: 'Flat shading, toon, custom materials' },
        { label: 'Minimal', description: 'Simple ambient + directional, performance-first' },
      ],
    },
    {
      question: 'Must this run smoothly on mobile?',
      header: 'Mobile',
      multiSelect: false,
      options: [
        { label: 'Yes — mobile-first', description: 'Must hit 60fps on mid-range phones' },
        { label: 'Yes — acceptable', description: '30fps on mobile is fine, 60fps on desktop' },
        { label: 'Desktop only', description: 'No mobile support needed' },
      ],
    },
  ],
})

---

Phase 3 — Architecture Design

Before generating code, design the scene architecture. Output:

 ──────────────────────────────────────────────────────────
  Phase 3  ·  SCENE ARCHITECTURE
 ──────────────────────────────────────────────────────────

  Scene Management  :  [single scene / scene graph / multi-scene]
  Camera System     :  [perspective / orthographic / system details]
  Lighting          :  [setup description]
  Model Pipeline    :  [GLTFLoader + Draco / procedural / hybrid]
  Texture Strategy  :  [compressed / atlas / lazy-loaded]
  Animation         :  [GSAP / Three.js Clock / AnimationMixer]
  Scroll Integration:  [ScrollTrigger / IntersectionObserver / none]
  UI Sync           :  [React state / events / custom bridge]
  Performance Plan  :  [specific optimizations]

  File Structure
  ├── [file 1]  —  [purpose]
  ├── [file 2]  —  [purpose]
  └── [file N]  —  [purpose]
 ──────────────────────────────────────────────────────────

For detailed architecture patterns, see references/architecture-patterns.md.

---

Phase 4 — Build Confirmation

Use AskUserQuestion before writing any code:

AskUserQuestion({
  questions: [
    {
      question: 'Architecture approved. How should I generate the code?',
      header: 'Build Mode',
      multiSelect: false,
      options: [
        {
          label: 'Full production code (Recommended)',
          description: 'Complete implementation with all optimizations',
        },
        { label: 'Modular components', description: 'Standalone modules I can integrate myself' },
        { label: 'Prototype first', description: 'Quick working version, optimize later' },
        {
          label: 'Highly optimized production',
          description:
            'Maximum performance — LOD, instancing, compressed textures, adaptive resolution',
        },
      ],
    },
  ],
})

Only begin coding after confirmation.

---

Phase 5 — Code Generation

Generate real code files only. Never markdown documentation.

All generated code must include:

• Clean modular structure with single-responsibility files
• Clear comments explaining non-obvious decisions
• Mobile-safe rendering (pixel ratio clamping, resize observers)
• Optimized asset loading (lazy, progressive, cached)
• Responsive scene sizing (ResizeObserver, not window.resize)
• Minimal GPU overhead (dispose calls, render-on-demand when possible)

File naming by stack:

For performance optimization patterns, see references/performance-patterns.md. For asset pipeline details, see references/asset-pipeline.md.

---

Phase 6 — Review + Learn

After implementation, use AskUserQuestion:

AskUserQuestion({
  questions: [
    {
      question: 'How did the implementation work out?',
      header: 'Review',
      multiSelect: false,
      options: [
        { label: 'Worked perfectly', description: 'No issues — template this pattern' },
        { label: 'Needed small fixes', description: "Minor adjustments — I'll describe them" },
        {
          label: 'Major issues',
          description: 'Architecture or performance problems — needs rework',
        },
      ],
    },
  ],
})

If fixes are reported, analyze: incorrect assumptions, architecture flaws, performance issues, asset pipeline issues. Update internal patterns for future use.

Self-Learning Storage

After each implementation, append to ~/.claude/skills/threejs-architect/logs/implementations.jsonl:

{
  "timestamp": "ISO-8601",
  "project_id": "sha256_of_path[:8]",
  "feature_type": "configurator | scroll | viewer | hero | viz | other",
  "stack": { "framework": "", "build": "", "state": "" },
  "scene_type": "",
  "models_format": "glb | fbx | procedural",
  "lighting": "pbr | stylized | minimal",
  "mobile": true,
  "build_mode": "full | modular | prototype | optimized",
  "review": "perfect | small-fixes | major-issues",
  "fixes_applied": [],
  "files_generated": [],
  "performance_techniques": [],
  "template_candidate": ""
}

When a feature_type + stack combination has 3+ successful implementations, enable one-shot mode: skip Phase 2 questions, present architecture directly, ask only for build confirmation.

---

Scene Type Detection

Automatically detect scene type from description and route to the right architecture:

For reusable scene templates, see references/scene-templates.md.

---

Common Mistakes

---

Quick Reference — Dependencies