登陸頁面動畫與 3D 效果
為一個已能正常運作的登陸頁面添加動畫與 3D 效果。你所添加的每一個效果都必須有明確的目的、一個減少動畫的變體,以及一個能讓頁面保持完整的備用方案。你開始修改前的頁面本身就是備用方案:如果腳本執行失敗、瀏覽器缺乏某項功能,或訪客要求減少動畫,他們看到的將是那個頁面,而不是一個空白頁面。
輸入
- **
landing/direction.md,Motion and 3D intent章節。**這是你的工作摘要。它會說明none,或者為每個動作時刻命名並解釋其目的。請實現它所命名的內容。不要添加它未命名的動作時刻。 - 由
landing-skills:landing-build構建的靜態頁面,或任何現有頁面。它必須能在停用 JavaScript 的情況下渲染所有文案和轉換行為。請先確認這一點:如果做不到,請在添加動畫前先修復,因為這裡的每個配方都假設靜態頁面是備用方案。 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 已經寫入了懸浮、聚焦、按下和停用狀態,以及一個包含發送、成功和錯誤狀態的表單腳本。在瀏覽器中打開頁面並確認以下四點:
- 使用 Tab 鍵導航時,每個連結、按鈕和欄位都顯示可見的焦點環。
- 按鈕和連結的懸浮和按下狀態有回應。
- 提交表單後,狀態訊息會出現並獲得焦點(如果缺失,
references/interaction.md中的「表單提交回饋」會添加此功能)。 - 沒有任何東西自動移動:沒有自動播放、沒有循環、沒有揭示效果。
可以選擇性地為懸浮和按下狀態添加時間控制(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 |
| 滾動驅動的相機路徑、著色器背景、粒子、圖片失真、WebGPU | references/webgl-effects.md |
| 使用哪個函式庫、其授權和大小、何時 CSS 就足夠了 | references/libraries.md |
| 減少動畫的變體、WebGL 備用方案、暫停、預算、保護英雄區域 | references/safety.md |
對於任何 3D 或 WebGL 工作,請先閱讀 references/safety.md(場景配方會匯入其輔助工具),然後閱讀 references/webgl-3d.md 中的「在任何場景之前」,最後才閱讀你需要的配方。
安全護欄
這些規則適用於每個效果。references/safety.md 包含程式碼。
- **英雄區域在無 JavaScript 情況下渲染。**標題、導語和行動呼籲都在 HTML 中,並在首次繪製時可見。不要從
opacity: 0開始標題或英雄圖片:opacity: 0的元素在顯示之前不會被視為 Largest Contentful Paint (LCP) 候選,因此長時間的進入動畫會延遲 LCP。在load事件之後載入 3D 程式碼,並在繪製第一幀之前用海報圖片佔位。 - **減少,而不是刪除。**方向文件自身關於減少動畫的陳述優先;以下是預設行為。在
prefers-reduced-motion: reduce下,移除視差、擦洗式滾動動畫、自動播放循環和大幅移動。保留回饋和短暫淡入。3D 場景僅在靜止且由使用者驅動時載入;跳過它並顯示海報是最簡單的正確選擇。為每個效果編寫減少動畫的變體,並監聽頁面打開時的偏好設定變化。一個將所有動畫持續時間歸零的全域規則本身就是一個可識別的「套路」。 - **WebGL 是可選的。**在下載任何 3D 程式碼之前檢查是否有上下文。在 React 中,用錯誤邊界包圍 Canvas。處理上下文遺失。備用方案是真實圖片,絕不是一個空框。
- **使用一個 Canvas。**第二個 WebGL 上下文會使記憶體和 GPU 工作量加倍。將相關的 3D 時刻放在一個黏性 Canvas 中。
- **離開螢幕後不執行任何操作。**Canvas、影片和循環在離開視野或標籤頁隱藏時停止。
- **滾動永不重新渲染框架。**在幀循環中讀取滾動位置,或讓 CSS 驅動它。不要在每次滾動事件或每幀時執行
setState。 - **僅對
transform和opacity進行動畫。**永遠不要對top、left、width或height進行動畫。 - **自托管所有資源。**模型、解碼器、環境貼圖和字體來自你的來源。某些輔助工具預設使用第三方 CDN;請覆蓋它們。
- **互動需要鍵盤路徑。**指針可以旋轉、拖曳或切換的任何東西,鍵盤也應該可以。
完成標準
在瀏覽器中檢查每個項目。最好使用瀏覽器工具;如果沒有,使用 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,是一個可選輔助工具。如果可用,請在頁面上執行它;它會標記模式層級的「套路」,例如庫存的揭示屬性和減少動畫的「關閉開關」。必需的檢查是用肉眼觀察:在有動畫和減少動畫的情況下分別滾動整個頁面一次,並確認每個移動的元素都具有你為其寫下的角色。
最後,為使用者提供一個簡短摘要:添加的每個時刻及其目的、添加的函式庫及其授權、仍需要的資源(例如用於替換原始佔位模型的真實模型、海報圖片),以及你無法執行的任何檢查。