Skip to content

notque/vexjoy-agent / skills/frontend/frontend

frontend

Unverified

Frontend: UI design, distinctive visual styles, HTML artifacts, Three.js 3D, TypeScript/React/Next.js apps, e-commerce, portfolios, React Native, web performance.

FileKindSize
SKILL.mdskill md22.5 KB
SPEC.mdmarkdown4.3 KB
agents/html-builder.mdmarkdown5.9 KB
assets/base-template.htmlother495 B
references/design-refs/accessibility-review.mdmarkdown13.0 KB
references/design-refs/design-critique.mdmarkdown10.4 KB
references/design-refs/design-handoff.mdmarkdown9.9 KB
references/design-refs/design-systems.mdmarkdown9.3 KB
references/design-refs/llm-design-failure-modes.mdmarkdown9.1 KB
references/design-refs/ux-copy.mdmarkdown9.5 KB
references/distinctive-frontend-design-refs/animation-patterns.mdmarkdown10.5 KB
references/distinctive-frontend-design-refs/background-techniques.mdmarkdown10.5 KB
references/distinctive-frontend-design-refs/balatro-shader-breakdown.mdmarkdown14.9 KB
references/distinctive-frontend-design-refs/card-shader-patterns.mdmarkdown10.9 KB
references/distinctive-frontend-design-refs/color-inspirations.jsonconfig9.4 KB
references/distinctive-frontend-design-refs/css-audit-patterns.mdmarkdown4.7 KB
references/distinctive-frontend-design-refs/font-catalog.jsonconfig9.7 KB
references/distinctive-frontend-design-refs/game-ui-polish.mdmarkdown6.3 KB
references/distinctive-frontend-design-refs/honest-placeholders.mdmarkdown3.2 KB
references/distinctive-frontend-design-refs/implementation-examples.mdmarkdown7.7 KB
references/distinctive-frontend-design-refs/macrostructure-catalog.mdmarkdown9.3 KB
references/distinctive-frontend-design-refs/oklch-color-harmony.mdmarkdown7.3 KB
references/distinctive-frontend-design-refs/performance-budgets.mdmarkdown10.6 KB
references/distinctive-frontend-design-refs/phase-details.mdmarkdown4.8 KB
references/distinctive-frontend-design-refs/pptx-conversion.mdmarkdown9.7 KB
references/distinctive-frontend-design-refs/roll-text.mdmarkdown7.2 KB
references/distinctive-frontend-design-refs/shader-integration-react.mdmarkdown16.7 KB
references/distinctive-frontend-design-refs/slide-controller.mdmarkdown9.4 KB
references/distinctive-frontend-design-refs/text-animation-patterns.mdmarkdown4.3 KB
references/html-artifact-refs/design-system.mdmarkdown10.2 KB
references/html-artifact-refs/diagram-layering.mdmarkdown3.9 KB
references/html-artifact-refs/infographic-layouts.mdmarkdown4.9 KB
references/html-artifact-refs/pdf-export.mdmarkdown6.0 KB
references/html-artifact-refs/pptx-export.mdmarkdown10.2 KB
references/html-artifact-refs/shape-diagram-illustration.mdmarkdown4.3 KB
references/nextjs-ecommerce.mdmarkdown3.4 KB
references/nextjs-ecommerce/admin-dashboard.mdmarkdown9.8 KB
references/nextjs-ecommerce/error-catalog.mdmarkdown7.9 KB
references/nextjs-ecommerce/expertise.mdmarkdown5.1 KB
references/nextjs-ecommerce/patterns-and-errors.mdmarkdown4.6 KB
references/nextjs-ecommerce/preferred-patterns.mdmarkdown8.0 KB
references/nextjs-ecommerce/shopping-cart-patterns.mdmarkdown7.7 KB
references/nextjs-ecommerce/stripe-integration.mdmarkdown9.5 KB
references/performance-optimization.mdmarkdown9.9 KB
references/performance-optimization/browser-dom-optimizations.mdmarkdown6.0 KB
references/performance-optimization/bundle-optimization.mdmarkdown7.9 KB
references/performance-optimization/core-web-vitals.mdmarkdown9.6 KB
references/performance-optimization/js-algorithm-optimizations.mdmarkdown9.6 KB
references/performance-optimization/metrics-and-monitoring.mdmarkdown8.8 KB
references/performance-optimization/nextjs-optimization.mdmarkdown10.6 KB
references/performance-optimization/performance-testing.mdmarkdown9.6 KB
references/performance-optimization/preferred-patterns.mdmarkdown7.4 KB
references/performance-optimization/react-async-patterns.mdmarkdown7.0 KB
references/performance-optimization/react-bundle-optimization.mdmarkdown6.3 KB
references/performance-optimization/react-rendering-performance.mdmarkdown12.0 KB
references/react-native.mdmarkdown4.4 KB
references/react-native/animation-patterns.mdmarkdown3.9 KB
references/react-native/error-handling.mdmarkdown7.7 KB
references/react-native/list-performance.mdmarkdown5.4 KB
references/react-native/monorepo-config.mdmarkdown2.3 KB
references/react-native/navigation-patterns.mdmarkdown2.0 KB
references/react-native/rendering-patterns.mdmarkdown3.2 KB
references/react-native/state-management.mdmarkdown3.3 KB
references/react-native/testing.mdmarkdown6.2 KB
references/react-native/ui-patterns.mdmarkdown5.0 KB
references/react-portfolio.mdmarkdown7.7 KB
references/react-portfolio/gallery-patterns.mdmarkdown2.5 KB
references/react-portfolio/image-optimization.mdmarkdown3.4 KB
references/react-portfolio/lightbox-patterns.mdmarkdown6.1 KB
references/react-portfolio/nextjs-app-router.mdmarkdown4.9 KB
references/react-portfolio/performance.mdmarkdown3.9 KB
references/react-portfolio/portfolio-seo.mdmarkdown4.8 KB
references/react-portfolio/responsive-design.mdmarkdown3.3 KB
references/threejs-builder-refs/advanced-animation.mdmarkdown12.1 KB
references/threejs-builder-refs/advanced-topics.mdmarkdown11.0 KB
references/threejs-builder-refs/build-recipes.mdmarkdown7.4 KB
references/threejs-builder-refs/game-architecture.mdmarkdown10.4 KB
references/threejs-builder-refs/game-patterns.mdmarkdown12.5 KB
references/threejs-builder-refs/gltf-loading.mdmarkdown8.6 KB
references/threejs-builder-refs/performance-patterns.mdmarkdown11.8 KB
references/threejs-builder-refs/react-three-fiber.mdmarkdown17.8 KB
references/threejs-builder-refs/shader-patterns.mdmarkdown15.0 KB
references/threejs-builder-refs/visual-polish.mdmarkdown16.3 KB
references/threejs-builder-refs/webgpu.mdmarkdown20.4 KB
references/typescript-frontend.mdmarkdown5.3 KB
references/typescript-frontend/engineering-rules.mdmarkdown7.8 KB
references/typescript-frontend/nextjs-security.mdmarkdown2.6 KB
references/typescript-frontend/react-view-transitions.mdmarkdown5.4 KB
references/ui-design.mdmarkdown10.2 KB
references/ui-design/ai-slop-detection.mdmarkdown8.5 KB
references/ui-design/design-conventions.mdmarkdown2.8 KB
references/ui-design/motion-and-interaction.mdmarkdown5.6 KB
scripts-distinctive-frontend-design/css_slop_rules.pyscript15.3 KB
scripts-distinctive-frontend-design/tests/test_css_slop_rules.pyscript6.9 KB
scripts-distinctive-frontend-design/tests/test_validate_design_advisory.pyscript3.3 KB
scripts-distinctive-frontend-design/tests/test_validate_design_macro.pyscript4.3 KB
scripts-distinctive-frontend-design/validate_design.pyscript22.2 KB
scripts-html-artifact/assemble-template.pyscript7.5 KB
scripts-html-artifact/css_slop_rules.pyscript15.4 KB
scripts-html-artifact/detect-shape.pyscript7.0 KB
scripts-html-artifact/fill-template.pyscript5.5 KB
scripts-html-artifact/pptx-bridge/__init__.pyscript490 B
scripts-html-artifact/pptx-bridge/_pptx_engine.pyscript26.4 KB
scripts-html-artifact/pptx-bridge/extract_slides.pyscript13.5 KB
scripts-html-artifact/pptx-bridge/render_pptx.pyscript6.9 KB
scripts-html-artifact/pptx-bridge/run-unified.pyscript11.6 KB
scripts-html-artifact/render-github-issues.pyscript7.5 KB
scripts-html-artifact/tests/test_assemble_template.pyscript29.5 KB
scripts-html-artifact/tests/test_css_slop_emission.pyscript7.9 KB
scripts-html-artifact/tests/test_detect_shape.pyscript5.3 KB
scripts-html-artifact/tests/test_fill_template.pyscript5.2 KB
scripts-html-artifact/tests/test_to_pdf.pyscript13.3 KB
scripts-html-artifact/tests/test_validate_artifact.pyscript13.6 KB
scripts-html-artifact/to-pdf.pyscript12.5 KB
scripts-html-artifact/validate-artifact.pyscript11.0 KB
templates/base-reset.cssother1.2 KB
templates/components/collapsible.cssother1.1 KB
templates/components/collapsible.jsscript516 B
templates/components/copy-button.cssother534 B
templates/components/copy-button.jsscript334 B
templates/components/drag-drop.cssother612 B
templates/components/drag-drop.jsscript1.1 KB
templates/components/filter.cssother1.1 KB
templates/components/filter.jsscript987 B
templates/components/keyboard-nav.cssother249 B
templates/components/keyboard-nav.jsscript900 B
templates/components/scrollytelling.cssother1.5 KB
templates/components/scrollytelling.jsscript2.0 KB
templates/components/slider.cssother848 B
templates/components/tabs.cssother770 B
templates/components/tabs.jsscript508 B
templates/components/theme-toggle.cssother1.2 KB
templates/components/theme-toggle.jsscript178 B
templates/fonts/ArchivoBlack-OFL.txtmarkdown4.4 KB
templates/fonts/archivo-black.cssother13.7 KB
templates/print/code-review-print.cssother1.9 KB
templates/print/data-viz-print.cssother1.5 KB
templates/print/deck-print.cssother1.5 KB
templates/print/default-print.cssother1.6 KB
templates/print/diagram-print.cssother1.6 KB
templates/print/editor-print.cssother2.1 KB
templates/print/prototype-print.cssother1.4 KB
templates/print/report-print.cssother1.8 KB
templates/print/spec-print.cssother1.4 KB
templates/saved/README.mdmarkdown1.8 KB
templates/saved/business-review.htmlother17.1 KB
templates/saved/business-review.slots.jsonconfig1.5 KB
templates/saved/github-issues.htmlother34.0 KB
templates/saved/project-kickoff.htmlother17.3 KB
templates/saved/project-kickoff.slots.jsonconfig1.7 KB
templates/saved/system-design.htmlother16.9 KB
templates/saved/system-design.slots.jsonconfig1.6 KB
templates/shapes/code-review.cssother2.7 KB
templates/shapes/data-viz.cssother2.3 KB
templates/shapes/deck.cssother1.9 KB
templates/shapes/diagram.cssother2.7 KB
templates/shapes/editor.cssother2.8 KB
templates/shapes/prototype.cssother2.7 KB
templates/shapes/report.cssother2.9 KB
templates/shapes/spec.cssother3.0 KB
templates/themes/birchline.cssother2.4 KB
templates/themes/dark-focus.cssother2.6 KB
templates/themes/interactive-warm.cssother4.5 KB
templates/themes/minimal-document.cssother2.6 KB

