Communitygithub.com

shengdabai/Tony-Claude-Code-Skills

HyperFrames를 위한 GSAP 애니메이션 레퍼런스입니다. gsap.to(), from(), fromTo(), easing, stagger, defaults, 타임라인(gsap.timeline(), position 파라미터, 레이블, 중첩, 재생 제어), 성능(transform, will-change, quickTo)을 다룹니다. HyperFrames 컴포지션에서 GSAP 애니메이션을 작성할 때 사용하세요.

Tony-Claude-Code-Skills란 무엇인가요?

이 스킬은 HyperFrames 환경에서 GSAP 애니메이션을 사용하는 방법을 상세히 안내합니다. HyperFrames는 자체 `gsap` 런타임 어댑터를 통해 GSAP를 제어하므로, 표준 GSAP 문서와는 다른 몇 가지 필수 규칙을 따라야 합니다. 특히, 애니메이션을 `paused: true` 상태로 동기적으로 생성하고 `window.__timelines` 객체에 `data-composition-id`와 정확히 일치하는 키로 등록해야 하며, 렌더링에 중요한 모션에는 `tl.play()`를 호출해서는 안 됩니다. 이 스킬은 gsap.to(), from(), fromTo(), gsap.timeline() 등 핵심 트윈 메서드와 타임라인뿐만 아니라, 이징, 스태거, 기본값 설정, 성능 최적화 기법(transform 및 opacity 선호, will-change, gsap.quickTo())까지 포괄합니다. CSS 변수, 함수 기반 값, 방향 회전, gsap.matchMedia()를 통한 반응형 및 접근성 처리와 같은 고급 주제도 다룹니다. Claude Code, Cursor, Codex와 같은 AI 에이전트가 이 스킬을 활용하여 HyperFrames용 GSAP 애니메이션 코드를 생성할 때, 최적의 성능과 HyperFrames 아키텍처와의 완벽한 호환성을 보장하는 데 필요한 모든 지침을 얻을 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shengdabai/Tony-Claude-Code-Skills/tree/HEAD/skills/hyperframes-gsap

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

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

문서

GSAP

HyperFrames 계약

HyperFrames는 자체 gsap 런타임 어댑터를 통해 GSAP를 제어합니다. 타임라인을 일시 중지된 상태로 동기적으로 생성하고, 정확한 data-composition-id와 함께 window.__timelines에 등록한 후, HyperFrames가 이를 탐색하도록 해야 합니다.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });

  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);

  window.__timelines["main"] = tl; // 키는 컴포지션 루트의 data-composition-id와 일치해야 함
</script>
  • 레지스트리 키는 컴포지션 루트의 data-composition-id와 일치해야 합니다.
  • 렌더링에 중요한 모션에 대해 tl.play()를 호출하지 마십시오.
  • 비동기 코드, 타이머 또는 이벤트 핸들러 내부에서 타임라인을 생성하지 마십시오.
  • 루프는 유한하게 유지하세요. HyperFrames는 유한한 비디오 시간을 렌더링합니다.

핵심 트윈 메서드

  • gsap.to(targets, vars) — 현재 상태에서 vars로 애니메이션합니다. 가장 일반적입니다.
  • gsap.from(targets, vars) — vars에서 현재 상태로 애니메이션합니다(진입 효과).
  • gsap.fromTo(targets, fromVars, toVars) — 명시적인 시작 및 종료 상태를 지정합니다.
  • gsap.set(targets, vars) — 즉시 적용합니다(duration 0).

항상 camelCase 속성 이름을 사용하세요 (예: backgroundColor, rotationX).

일반적인 vars

  • duration — 초 (기본값 0.5).
  • delay — 시작 전 지연 시간(초).
  • ease — "power1.out" (기본값), "power3.inOut", "back.out(1.7)", "elastic.out(1, 0.3)", "none".
  • stagger — 숫자 0.1 또는 객체: { amount: 0.3, from: "center" }, { each: 0.1, from: "random" }.
  • overwrite — false (기본값), true, 또는 "auto".
  • repeat — 유한한 숫자, HyperFrames에서는 절대 -1을 사용하지 마십시오. 표시되는 시간에서 반복 횟수를 계산하세요. yoyo — 반복 시 방향을 번갈아 가며 적용합니다.
  • onComplete, onStart, onUpdate — 콜백 함수입니다.
  • immediateRender — from()/fromTo()의 기본값은 true입니다. 동일한 속성+요소를 대상으로 하는 이후 트윈에서 덮어쓰기를 피하려면 false로 설정하세요.

변환 및 CSS

원시 transform 문자열보다 GSAP의 transform 별칭을 선호하세요:

GSAP 속성동등 항목
x, y, ztranslateX/Y/Z (px)
xPercent, yPercenttranslateX/Y in %
scale, scaleX, scaleYscale
rotationrotate (deg)
rotationX, rotationY3D rotate
skewX, skewYskew
transformOrigintransform-origin
  • autoAlpha — opacity보다 선호합니다. 0일 때: visibility: hidden도 설정합니다.
  • CSS 변수 — "--hue": 180.
  • svgOrigin (SVG 전용) — 전역 SVG 좌표 공간 원점입니다. transformOrigin과 함께 사용하지 마세요.
  • 방향 회전 — "360_cw", "-170_short", "90_ccw".
  • clearProps — "all" 또는 쉼표로 구분된 목록; 완료 시 인라인 스타일을 제거합니다.
  • 상대 값 — "+=20", "-=10", "*=2".

함수 기반 값

gsap.to(".item", {
  x: (i, target, targets) => i * 50,
  stagger: 0.1,
});

이징

내장 이즈: power1–power4, back, bounce, circ, elastic, expo, sine. 각각 .in, .out, .inOut 접미사를 가집니다.

기본값

gsap.defaults({ duration: 0.6, ease: "power2.out" });

트윈 제어

const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);

gsap.matchMedia() (반응형 + 접근성)

미디어 쿼리가 일치할 때만 설정을 실행하고, 일치가 중단되면 자동으로 되돌립니다.

let mm = gsap.matchMedia();
mm.add(
  {
    isDesktop: "(min-width: 800px)",
    reduceMotion: "(prefers-reduced-motion: reduce)",
  },
  (context) => {
    const { isDesktop, reduceMotion } = context.conditions;
    gsap.to(".box", {
      rotation: isDesktop ? 360 : 180,
      duration: reduceMotion ? 0 : 2,
    });
  },
);

타임라인

타임라인 생성

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

위치 파라미터

세 번째 인수는 배치를 제어합니다:

  • 절대적: 1 — 1초 지점
  • 상대적: "+=0.5" — 끝난 후; "-=0.2" — 끝나기 전
  • 레이블: "intro", "intro+=0.3"
  • 정렬: "<" — 이전 항목과 같은 시작점; ">" — 이전 항목이 끝난 후; "<0.2" — 이전 항목이 시작된 후 0.2초
tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // .a와 같은 시작점
tl.to(".c", { opacity: 0 }, "<0.2"); // .b가 시작된 후 0.2초

레이블

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");

타임라인 옵션

  • paused: true — 일시 중지된 상태로 생성합니다. 시작하려면 .play()를 호출하세요.
  • repeat, yoyo — 전체 타임라인에 적용됩니다.
  • defaults — 모든 하위 트윈에 병합되는 변수입니다.

타임라인 중첩

const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);

재생 제어

tl.play(), tl.pause(), tl.reverse(), tl.restart(), tl.time(2), tl.progress(0.5), tl.kill().


성능

Transform 및 Opacity 선호

x, y, scale, rotation, opacity를 애니메이션하면 컴포지터에서 처리됩니다. transform으로 동일한 효과를 낼 수 있다면 width, height, top, left는 피하세요.

will-change

will-change: transform;

실제로 애니메이션하는 요소에만 적용하세요.

gsap.quickTo() (빈번한 업데이트)

let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
  yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
  xTo(e.pageX);
  yTo(e.pageY);
});

여러 트윈 대신 스태거 사용

별도의 트윈과 수동 지연 대신 stagger를 사용하세요.

정리

화면 밖 애니메이션은 일시 중지하거나 종료하세요.


참조 (요청 시 로드됨)

  • references/effects.md — 바로 사용 가능한 효과: 타자기 텍스트, 오디오 비주얼라이저. HyperFrames용 기성 효과 패턴이 필요할 때 읽으세요.

모범 사례

  • camelCase 속성 이름을 사용하고, transform 별칭과 autoAlpha를 선호하세요.
  • delay를 사용한 체이닝보다 타임라인을 선호하고, 위치 파라미터를 사용하세요.
  • 읽기 쉬운 시퀀싱을 위해 addLabel()로 레이블을 추가하세요.
  • 타임라인 생성자에 기본값을 전달하세요.
  • 재생을 제어해야 할 때 tween/timeline의 반환 값을 저장하세요.

하지 말아야 할 것

  • transform으로 충분할 때 레이아웃 속성 (width/height/top/left)을 애니메이션하지 마세요.
  • 동일한 SVG 요소에 svgOrigin과 transformOrigin을 함께 사용하지 마세요.
  • 타임라인이 시퀀싱할 수 있는데 delay로 애니메이션을 체이닝하지 마세요.
  • DOM이 존재하기 전에 트윈을 생성하지 마세요.
  • 정리를 건너뛰지 마세요. 더 이상 필요하지 않은 트윈은 항상 종료하세요.
  • HyperFrames 컴포지션에서 무한 반복 값을 사용하지 마세요. 표시되는 시간에서 계산된 유한한 반복 횟수를 사용하세요.

크레딧 및 참고 자료

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

shengdabai/Tony-Claude-Code-Skills

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

shengdabai/Tony-Claude-Code-Skills

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

shengdabai/Tony-Claude-Code-Skills

Read-only queue dashboard for workspace-aware ship. (gstack)

shengdabai/Tony-Claude-Code-Skills

Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.

shengdabai/Tony-Claude-Code-Skills

Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill.

shengdabai/Tony-Claude-Code-Skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

shengdabai/Tony-Claude-Code-Skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

shengdabai/Tony-Claude-Code-Skills

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

관련 스킬