{Object.entries(variants).map(([name, preset]) => (
{children(preset)}
))}
)
}
```
### 2.2 Feature Flag로 모션 on/off
```typescript
// src/shared/lib/motion-feature-flags.ts
import { useFeatureFlag } from '@/shared/lib/feature-flags'
interface MotionConfig {
/** 전체 애니메이션 활성화 여부 */
animationsEnabled: boolean
/** 페이지 전환 애니메이션 */
pageTransitions: boolean
/** 마이크로 인터랙션 (hover, tap) */
microInteractions: boolean
/** 스크롤 애니메이션 */
scrollAnimations: boolean
/** Lottie 애니메이션 */
lottieAnimations: boolean
/** 로딩 스켈레톤 애니메이션 */
skeletonAnimations: boolean
}
export function useMotionConfig(): MotionConfig {
const animationsEnabled = useFeatureFlag('motion-enabled', true)
const pageTransitions = useFeatureFlag('motion-page-transitions', true)
const microInteractions = useFeatureFlag('motion-micro-interactions', true)
const scrollAnimations = useFeatureFlag('motion-scroll-animations', true)
const lottieAnimations = useFeatureFlag('motion-lottie', true)
const skeletonAnimations = useFeatureFlag('motion-skeleton', true)
return {
animationsEnabled,
pageTransitions: animationsEnabled && pageTransitions,
microInteractions: animationsEnabled && microInteractions,
scrollAnimations: animationsEnabled && scrollAnimations,
lottieAnimations: animationsEnabled && lottieAnimations,
skeletonAnimations: animationsEnabled && skeletonAnimations,
}
}
// Feature Flag 연동 모션 래퍼
export function useConditionalMotion(
flagKey: keyof MotionConfig,
animateProps: Record{name} (duration: {preset.duration}s, ease: {preset.ease})
Motion: {isReduced ? 'REDUCED' : 'FULL'}
)
}
```
---
## 3. 애니메이션 기술 비교
**일상 비유**: 카페에서 컵 그림을 그리는 방법과 같다. 칠판에 분필(CSS)은 빠르고 손쉽고, 종이에 펜(WAAPI)은 정밀 제어가 가능하며, 디지털 태블릿(GSAP/Timeline)은 정교한 시퀀스가 가능하지만 장비가 무겁다. 인스타용 짧은 영상(Lottie)은 사전 렌더링된 결과물에 가깝다.
이 그림은 사용 목적에 따라 어떤 애니메이션 기술을 골라야 하는지 결정 트리로 보여줍니다.
```mermaid
flowchart TD
Start[애니메이션 도입 결정] --> Q1{스크롤 연동?}
Q1 -->|Yes| Q1a{BaselineCSS Scroll-Driven 지원?} Q1a -->|Yes| CSS_SD[CSS Scroll-Driven] Q1a -->|No| IO[IntersectionObserver fallback] Q1 -->|No| Q2{페이지/라우트 전환?} Q2 -->|Yes| VT[View Transitions API
+ fallback] Q2 -->|No| Q3{React 컴포넌트
진입/퇴장?} Q3 -->|Yes| Q3a{복잡한 시퀀스/SVG?} Q3a -->|Yes| GSAP[Timeline lib
GSAP/Motion] Q3a -->|No| Motion[React motion lib] Q3 -->|No| Q4{단순 호버/전환?} Q4 -->|Yes| CSSA[CSS Animations/Transitions] Q4 -->|No| WAAPI[Web Animations API] ``` | 기술 | 적합 용도 | 번들 크기 | 성능 | 접근성 | 학습 곡선 | | -------------------------------- | --------------------------------- | ----------------- | ---- | ----------------- | --------- | | **CSS Animations** | 간단한 전환, 호버 | 0 KB | 최고 | 기본 지원 | 낮음 | | **CSS `linear()` easing** | 스프링 물리 곡선 | 0 KB | 최고 | 기본 지원 | 낮음 | | **Web Animations API** | JS 제어 필요한 경우 | 0 KB | 높음 | 수동 | 중간 | | **React motion library** | React 컴포넌트 애니메이션 | 라이브러리별 상이 | 높음 | 훅 제공 여부 확인 | 중간 | | **Timeline library** | 복잡한 타임라인, SVG, 정밀 제어 | 라이브러리별 상이 | 높음 | 수동 | 높음 | | **View Transitions L1** | SPA 페이지 전환 | 0 KB | 높음 | 브라우저 내장 | 낮음 | | **View Transitions L2 (MPA)** | 다중 페이지 전환 (cross-document) | 0 KB | 높음 | 브라우저 내장 | 낮음 | | **Vector animation renderer** | 일러스트/아이콘 애니메이션 | 렌더러별 상이 | 중간 | 수동 | 낮음 | | **Lightweight timeline library** | 경량 타임라인 | 라이브러리별 상이 | 높음 | 수동 | 낮음 | | **CSS Scroll-Driven** | 스크롤 연동 (Baseline 2025) | 0 KB | 최고 | 기본 지원 | 중간 | ### 선택 가이드 **일상 비유**: 시계의 째깍 소리(CSS)는 기계가 자동으로 내고, 음악 메트로놈(JS)은 사람이 박자를 직접 조절한다. 같은 60bpm을 내더라도 자동(CSS)이 배터리(메인스레드)를 덜 쓴다. 단, 사람이 박자를 도중에 바꾸려면 메트로놈(JS)이 필요하다. 이 그림은 CSS와 JS 애니메이션을 어떤 기준으로 나눠 쓸지 보여줍니다. ```mermaid flowchart LR Trigger[애니메이션 트리거] --> Q1{사용자 입력에
실시간 반응?} Q1 -->|Yes| Q2{값을 도중에
변경/일시정지?} Q1 -->|No| Q3{상태 전환만?} Q2 -->|Yes| JS[Web Animations API
또는 motion lib] Q2 -->|No| Q3 Q3 -->|Yes| CSS[CSS transition/animation] Q3 -->|No| Q4{스크롤/뷰포트?} Q4 -->|Yes| ScrollCSS[CSS scroll/view timeline] Q4 -->|No| CSS JS --> Budget[INP/long task 예산 검증] CSS --> Budget ScrollCSS --> Budget ``` ``` 간단한 호버/전환 → CSS Animations (JS 불필요) React 컴포넌트 진입/퇴장 → React motion library 페이지 전환 → View Transitions API (+ fallback) 스크롤 기반 → CSS scroll() / IntersectionObserver fallback 복잡한 시퀀스 → Timeline library 일러스트 애니메이션 → Vector animation renderer 스크롤 연동 (JS 없이) → CSS Scroll-Driven Animations ``` ### CSS Animations 기본 패턴 ```css /* GPU 가속 속성만 사용하는 애니메이션 */ /* 1. fadeInUp - 가장 범용적인 진입 애니메이션 */ @keyframes fadeInUp { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } } .animate-fade-in-up { animation: fadeInUp 0.3s ease-out both; } /* 2. 스켈레톤 로딩 - 콘텐츠 로드 전 시각적 피드백 */ @keyframes shimmer { from { transform: translateX(-100%); } to { transform: translateX(100%); } } .skeleton { position: relative; overflow: hidden; background: #e5e7eb; } .skeleton::after { content: ''; position: absolute; inset: 0; background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.4), transparent); animation: shimmer 1.5s infinite; } /* 3. 스핀 로더 - transform만 사용하여 GPU 가속 */ @keyframes spin { to { transform: rotate(360deg); } } .spinner { width: 24px; height: 24px; border: 2px solid #e5e7eb; border-top-color: #3b82f6; border-radius: 50%; animation: spin 0.6s linear infinite; } /* 4. 펄스 효과 - 주의를 끄는 인터랙션 */ @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } } .animate-pulse { animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite; } /* 5. reduced-motion 대응 - 반드시 포함 */ @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; scroll-behavior: auto !important; } } ``` ### Web Animations API 패턴 ```typescript // src/shared/lib/web-animations.ts // 네이티브 Web Animations API 유틸리티 (번들 0KB) interface AnimationOptions { duration?: number easing?: string fill?: FillMode delay?: number } /** fadeInUp 애니메이션 - 가장 범용적인 진입 효과 */ export function fadeInUp(element: HTMLElement, options: AnimationOptions = {}): Animation { const { duration = 300, easing = 'ease-out', fill = 'forwards', delay = 0 } = options return element.animate( [ { opacity: 0, transform: 'translateY(20px)' }, { opacity: 1, transform: 'translateY(0)' }, ], { duration, easing, fill, delay }, ) } /** stagger 패턴 - 자식 요소를 순차적으로 등장시킴 */ export function staggerChildren( container: HTMLElement, selector: string, options: AnimationOptions & { stagger?: number } = {}, ): Animation[] { const { stagger = 50, ...animOptions } = options const children = container.querySelectorAll
{/* 탭 헤더 */}
{tabs.find((t) => t.id === activeTab)?.content}
)
}
```
---
## 4. View Transitions API 실전 패턴
**일상 비유**: 뮤지컬 무대의 암전(snapshot)→세트 교체(DOM 변경)→조명 점등(animation)과 같다. 관객(사용자)은 깜빡임 없이 새 장면을 본다. 미지원 브라우저는 암전 없이 세트만 바뀌므로 fallback이 필요하다.
이 그림은 View Transitions API의 라이프사이클과 상태 전이를 보여줍니다.
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> CapturingOld: startViewTransition()
CapturingOld --> DomUpdate: snapshot 완료
DomUpdate --> CapturingNew: 콜백 실행
CapturingNew --> Animating: new snapshot 완료
Animating --> Finished: animation end
Animating --> Skipped: skipTransition()
Skipped --> Idle
Finished --> Idle
note right of CapturingOld
이전 화면 픽셀 저장
::view-transition-old(root)
end note
note right of CapturingNew
새 화면 픽셀 저장
::view-transition-new(root)
end note
```
이 그림은 호출자 코드와 브라우저가 View Transition을 어떻게 주고받는지 보여줍니다.
```mermaid
sequenceDiagram
participant U as 사용자
participant App as App 코드
participant VT as document.startViewTransition
participant DOM as DOM
participant Anim as Compositor
U->>App: 라우트/상태 변경
App->>VT: startViewTransition(callback)
VT->>DOM: 1) old snapshot 캡처
VT->>App: 2) callback 실행
App->>DOM: 3) DOM 업데이트
VT->>DOM: 4) new snapshot 캡처
VT->>Anim: 5) ::view-transition pseudo CSS 적용
Anim-->>U: 6) crossfade/morph 실행
Anim-->>App: transition.finished resolve
```
> **참고**: View Transitions API는 현재 공식 문서 기준 Chrome, Edge, Safari 18+에서 정식 지원되며, Firefox는 진행 중입니다(L1 부분 지원). 더 자세한 호환성 현황은 [13. 브라우저 호환성 가이드](./13_브라우저_호환성_가이드.md)에서 확인하세요.
>
> **Level 1 vs Level 2 차이**
>
> - **L1 (Same-Document)**: SPA 내에서 `document.startViewTransition()` 호출 -- 같은 문서 안에서 DOM 변경 전환.
> - **L2 (Cross-Document, 최신 안정화)**: MPA에서 `@view-transition { navigation: auto }` CSS 한 줄로 페이지 간 전환을 JS 없이 활성화. Next.js MPA 라우팅이나 Astro 같은 정적 페이지에서 즉시 활용 가능.
### Level 2 (Cross-Document) 최소 설정
```css
/* src/shared/styles/cross-document-transitions.css */
/* MPA -- HTML 페이지 간 자동 전환 */
@view-transition {
navigation: auto;
}
/* 페이지 공통 전환 -- crossfade */
::view-transition-old(root),
::view-transition-new(root) {
animation-duration: 300ms;
/* 현재 Baseline -- 스프링 물리는 CSS만으로 표현 가능 */
animation-timing-function: linear(
0,
0.045,
0.18,
0.4,
0.7,
1.025,
1.205,
1.3,
1.32,
1.3,
1.225,
1.135,
1.05,
0.985,
0.94,
0.92,
0.92,
0.935,
0.965,
1,
1.03,
1.045,
1.045,
1.035,
1.02,
1.01,
1,
0.995,
0.995,
1
);
}
/* 특정 요소만 morph -- 공유 요소 애니메이션 */
.product-hero {
view-transition-name: product-hero;
}
```
```html
```
> Cross-document 전환은 **동일 출처(same-origin)** 페이지 간에만 작동하며, `prefers-reduced-motion` 사용자에게는 자동으로 비활성화된다.
### useViewTransition 훅
```typescript
// src/shared/lib/use-view-transition.ts
import { useCallback, useRef } from 'react'
type TransitionType = 'crossfade' | 'slide-left' | 'slide-right' | 'scale' | 'none'
interface ViewTransitionOptions {
type?: TransitionType
duration?: number
}
interface ViewTransitionResult {
startTransition: (callback: () => void | Promise
{tabs.map((tab) => (
))}
{/* 탭 콘텐츠 */}
View Transitions
{logs.map((log, i) => (
)
}
```
---
## 5. 스크롤 기반 애니메이션
**일상 비유**: 도서관에서 책장을 따라 걸어갈 때 책 제목이 또렷해지는 경험 같다. CSS Scroll-Driven은 책장이 직접 조명을 켜는 방식(브라우저 합성)이고, IntersectionObserver fallback은 사서(JS)가 옆에 서서 알려주는 방식이다.
이 그림은 스크롤 애니메이션 기술을 어떤 순서로 시도하고 어디서 fallback할지 보여줍니다.
```mermaid
flowchart TD
Start[스크롤 연동 요구] --> Feat{Baseline
[{new Date(log.timestamp).toLocaleTimeString()}] {log.type} ({log.duration})
))}
animation-timeline?} Feat -->|Yes| CSS[CSS scroll/view timeline] Feat -->|No| IO{IntersectionObserver
지원?} IO -->|Yes| JS[IO 기반 reveal/parallax] IO -->|No| Static[정적 콘텐츠 유지
motion 생략] CSS --> RM{prefers-reduced-motion} JS --> RM RM -->|reduce| Static RM -->|no-preference| Verify[성능/회귀 검증] Static --> Verify ``` > **참고**: CSS Scroll-Driven Animations는 현재 공식 문서 기준 Chrome/Edge 115+, Safari 26+에서 정식 지원되며, Firefox 137부터 부분 지원이 시작되었습니다. 미지원 브라우저를 위해 IntersectionObserver 기반 JS 폴백을 함께 구현하세요. 성능 측정은 [08. 성능 최적화 가이드](./08_성능_최적화_가이드.md)를 참고합니다. > > **CSS `linear()` 스프링 물리 (최신 Baseline)** > 기존 `cubic-bezier`로 표현하기 어려운 스프링/바운스 곡선을 CSS만으로 구현 가능하다. JavaScript Spring physics 라이브러리 의존도를 크게 줄일 수 있다. > > ```css > /* 스프링 물리 -- React Spring 없이 CSS만으로 */ > .spring-in { > animation: spring-in 600ms forwards; > animation-timing-function: linear( > 0, > 0.009, > 0.035 2.1%, > 0.141, > 0.281 6.7%, > 0.723 12.9%, > 0.938 16.7%, > 1.017, > 1.077, > 1.121, > 1.149 24.3%, > 1.159, > 1.163, > 1.161, > 1.154 29.9%, > 1.129 32.8%, > 1.051 39.6%, > 1.017 43.1%, > 0.991, > 0.977 51%, > 0.974, > 0.975, > 0.991 65.5%, > 1 > ); > } > /* Scroll Timeline + linear() 조합 -- 스크롤에 스프링 반응 */ > .reveal-spring { > animation: reveal linear both; > animation-timeline: view(); > animation-range: entry 10% cover 40%; > animation-timing-function: linear(0, 0.5 30%, 0.95 60%, 1); > } > ``` ### CSS Scroll-Driven Animations (네이티브) ```css /* 프로그레스 바: CSS만으로 구현 (JS 불필요, 최고 성능) */ .scroll-progress { position: fixed; top: 0; left: 0; width: 100%; height: 3px; background: #3b82f6; transform-origin: left; animation: progress-bar linear; animation-timeline: scroll(root); /* 루트 스크롤에 연동 */ } @keyframes progress-bar { from { transform: scaleX(0); } to { transform: scaleX(1); } } /* 요소가 뷰포트를 통과하며 애니메이션 - view() 타임라인 */ .reveal-on-scroll { animation: reveal linear both; animation-timeline: view(); /* 요소의 뷰포트 가시성에 연동 */ animation-range: entry 10% cover 40%; /* 진입 10%~40% 구간에서 실행 */ } @keyframes reveal { from { opacity: 0; transform: translateY(40px); } to { opacity: 1; transform: translateY(0); } } /* 패럴랙스: CSS scroll()로 깊이감 표현 */ .parallax-layer { animation: parallax linear; animation-timeline: scroll(root); } @keyframes parallax { to { transform: translateY(-30%); } } /* 카드 스택 효과: 스크롤에 따라 카드가 겹치며 올라옴 */ .card-stack-item { animation: card-stack-reveal linear both; animation-timeline: view(); animation-range: entry 0% cover 50%; } @keyframes card-stack-reveal { from { opacity: 0; transform: translateY(100px) scale(0.9) rotateX(10deg); } to { opacity: 1; transform: translateY(0) scale(1) rotateX(0deg); } } /* 텍스트 하이라이트 진행: 스크롤 위치에 따라 텍스트 강조 */ .highlight-on-scroll { background: linear-gradient(to right, #fbbf24, #fbbf24) no-repeat; background-size: 0% 100%; animation: highlight-progress linear both; animation-timeline: view(); animation-range: entry 20% cover 60%; } @keyframes highlight-progress { to { background-size: 100% 100%; } } ``` ### React 스크롤 애니메이션 훅 ```typescript // src/shared/lib/use-scroll-animation.ts // IntersectionObserver 기반 스크롤 애니메이션 (모든 브라우저 지원) import { useEffect, useRef, useState, type RefObject } from 'react' interface ScrollAnimationOptions { threshold?: number // 요소가 얼마나 보여야 트리거 (0~1) rootMargin?: string // 뷰포트 마진 (조기/지연 트리거) once?: boolean // 한 번만 실행 여부 } export function useScrollAnimation
{/* SplitText 등으로 글자 분리 시 .char 클래스 부여 */} W e l c o m e
부제목 텍스트
예: total 4초 / frame drop 0] --> Hero[Hero 진입
0.8초 1회] Budget --> Micro[마이크로 인터랙션
0.1-0.3초 N회] Budget --> Page[페이지 전환
0.3-0.5초] Budget --> Scroll[스크롤 연동
지속·CSS scroll/view timeline] Hero --> Reserve[INP/long task
예산 50ms 남김] Micro --> Reserve Page --> Reserve Scroll --> Reserve Reserve --> Verify[Lighthouse/RUM
p75 검증] ``` > **참고**: 애니메이션 성능은 Core Web Vitals의 INP(Interaction to Next Paint)에 직접 영향을 줍니다. [08. 성능 최적화 가이드](./08_성능_최적화_가이드.md)의 INP 섹션을 함께 참고하세요. ### 성능 규칙 | 규칙 | 설명 | 위반 시 영향 | | ------------------------- | -------------------------------------------------------------------- | ----------------------------------- | | **GPU 속성만 애니메이션** | `transform`, `opacity`만 사용. `width`, `height`, `top`, `left` 금지 | 레이아웃 리플로우 발생, 프레임 드롭 | | **will-change 최소 사용** | 애니메이션 시작 직전 추가, 종료 후 제거 | 메모리 과다 소비, GPU 레이어 폭증 | | **contain 활용** | `contain: layout style paint`로 리플로우 격리 | 부모/형제 요소까지 리플로우 전파 | | **뷰포트 밖 정지** | IntersectionObserver로 보이지 않는 애니메이션 정지 | CPU/GPU 리소스 낭비 | | **requestAnimationFrame** | JS 애니메이션은 반드시 rAF 사용 | 프레임 타이밍 불일치, 쟁크 | | **composite 최적화** | Web Animations API의 `composite: 'add'` 활용 | 애니메이션 합성 비효율 | | **CSS 우선 원칙** | CSS로 가능한 것은 JS 미사용 | 메인 스레드 차단, 번들 사이즈 증가 | ### will-change 안전 사용 패턴 ```typescript // src/shared/lib/will-change-manager.ts // will-change를 안전하게 관리하는 유틸 (메모리 누수 방지) /** * will-change는 브라우저에 "곧 이 속성이 변경될 것"이라고 알려주는 힌트. * 남용하면 GPU 레이어가 과도하게 생성되어 오히려 성능 저하 발생. * 이 유틸은 애니메이션 직전에 추가하고 완료 후 자동 제거한다. */ export function applyWillChange( element: HTMLElement, properties: string[], durationMs: number = 1000, ): () => void { // will-change 속성 설정 element.style.willChange = properties.join(', ') // 지정 시간 후 자동 제거 (메모리 보호) const timerId = window.setTimeout(() => { element.style.willChange = 'auto' }, durationMs) // 수동 정리 함수 반환 return () => { window.clearTimeout(timerId) element.style.willChange = 'auto' } } /** * 호버/포커스 시에만 will-change 적용하는 이벤트 리스너 * 상시 will-change보다 메모리 효율적 */ export function applyWillChangeOnInteraction( element: HTMLElement, properties: string[], ): () => void { const handleEnter = (): void => { element.style.willChange = properties.join(', ') } const handleLeave = (): void => { element.style.willChange = 'auto' } element.addEventListener('mouseenter', handleEnter) element.addEventListener('mouseleave', handleLeave) element.addEventListener('focusin', handleEnter) element.addEventListener('focusout', handleLeave) return () => { element.removeEventListener('mouseenter', handleEnter) element.removeEventListener('mouseleave', handleLeave) element.removeEventListener('focusin', handleEnter) element.removeEventListener('focusout', handleLeave) element.style.willChange = 'auto' } } ``` ### 애니메이션 성능 모니터 (Preview 전용) ```typescript // src/shared/lib/animation-performance-monitor.ts import { envConfig } from '@/shared/config/environment' interface AnimationMetric { name: string fps: number droppedFrames: number duration: number } /** 애니메이션 실행 중 실시간 FPS를 측정하는 유틸 */ export function measureAnimationPerformance( name: string, durationMs: number = 1000, ): Promise
aria-hidden] Dec -->|Yes| Convert1[opacity-only
0.01ms] Kind -->|기능적| Func[duration 단축 후
최종 상태로 즉시 전환] Kind -->|상태 피드백| Feed[유지하되 짧게
aria-live=assertive] Disable --> Snapshot[Playwright screenshot
reducedMotion: reduce] Convert1 --> Snapshot Func --> Snapshot Feed --> Snapshot Snapshot --> Pass{회귀 없음?} Pass -->|Yes| Merge[PR 통과] Pass -->|No| Fix[fallback 재설계] Fix --> Kind ``` 이 그림은 접근성 검증이 모션 PR의 어디서 자동/수동으로 발생하는지를 보여줍니다. ```mermaid flowchart LR Dev[모션 구현] --> Lint[ESLint motion 규칙
토큰/속성/RM 분기] Lint --> Unit[단위 테스트
variants reduced 분기] Unit --> E2E[Playwright emulateMedia
reducedMotion reduce] E2E --> A11yScan[axe-core/Pa11y
focus/ARIA] A11yScan --> Manual[수동 키보드 smoke
탭/엔터/Esc] Manual --> Sign[A11y owner sign-off] ``` > **참고**: 접근성 관련 상세 가이드라인은 [19. 웹 접근성 가이드](./19_웹_접근성_가이드.md)를 참고하세요. 본 섹션은 애니메이션 특화 접근성에 집중합니다. ### 완전한 접근성 대응 ```typescript // src/shared/lib/motion-accessibility.ts import { type Variants } from 'motion/react' /** * reduced-motion 사용자를 위한 variant 생성 유틸 * 모든 애니메이션에 적용하여 일관된 접근성 보장 * * 사용 예시: * const { full, reduced } = createAccessibleVariants(myVariants); * const variants = prefersReduced ? reduced : full; */ export function createAccessibleVariants( fullMotion: Variants, reducedMotion?: Variants, ): { full: Variants; reduced: Variants } { // reduced-motion 기본값: opacity만 변경, transform 제거 const defaultReduced: Variants = {} for (const [key, value] of Object.entries(fullMotion)) { if (typeof value === 'object' && value !== null) { const v = value as Record
{isVisible && (
)
}
```
---
## 10. 모션 디자인 토큰 & 시스템 통합
> **참고**: 디자인 토큰 체계는 [20. 디자인 시스템 가이드](./20_디자인_시스템_가이드.md)의 토큰 섹션과 통합하여 사용합니다.
애니메이션의 일관성을 보장하기 위해 duration, easing, delay 등을 디자인 토큰으로 관리합니다. 하드코딩된 값 대신 토큰을 사용하면 전역 조정과 실험군 검증이 쉬워집니다.
**일상 비유**: 모든 직원이 회사 표준 시계(토큰)를 차도록 강제하면, 매장마다 다른 시간으로 회의를 잡는 일이 사라진다. 디자이너가 표준 시계의 분 단위를 바꾸면 전 매장이 동시에 따라간다.
이 그림은 디자인 토큰이 어디서 정의되고 어떤 경로로 코드/도구에 흘러 들어가는지 의존성을 보여줍니다.
```mermaid
flowchart TD
Source[Figma Tokens / DTCG] --> Build[Style Dictionary 빌드]
Build --> CSS["motion-tokens.css
{src.split('/').pop()} | {renderer} | {loop ? 'loop' : 'once'}
)}
@theme custom property"] Build --> TS["motion-tokens.ts
DURATION/EASE/STAGGER"] Build --> Tailwind["tailwind.config
animation utilities"] CSS --> ComponentCSS[CSS/SCSS 컴포넌트] TS --> Motion[motion/react variants] TS --> GSAP[GSAP timeline] Tailwind --> Class[Tailwind class 사용처] ComponentCSS --> Lint[ESLint no-hardcoded-duration] Motion --> Lint GSAP --> Lint Class --> Lint Lint --> PR[PR 게이트] ``` ### 모션 토큰 정의 ```css /* src/shared/styles/motion-tokens.css */ /* Tailwind v4 CSS-first 설정과 통합 */ @theme { /* ── Duration 토큰 ── */ --duration-instant: 0ms; /* 상태 변경 (즉시) */ --duration-fast: 100ms; /* 마이크로 인터랙션 (호버, 탭) */ --duration-normal: 200ms; /* 일반 전환 (토글, 드롭다운) */ --duration-slow: 300ms; /* 진입/퇴장 애니메이션 */ --duration-slower: 500ms; /* 페이지 전환, 모달 */ --duration-slowest: 800ms; /* 히어로 섹션, 랜딩 */ /* ── Easing 토큰 ── */ --ease-default: cubic-bezier(0.4, 0, 0.2, 1); /* Material 기본 */ --ease-in: cubic-bezier(0.4, 0, 1, 1); /* 가속 (퇴장) */ --ease-out: cubic-bezier(0, 0, 0.2, 1); /* 감속 (진입) */ --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1); /* 가속→감속 */ --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275); /* 바운스 느낌 */ --ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55); /* 강한 바운스 */ /* ── Stagger 토큰 ── */ --stagger-fast: 30ms; /* 리스트 아이템 */ --stagger-normal: 50ms; /* 카드 그리드 */ --stagger-slow: 80ms; /* 히어로 텍스트 */ } ``` ### TypeScript 모션 토큰 ```typescript // src/shared/config/motion-tokens.ts // CSS 토큰과 동기화된 TypeScript 상수 /** Duration 토큰 (초 단위 - Framer Motion 호환) */ export const DURATION = { instant: 0, fast: 0.1, normal: 0.2, slow: 0.3, slower: 0.5, slowest: 0.8, } as const /** Easing 토큰 */ export const EASE = { default: [0.4, 0, 0.2, 1] as const, in: [0.4, 0, 1, 1] as const, out: [0, 0, 0.2, 1] as const, inOut: [0.4, 0, 0.2, 1] as const, spring: { type: 'spring' as const, stiffness: 300, damping: 30 }, bounce: { type: 'spring' as const, stiffness: 500, damping: 25 }, } as const /** Stagger 토큰 (초 단위) */ export const STAGGER = { fast: 0.03, normal: 0.05, slow: 0.08, } as const /** * 토큰 기반 transition 생성 헬퍼 * 하드코딩 대신 토큰을 사용하여 일관성 보장 */ export function createTransition( duration: keyof typeof DURATION = 'normal', ease: keyof Omit