Communitygithub.com

erlinerd/erlin-skills

為 Next.js/React 網站引入 motion 動效庫、從 framer-motion 遷移導入,並鋪設滾動揭示、stagger 網格、頁面過渡與導航動效。不負責 SwiftUI、CSS-only 或 Remotion 影片動畫。

erlin-skills 是什麼?

此技能專注於在 Next.js/React 專案中加入 motion 動畫庫,或從 framer-motion 遷移導入,並實作滾動揭示、stagger 網格、頁面過渡與導航動效。其核心原則是「動畫絕不能讓內容消失」,例如之前 `whileInView` 曾導致專案卡片卡在 `opacity:0`,因此設計了可見性兜底機制:使用 IntersectionObserver 搭配 2.5 秒超時,確保在 observer、JS 或 hydration 失敗時內容仍可訪問。支援 App Router 與 Pages Router,並自動偵測路由結構與語言前綴來決定 template 放置位置。同時要求尊重 `prefers-reduced-motion`、LCP 元素不加入場動畫,以及統一的緩動曲線 `[0.22, 1, 0.36, 1]`。技能也包含完整的驗證流程:使用專案實際的包管理器執行 lint 與 build,並僅在用戶授權時提交相關檔案。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/erlinerd/erlin-skills/tree/HEAD/skills/web/erlin-web-motion

在你喜歡的 AI 中提問

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

說明文件

目標

Erlin 的個人站動效方法論:為 Next.js/React 站點引入 motion 動效庫、從 framer-motion 遷移導入、鋪設滾動揭示 / stagger 網格 / 頁面過渡 / 導航動效,同時絕不讓動效把內容搞丟。核心教訓:whileInView 曾讓首頁專案卡片卡在 opacity:0(「專案卡片沒了」)。因此需要可見性兜底;已有可靠實作可保留,Reveal 是選用參考,不全面禁止 whileInView。

執行步驟

  1. 先判斷專案環境(動手前花 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。
  2. 沿用現有依賴:已有 framer-motion 且滿足需求時繼續使用,不因新增動效預設遷移。僅使用者要求遷移或當前能力/相容性確有必要時,檢查版本差異後按專案套件管理器安裝 motion,逐處核實 motion/react 導入與 API;確認無殘留依賴後再移除舊套件。不順手改無關注釋或文件。

  3. 鋪設動效:按需參考 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 外包一層,保住語義。
  4. 應用位置與 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—
  5. 驗證與交付:按第 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 有 instant prop,或者初始態直接是最終態,否則 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 不變的列表項不會重播動畫——這是預期行為,新出現的項自動觸發。
  • 已有元件歸屬: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 本次任務相關檔案,倉庫裡無關的未提交改動不順手帶進提交。
  • 漸進增強:不要動已經能工作的動效元件來「統一風格」,依據需求和可及性證據判斷。

相關技能