references/threejs-builder-refs/react-three-fiber.md

View on GitHub
# React Three Fiber (R3F) Reference

Paradigm-specific reference for building 3D applications with React Three Fiber.
Load this file when the project uses `@react-three/fiber`, Drei, or any React-based 3D setup.

---

## Core Architecture

R3F wraps Three.js in a declarative React layer. Every Three.js object becomes a JSX element.
The mental model shift: you don't call `new THREE.Mesh()` — you render `<mesh>`.

### Project Setup

```bash
npm create vite@latest my-3d-app -- --template react-ts
cd my-3d-app
npm install three @react-three/fiber @react-three/drei
npm install -D @types/three
```

**Key packages and when to use them:**

| Package | Purpose | Always Install? |
|---------|---------|-----------------|
| `three` | Core Three.js | Yes |
| `@react-three/fiber` | React renderer for Three.js | Yes |
| `@react-three/drei` | Helper components (OrbitControls, Text, Environment, etc.) | Yes — almost always needed |
| `@react-three/postprocessing` | Post-processing effects (Bloom, SSAO, etc.) | When effects needed |
| `zustand` | State management for game/interactive state | When complex state needed |
| `leva` | Debug GUI controls | During development |
| `@react-three/rapier` | Physics (Rapier WASM) | When physics needed |

