Communitygithub.com

Abduovv/Arcadia-frontend

페이지 로딩 시 모든 요소가 한꺼번에 나타나는 버벅임을 수정합니다. 안무된 페이지 진입, 스태거 목록, 모달 전환, 필터 크로스페이드, 실시간 데이터 애니메이션, 마이크로 인터랙션을 위한 프로덕션 framer-motion 레시피입니다.

Arcadia-frontend란 무엇인가요?

이 스킬은 프론트엔드 페이지 로딩 애니메이션의 일반적인 문제인 '모든 요소가 동시에 등장하는 현상'을 해결하기 위한 프로덕션급 framer-motion 레시피를 제공합니다. 사용자는 페이지 레벨 컴포넌트를 빌드하거나 애니메이션 코드를 리뷰할 때 이 스킬을 트리거할 수 있으며, 페이지 안무, 리스트 스태거, 모달 및 드롭다운, 필터 전환, 실시간 데이터(숫자 롤링, 차트 모핑, 도넛 차트), 마이크로 인터랙션(호버, 버튼 피드백, 툴팁) 등 7가지 주요 패턴에 대한 참조 파일을 제공합니다. 스킬은 ASCII 스토리보드 주석, 명명된 타이밍 상수, 스프링 물리 기반 모션, 스테이지 기반 시퀀싱, `prefers-reduced-motion` 존중 등의 핵심 원칙을 강조하며, `frontend-design-guidelines`, `number-formatting`, `brand-design`과 같은 다른 스킬과 통합됩니다. 이 스킬은 Claude Code, Cursor, Codex, Copilot 등 모든 에이전트 기반 개발 도구에서 사용할 수 있으며, 텔레메트리 기능을 통해 사용 패턴을 익명으로 추적하여 개선에 기여할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Abduovv/Arcadia-frontend/tree/HEAD/.agents/skills/page-load-animations

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

서문 (먼저 실행)

_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 코드를 안티패턴 검토할 때
  • 사용자가 "페이지가 버벅거려요" 또는 "모든 것이 한꺼번에 나타나요"라고 말할 때

페이지 레벨 컴포넌트를 구축 중이고 이 스킬이 아직 트리거되지 않았다면, 직접 트리거하세요.

워크플로우

애니메이션 코드를 작성하기 전에, 관련 참조 파일을 식별하고 읽으세요:

필요한 것만 로드하세요. 모든 참조를 미리 읽지 마세요.

모드 1: 새 애니메이션 구축

  1. 필요한 패턴에 대해 관련 참조 파일(들)을 읽으세요.
  2. ASCII 스토리보드 주석으로 시작하세요 — 코드를 작성하기 전에 전체 시퀀스를 계획하세요.
  3. 모든 지연에 대해 명명된 상수가 포함된 TIMING 객체를 정의하세요.
  4. 참조의 패턴을 사용하여 구현하세요. 기본적으로 스프링 물리를 사용하세요.
  5. 완료 보고 전에 아래의 '필수 사항'을 확인하세요.

모드 2: 기존 애니메이션 코드 검토

  1. 일반적인 안티패턴을 스캔하세요:
    # 부모와 자식 모두에 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
    
  2. 발견된 각 문제에 대해 관련 참조 파일의 특정 안티패턴 규칙을 참조하세요.
  3. 정확한 코드 패치를 제공하세요.

모드 3: 빠른 조회

사용자가 "X를 위한 스프링 설정은?" 또는 "Y를 어떻게 애니메이션하나요?"라고 묻는다면, 전체 워크플로우를 실행하지 않고 참조 파일과 스프링 프리셋에서 직접 답변하세요.

필수 사항

  1. ASCII 스토리보드 주석. 모든 애니메이션 페이지는 전체 시퀀스를 한눈에 보여주는 타임라인 주석으로 시작합니다. 시간은 마운트 시점부터 절대값이며 오른쪽 정렬됩니다.
  2. 명명된 타이밍 상수. 모든 지연은 파일 상단의 TIMING 객체에 들어갑니다. setTimeout 또는 delay prop에 매직 넘버를 사용하지 마세요.
  3. 스프링 우선. 자연스럽고 인터럽트 가능한 모션을 위해 지속 시간 기반 이징보다 스프링 물리를 선호하세요. 페이드 및 툴팁에만 지속 시간을 사용하세요.
  4. 스테이지 기반 시퀀싱. 단일 정수 상태로 다중 섹션 시퀀스를 구동합니다. 분산된 불리언 플래그를 사용하지 마세요.
  5. stage >= N 패턴. 섹션은 한 번 나타나면 계속 보입니다. 절대 stage === N을 사용하지 마세요.
  6. 절대 부모와 자식 모두에 layout을 사용하지 마세요. 이것이 버벅거리는 필터 애니메이션의 1순위 원인입니다. 대신 ResizeObserver와 함께 AnimatedHeight를 사용하세요.
  7. 절대 AnimatePresence와 함께 staggerChildren을 사용하지 마세요. 신뢰할 수 없습니다. 수동 delay: i * stagger를 사용하세요.
  8. prefers-reduced-motion을 존중하세요. animation.md에서 상속됩니다. 모든 애니메이션은 우아하게 저하되어야 합니다.
  9. 마운트와 업데이트 구분. 마운트 애니메이션은 극적입니다 (600ms, 표현적인 이징). 업데이트 애니메이션은 미묘합니다 (150ms, 부드러운 이징). 다른 단계, 다른 설정.

디자인 원칙

  1. 스토리보드 우선 — 코드 작성 전에 시퀀스 계획
  2. 스프링 우선 — 지속 시간 기반 이징보다 스프링 물리
  3. 명명된 상수 — 모든 타이밍 값은 선언되며 인라인이 아님
  4. 스테이지 기반 — 단일 정수 상태가 복잡한 시퀀스를 오케스트레이션
  5. 데이터 기반 — 반복 요소는 인덱스 기반 지연으로 .map()을 사용, 복사-붙여넣기 블록 금지
  6. 측정, 추측 금지 — 동적 높이는 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로 바꾸세요.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