打造精緻前端動態效果
將動態效果視為產品互動的一部分來建構，而非事後附加的裝飾。追蹤真正的渲染擁有者，選擇最適合的技術方案，保留狀態語義，並在真實瀏覽器中驗證結果。
工作流程
- 在提出實作方案前先檢查目標。
- 定位實際的路由、元件、樣式、狀態擁有者、事件擁有者以及現有的動畫堆疊。
- 閱讀專案說明，保留不相關的改動。
- 如果使用者要求先討論，則停留在具體的動畫規格說明階段，直到獲得批准。
- 定義動畫合約。
- 說明觸發條件、起始與結束狀態、持續時間、緩動或彈簧效果、中斷行為、重複行為、圖層疊加以及降低動畫效果的結果。
- 將業務狀態與視覺回饋分開。除非產品明確要求，否則刪除動作、導航或表單提交不應依賴於一個裝飾性時間軸的完成。
- 選擇參考素材。
- 執行
python3 scripts/query_catalog.py --need "<效果描述>" --top 4。 - 閱讀
references/motion-routing.md以選擇技術。 - 在複製程式碼或添加依賴前，檢查所選倉庫的當前官方 README、相關原始碼、依賴/API 版本以及授權許可。將目錄元資料視為一個有時間戳記的路由快照，而非永久事實。
- 執行
- 選擇採用模式。
- 當目標專案中已安裝的動畫堆疊能乾淨地滿足合約要求時，優先使用它。
- 僅在程式碼和授權許可允許的情況下，複製並改編一個小元件；移除示範殼層假設和未使用的依賴。
- 當一個函式庫的執行模型能顯著降低複雜性或風險時，才將其添加為依賴。
- 當一個倉庫過於老舊、框架不匹配或過於臃腫時，提取其技術而非整個套件。
- 實作最小的連貫動畫系統。
- 將時間和緩動的數值集中管理。
- 清理 RAF 迴圈、觀察者、事件處理器、畫布、時間軸、紋理和 GPU 資源。
- 處理重新掛載、快速重複輸入、中斷、路由變化、視窗縮放、隱藏分頁以及 React Strict 模式。
- 在 SSR 應用程式中正確區分瀏覽器專用程式碼，並在可行時對重量級視覺引擎進行懶加載。
- 使用
references/quality-gates.md進行驗證。- 執行重點靜態檢查和測試。
- 在寬螢幕桌面、中間/平板和手機尺寸上測試真實執行環境。
- 檢查轉場連續性、最終幾何形狀、控制台錯誤、水平溢出、輸入行為、減少動畫效果以及實際效能。
- 報告結果。
- 以現在能正常運作的部分作為開頭。
- 說明選擇的技術或原始碼倉庫及其適合的原因。
- 誠實地說明已驗證的內容以及任何仍存在的限制。
選擇規則
- 對於少量的合成屬性及簡單的確定性狀態，使用 CSS 轉場/關鍵影格。
- 對於 React 的進場/離場、共享佈局、手勢、動畫數值以及協調的元件轉場，使用 Motion。
- 對於可中斷的物理動畫，且速度連續性和自然反應比固定時間軸更重要時，使用 React Spring。
- 對於明確的多階段時間軸、密集編排、SVG/路徑動畫、滾動編舞或指令式整合，使用 GSAP。
- 對於在 React 特定抽象之外，緊湊的 DOM/SVG/物件/畫布補間動畫以及交錯生成效果，使用 Anime.js。
- 僅將 Disintegrate 用作 DOM 快照粒子化的技術/參考；預期其依赖于 html2canvas 的精確度限制，並使其生命週期現代化。
- 對可配置的環境粒子、五彩紙屑、煙火和背景使用 tsParticles；不要將其誤標為精確的 DOM 分解工具。
- 對於大量的 2D 粒子、濾鏡、精靈圖、著色器驅動的 2D 效果以及明確的 GPU 資源控制，使用 PixiJS。
- 將 React Bits、Magic UI 或 Motion Primitives 用作原始碼集合。由於依賴、渲染成本和品質各不相同，請檢查每個元件。
產品護欄
- 保持空間因果關係：動畫應解釋物體從何而來、去往何處或發生了什麼變化。
- 優先使用 transform 和 opacity；僅在有證據表明成本可接受的情況下，才為佈局屬性添加動畫。
- 永遠不要用動畫來掩蓋損壞的佈局。
- 避免環境、滾動、懸停和進場動畫同時競爭使用者注意力。
- 提供等同於鍵盤的操作行為，並保留焦點語義。
- 尊重
prefers-reduced-motion；用即時的狀態變更或克制的交叉淡入淡出來取代移動。 - 不要僅憑程式碼檢查就聲稱動畫流暢。必須在渲染路徑上驗證，並報告測試範圍。
- 除非使用者明確授權，否則不得在當前會話中更改代理/路由規則或不相關的本地環境配置。
資源
references/repositories.json：包含十個原始碼倉庫、授權許可、優點、風險和原始碼入口點的有日期戳記的目錄。references/motion-routing.md：決策指南和產品就緒的架構模式。references/quality-gates.md：實作和即時視覺驗證清單。scripts/query_catalog.py：通過自然語言需求或標籤來驗證和搜尋倉庫目錄。