### Canvas Component

Every R3F app starts with `<Canvas>`, which creates the WebGL renderer, scene, and default camera:

```tsx
import { Canvas } from '@react-three/fiber'

function App() {
  return (
    <Canvas
      camera={{ position: [0, 2, 5], fov: 50 }}
      gl={{ antialias: true, toneMapping: THREE.ACESFilmicToneMapping }}
      shadows
    >
      <Scene />
    </Canvas>
  )
}
```

**Canvas props that matter:**
- `camera` — set position and fov here, not inside the scene (avoids re-creation on re-render)
- `gl` — renderer options; `antialias: true` and tone mapping are common defaults
- `shadows` — enables shadow maps (still need `castShadow`/`receiveShadow` on objects)
- `dpr` — device pixel ratio; `[1, 2]` caps at 2x for performance
- `frameloop="demand"` — only render when state changes (for static scenes or manual invalidation)

---

## Component Patterns

### Basic Mesh

```tsx
function Box({ position }: { position: [number, number, number] }) {
  const meshRef = useRef<THREE.Mesh>(null!)

  useFrame((state, delta) => {
    meshRef.current.rotation.x += delta
  })

  return (
    <mesh ref={meshRef} position={position}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color="orange" />
    </mesh>
  )
}
```

**Key pattern**: geometry and material are children of `<mesh>`, not props. The `args` prop maps to constructor arguments. `<boxGeometry args={[1, 1, 1]} />` = `new THREE.BoxGeometry(1, 1, 1)`.

