[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,101 @@
+---
+id: react-animation-performance
+title: React 애니메이션 — GPU 가속과 CSS 우선
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [react, animation, performance, transform, vibe-coding]
+tech_stack: { language: "TypeScript / Framer Motion / CSS", applicable_to: ["Web"] }
+applied_in: []
+aliases: [transform, will-change, requestAnimationFrame, framer-motion]
+---
+
+# React 애니메이션 성능
+
+> 60fps 의 비밀: **transform / opacity 만 애니메이션**. width / height / top / left 는 layout/paint trigger → jank. JS 로 setState 매 frame 도 안 됨.
+
+## 📖 핵심 개념
+- 브라우저 렌더 단계: JS → Style → Layout → Paint → Composite.
+- transform/opacity 는 Composite 만 쓰는 GPU layer — 다른 단계 skip.
+- React setState per frame = re-render 60회/초. 컴포넌트 트리에 따라 폭발.
+
+## 💻 코드 패턴
+
+### CSS 우선
+```css
+.modal {
+  transform: translateY(100%);
+  opacity: 0;
+  transition: transform 200ms ease-out, opacity 200ms ease-out;
+}
+.modal.open { transform: translateY(0); opacity: 1; }
+```
+
+### Framer Motion — declarative
+```tsx
+import { motion, AnimatePresence } from 'framer-motion';
+
+<AnimatePresence>
+  {open && (
+    <motion.div
+      initial={{ y: 100, opacity: 0 }}
+      animate={{ y: 0, opacity: 1 }}
+      exit={{ y: 100, opacity: 0 }}
+      transition={{ type: 'spring', stiffness: 300, damping: 30 }}
+    >
+      ...
+    </motion.div>
+  )}
+</AnimatePresence>
+```
+
+### 직접 ref + transform — React state 우회
+```tsx
+function DragBox() {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      // setState X — DOM 직접
+      if (ref.current) ref.current.style.transform = `translate(${e.clientX}px, ${e.clientY}px)`;
+    };
+    window.addEventListener('mousemove', onMove);
+    return () => window.removeEventListener('mousemove', onMove);
+  }, []);
+  return <div ref={ref} />;
+}
+```
+
+### will-change — 신중히
+```css
+.about-to-animate { will-change: transform; }
+/* 애니메이션 끝나면 제거. 영구 두면 메모리 부담 */
+```
+
+## 🤔 의사결정 기준
+| 효과 | 도구 |
+|---|---|
+| 단순 hover / focus | CSS transition |
+| 복잡 enter/exit + spring | Framer Motion |
+| Drag / gesture | react-use-gesture + useSpring 또는 useMotionValue |
+| Canvas / WebGL | requestAnimationFrame + 별도 라이브러리 (three.js) |
+| 프레임 단위 React state | ❌ — DOM 직접 또는 motion value |
+
+## ❌ 안티패턴
+- **width/height/top/left 애니메이션**: layout thrash. transform: scale / translate 로.
+- **per-frame setState**: 컴포넌트 트리 재렌더. ref + DOM 직접 또는 motion.
+- **will-change 영구 적용**: GPU 메모리. 애니메이션 시작 직전 추가, 끝나면 제거.
+- **거대 list 모두에 transition**: 스크롤 시 60fps 깨짐. visible 영역만.
+- **가속도 무한**: spring 계산 안 멈춤 → CPU. damping ≥ 10 권장.
+- **React.memo 없는 자식이 부모 animation state 받음**: 매 frame 재렌더.
+- **resize observer 안에 무거운 작업**: throttle / debounce.
+
+## 🤖 LLM 활용 힌트
+- "transform / opacity 만 애니메이션. layout 속성 금지" 강조.
+- per-frame 작업은 useRef + DOM 직접.
+
+## 🔗 관련 문서
+- [[React_Rendering_Optimization]]
+- [[React_Refs_Patterns]]