애니메이션 구축하기
이 저장소 (Asymmetric-al/core)
이 스킬은 Core의 디자인 엔지니어링 및 운영 모션 계약을 따른 후 웹 모션을 구현할 때 사용하세요. 업스트림 새로고침 후 이 오버레이를 조정한 다음 bun run skills:sync를 실행하세요.
트리거
- 웹 애니메이션, 전환 또는 마이크로 인터랙션을 구축하거나 재작성할 때.
- Expo/React Native(
animate-expo), 코드베이스 감사(improve-animations), 또는 엄격한 모션 전용 리뷰(review-animations)에는 사용하지 마세요.
워크플로우
docs/ai/skills/emil-design-engineering/SKILL.md와docs/ai/skills/anim/SKILL.md를 먼저 로드하세요.- 기존 Core 모션 토큰과 Base UI 프리미티브를 재사용하세요. 지속 시간, 이징을 포크하거나 Radix API를 도입하지 마세요.
packages/ui/styles/globals.css의 글로벌 베이스라인에 reduced-motion을 유지하세요.- 작업이 토스트, 드로어, 메뉴 또는 드롭다운을 필요로 한다면
@asym/ui/ Base UI를 재사용하세요. 사용자가 명시적으로 어떤 라이브러리를 사용할지 묻지 않는 한pick-ui-library를 호출하지 마세요.
체크리스트
- 애니메이션에 목적이 있으며 가능한 transform/opacity에 머물러 있습니다.
- Core 토큰, Base UI 및
anim이 설명적인 업스트림 값보다 우선합니다. - 공유 유틸리티와
@asym/lib/motion-presets가 새로운 타이밍 리터럴보다 선호됩니다.
구축 스킬입니다. 하나의 작업만 수행합니다: 모션 요청을 엄격한 리뷰를 통과할 구현으로 전환합니다. 코드베이스를 감사하지 않고(improve-animations), diff를 비평하지 않고(review-animations), 애니메이션 가능한 부분을 찾지 않고(find-animation-opportunities), React Native용으로 구축하지 않습니다(animate-expo).
운영 자세
당신은 스스로 애니메이션을 구축하는 시니어 디자인 엔지니어입니다. 기준은 Emil Kowalski의 애니메이션 철학입니다 — review-animations가 적용하는 동일한 기준입니다. 첫 번째 리뷰에서 통과할 수 있도록 작성하세요.
두 가지 실패 모드가 있으며, 첫 번째가 더 심각합니다:
- 애니메이션을 적용해서는 안 되는 것에 애니메이션을 적용하는 경우. 아래 게이트는 때로는 코드 한 줄도 생성하지 않기 위해 존재합니다. 그것은 성공이지, 회피가 아닙니다.
- 올바른 것을 잘못된 재료로 애니메이션하는 경우 — 진입에
ease-in,scale(0), 토스트에 keyframes, 드롭다운을 느리게 만드는 지속 시간.
모션 옵션을 메뉴로 제시하지 마세요. 결정을 내리고, 한 줄로 이유를 설명하고, 코드를 작성하세요.
엄격한 규칙
- 순서대로 시퀀스를 실행하세요. 1단계와 2단계가 모든 것을 결정합니다. 애니메이션 여부를 알기 전에 곡선을 찾지 마세요.
- 근사값 없음. 모든 곡선, 지속 시간 및 스프링 설정은 아래 표에서 가져옵니다. 익숙해 보인다고
cubic-bezier(0.4, 0, 0.2, 1)을 발명하지 마세요. - 코드베이스의 토큰을 확장하고, 포크하지 마세요.
--ease-out-soft또는 지속 시간 토큰이packages/ui/styles/globals.css에 이미 존재한다면 사용하세요. 병렬 시스템을 추가하는 것은 결함입니다. - Reduced motion과 호버 게이팅은 애니메이션과 함께 제공되며, 후속 작업이 아닙니다.
- 작동하는 가장 저렴한 도구. 페이드를 위해 모션 라이브러리를 설치하지 마세요.
구축 시퀀스
1. 이것이 전혀 애니메이션되어야 하는가?
| 빈도 | 결정 |
|---|---|
| 하루 100회 이상 (키보드 단축키, 명령 팔레트 토글) | 절대 애니메이션하지 않음. 여기서 중단. |
| 하루 수십 회 (호버 효과, 목록 탐색) | 거의 인지할 수 없을 정도로만 — 빠르고 미묘하거나 없음 |
| 가끔 (모달, 드로어, 토스트) | 표준 애니메이션 |
| 드물게 / 처음 (온보딩, 성공, 축하) | 여기에 즐거움 예산이 있음 |
키보드로 시작된 액션은 판단의 여지가 없이 자격을 상실시킵니다. Raycast에는 열기/닫기 애니메이션이 없습니다 — 하루에 수백 번 열리는 것에는 그것이 올바른 것입니다.
요청이 이 게이트를 통과하지 못하면, 명확히 말하고 애니메이션을 작성하지 마세요. 대신 비모션 대안(즉각적인 상태 변경, 정적 어포던스)을 제안하세요.
2. 목적은 무엇인가?
계속하기 전에 다음 단어 중 하나로 이름을 지정하세요:
- 피드백 — 인터페이스가 사용자의 입력을 받았음을 확인
- 공간 일관성 — 무언가가 어디서 왔는지 또는 어디로 갔는지 표시
- 상태 표시 — 상태 변경을 이해할 수 있게 함
- 급격한 변경 방지 — 그렇지 않으면 순간이동할 콘텐츠 연결
- 설명 — 무언가가 어떻게 작동하는지 시연 (마케팅/온보딩 전용)
- 즐거움 — 오직 드물게/처음 계층에서만 허용됨
이름을 못 정하겠나요? 구축하지 마세요. 자주 보이는 요소에서 "멋져 보여서"는 중단해야 할 이유입니다.
또한 기능을 확인하세요: 사용자가 읽거나 작업 중인 데이터는 스타일을 위해 움직이면 안 됩니다. 장식용 마우스 추적 효과는 은행 앱의 그래프가 아닌 마케팅 페이지에 속합니다.
3. 도구 선택 — 작동하는 가장 저렴한 것
아래로 내려가며; 첫 번째 맞는 것에서 멈추세요.
| 필요 | 도구 |
|---|---|
| 호버, 누름, 색상, 클래스나 속성으로 제어하는 상태 토글 | CSS 전환 |
| 마운트 시 진입 애니메이션, JS 상태 없음 | CSS @starting-style |
| 페이지 로딩 중에도 부드러움을 유지해야 하는 미리 결정된 모션 | CSS 애니메이션 (메인 스레드 외부에서 실행) |
| 프로그래매틱 제어, CSS 성능, 라이브러리 없음 | WAAPI (element.animate()) |
| 스프링, 레이아웃 애니메이션, 종료 애니메이션, 제스처 기반 값 | Motion (motion.dev) |
CSS 애니메이션은 부하 시 JS보다 우수합니다 — 메인 스레드 외부에서 실행되는 반면, requestAnimationFrame 기반 애니메이션은 브라우저가 로드, 스크립트 실행 또는 페인트하는 동안 프레임을 드롭합니다. 미리 결정된 모션에는 CSS를, 동적이고 중단 가능한 모션에는 JS를 사용하세요.
작업이 애니메이션보다는 컴포넌트 — 토스트, 드로어, 명령 메뉴, 드롭다운 — 를 필요로 한다면 @asym/ui와 Base UI를 재사용하세요. 사용자가 명시적으로 어떤 라이브러리를 사용할지 묻지 않는 한 pick-ui-library를 호출하지 마세요. 직접 만드는 것은 <div> 드롭다운과 포커스 관리 없음으로 끝나는 길입니다.
4. 속성 선택
transform및opacity만. 레이아웃과 페인트를 건너뛰고 GPU에서 실행됩니다.width/height/margin/padding/top/left는 세 가지 모두를 트리거합니다. (clip-path는 승인된 네 번째입니다 — RECIPES.md 참조.height는 transform 대안이 없는 아코디언에 한해 허용됩니다.)- 절대
scale(0)을 사용하지 마세요.scale(0.9–0.97)+opacity: 0에서 시작하세요. 현실 세계에서 아무것도 없는 곳에서 나타나는 것은 없습니다. - 팝오버, 드롭다운, 메뉴, 툴팁의 경우 트리거에
transform-origin— Base UI의var(--transform-origin). 모달은 예외입니다; 트리거에 고정되지 않으므로 중앙에 유지됩니다. translate()의 백분율은 요소 자체 크기에 상대적입니다 —translateY(100%)는 콘텐츠에 관계없이 자체 높이만큼 이동합니다. 하드코딩된 픽셀보다 선호합니다.- Motion에서
x,y,scale은 지원되는 독립적인 transform입니다. 성능이 좋습니다. 메인 스레드가 바쁠 때 애니메이션이 컴포지터에서 유지되어야 하는 경우에만 전체transform문자열을 사용하세요:
<motion.div animate={{ x: 100 }} />
<motion.div animate={{ transform: "translateX(100px)" }} />
- 부모의 CSS 변수에서 자식의 transform을 구동하지 마세요 — 모든 자식에 대해 스타일을 재계산합니다. 요소에 직접
transform을 설정하세요.
5. 이징 및 지속 시간 — 또는 스프링
이징, 결정 순서:
| 상황 | 이징 |
|---|---|
| 진입 또는 종료 | ease-out |
| 화면에서 이동 / 변형 | ease-in-out |
| 호버 / 색상 변경 | ease |
| 일정한 모션 (마키, 진행률) | linear |
| 기본 | ease-out |
UI에 절대 ease-in을 사용하지 마세요. 느리게 시작하여 사용자가 보고 있는 정확한 순간을 지연시킵니다. 200ms의 ease-out은 200ms의 ease-in보다 더 빠르게 느껴집니다.
내장 CSS 이징은 너무 약합니다. 다음을 사용하세요:
--ease-out-soft: cubic-bezier(
0.22,
1,
0.36,
1
); /* Core 토큰; UI에 강한 ease-out */
--ease-in-out-soft: cubic-bezier(
0.77,
0,
0.175,
1
); /* 화면 내 이동에 강한 ease-in-out */
--ease-drawer: cubic-bezier(
0.32,
0.72,
0,
1
); /* iOS 스타일 드로어 곡선 (Ionic) */
여기 없는 곡선이 필요하세요? easing.dev 또는 easings.co에서 가져오세요. 직접 만들지 마세요.
지속 시간:
| 요소 | 지속 시간 |
|---|---|
| 버튼 누름 피드백 | var(--duration-press) (120ms) |
| 툴팁, 작은 팝오버 | var(--duration-micro) (150ms) |
| 드롭다운, 선택 | var(--duration-standard) (220ms) |
| 모달 | var(--duration-modal) (220ms) |
| 드로어 | var(--duration-drawer) (320ms) |
| 마케팅 / 설명용 | 더 길 수 있음 |
UI 애니메이션은 300ms 미만으로 유지하세요. 180ms 드롭다운이 400ms 드롭다운보다 더 반응성이 좋게 느껴집니다.
대신 스프링을 사용하세요 모션이 드래그 + 관성, 살아있는 듯한 요소, 사용자가 중단하거나 되돌릴 수 있는 제스처, 또는 장식용 마우스 추적일 때:
{ type: "spring", duration: 0.5, bounce: 0.2 } // Apple 스타일 — 추론하기 쉬움
{ type: "spring", mass: 1, stiffness: 100, damping: 10 } // 전통적인 물리 — 더 많은 제어
바운스는 0.1–0.3으로 유지하고, 대부분의 UI에서 바운스를 피하세요 — 드래그-투-디스미스 및 장난기 있는 상호작용을 위해 예약하세요.
6. 중단 및 종료
- 빠르게 트리거되는 모든 것에는 전환을, keyframes가 아닌 — 토스트, 토글, 사용자가 1초에 두 번 발사할 수 있는 모든 것. 전환은 현재 값에서 재타겟팅합니다. keyframes는 0에서 다시 시작합니다.
- 제스처에는 스프링 — 중단을 통해 속도를 전달하기 때문입니다.
- 들어온 방식으로 나가세요. 아래에서 슬라이드 인하는 토스트는 아래로 나갑니다. 대칭 경로는 스와이프-투-디스미스가 직관적으로 느껴지게 만듭니다.
- 사용자가 결정하는 곳에서는 비대칭 타이밍. 의도적인 단계(홀드-투-컨펌 누름: 2s 선형)에서는 느리게, 시스템 응답(해제: 200ms ease-out)에서는 빠르게.
7. Reduced motion 및 포인터 게이팅
매번 애니메이션과 함께 제공됩니다.
@media (prefers-reduced-motion: reduce) {
.element {
animation: fade 0.2s ease;
} /* opacity/color 유지, transform 기반 모션 제거 */
}
@media (hover: hover) and (pointer: fine) {
.element:hover {
transform: scale(1.05);
} /* 터치는 탭 시 잘못된 호버를 발생시킴 */
}
const reduce = useReducedMotion();
const closedX = reduce ? 0 : "-100%";
Reduced motion은 더 적고 부드러운 애니메이션을 의미하며, 완전히 없애는 것이 아닙니다 — 이해를 돕는 전환은 유지하고, 이동 및 위치 변경은 제거하세요.
레시피
일반적인 경우(버튼 누름, 드롭다운, 툴팁, 모달, 드로어, 토스트, 아코디언, 스태거, 홀드-투-컨펌, 탭 표시기, 스크롤 리빌, 드래그-투-디스미스)에 대한 즉시 구축 가능한 구현은 RECIPES.md를 참조하세요. 요청이 해당 컴포넌트 중 하나와 일치할 때마다 로드하고, 빈 파일이 아닌 레시피에서 시작하세요.
절대 제공하지 말 것
완료하기 전에 자체 점검하세요. 각각은 review-animations에서 자동 차단 항목입니다:
| 절대 사용 금지 | 대신 |
|---|---|
transition: all | 정확한 속성 이름 지정 |
transform: scale(0) 진입 | scale(0.95) + opacity: 0 |
UI 요소에 ease-in | ease-out 또는 강한 사용자 정의 곡선 |
의도적인 애니메이션에 내장 ease-out | cubic-bezier(0.23, 1, 0.32, 1) |
| 키보드 단축키 또는 하루 100회 이상 액션에 애니메이션 | 애니메이션 없음 |
| 이유 없이 300ms 초과 UI 지속 시간 | 150–250ms |
트리거에 고정된 팝오버에서 transform-origin: center | var(--transform-origin) (모달은 예외) |
| 토스트, 토글, 빠르게 트리거되는 요소에 keyframes | CSS 전환 |
width/height/margin/padding/top/left 애니메이션 | transform / opacity |
부하 중 Motion x/y/scale 속성 | 전체 transform 문자열 |
게이팅되지 않은 :hover 모션 | @media (hover: hover) and (pointer: fine) |
prefers-reduced-motion 누락 | 더 부드러운 변형, 완전 제거는 아님 |
| 모든 것이 한 번에 진입 | 30–80ms 스태거 |
출력
코드를 작성하세요. 그런 다음, 최대 몇 줄로:
- 게이트 결과 — 빈도 계층과 명명된 목적. 요청에서 거부된 것이 있다면, 무엇과 이유를 말하세요.
- 재료 — 도구, 속성, 곡선, 지속 시간 또는 스프링 설정, 각각 한 줄씩.
- 감각 확인할 사항 — 결과가 코드로 판단할 수 없는 감각(크로스페이드, 스프링의 바운스, 진입 목록에서 opacity/height 균형)에 의존한다면, 말하고 확인 방법을 지시하세요: 2–5배 지속 시간이나 DevTools 애니메이션 검사기에서 재생, 프레임별 단계, 실제 기기에서 제스처 테스트, 다음 날 다시 확인.