immersive-web 是做什麼的?
如何打造感覺像頂尖電影與遊戲,載入卻像一般網頁,並且不遺漏任何人的 3D、著色器與滾動驅動體驗。
此技能是一個層級。 ui-craft 技能(同一個外掛)負責一般的介面設計:佈局、層級、字型、顏色、元件、表單、狀態。請用它來處理所有這些事,並且不要在此重複。此技能則在其上增加另一個層級:場景、燈光、材質、著色器、攝影機、滾動與電影級動畫。兩者都讀取相同的主題 Token,因此一個主題驅動頁面與場景(references/theme-bridge.md)。
誠實的限制。 你可以導演一個場景、為它打光、移動攝影機、編寫著色器並匯入模型。但你無法從無到有雕刻出電影品質的 3D 藝術品。請從簡單的幾何形狀、著色器、文字與光線來構圖,或是使用團隊提供的模型。切勿用粗略的主題塗鴉來蒙混過關。
1. 九條鐵律
無論看起來多好,違反任何一條,工作就不算完成。
- 內容優先。 標題、內文、連結與按鈕必須是真實的 HTML,在任何腳本執行前即可閱讀。場景是附加在上面的,消失時也不會造成損失。永遠不要將頁面的文字繪製到 canvas 中。永遠不要為了等待腳本顯現,而在 CSS 中將內容隱藏在
opacity: 0。 - 每個效果都有三種狀態。 完整;減少動畫(靜止幀或短暫淡出:
prefers-reduced-motion,以及原生應用程式中的作業系統設定);無 GPU(當 WebGL 或 WebGPU 缺失、失敗或 context 遺失時,顯示的海報圖像或 CSS/SVG 藝術)。先設計兩種備援方案。它們也是首先載入的內容。備援方案是同一張圖,只是更安靜:從相同角度呈現相同主體(從場景本身製作的海報),對於資料場景,則是以平面方式繪製相同資料。空白方塊、純色漸層或「圖片即將出現」都是失敗。 - 在開始建構前決定速度預算(§4)。頁面的文字先繪製;引擎之後再載入。在手機上,場景的成本必須低於內容。
- 每個頁面只有一個標誌性時刻,並讓它值得被記住。 一個場景,一個想法,完整呈現。其他一切保持安靜。到處都是效果會被認為是套用模板,並使人感到疲倦。節制限制了效果的數量,而非它們的強度:這個唯一的時刻是一個屬於此產品的事件(水壺倒水;當眼睛適應時,天空佈滿星星),要大膽地安排場景,讓人會想告訴朋友。一個只會隨著滾動而轉動的物體不是一個時刻。
- 永遠不要劫持滾動。 瀏覽器負責滾動;你只讀取位置。不要改變速度或方向,不要劫持滾輪,不要使用假的滾動條。使用
position: sticky來固定,保持簡短,並提供跳過的方式。 - 文字與場景永遠不共享空間。 在任何滾動位置,文字都應位於主體旁邊或自己的平面上,絕不跨越主體。覆蓋在場景上的導航與按鈕必須有一層遮罩或一個表面。檢查每一張滾動截圖,而不只是第一張。
- 鍵盤與螢幕閱讀器能觸及所有真實的內容。 Tab 順序遵循閱讀順序。裝飾性的 canvas 設定為
aria-hidden="true";有意義的 canvas 則在旁邊提供文字替代方案。任何能透過拖曳場景做到的事,也必須能透過按鈕做到。 - 動畫會靜止,聲音會等待,沒有閃爍。 環境動畫必須在 5 秒內靜止,或提供可見的暫停控制。聲音在要求之前處於關閉狀態。每秒閃爍次數永遠不超過 3 次。任何內容都不應在螢幕外或隱藏的頁籤中執行。
- 原創與授權。 學習一個類型的語言;切勿複製產品的樣貌、模型、角色、標誌或聲音。只能使用你自己製作的素材,或具有明確授權的素材(像是 Poly Haven 和 ambientCG 這類 CC0 函式庫是安全的),並記錄每一個素材。
2. 工作流程(每次都要這樣做)
-
先觀察,再建構。 找到主題:
theme.css、DESIGN.md(來自 ui-craft Studio)、Token、Tailwind 設定、品牌顏色。讀取--immersive和簡報中的「沉浸式與動畫」部分(如果有的話):它們說明了業主選擇的強度。檢查技術棧(純 HTML、React、Vue、應用程式外殼)和任何已提供的 3D 素材。如果完全沒有主題,先使用 ui-craft 來選擇一個方向。 -
選擇階梯(§3)上的等級。 如果主題有說明就從主題取得;否則,選擇能傳達想法的最低等級。等級 3 很少見。
-
選擇能完成任務的最輕量化工具。
需求 使用 成本 顯示、無視差的滾動效果、頁面轉場 僅 CSS:滾動驅動動畫、 position: sticky、View Transitions0 KB 平面的動態紋理、線條、區域、2D 圖形 Canvas 2D 或 SVG,或在單一三角形上的一個片段著色器(純 WebGL,無函式庫) 2-5 KB 顯示一個可供使用者轉動的 3D 模型 <model-viewer>約 250 KB,惰性載入 一個真實場景:數個物體、燈光、移動的攝影機 three.js(React 應用程式:React Three Fiber),使用動態 import()載入150-180 KB gzip,惰性載入 CSS 無法表達的、與滾動綁定的時間軸 GSAP ScrollTrigger(免費但非開源:載入它,切勿在內部複製它)或 Motion 25-45 KB 最新的 GPU 功能 WebGPU 作為 WebGL 路徑之上的升級,絕不單獨使用 - 不要預設加入平滑滾動函式庫。如果簡報要求,它必須在減少動畫模式下自行關閉。
-
撰寫沉浸式簡報(將其加入 ui-craft 設計簡報中),在編寫程式碼之前:
等級:2 標誌性(主題設有 --immersive:2) 技術棧:純 HTML + three.js,惰性載入 標誌性時刻(一個事件,而非旋轉檯):在第 3 拍時,水壺傾斜,一股細流傾倒而出,保持水柱形狀 場景:一個霧面陶瓷水壺,位於頁面背景的一片光暈中;來自左上方的柔光主光,暖色的邊緣光 文字車道:在桌機上位於左欄,在手機上則位於固定場景下方;水壺從不跨越它 攝影機:類似 35mm,略為俯視,不自行移動 節奏:溫和(--dur-slow 400ms) 拍子(僅限等級 3):1 整個水壺 - 2 壺嘴,特寫 - 3 倒水 - 4 放在桌上的整套 減少動畫:每個拍子一張靜止渲染圖,交叉淡入淡出 無 GPU:同一場景的海報,相同角度 預算:文字先繪製;引擎之後載入;手機上場景低於 1.5 MB;觸控裝置像素比 1.5 -
按此順序建構。 (a) 使用 ui-craft 將整個頁面製作成純 HTML 與 CSS,並在場景位置放置海報或 CSS 備援方案。它必須已經是一個好頁面。 (b) 場景外殼:
assets/scene-shell.js提供惰性啟動、靜止幀、備援方案、螢幕外暫停、像素比上限、context 遺失復原。 (c) 主題橋接:assets/theme-bridge.js使顏色、圓角半徑和節奏來自 Token。 (d) 場景本身,以最簡單的形式。 (e) 動畫與滾動。 (f) 打磨:光線、材質、顆粒感、時間點。assets/starter.html是一個已完成 (a)-(c) 的運作中頁面;取代其中的佔位場景。 -
檢查,然後觀看。 執行
node <skill-dir>/scripts/immersive-check.mjs page.html。它會以五種方式載入頁面(桌機、手機、減少動畫、無 WebGL、無 JavaScript),測量資源大小、繪製呼叫次數、像素比、原生滾動與暫停,並儲存螢幕截圖。對於應用程式視窗(Electron、Tauri、已登入的網頁應用程式),加上--app以跳過無 JavaScript 測試。打開每一張截圖。 修正失敗的部分。最需要仔細觀察的是三張:滾動的中段(是否有任何文字跨越了主體?)、手機的中段(場景與文字是否在同一個畫面中,沒有空白的區塊?)、以及無 WebGL 的那張(是同一張圖,還是個空洞?)。從場景本身製作海報:--poster hero-poster.png會從桌機測試中儲存場景的方塊(--scheme light或dark選擇主題),準備好作為備援圖像使用。然後執行 ui-craft 的ui-audit.mjs來檢查對比度、觸控目標與字型,並以與桌機相同嚴格的標準來評斷手機。最後檢查:references/accessibility-fallbacks.md檢查清單。
3. 沉浸階梯
每個產品都位於一個階梯上。主題可以將其設定為 --immersive: 0-3;16 個 ui-craft 方向中的每一個都設定了一個預設值(references/theme-bridge.md)。
| 等級 | 這是什麼 | 適合 | 不適合 |
|---|---|---|---|
| 0 靜止 | 沒有 3D、著色器或滾動效果。僅有一般介面動畫 | 金融工具、管理後台、政府網站、健康表單、資料密集的儀表板、任何整天都在使用的東西 | - |
| 1 點綴 | 一個安靜的生動細節:一種材質、一個緩慢的著色器紋理、一個 View Transition。幾秒鐘後會趨於靜止。沒有滾動驅動的場景 | SaaS 應用程式、文件、大多數產品 UI、桌機與行動應用程式 | 人們感到焦慮或匆忙的任務 |
| 2 標誌性 | 一個英雄時刻:一個物體或著色器回應滑鼠指標或首次滾動。然後是一般頁面 | 登陸頁面、產品頁面、作品集、入門引導、啟動畫面 | 人們每天重新造訪的頁面 |
| 3 故事 | 一個包含 3-5 個拍子、具有一個持續性場景的滾動驅動序列 | 發表會、活動、編輯專題、博物館與品牌故事 | 應用程式、結帳流程、任何有任務性質的東西 |
階梯規則:等級是一個上限,而非目標。使用頻率會降低等級:一個人看到某個畫面的頻率越高,等級就應越低。任務性質會降低等級:當有人在付費、簽署或解決問題時,使用等級 0。如果不確定,就往下降一級並把它做得更好。
4. 預算
可行的目標。請衡量,而非猜測。標記 * 的數字是合理的預設值,並非公開的限制。
| 項目 | 手機 | 桌機 |
|---|---|---|
| 最大內容繪製 (LCP)(必須是文字或海報,永遠不可是 canvas) | 2.5 秒或更少 | 2.5 秒或更少 |
| 首次繪製前請求的腳本 | 低於 170 KB 壓縮後 | 相同 |
| 引擎(three.js 約 180 KB gzip) | 首次繪製之後,動態 import(),僅在場景接近視埠時 | 相同 |
| 第一場景負載:引擎 + 模型 + 紋理 * | 低於 1.5 MB | 低於 4 MB |
| 英雄模型(GLB,壓縮) * | 低於 2 MB,20-60k 三角形 | 低於 5 MB,最多 100k |
| 紋理 | 1024 px;僅英雄模型使用 2048;使用 KTX2 以節省 GPU 記憶體 | 2048;僅特寫鏡頭使用 4096 |
| 像素比 | 上限 1.5,速度慢時降至 1 | 上限 2 |
| 每幀繪製呼叫 * | 低於 100 | 低於 300 |
| 即時燈光 | 1 個主光(+ 環境光);1 個 1024 的陰影貼圖,或使用烘焙 / 模糊陰影 | 1-3 個;最多 2048 的陰影貼圖 |
| 後處理特效 | 0-1 | 1-3 |
| 幀時間 | 穩定 60 fps;在低於 30 fps 前逐步降低品質 | 60 fps |
| 滾動故事 | 3-5 個拍子,每個 100-150vh,固定滾動範圍在 5 個螢幕以內 *,提供跳過連結 | 相同 |
| 預載入器 | 無;頁面在 1-2 秒內可讀,場景在準備好時淡入 | 相同 |
一個 2048 px 的紋理在解壓縮後約佔用 22 MB 的影片記憶體,無論其檔案大小為何,除非它是 KTX2。詳細資訊與降級順序:references/performance.md。
5. 一個主題驅動所有層級
- 從 Token 中讀取顏色(
--bg、--surface、--accent、--accent-soft、--text、--border...),永遠不要在著色器或材質中硬編碼一個十六進位色碼。assets/theme-bridge.js中的readTheme()會回傳每個顏色,分別用於光照計算的線性 RGB 以及平面繪圖的 sRGB,而watchTheme()則會在淺色/深色模式切換時重新讀取。 - 場景位於頁面背景之上:一個透明的 canvas,或一個等於
--bg的透明顏色。沒有可見的矩形,沒有第二個背景顏色。 - 強調色在 3D 中也保持稀有:一個物體、一盞燈、一條線。大部分保持中性。
- 主題的形狀會延續:圓角半徑變成斜角與邊緣半徑;深度風格變成陰影風格(極細線:細輪廓,幾乎沒有陰影;柔和:寬而柔的接觸陰影;清晰:更緊密且有光澤;唇邊:一個硬偏移邊緣;平面:無)。
- 動畫 Token 設定節奏:
--dur-*和--ease-out決定了攝影機移動和滾動緩動(橋接中的bezier()),因此一個「即時」的工具和一個「緩慢」的奢華品牌,使用相同的程式碼卻會產生不同的移動方式。僅在主題曲線過衝時才使用彈跳效果。 - 文字維持為 HTML,使用
--font-display和--font-sans,覆蓋在 canvas 之上或旁邊。
6. 技巧,簡而言之
場景與攝影機 (references/scene-camera.md)
- 一個主體,一個清晰的輪廓,以及大量的留白空間。首先為手機的長形畫面構圖。
- 長焦鏡頭(視野 20-35 度)能美化物體;廣角鏡頭會產生變形。攝影機移動緩慢且有原因,或者完全不移動。
- 按需渲染。沒有在變化的場景就不繪製任何東西。
光線與材質 (references/materials-lighting.md)
- 來自上方的一盞主光(與 UI 相同單一光源),一個柔和補光,一個邊緣光用來將主體與背景分離。光線永遠不是純白;陰影永遠不是純黑。
- 讓主體落地:一個柔和的接觸陰影,否則它會看起來像漂浮著。
- 在判斷任何事物之前先設定好色彩空間。太暗或褪色是色彩空間的錯誤,而非打光的問題。
- 當場景是靜止時,將光線烘焙到紋理中。這是最便宜的光源。
著色器 (references/shaders.md)
- 著色器是一種有任務的材質、光線或紋理。不是桌布。
- 調色板使用 2-4 個主題色,並在 OKLab 色彩空間中混合,以保持中間色調的乾淨。不要使用彩虹色。
- 增加 2-4% 的顆粒感來隱藏柔和漸層中的色帶。保持片段著色器在手機上的低成本:減少紋理讀取,避免長迴圈。
滾動故事敘述 (references/scroll-storytelling.md)
- 每個拍子都是一個想法,並伴隨一行真實的文字。如果一個拍子沒有什麼可說,就刪掉它。
- 文字正常滾動;場景保持靜止(sticky)並隨之變化。使用 scrub 位置,而非時間。
- 減少動畫會將影片變成幻燈片:每個拍子一張靜止圖。
電影級動畫 (references/cinematic-motion.md)
- 在不同想法之間使用切換或溶解;在一個想法內部移動。停駐在重要的東西上。緩動曲線是表演:是重量,而非裝飾。
- 介面動畫保持 ui-craft 的時間(100-300 ms)。場景與攝影機移動需要 600-1200 ms。頁面轉場 200-500 ms,並且 URL、返回按鈕與焦點必須保持運作。
從 Blender 到瀏覽器 (references/blender-pipeline.md)
- 僅使用 Principled BSDF,將其餘全部烘焙,匯出 GLB,然後壓縮:
gltf-transform optimize,meshopt 或 Draco,KTX2 紋理。檢查檔案...