### Lighting Setup

```tsx
function Lighting() {
  return (
    <>
      <ambientLight intensity={0.4} />
      <directionalLight
        position={[10, 10, 5]}
        intensity={1}
        castShadow
        shadow-mapSize={[2048, 2048]}
      />
    </>
  )
}
```

**R3F dash notation**: `shadow-mapSize` sets `light.shadow.mapSize`. This works for any nested property: `position-x={5}` sets `mesh.position.x = 5`.

---

## Camera Controls — The #1 R3F Pitfall

This is the most common source of bugs in R3F projects. OrbitControls and custom camera controllers **conflict silently** — both try to update the camera every frame, causing jitter, locked cameras, or unexpected behavior.

### Decision Tree

```
Do you need the user to orbit/pan/zoom freely?
  YES → Use OrbitControls from drei
  NO → Does the camera follow a target or path?
    YES → Use useFrame + refs for custom camera
    NO → Set camera position on <Canvas> and leave it static
```

### OrbitControls (user-controlled camera)

```tsx
import { OrbitControls } from '@react-three/drei'

// Inside Canvas:
<OrbitControls
  enableDamping
  dampingFactor={0.05}
  minDistance={2}
  maxDistance={20}
  maxPolarAngle={Math.PI / 2}  // Prevent looking below ground
/>
```

