Communitygithub.com

Abduovv/Arcadia-frontend

修復所有內容同時出現的頁面載入卡頓問題。提供生產級的 framer-motion 配方,實現編排過的頁面進場、交錯清單、模態框轉場、濾鏡交叉淡入、即時資料動畫以及微互動。

Arcadia-frontend 是什麼?

此技能專注於解決前端頁面載入時,所有元素同時彈出的常見卡頓問題,並提供一套基於 framer-motion 的生產級動畫配方。其核心價值在於將混沌的頁面載入轉化為有編排、有層次的流暢體驗,特別適用於包含多個區塊的儀表板、詳細資料頁或登陸頁。 技能支援多種動畫模式,包括使用 ASCII 分鏡與階段驅動的頁面進場協調、基於索引的交錯列表、具有三層結構的模態框與下拉選單動畫、結合 ResizeObserver 的濾鏡切換與內容交叉淡入,以及即時更新的數字滾動、圖表變形與環形圖揭示等資料視覺化動畫。此外,也涵蓋按鈕回饋、旋轉圖示與工具提示等微互動。 它以 Spring 物理動畫為預設,強調使用命名常數管理時序、以單一整數階段狀態驅動複雜序列,並嚴格遵循 `prefers-reduced-motion` 無障礙規範。此技能可與 `frontend-design-guidelines`(繼承動畫基礎限制)、`number-formatting`(數字格式化)及 `brand-design`(品牌色彩)等其他技能整合。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Abduovv/Arcadia-frontend/tree/HEAD/.agents/skills/page-load-animations

在你喜歡的 AI 中提問

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

說明文件

前言(請先執行)

_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 程式碼,找出反模式
  • 使用者說「頁面感覺很卡」或「所有東西同時出現」

如果你正在建立頁面級元件,且此技能尚未被觸發,請自行觸發它。

工作流程

在撰寫動畫程式碼之前,先辨識相關的參考檔案並閱讀:

只載入你需要的部分。不要一次讀取所有參考檔案。

模式 1:建立新的動畫

  1. 閱讀你所需模式的相關參考檔案。
  2. 從 ASCII 分鏡註解開始——在撰寫任何程式碼之前,先規劃完整的序列。
  3. 定義一個 TIMING 物件,為每個延遲使用具名常數。
  4. 使用參考檔案中的模式來實作。預設使用彈簧物理動畫。
  5. 在回報完成之前,根據下方的「不可協商條件」進行驗證。

模式 2:審查現有的動畫程式碼

  1. 掃描常見的反模式:
    # 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
    
  2. 針對每個發現的問題,引用相關參考檔案中的特定反模式規則。
  3. 提供確切的程式碼修補。

模式 3:快速查詢

如果使用者問「X 的彈簧配置是什麼?」或「我該如何為 Y 加入動畫?」,直接從參考檔案和彈簧預設值中回答,無需執行完整的工作流程。

不可協商條件

  1. **ASCII 分鏡註解。**每個動畫頁面都以一個時間軸註解開始,一目了然地顯示完整序列。時間從掛載開始計算為絕對時間,並向右對齊。
  2. **具名時序常數。**每個延遲都放在檔案頂部的 TIMING 物件中。setTimeout 或 delay 屬性中不得有魔術數字。
  3. **彈簧優先。**對於自然且可中斷的動畫,優先使用彈簧物理動畫,而非基於持續時間的緩動。僅在淡入淡出和工具提示中使用持續時間。
  4. **階段驅動的序列。**單一整數狀態驅動多區塊序列。不得使用分散的布林旗標。
  5. **stage >= N 模式。**區塊一旦出現就保持可見。永遠不要使用 stage === N。
  6. **永遠不要在父層和子層同時使用 layout。**這是導致篩選動畫抖動的第一大原因。請改用搭配 ResizeObserver 的 AnimatedHeight。
  7. **永遠不要將 staggerChildren 與 AnimatePresence 搭配使用。**它無法可靠運作。請改用手動的 delay: i * stagger。
  8. **尊重 prefers-reduced-motion。**繼承自 animation.md。每個動畫都必須優雅地降級。
  9. **掛載與更新的區別。**掛載動畫是戲劇性的(600 毫秒,富有表現力的緩動)。更新動畫是微妙的(150 毫秒,流暢的緩動)。不同的階段,不同的配置。

設計原則

  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 — 三層模態框動畫(背景遮罩、面板、內容交錯)、下拉選單模式、關閉行為
  • 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.

相關技能