Communitygithub.com

Im-Fran/landing-skills

用於在登陸頁面添加動畫、滾動效果、視差、頁面轉場、滑鼠懸浮或游標互動、3D、WebGL、著色器或粒子效果,或在 GSAP、Motion、Lenis、Three.js、React Three Fiber、Rive 或 Lottie 之間做選擇。

landing-skills 是什麼?

此技能專為開發人員和 AI 代理設計,用於在已能正常運作的靜態登陸頁面上,安全且有目的地添加動畫和 3D 效果。其核心原則是「漸進增強」:所有動畫效果都必須有明確的用途(如引導注意、提供回饋或展示產品)、提供減少動畫的替代方案,並確保在 JavaScript 失敗或瀏覽器不支援時,頁面內容仍完整可讀。此技能支援多種平台和技術棧,包括純 HTML/CSS/JavaScript 以及 React(Vite、Next.js),並提供從簡單 CSS 到複雜 WebGL 的階梯式方案選擇。它透過詳細的參考文件和「安全護欄」來避免常見錯誤,例如不影響 Largest Contentful Paint (LCP)、處理 `prefers-reduced-motion`、僅對 `transform` 和 `opacity` 進行動畫、以及確保所有 3D 資產自托管。完成標準包括在瀏覽器中驗證每一項效果,並確保鍵盤可訪問性。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Im-Fran/landing-skills/tree/HEAD/skills/landing-motion

在你喜歡的 AI 中提問

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

說明文件

登陸頁面動畫與 3D 效果

為一個已能正常運作的登陸頁面添加動畫與 3D 效果。你所添加的每一個效果都必須有明確的目的、一個減少動畫的變體,以及一個能讓頁面保持完整的備用方案。你開始修改前的頁面本身就是備用方案:如果腳本執行失敗、瀏覽器缺乏某項功能,或訪客要求減少動畫,他們看到的將是那個頁面,而不是一個空白頁面。

輸入

  1. **landing/direction.md,Motion and 3D intent 章節。**這是你的工作摘要。它會說明 none,或者為每個動作時刻命名並解釋其目的。請實現它所命名的內容。不要添加它未命名的動作時刻。
  2. 由 landing-skills:landing-build 構建的靜態頁面,或任何現有頁面。它必須能在停用 JavaScript 的情況下渲染所有文案和轉換行為。請先確認這一點:如果做不到,請在添加動畫前先修復,因為這裡的每個配方都假設靜態頁面是備用方案。
  3. landing/tokens.css(如果存在的話)。在著色器和備用方案中使用其顏色。將動畫 Token(持續時間、緩動函數)放在你自己的樣式表中;保留 tokens.css 作為美術指導所定義的樣子。