**When to use**: Product viewers, 3D model inspectors, sandbox scenes where the user explores freely.

### Custom Camera Controller (app-controlled camera)

```tsx
function CameraController({ target }: { target: THREE.Vector3 }) {
  useFrame((state) => {
    // Smoothly move camera to follow target
    state.camera.position.lerp(
      new THREE.Vector3(target.x, target.y + 5, target.z + 10),
      0.05
    )
    state.camera.lookAt(target)
  })
  return null
}
```

**When to use**: Games, guided experiences, cinematic sequences, any scene where the app decides camera position.

### Single Camera Controller Per Scene

```tsx
// BAD: OrbitControls + custom camera = conflict
<OrbitControls />
<CameraController target={playerPos} />
```

Both components write to the camera every frame. OrbitControls overwrites the custom position, or vice versa, depending on execution order. The result is a frozen or jittering camera. **Pick one approach per scene.**

If you need both (e.g., orbit in menu, follow in gameplay), conditionally render only one:

```tsx
{gameState === 'menu' ? <OrbitControls /> : <CameraController target={playerPos} />}
```

---

## useFrame — The Animation Loop

`useFrame` is R3F's equivalent of `requestAnimationFrame`. It runs every frame inside the React reconciler.

```tsx
useFrame((state, delta) => {
  // state.clock — THREE.Clock
  // state.camera — the active camera
  // state.mouse — normalized mouse position [-1, 1]
  // state.scene — the THREE.Scene
  // delta — time since last frame in seconds
  meshRef.current.rotation.y += delta * 0.5
})
```

### useFrame Rules

| Do | Don't | Why |
|----|-------|-----|
| Mutate refs (`meshRef.current.rotation.y += delta`) | Set React state (`setPosition(...)`) | State triggers re-render; refs don't. Re-renders in useFrame = 60 re-renders/sec = frozen app |
| Use `delta` for time-based animation | Use fixed increments (`+= 0.01`) | Fixed increments run faster on high-refresh displays |
| Create vectors/objects outside useFrame | Create `new THREE.Vector3()` inside useFrame | Allocations inside the loop cause GC pauses every few seconds |
| Access `state.clock.elapsedTime` for absolute time | Track your own timer | The clock is already there and synchronized |

### Pre-allocating Vectors

```tsx
// GOOD: allocate once, reuse in frame loop
const tempVec = useMemo(() => new THREE.Vector3(), [])

useFrame(() => {
  tempVec.set(target.x, target.y + 2, target.z + 5)
  meshRef.current.position.lerp(tempVec, 0.1)
})
```

```tsx
// BAD: allocates every frame (60 allocations/sec)
useFrame(() => {
  const targetPos = new THREE.Vector3(target.x, target.y + 2, target.z + 5)
  meshRef.current.position.lerp(targetPos, 0.1)
})
```

---

## Post-Processing

