서문 (먼저 실행)
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRY: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"page-load-animations","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"page-load-animations","phase":"build","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
true
fi
TEL_PROMPTED 값이 no인 경우: 스킬 워크플로우를 시작하기 전에 사용자에게 텔레메트리에 대해 질문하세요.
AskUserQuestion을 사용하세요:
superstack 개선에 도움을 주세요! 어떤 스킬이 사용되는지, 얼마나 오래 걸리는지 추적합니다 — 코드, 파일 경로, 개인 식별 정보는 수집하지 않습니다.
~/.superstack/config.json에서 언제든지 변경 가능합니다.
옵션:
- A) 네, superstack 개선에 도움 (익명)
- B) 아니요, 괜찮습니다
A 선택 시, 다음 bash를 실행:
echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted
B 선택 시, 다음 bash를 실행:
echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted
이 작업은 한 번만 수행됩니다. TEL_PROMPTED가 yes이면 이 과정을 완전히 건너뛰고 스킬 워크플로우로 진행합니다.
잘못된 스킬인가요? SKILL_ROUTER.md에서 모든 사용 가능한 스킬을 확인하세요.
페이지 로드 애니메이션
전투에서 검증된 framer-motion 레시피에서 가져온 패턴입니다. 원래 영감: suzi-ux-motions.
페이지 로딩이 혼란스럽지 않고 의도적으로 느껴지도록 만드는 프로덕션 framer-motion 레시피입니다. 이 스킬이 존재하는 이유는 크립토 UI에서 가장 흔한 애니메이션 문제가 애니메이션의 부재가 아니라, 안무, 스태거, 스프링 물리 없이 모든 것이 동시에 나타나기 때문입니다. 코드가 정확하더라도 결과물이 버벅거리는 느낌을 줍니다.
이 스킬은 구현 레시피를 제공합니다. 애니메이션 이론(언제 애니메이션을 적용할지, 지속 시간 계층, 이징 곡선, 모션 감소)은 frontend-design-guidelines/references/animation.md를 참조하세요. 이 스킬은 모든 기본 제약 조건을 상속합니다.
권한 모델
animation.md= 기본 제약 조건 (지속 시간 계층, 이징, 모션 감소, GPU 속성)- 이 스킬 = 해당 제약 조건 내에서 구현하는 프로덕션 레시피
frontend-design-guidelines는 framer-motion 패턴에 대해 이 스킬에 위임하며, 그 반대는 아닙니다.
설정
npm install framer-motion
간단한 상태 변경에는 CSS 전환이 기본값입니다 (animation.md에 따라). 스프링 물리, 오케스트레이션된 시퀀스, AnimatePresence 종료 애니메이션, 제스처/드래그, 또는 공유 레이아웃 전환이 필요할 때 framer-motion을 사용하세요.
이 스킬을 실행해야 하는 경우
다음과 같은 경우 언제든지 이 레시피를 적용하세요:
- 여러 섹션을 로드하는 페이지 구축 시 (대시보드, 상세 화면, 랜딩 페이지)
- 마운트 시 리스트, 카드 그리드, 또는 테이블을 스태거할 때
- 모달, 드롭다운, 또는 팝오버를 애니메이션할 때
- 콘텐츠가 변경되고 높이가 변하는 탭 또는 필터를 전환할 때
- 실시간으로 업데이트되는 숫자, 차트, 또는 도넛 그래프를 표시할 때
- 호버 피드백, 쉐브론 회전, 또는 툴팁 진입을 추가할 때
- 기존 framer-motion 코드를 안티패턴 검토할 때
- 사용자가 "페이지가 버벅거려요" 또는 "모든 것이 한꺼번에 나타나요"라고 말할 때
페이지 레벨 컴포넌트를 구축 중이고 이 스킬이 아직 트리거되지 않았다면, 직접 트리거하세요.
워크플로우
애니메이션 코드를 작성하기 전에, 관련 참조 파일을 식별하고 읽으세요:
- 페이지 로드 진입 오케스트레이션 → references/page-choreography.md
- 리스트 또는 카드 그리드 스태거 → references/list-stagger.md
- 모달, 드롭다운, 또는 팝오버 애니메이션 → references/popups-modals.md
- 높이 변화가 있는 탭/필터 전환 → references/filter-transitions.md
- 숫자 롤링, 차트 모핑, 도넛 차트 → references/live-data.md
- 버튼 피드백, 쉐브론 회전, 툴팁 → references/hover-micro.md
- 스프링 프리셋 또는 이징 곡선 조회 → references/spring-presets.md
필요한 것만 로드하세요. 모든 참조를 미리 읽지 마세요.
모드 1: 새 애니메이션 구축
- 필요한 패턴에 대해 관련 참조 파일(들)을 읽으세요.
- ASCII 스토리보드 주석으로 시작하세요 — 코드를 작성하기 전에 전체 시퀀스를 계획하세요.
- 모든 지연에 대해 명명된 상수가 포함된 TIMING 객체를 정의하세요.
- 참조의 패턴을 사용하여 구현하세요. 기본적으로 스프링 물리를 사용하세요.
- 완료 보고 전에 아래의 '필수 사항'을 확인하세요.
모드 2: 기존 애니메이션 코드 검토
- 일반적인 안티패턴을 스캔하세요:
# 부모와 자식 모두에 layout prop (버벅임 원인) grep -rn "layout" --include="*.tsx" --include="*.jsx" | head -20 # AnimatePresence와 함께 사용된 staggerChildren (신뢰할 수 없음) grep -rn "staggerChildren" --include="*.tsx" --include="*.jsx" | head -10 # transition-all (의도하지 않은 속성 애니메이션) grep -rn "transition-all\|transition: all" --include="*.tsx" --include="*.css" | head -10 # 모션 감소 처리 누락 grep -rn "motion\.\|animate=" --include="*.tsx" -l | while read f; do grep -L "reduced-motion\|useReducedMotion\|motion-safe" "$f"; done | head -10 - 발견된 각 문제에 대해 관련 참조 파일의 특정 안티패턴 규칙을 참조하세요.
- 정확한 코드 패치를 제공하세요.
모드 3: 빠른 조회
사용자가 "X를 위한 스프링 설정은?" 또는 "Y를 어떻게 애니메이션하나요?"라고 묻는다면, 전체 워크플로우를 실행하지 않고 참조 파일과 스프링 프리셋에서 직접 답변하세요.
필수 사항
- ASCII 스토리보드 주석. 모든 애니메이션 페이지는 전체 시퀀스를 한눈에 보여주는 타임라인 주석으로 시작합니다. 시간은 마운트 시점부터 절대값이며 오른쪽 정렬됩니다.
- 명명된 타이밍 상수. 모든 지연은 파일 상단의 TIMING 객체에 들어갑니다.
setTimeout또는delayprop에 매직 넘버를 사용하지 마세요. - 스프링 우선. 자연스럽고 인터럽트 가능한 모션을 위해 지속 시간 기반 이징보다 스프링 물리를 선호하세요. 페이드 및 툴팁에만 지속 시간을 사용하세요.
- 스테이지 기반 시퀀싱. 단일 정수 상태로 다중 섹션 시퀀스를 구동합니다. 분산된 불리언 플래그를 사용하지 마세요.
stage >= N패턴. 섹션은 한 번 나타나면 계속 보입니다. 절대stage === N을 사용하지 마세요.- 절대 부모와 자식 모두에
layout을 사용하지 마세요. 이것이 버벅거리는 필터 애니메이션의 1순위 원인입니다. 대신ResizeObserver와 함께AnimatedHeight를 사용하세요. - 절대
AnimatePresence와 함께staggerChildren을 사용하지 마세요. 신뢰할 수 없습니다. 수동delay: i * stagger를 사용하세요. prefers-reduced-motion을 존중하세요.animation.md에서 상속됩니다. 모든 애니메이션은 우아하게 저하되어야 합니다.- 마운트와 업데이트 구분. 마운트 애니메이션은 극적입니다 (600ms, 표현적인 이징). 업데이트 애니메이션은 미묘합니다 (150ms, 부드러운 이징). 다른 단계, 다른 설정.
디자인 원칙
- 스토리보드 우선 — 코드 작성 전에 시퀀스 계획
- 스프링 우선 — 지속 시간 기반 이징보다 스프링 물리
- 명명된 상수 — 모든 타이밍 값은 선언되며 인라인이 아님
- 스테이지 기반 — 단일 정수 상태가 복잡한 시퀀스를 오케스트레이션
- 데이터 기반 — 반복 요소는 인덱스 기반 지연으로
.map()을 사용, 복사-붙여넣기 블록 금지 - 측정, 추측 금지 — 동적 높이는
ResizeObserver사용, 하드코딩된 픽셀 높이 금지
다른 스킬과의 통합
frontend-design-guidelines— 일반 UI 스킬. framer-motion 작업을 이 스킬에 위임합니다. 둘 다 실행될 때,animation.md기본 규칙은 제약 조건에 대해 권위가 있고, 이 스킬은 구현 레시피에 대해 권위가 있습니다.number-formatting— 실시간 업데이트 숫자 표시의 경우, 형식 지정 사양은number-formatting을, 롤링 숫자 애니메이션 패턴은 이 스킬을 사용하세요.brand-design— 브랜드 색상은 애니메이션 색상 선택에 영향을 줄 수 있습니다 (긍정/부정 표시기, 강조 하이라이트).
리소스
references/
- references/page-choreography.md — ASCII 스토리보드, TIMING 객체, 섹션 설정, 스프링 프리셋 및
stage >= N패턴을 사용한 스테이지 기반 페이지 진입 - references/list-stagger.md — 인덱스 기반 스태거 지연, StaggerItem 래퍼, 타이밍/오프셋 지침 및 안티패턴
- references/popups-modals.md — 3계층 모달 애니메이션 (배경, 패널, 콘텐츠 스태거), 드롭다운 패턴, 닫기 동작
- references/filter-transitions.md — ResizeObserver를 사용한 AnimatedHeight, 키가 있는 래퍼로 크로스페이드, 중요한
layout안티패턴 - references/live-data.md — 롤링 숫자 (슬롯 머신), SVG 도넛 차트, 차트 모핑, 마운트 대 업데이트 단계 관리
- references/hover-micro.md — CSS 대 framer-motion 결정 매트릭스, 버튼 피드백, 쉐브론 회전, 툴팁 진입, 복사 피드백
- references/spring-presets.md — 모든 프리셋을 표 + JSON 형식으로: 스프링 설정, 이징 곡선, 스태거 값, 지속 시간 프리셋
교차 스킬 참조
frontend-design-guidelines/references/animation.md— 이 스킬이 상속하는 기본 제약 조건 (지속 시간 계층, 이징, 모션 감소, GPU 속성)number-formatting— 숫자 표시 규칙용 (형식 지정, 애니메이션 아님)
빠른 시작
# 트리거 예시:
# "페이지 로딩을 고쳐주세요 — 모든 게 한꺼번에 나타나요"
# "이 대시보드에 진입 애니메이션을 추가해주세요"
# "모달 애니메이션이 버벅거려요"
# "이 카드들을 어떻게 스태거하나요?"
# "드롭다운에 어떤 스프링 설정을 사용해야 하나요?"
# "잔액 표시에 롤링 숫자 애니메이션을 추가해주세요"
# 페이지 레벨 컴포넌트를 구축할 때 자동으로 실행
텔레메트리 (마지막에 실행)
스킬 워크플로우가 완료된 후 (성공, 오류, 또는 중단), 텔레메트리 이벤트를 기록하세요.
워크플로우 결과에 따라 결과를 결정하세요: 정상 완료 시 success, 실패 시 error, 사용자가 중단 시 abort.
다음 bash를 실행하세요:
_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - ${_TEL_START:-$_TEL_END} ))
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
if [ "$_TEL_TIER" != "off" ]; then
echo '{"skill":"page-load-animations","phase":"build","event":"completed","outcome":"OUTCOME","duration_s":"'$_TEL_DUR'","session":"'$_SESSION_ID'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","platform":"'$(uname -s)-$(uname -m)'"}' >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
true
fi
워크플로우 결과에 따라 OUTCOME을 success/error/abort로 바꾸세요.