當缺少輸入時:

  • 沒有 direction.md:詢問使用者哪些元素應該移動以及原因。如果你無法詢問,預設值為 none(請參閱「決定哪些元素移動」);在你的摘要中說明這一點。
  • 沒有靜態頁面:停止並先建立一個(landing-skills:landing-build),或要求提供。將動畫疊加在一個僅存在於 JavaScript 中的頁面上,會導致失敗的 3D 場景連同標題和行動呼籲一起崩塌。
  • 技術棧:讀取 package.json。如果使用 React(Vite、Next),則採用配方的 React 變體;其他情況則採用純 HTML、CSS 和 JavaScript 變體。純客戶端 React 應用程式(所有內容渲染到空的 #root 中)從根本上無法通過無 JavaScript 檢查:文案必須首先存在於 HTML 中,透過伺服器端渲染、預渲染或 references/webgl-3d.md 中的島嶼模式來實現。

決定哪些元素移動

從 direction.md 中的意圖開始。對於它命名的每個時刻,寫下:元素、角色(進入、回饋、滾動相關、環境或互動 3D),以及訪客從中學到什麼。如果你無法完成這個句子,就刪除該時刻。

none 是一個有效的答案,通常是正確的答案,並且在意圖缺失時作為預設值。許多頁面除了回饋狀態外沒有任何動畫也能保持完整,特別是當照片或文案本身就足以傳達訊息時;一個幾乎沒有動畫的頁面不會因此損失什麼。

在 none 的情況下,這只是一個簡短的檢查,而不是新的工作。landing-skills:landing-build 已經寫入了懸浮、聚焦、按下和停用狀態,以及一個包含發送、成功和錯誤狀態的表單腳本。在瀏覽器中打開頁面並確認以下四點:

  1. 使用 Tab 鍵導航時,每個連結、按鈕和欄位都顯示可見的焦點環。
  2. 按鈕和連結的懸浮和按下狀態有回應。
  3. 提交表單後,狀態訊息會出現並獲得焦點(如果缺失,references/interaction.md 中的「表單提交回饋」會添加此功能)。
  4. 沒有任何東西自動移動:沒有自動播放、沒有循環、沒有揭示效果。

可以選擇性地為懸浮和按下狀態添加時間控制(references/interaction.md 中的「懸浮和按下狀態」)。然後停止。如果你無法打開瀏覽器,請說明原因,並將上述四點列為「未執行」;不要報告頁面已檢查。

當意圖命名了動作時刻時:

  • **每頁一個簽名式時刻。**英雄序列、產品展示、3D 物件。其他所有東西都比它更安靜。
  • **按角色變化,絕不按區塊變化。**回饋速度快(100 到 200 毫秒),進入動畫較慢,滾動連結動畫跟隨滾動。對每個區塊應用相同的淡入上移、緩動和交錯效果是最易識別的生成頁面模式,而且它無法讓訪客學到任何東西。
  • **大多數內容不移動。**訪客正在閱讀的文字永不移動:段落上沒有視差,沒有隱藏區塊直到滾動到才顯示的揭示效果。
  • **展示,而非裝飾。**能夠展示產品如何運作的動畫(一系列狀態、分解視圖、前後對比)才值得其成本。僅僅表達「這個頁面有動畫」的動畫則不然。

在撰寫任何動畫之前,請閱讀 references/foundations.md。它包含持續時間、緩動函數以及被視為生成頁面的模式列表,以及每種模式應採取的替代方案。

將配方應用於頁面

配方是附加到現有頁面上,而不是重新設計它。

  • 來自 landing-skills:landing-build 的靜態頁面會為方向命名的每個時刻留下一個佔位符:一個海報圖片或標註了最終尺寸的標籤佔位符。如果構建過程沒有,請在該元素上標記 data-moment="<名稱>"(名稱來自 Motion and 3D intent),並將配方附加到它上面:將配方的容器類添加到該元素,或透過屬性選擇它。
  • 每個配方的程式碼部分開頭會一行說明它添加的新類(作為此技能新增的)以及它使用且未修改的構建類。添加新類;永遠不要重新定義構建自己的類(.hero、.hero__title、.button、.section、.split 等)。如果配方需要的佈局不在構建的元素中,則用你自己的新元素將其包裹起來。
  • 使用構建的 Token(--color-*、--space-*、--radius-control)來滿足配方所需的任何顏色或大小,絕不使用新的字面值。

選擇配方

選擇能產生效果的最低層級:CSS,然後是小腳本,然後是 GSAP 或 Motion,最後是 WebGL。每個配方都有「使用時機」、「避免時機」、「程式碼」、「減少動畫」和「成本」;3D 配方還會添加「備用方案」。

需求閱讀
持續時間、緩動函數、彈簧、交錯、什麼被視為生成references/foundations.md
英雄進入動畫、分割文字標題、剪裁路徑或遮罩揭示、計數器references/entrances-text.md
滾動進度、滾動連結進入動畫、黏性敘事、固定或水平區塊、平滑滾動references/scroll.md
滾動深度層、指針深度、圖片或影片視差、React 中的視差references/parallax.md
懸浮和按下按鈕時間、表單提交回饋、磁性按鈕、游標跟隨器、傾斜、拖曳、步進轉盤、視圖轉場references/interaction.md
可旋轉的 3D 物件、滾動驅動的分解視圖、用於兩個分離階段的單一上下文、glTF 模型、React Three Fiber 島嶼references/webgl-3d.md
匯入和排除的內容、建置中未使用的解碼器檔案、製作海報、模型壓縮和紋理references/webgl-assets.md
滾動驅動的相機路徑、著色器背景、粒子、圖片失真、WebGPUreferences/webgl-effects.md
使用哪個函式庫、其授權和大小、何時 CSS 就足夠了references/libraries.md
減少動畫的變體、WebGL 備用方案、暫停、預算、保護英雄區域references/safety.md

對於任何 3D 或 WebGL 工作,請先閱讀 references/safety.md(場景配方會匯入其輔助工具),然後閱讀 references/webgl-3d.md 中的「在任何場景之前」,最後才閱讀你需要的配方。

安全護欄

這些規則適用於每個效果。references/safety.md 包含程式碼。

  1. **英雄區域在無 JavaScript 情況下渲染。**標題、導語和行動呼籲都在 HTML 中,並在首次繪製時可見。不要從 opacity: 0 開始標題或英雄圖片:opacity: 0 的元素在顯示之前不會被視為 Largest Contentful Paint (LCP) 候選,因此長時間的進入動畫會延遲 LCP。在 load 事件之後載入 3D 程式碼,並在繪製第一幀之前用海報圖片佔位。
  2. **減少,而不是刪除。**方向文件自身關於減少動畫的陳述優先;以下是預設行為。在 prefers-reduced-motion: reduce 下,移除視差、擦洗式滾動動畫、自動播放循環和大幅移動。保留回饋和短暫淡入。3D 場景僅在靜止且由使用者驅動時載入;跳過它並顯示海報是最簡單的正確選擇。為每個效果編寫減少動畫的變體,並監聽頁面打開時的偏好設定變化。一個將所有動畫持續時間歸零的全域規則本身就是一個可識別的「套路」。
  3. **WebGL 是可選的。**在下載任何 3D 程式碼之前檢查是否有上下文。在 React 中,用錯誤邊界包圍 Canvas。處理上下文遺失。備用方案是真實圖片,絕不是一個空框。
  4. **使用一個 Canvas。**第二個 WebGL 上下文會使記憶體和 GPU 工作量加倍。將相關的 3D 時刻放在一個黏性 Canvas 中。
  5. **離開螢幕後不執行任何操作。**Canvas、影片和循環在離開視野或標籤頁隱藏時停止。
  6. **滾動永不重新渲染框架。**在幀循環中讀取滾動位置,或讓 CSS 驅動它。不要在每次滾動事件或每幀時執行 setState。
  7. **僅對 transform 和 opacity 進行動畫。**永遠不要對 top、left、width 或 height 進行動畫。
  8. **自托管所有資源。**模型、解碼器、環境貼圖和字體來自你的來源。某些輔助工具預設使用第三方 CDN;請覆蓋它們。
  9. **互動需要鍵盤路徑。**指針可以旋轉、拖曳或切換的任何東西,鍵盤也應該可以。

完成標準

在瀏覽器中檢查每個項目。最好使用瀏覽器工具;如果沒有,使用 landing-skills:landing-review 的截圖腳本,並說明你無法執行哪些檢查。

  • Motion and 3D intent 中命名的每個時刻都存在,並且除了回饋狀態之外沒有添加任何其他內容。
  • 停用 JavaScript 時:所有文案和轉換行為都存在。
  • 模擬減少動畫時:頁面完整可讀,沒有自動播放、沒有視差、沒有擦洗動畫;回饋狀態仍然有回應。
  • 停用 WebGL 時(Chromium 標記 --disable-webgl):場景所在位置顯示海報或靜態圖片,英雄文字和行動呼籲不受影響。
  • 英雄文字在載入任何 3D 程式碼之前就可見(透過節流網路來檢查)。
  • 預設情況下,沒有兩個區塊共享相同的進入動畫;簽名式時刻是唯一的大型動畫。
  • Canvas 在滾出視野時停止繪製(檢查效能面板,或如 references/safety.md 中的繪製呼叫計數器)。
  • 網路面板顯示沒有對 3D 資源的第三方主機請求。
  • 在生產構建中,three.js 和其他 3D 程式碼位於不屬於入口套件的 Chunk 中。
  • 鍵盤:每個旋轉、拖曳和切換都能用按鍵操作;焦點保持可見。

「套路」檢測器 detect-tells.mjs 屬於 landing-skills:landing-review,是一個可選輔助工具。如果可用,請在頁面上執行它;它會標記模式層級的「套路」,例如庫存的揭示屬性和減少動畫的「關閉開關」。必需的檢查是用肉眼觀察:在有動畫和減少動畫的情況下分別滾動整個頁面一次,並確認每個移動的元素都具有你為其寫下的角色。

最後,為使用者提供一個簡短摘要:添加的每個時刻及其目的、添加的函式庫及其授權、仍需要的資源(例如用於替換原始佔位模型的真實模型、海報圖片),以及你無法執行的任何檢查。

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

相關技能