R3F post-processing uses `@react-three/postprocessing`, which wraps the `postprocessing` library (not Three.js's built-in EffectComposer — the `postprocessing` npm package is significantly more performant).

### Setup

```bash
npm install @react-three/postprocessing postprocessing
```

### Bloom (Makes Emissive Materials Glow)

Bloom is what makes emissive materials actually visible as glowing. Without bloom, `emissiveIntensity` just makes the surface brighter — it doesn't produce the glow halo effect.

```tsx
import { EffectComposer, Bloom } from '@react-three/postprocessing'

function Effects() {
  return (
    <EffectComposer>
      <Bloom
        luminanceThreshold={0.9}
        luminanceSmoothing={0.025}
        intensity={1.5}
        mipmapBlur
      />
    </EffectComposer>
  )
}

// Material that glows:
<meshStandardMaterial
  color="#ff6600"
  emissive="#ff6600"
  emissiveIntensity={2}
  toneMapped={false}  // Required for bloom to pick up the HDR value
/>
```

**Critical**: `toneMapped={false}` on the material is required for bloom. Without it, the renderer clamps emissive values to [0,1] before the bloom pass sees them, and nothing glows.

### Common Effects

```tsx
import { EffectComposer, Bloom, ChromaticAberration, Vignette, SSAO } from '@react-three/postprocessing'

<EffectComposer>
  <Bloom luminanceThreshold={0.9} intensity={1.5} mipmapBlur />
  <ChromaticAberration offset={[0.002, 0.002]} />
  <Vignette eskil={false} offset={0.1} darkness={1.1} />
  <SSAO radius={0.05} intensity={15} />
</EffectComposer>
```

**Effect order matters** — effects run in the order they appear in the JSX. Bloom should generally come first (operates on HDR values), then color effects, then vignette (screen-space overlay).

---

## Drei Helper Components

`@react-three/drei` provides 100+ helper components. Here are the most commonly needed:

### Environment and Lighting

```tsx
import { Environment, ContactShadows, Sky } from '@react-three/drei'

// HDR environment for reflections + ambient light
<Environment preset="city" />  // presets: apartment, city, dawn, forest, lobby, night, park, studio, sunset, warehouse

// Soft contact shadows on a ground plane
<ContactShadows position={[0, -0.5, 0]} opacity={0.4} blur={2} />

// Procedural sky
<Sky sunPosition={[100, 20, 100]} />
```

### Text

```tsx
import { Text, Text3D } from '@react-three/drei'

// 2D billboard text (always faces camera)
<Text fontSize={0.5} color="white" anchorX="center" anchorY="middle">
  Hello World
</Text>

// 3D extruded text (needs a font JSON)
<Text3D font="/fonts/helvetiker_regular.typeface.json" size={0.75} height={0.2}>
  Hello
  <meshStandardMaterial color="gold" />
</Text3D>
```

### Loading Models

```tsx
import { useGLTF, Clone } from '@react-three/drei'

function Model({ url }: { url: string }) {
  const { scene } = useGLTF(url)
  return <Clone object={scene} />
}

// Preload for no loading flash:
useGLTF.preload('/models/robot.glb')
```

**Use `<Clone>`** instead of `<primitive object={scene} />` when you need multiple instances — `primitive` reuses the same Three.js object (can only appear once in the scene graph), while `Clone` creates a deep copy.

### Other Essential Drei Components

| Component | Purpose |
|-----------|---------|
| `<Html>` | Embed HTML/CSS inside the 3D scene (follows 3D position) |
| `<Float>` | Gentle floating animation on children |
| `<PresentationControls>` | Drag-to-rotate for product viewers (alternative to OrbitControls) |
| `<RoundedBox>` | Box with rounded edges |
| `<Center>` | Auto-center children in the scene |
| `<useTexture>` | Load textures with suspense |
| `<Instances>` / `<Instance>` | Declarative instanced meshes |
| `<Sparkles>` | Particle sparkle effect |
| `<Stars>` | Starfield background |
| `<Grid>` | Configurable ground grid |

---

## State Management with Zustand

For interactive or game-like R3F apps, use Zustand for state. It works seamlessly with R3F because both use refs and subscriptions, not React re-renders.

```tsx
import { create } from 'zustand'

interface GameState {
  score: number
  playerPosition: [number, number, number]
  incrementScore: () => void
  setPlayerPosition: (pos: [number, number, number]) => void
}

const useGameStore = create<GameState>((set) => ({
  score: 0,
  playerPosition: [0, 0, 0],
  incrementScore: () => set((state) => ({ score: state.score + 1 })),
  setPlayerPosition: (pos) => set({ playerPosition: pos }),
}))
```

### Reading State in useFrame Without Re-renders

```tsx
function Player() {
  const meshRef = useRef<THREE.Mesh>(null!)

  useFrame(() => {
    // Direct subscription — no re-render
    const pos = useGameStore.getState().playerPosition
    meshRef.current.position.set(...pos)
  })

  return <mesh ref={meshRef}><boxGeometry /><meshStandardMaterial /></mesh>
}
```

**Key pattern**: Use `getState()` inside `useFrame`, not the hook's return value. The hook triggers re-renders; `getState()` reads the latest value without triggering React's reconciler.

### UI Overlay Reading State

```tsx
function HUD() {
  const score = useGameStore((state) => state.score)
  return <div className="hud">Score: {score}</div>
}
```

For UI components that render outside `<Canvas>`, use the normal Zustand hook — re-renders are fine for DOM elements.

---

## Performance Patterns

### Instanced Meshes

When rendering 100+ identical objects, use instancing:

```tsx
import { Instances, Instance } from '@react-three/drei'

function Particles({ count = 1000 }) {
  const particles = useMemo(() =>
    Array.from({ length: count }, () => ({
      position: [
        (Math.random() - 0.5) * 20,
        (Math.random() - 0.5) * 20,
        (Math.random() - 0.5) * 20,
      ] as [number, number, number],
      scale: Math.random() * 0.5 + 0.1,
    })),
    [count]
  )

  return (
    <Instances limit={count}>
      <sphereGeometry args={[1, 8, 8]} />
      <meshStandardMaterial color="#88ccff" />
      {particles.map((p, i) => (
        <Instance key={i} position={p.position} scale={p.scale} />
      ))}
    </Instances>
  )
}
```

### Geometry and Material Reuse

```tsx
// GOOD: Define geometry/material once, use in multiple meshes
const sharedGeo = useMemo(() => new THREE.BoxGeometry(1, 1, 1), [])
const sharedMat = useMemo(() => new THREE.MeshStandardMaterial({ color: 'orange' }), [])

return (
  <>
    <mesh geometry={sharedGeo} material={sharedMat} position={[0, 0, 0]} />
    <mesh geometry={sharedGeo} material={sharedMat} position={[2, 0, 0]} />
    <mesh geometry={sharedGeo} material={sharedMat} position={[4, 0, 0]} />
  </>
)
```

### Performance Monitoring

```tsx
import { Perf } from 'r3f-perf'

// Inside Canvas, during development only:
<Perf position="top-left" />
```

### Common Performance Killers

| Problem | Detection | Fix |
|---------|-----------|-----|
| State updates in useFrame | Search for `useState` or `set` calls inside `useFrame` | Use refs instead of state for per-frame mutations |
| Geometry allocation in render | Search for `new THREE.` inside `useFrame` or component body without `useMemo` | Allocate once with `useMemo`, mutate in `useFrame` |
| Too many draw calls | r3f-perf shows draw call count > 200 | Use `<Instances>`, merge static geometries, use LOD |
| Large textures | GPU memory > 500MB | Compress textures (KTX2), use `useTexture` with responsive sizes |
| Shadow map too large | Frame time spikes | Cap `shadow-mapSize` at `[1024, 1024]` unless close-up detail needed |
| Re-rendering entire scene | React DevTools shows frequent renders | Memoize components, use refs for animation, isolate state consumers |

---

## Common Patterns to Detect and Fix

### 1. Mixing Imperative and Declarative

```tsx
// BAD: Imperative Three.js inside R3F
useEffect(() => {
  const geometry = new THREE.BoxGeometry(1, 1, 1)
  const material = new THREE.MeshStandardMaterial({ color: 'red' })
  const mesh = new THREE.Mesh(geometry, material)
  scene.add(mesh)  // Manual scene manipulation
  return () => { scene.remove(mesh) }
}, [])

// GOOD: Declarative R3F
<mesh>
  <boxGeometry args={[1, 1, 1]} />
  <meshStandardMaterial color="red" />
</mesh>
```

R3F manages the scene graph. Manual `scene.add()` bypasses React's reconciler and causes orphaned objects, missing cleanup, and state desync.

### 2. useEffect for Animation

```tsx
// BAD: useEffect + requestAnimationFrame
useEffect(() => {
  let id: number
  function animate() {
    id = requestAnimationFrame(animate)
    meshRef.current.rotation.y += 0.01
  }
  animate()
  return () => cancelAnimationFrame(id)
}, [])

// GOOD: useFrame
useFrame((_, delta) => {
  meshRef.current.rotation.y += delta
})
```

`useFrame` is managed by R3F's render loop. Using `requestAnimationFrame` directly creates a separate loop that's not synchronized with R3F's renderer, causing double-renders and timing issues.

### 3. Heavy Computation in Components

```tsx
// BAD: Recalculates on every render
function Terrain() {
  const vertices = generateTerrain(1000, 1000)  // Expensive!
  return <mesh><bufferGeometry>...</bufferGeometry></mesh>
}

// GOOD: Memoize expensive computations
function Terrain() {
  const vertices = useMemo(() => generateTerrain(1000, 1000), [])
  return <mesh><bufferGeometry>...</bufferGeometry></mesh>
}
```

### 4. Forgetting Suspense for Asset Loading

```tsx
// BAD: No loading state — white flash or error
function App() {
  return (
    <Canvas>
      <Model url="/heavy-model.glb" />
    </Canvas>
  )
}

// GOOD: Suspense boundary with fallback
function App() {
  return (
    <Canvas>
      <Suspense fallback={<LoadingIndicator />}>
        <Model url="/heavy-model.glb" />
      </Suspense>
    </Canvas>
  )
}

function LoadingIndicator() {
  return (
    <mesh>
      <sphereGeometry args={[0.5, 16, 16]} />
      <meshBasicMaterial color="#666" wireframe />
    </mesh>
  )
}
```

`useGLTF`, `useTexture`, and other loaders throw promises (React Suspense). Without a `<Suspense>` boundary, the app crashes.

---

## Error Handling

### Error: "R3F: Canvas is not allowed to have children that aren't THREE elements"
Cause: Regular HTML elements inside `<Canvas>` (e.g., `<div>`, `<p>`)
Solution: Use `<Html>` from drei to embed HTML, or place HTML outside the Canvas.

### Error: "Cannot read properties of null (reading 'rotation')"
Cause: Ref accessed before mount, or conditional rendering removed the mesh
Solution: Add null check in useFrame: `if (!meshRef.current) return`

### Error: Objects appear but no lighting/all black
Cause: Missing lights in the scene, or using `MeshStandardMaterial` without any light source
Solution: Add `<ambientLight intensity={0.5} />` and a directional light. Or use `<Environment>` from drei.

### Error: Model loads but is invisible
Cause: Model scale is extremely small or large relative to camera, or model is at a distant position
Solution: Use drei's `<Center>` component, or compute bounding box and adjust camera.

### Error: Controls feel laggy or jittery
Cause: OrbitControls + custom camera controller both active, or state updates causing re-renders during orbit
Solution: Use only one camera control method. Check for useState calls triggered by mouse events.

### Error: Post-processing bloom has no visible effect
Cause: `toneMapped` is not set to `false` on emissive materials, or `emissiveIntensity` is too low
Solution: Set `toneMapped={false}` on the material AND increase `emissiveIntensity` above 1.0.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall