Communitygithub.com

nateherkai/hyperframes-student-kit

適用於 HyperFrames 的 GSAP 動畫參考。涵蓋 gsap.to()、from()、fromTo()、easing、stagger、defaults、時間軸(gsap.timeline()、位置參數、標籤、巢狀結構、播放控制)以及效能優化(transform、will-change、quickTo)。在撰寫 HyperFrames 組合中的 GSAP 動畫時使用。

hyperframes-student-kit 是什麼?

此技能作為 GSAP(GreenSock Animation Platform)在 HyperFrames 環境中的完整參考指南。它詳細說明了核心補間方法(如 gsap.to()、from() 和 fromTo()),以及常見的變數屬性(包括 duration、ease、stagger、重複和回呼函式)。其中一個重點是突顯 GSAP 的 transform 別名(如 x、y、scale、rotation),以實現更高效且可組合的 CSS 動畫。此外,它還涵蓋了時間軸(Timelines)的進階使用,包括嵌套、透過位置參數進行精確排序、標籤管理和播放控制,讓開發者能以聲明式的方式編排複雜的動畫序列。技能也提供了效能優化的具體建議,例如優先使用 transform 和 opacity、利用 will-change、使用 gsap.quickTo() 處理頻繁更新,以及透過 stagger 批次處理多個元素動畫。同時,它還整合了 gsap.matchMedia() 來實現響應式設計和無障礙支援。這項技能廣泛適用於 Claude Code、Cursor 和 Codex 等 AI 輔助開發工具,幫助開發者在 HyperFrames 組合中快速查找正確的 GSAP API 語法、遵循最佳實踐,並避免常見陷阱,從而顯著提升動畫開發效率與品質。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nateherkai/hyperframes-student-kit/tree/HEAD/.agents/skills/gsap

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

GSAP

核心補間方法

  • gsap.to(targets, vars) — 從當前狀態動畫到 vars。最常用。
  • gsap.from(targets, vars) — 從 vars 動畫到當前狀態(進場效果)。
  • gsap.fromTo(targets, fromVars, toVars) — 明確指定起始與結束狀態。
  • gsap.set(targets, vars) — 立即套用(持續時間 0)。

始終使用 駝峰式命名(camelCase) 的屬性名稱(例如 backgroundColor、rotationX)。

常用變數

  • 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 — 數值或 -1(無限循環)。yoyo — 與 repeat 搭配使用,交替動畫方向。
  • onComplete、onStart、onUpdate — 回呼函式。
  • immediateRender — 對於 from()/fromTo() 預設為 true。如果後續有針對同一屬性與元素的補間動畫,請設為 false 以避免被覆寫。

變形與 CSS

優先使用 GSAP 的 transform 別名,而非原生 transform 字串:

GSAP 屬性等效 CSS
x、y、ztranslateX/Y/Z(px)
xPercent、yPercenttranslateX/Y (%)
scale、scaleX、scaleYscale
rotationrotate(度)
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,
});

緩動函數(Easing)

內建緩動: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,
    });
  },
);

時間軸(Timelines)

建立時間軸

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

位置參數(Position Parameter)

第三個參數控制放置位置:

  • 絕對位置: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 進行動畫處理時,會保持在合成器(compositor)層級。當 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 優於多個補間

使用 stagger 替代多個帶有手動延遲的獨立補間。

清理

暫停或銷毀畫面外的動畫。


參考資料(按需載入)

  • references/effects.md — 即用型效果:打字機文字、音訊視覺化工具。當需要 HyperFrames 的現成效果模式時請閱讀。

最佳實踐

  • 使用駝峰式命名屬性名稱;優先使用 transform 別名和 autoAlpha。
  • 優先使用時間軸而非透過 delay 進行鏈式調用;使用位置參數。
  • 使用 addLabel() 新增標籤,實現可讀性高的序列編排。
  • 將預設值傳入時間軸建構式。
  • 在需要控制播放時儲存補間/時間軸的回傳值。

禁止事項

  • 當 transform 可達成相同效果時,不要對佈局屬性(width/height/top/left)進行動畫。
  • 在同一個 SVG 元素上同時使用 svgOrigin 和 transformOrigin。
  • 當時間軸可以編排序列時,不要使用 delay 來鏈式串接動畫。
  • 在 DOM 存在之前建立補間動畫。
  • 忽略清理工作 — 在不再需要時務必銷毀補間動畫。

Individual skills in this repo

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

nateherkai/hyperframes-student-kit

Agent 2 of the video editing pipeline. Finds and removes spoken mistakes — stutters, repeated words, false starts, and retakes (re-recorded lines) — from a talking-head recording. Use after cut-silences, when asked to cut mistakes, remove stutters / repeats / filler restarts, clean up flubs, or keep the best take. Works review-gated: it proposes every cut with context and a reason for approval, then renders only the approved cuts via ffmpeg. Requires a word-level transcript.

nateherkai/hyperframes-student-kit

Agent 1 of the video editing pipeline. Removes silences and dead air from a talking-head recording. Use when asked to cut silences, trim pauses, remove dead air / gaps, or tighten the pacing of a raw video, given a word-level transcript. Produces an edit list (EDL), a re-timed transcript for downstream agents, and optionally the cut video via ffmpeg. Does NOT cut mistakes, repeats, or false starts — that is the cut-mistakes agent.

nateherkai/hyperframes-student-kit

Edit a raw talking-head video through transcription, silence trimming, mistake review, visual storytelling, motion graphics, and verified HyperFrames rendering. Use for a complete edit; route a single requested operation directly to its specialist skill.

nateherkai/hyperframes-student-kit

HyperFrames CLI tool — hyperframes init, lint, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting or validating compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.

nateherkai/hyperframes-student-kit

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

nateherkai/hyperframes-student-kit

Plan, write, time, style, and validate motion-graphic beats for long-form talking-head HyperFrames videos. Use when Codex is asked to add or improve visual beats, glassmorphism lower thirds, crumpled-paper full-screen takeovers, transcript-synced callouts, pacing coverage, YouTube retention graphics, or render-ready overlays in an existing HyperFrames video project.

nateherkai/motion-showreel

Build 10–30s motion-design showreels in the style of Nate's Opus 5.5 CLAUDE/MOTION REEL — brand motif chapters, HUD, BPM-locked cuts, logo lockup.

nateherkai/website-to-hyperframes

Capture a website URL and produce a HyperFrames promo/product-tour video — site → finished marketing video outcome.

相關技能