目標
Erlin 的個人站動效方法論:為 Next.js/React 站點引入 motion 動效庫、從 framer-motion 遷移導入、鋪設滾動揭示 / stagger 網格 / 頁面過渡 / 導航動效,同時絕不讓動效把內容搞丟。核心教訓:whileInView 曾讓首頁專案卡片卡在 opacity:0(「專案卡片沒了」)。因此需要可見性兜底;已有可靠實作可保留,Reveal 是選用參考,不全面禁止 whileInView。
執行步驟
-
先判斷專案環境(動手前花 30 秒確認,避免套錯模板):
- 套件管理器:只認一個 lockfile:
pnpm-lock.yaml→ pnpm,package-lock.json→ npm,yarn.lock→ yarn,bun.lock或bun.lockb→ bun。多個 lockfile 時停止並詢問使用者;沒有 lockfile 時讀取package.json的packageManager,仍無法判斷就停止,不猜套件管理器。後續安裝、遷移、lint、build 指令都跟隨已確認的管理器。 - Next/React 版本:檢查實際 Next/React 與動畫庫版本、peer dependencies 和官方相容說明,不硬編碼版本或宣稱跨版本 API 完全相容。
- 路由結構(選模板落位前先探測,不預設 App Router):有
app/目錄 → App Router,按下述規則選 template;只有pages/→ Pages Router,無template.tsx機制,改在pages/_app.tsx或目標頁面元件層做過渡並向使用者說明差異;兩者皆無 → 非 Next 專案,按框架自身掛載點等價實作。App Router:有 locale-prefixed 路由(app/[locale]/目錄)時,template 放app/[locale]/template.tsx;無 locale 路由(如用 client 端語言切換)放app/template.tsx,Next 同樣每次導航重掛載,淡入照常生效。 - 元件當前是否是 server 元件:需要互動的 motion 元素隔離到最小 client 元件;不要直接把含伺服器邏輯的整個元件改為 client。
- 套件管理器:只認一個 lockfile:
-
沿用現有依賴:已有
framer-motion且滿足需求時繼續使用,不因新增動效預設遷移。僅使用者要求遷移或當前能力/相容性確有必要時,檢查版本差異後按專案套件管理器安裝motion,逐處核實motion/react導入與 API;確認無殘留依賴後再移除舊套件。不順手改無關注釋或文件。 -
鋪設動效:按需參考 Reveal:模板見
assets/reveal.tsx,複製到components/motion/reveal.tsx並適配路徑別名。設計要點(按專案適配):- 可見性兜底:模板用 IntersectionObserver + 2.5s 超時;2.5s 只是參考參數,按頁面與載入行為調整。可使用已驗證的 whileInView 或其他機制,確保 observer、JS 或 hydration 失敗時內容仍可存取。
- 根據 SSR/hydration 與專案 lint 規則處理 reduced-motion 和 observer 缺失;避免 hydration 不一致及無必要的同步 effect 更新,不把一次 lint 經驗當所有 API 的禁令。
- reduced motion 直接渲染最終狀態。
- 純 CSS transition(
cubic-bezier(0.22,1,0.36,1)),不用 motion.div,零動畫執行時開銷。 Reveal自帶 className prop:原本是div的卡片(如glass卡)直接把類名傳給 Reveal,省一層巢狀;article/section等有語義的元素用 Reveal 外包一層,保住語義。
-
應用位置與 stagger 公式:
位置 做法 delay 卡片網格(首頁多個區塊) 每項包 RevealMath.min(i * 0.08, 0.4),封頂防長網格拖沓文章列表(writing、latest-writing) 每行包 Reveali * 0.05~0.07,封頂Math.min(i*0.05, 0.3)防長列表拖沓專案大圖行的文字列 Reveal固定 0.15,與圖片視差錯開正文/聯繫卡片(about) 大塊 Reveal第二塊 0.1導覽列 motion.header初始y:"-100%"滑入,滾動隱藏復用同一 transform— 行動選單 AnimatePresence+opacity/y過渡,替換block/hidden切換— 路由切換 新建 app/template.tsx(無 locale 路由)或app/[locale]/template.tsx(locale-prefixed;Next 每次導航重掛載 template)做opacity+y淡入,0.35s— -
驗證與交付:按第 1 步確認的套件管理器:
pnpm lint && pnpm build # pnpm 專案;build 必須成功(全站 SSG 專案含 SSG 匯出) npm run lint && npm run build # npm 專案僅使用者授權提交時,按專案提交慣例,例:
feat(motion): 遷移 motion 庫並新增全站動效。只 add 本次任務相關檔案——倉庫裡若混有無關的未提交改動,不要順手帶進本次提交。
判斷規則
- 何時使用:為 Next.js 站點新增動效/動畫;把
framer-motion遷移到motion套件(遷移前核對目前版本 API);使用者要求「滾動揭示」「stagger」「頁面過渡」「更多動效」。 - 不負責:SwiftUI、CSS-only 或 Remotion 影片動畫。
- 動效設計規則(踩坑總結):
- LCP 元素(H1、hero)不加入場動畫:
SkewReveal有instantprop,或者初始態直接是最終態,否則 SSR 文字會閃爍。 - 所有動效尊重
prefers-reduced-motion:用useReducedMotion(),reduced 時渲染最終態/不註冊監聽。 - 統一緩動
[0.22, 1, 0.36, 1](easeOutQuint 風格),時長 0.3–0.8s,克制優先。 - 懸浮動效用 CSS transition 即可(如
hover:-translate-y-1、group-hover:scale-105),不必引 motion。 - 客戶端過濾(如 tag 篩選)時,key 不變的列表項不會重播動畫——這是預期行為,新出現的項自動觸發。
- LCP 元素(H1、hero)不加入場動畫:
- 已有元件歸屬:SkewReveal 入場、Parallax 視差、Magnetic 磁吸、MouseParallax 保留即可,新動效與它們同目錄共存;若專案已有
.zcode/.agents動效元件目錄(如components/motion/),新元件放同目錄。 - server/client 邊界:伺服器元件可直接渲染
Reveal(它是 client 元件,作為子元件使用無礙)。
動效完成前實際檢查視覺、可及性與內容可見性;本技能管 Next.js/React 的 motion 實作技術;RN/Expo 或其他技術棧的動畫按同一原則直接實作,不依賴本技能腳本。
輸出格式
Reveal元件落位:從assets/reveal.tsx複製到components/motion/reveal.tsx並適配路徑別名。- 路由過渡:
app/template.tsx(無 locale 路由)或app/[locale]/template.tsx(locale-prefixed),opacity+y淡入 0.35s。 - 提交資訊:conventional commits + 中文描述,例:
feat(motion): 遷移 motion 庫並新增全站動效。
範例
使用者問題
"給站點加滾動揭示,順便把 framer-motion 換成 motion。"
工具返回
pnpm
pnpm add motion && pnpm remove framer-motion 成功,package.json 裡出現 相容專案的 motion 版本;pnpm lint && pnpm build 全站 SSG 保持成功。
sed
sed -i '' 's/from "framer-motion"/from "motion\/react"/g' <files> 執行後,所有導入指向 motion/react;僅更新本次遷移相關且確已過期的說明。
最終輸出
components/motion/reveal.tsx(手動 IntersectionObserver + 2.5s 保險絲)+ 卡片/列表 stagger + app/template.tsx 路由淡入;lint、build 通過;報告實際驗證;僅已有提交授權時提交本次相關檔案。
門禁
- 內容紅線:絕不讓動效把內容搞丟——驗證 SSR、reduced-motion、observer/腳本異常時內容可存取;Reveal 與超時參數是參考實作,不機械禁用 API。
- 可及性紅線:所有動效尊重
prefers-reduced-motion;LCP 元素(H1、hero)不加入場動畫。 - 驗證:按確認的套件管理器跑
lint && build,build必須保持成功(專案是全站 SSG 時,SSG 匯出同樣不得被破壞;SSR/ISR 專案以 build 通過為準,不虛構 SSG 要求)。 - 提交紀律:只 add 本次任務相關檔案,倉庫裡無關的未提交改動不順手帶進提交。
- 漸進增強:不要動已經能工作的動效元件來「統一風格」,依據需求和可及性證據判斷。