前言(請先執行)
_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 配方,讓頁面載入感覺經過精心設計,而非雜亂無章。這個技能之所以存在,是因為在區塊鏈使用者介面中最常見的動畫問題不是「缺少動畫」,而是「所有內容同時出現,缺乏編排、交錯或彈簧物理效果」。即使程式碼正確,結果仍會感覺卡頓。
本技能提供實作配方。至於動畫理論(何時該用動畫、持續時間分級、緩動曲線、減少動態設定),請參閱 frontend-design-guidelines/references/animation.md。本技能繼承了所有那些基礎限制條件。
權威模型
animation.md= 基礎限制條件(持續時間分級、緩動曲線、減少動態、GPU 屬性)- 本技能 = 在那些限制條件內實作的生產配方
frontend-design-guidelines將 framer-motion 模式的實作委派給本技能,而非反過來
設定
npm install framer-motion
CSS 轉場是簡單狀態變更的預設做法(根據 animation.md)。當你需要以下功能時,才使用 framer-motion:彈簧物理效果、編排序列、AnimatePresence 退出動畫、手勢/拖曳,或共享佈局轉場。
何時觸發此技能
每當你正在進行以下工作時,套用這些配方:
- 建立一個載入多個區塊的頁面(儀表板、詳細資料畫面、登陸頁)
- 在掛載時交錯顯示清單、卡片網格或表格
- 為模態框、下拉選單或彈出視窗加入動畫
- 切換頁籤或篩選條件時,內容變更且高度變化
- 顯示即時更新的數字、圖表或環形圖
- 加入懸停回饋、箭頭旋轉或工具提示進場動畫
- 審查現有的 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 屬性同時出現在父層與子層(抖動的來源) grep -rn "layout" --include="*.tsx" --include="*.jsx" | head -20 # staggerChildren 與 AnimatePresence 搭配使用(不可靠) 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或delay屬性中不得有魔術數字。 - **彈簧優先。**對於自然且可中斷的動畫,優先使用彈簧物理動畫,而非基於持續時間的緩動。僅在淡入淡出和工具提示中使用持續時間。
- **階段驅動的序列。**單一整數狀態驅動多區塊序列。不得使用分散的布林旗標。
- **
stage >= N模式。**區塊一旦出現就保持可見。永遠不要使用stage === N。 - **永遠不要在父層和子層同時使用
layout。**這是導致篩選動畫抖動的第一大原因。請改用搭配ResizeObserver的AnimatedHeight。 - **永遠不要將
staggerChildren與AnimatePresence搭配使用。**它無法可靠運作。請改用手動的delay: i * stagger。 - **尊重
prefers-reduced-motion。**繼承自animation.md。每個動畫都必須優雅地降級。 - **掛載與更新的區別。**掛載動畫是戲劇性的(600 毫秒,富有表現力的緩動)。更新動畫是微妙的(150 毫秒,流暢的緩動)。不同的階段,不同的配置。
設計原則
- 分鏡優先——在撰寫程式碼之前先規劃序列
- 彈簧優先——彈簧物理動畫優先於基於持續時間的緩動
- 具名常數——每個時序值都被宣告,而非內聯
- 階段驅動——單一整數狀態協調複雜序列
- 資料驅動——重複元素使用帶有基於索引延遲的
.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 — 三層模態框動畫(背景遮罩、面板、內容交錯)、下拉選單模式、關閉行為
- 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。