文件 / 09
Kit：每個檔案各做什麼
Cinematic UI kit 的每個檔案，從 reel.js 捲動場景與設計過的剪接，到 grade.js、type-fx.js、plane.js 和 App 模式的骨架，以及各自需要什麼。
kit/ 是沒有任何長相的基礎設施。它的鏡頭與印刷效果全都從零開始，沒有任何東西是必須用的：用它做的兩個網站，不該有任何看得見的共同點。把需要的檔案複製進專案，而且每次新製作開始時都要重新複製，因為舊的複本會過期。
做網站只需要 reel.js 和 reel.css。3D 舞台只是眾多媒材之一。
| 檔案 | 用途 | 依賴 |
|---|---|---|
reel.js、reel.css |
播放頭。[data-scene] 區塊搭配釘住的畫格；每個場景在同一條由捲動驅動的 GSAP 主時間軸上取得 enter、main、exit 片段。以 data-cut 做設計過的剪接。減少動態模式的靜態畫面。任何畫格都能由一個數字重現 |
GSAP |
looks.js |
非擬真媒材的實驗室：水墨、鉛筆素描、像素、網點／riso 與 CRT 的 look，賽璐珞材質與描邊，液態與漸變光圖層，2.5D 圖層，DOM 與 SVG 的手繪線抖動 | three、stage.js（boil 除外） |
stage.js |
3D 或 canvas 作品用的攝影棚：HDR Three.js 管線、環境光照明、可補間的鏡頭 rig 與色彩 look、選用的泛光與景深、品質分級、WebGL 退路 | three |
props.js |
擬真場景的道具間：無縫背景、程序生成的表面貼圖、車旋成形、PBR 材質起點、灰塵 | three、stage.js |
type-fx.js、type-fx.html |
字體部門：四十四種文字表演，分成衝擊、流動、3D、切換、風格等家族以及獎項動作。每個畫格都是進度與時間的純函式，真正的文字留在 DOM 裡。HTML 檔是展示頁 | 無 |
grade.js、grade.html |
給 DOM 網站用的調色，參數與 3D 舞台的 look 相同，另有光暈、顆粒、暗角、漏光與片門晃動。HTML 檔是展示頁 | 無 |
plane.js |
給介面當主角的場景用的 UI 平面鏡頭：真實 DOM 放進 CSS 透視、從極特寫到遠景的景別預設、不靠 WebGL 的 DOM 景深與跟焦、景別稽核 | GSAP（部分功能） |
site-dom.html |
不用 canvas 的網站灰階 animatic：字體、平面圖形、圖片位置。圖形、字體、手繪或攝影的片子從這裡開始 | reel.js |
site.html |
跑在 3D 舞台上的網站灰階 animatic | 以上全部 |
app.js |
App 模式的骨架：狀態存在 URL 的路由、試片狀態、凍結時鐘、快捷鍵、列間導航、抽屜、命令面板、可復原的提示 | 無 |
fixtures.js |
有真實形狀的種子替身資料 | 無 |
app-shell.html |
含全部八種狀態的 App 灰階 animatic。App 模式從這裡開始 | app.js、fixtures.js |
用幾行寫出網站模式
<main>
<section data-scene="arrival" data-still="0.6" style="--length: 250"><div class="frame">...</div></section>
<section data-scene="turn" data-cut style="--cut: 100; --length: 300"><div class="frame">...</div></section>
<section data-scene="plans" data-flow><div class="frame">...</div></section>
</main>| 標記 | 意義 |
|---|---|
data-scene="name" |
一個場景；名稱是 reel.scene() 與試片用的代號 |
--length: 250 |
捲動長度（單位 vh）；畫格會被釘住 length - 100 |
.frame |
鏡頭：sticky、高度正好一個視窗、overflow: clip |
data-flow |
閱讀場景，高度剛好等於內容，不釘住 |
data-cut 搭配 --cut: 100 |
設計過的剪接：這個畫格會疊在前一個畫格之上，被釘住 --cut vh |
data-still="0.6" |
關鍵畫面的位置，同時也是減少動態模式的靜態姿勢 |
data-hold |
標示刻意靜止的場景，試片時不會被標成死停格 |
需要知道的事
- 頁面必須透過 HTTP 提供；ES module 不能從
file://載入。請用支援 byte-range 請求的伺服器（npx serve、Vite 或任何正式的開發伺服器）。沒有 range 的話，瀏覽器無法在影片裡跳播。python -m http.server不支援。 - Animatic 是以 three 0.186.1、GSAP 3.15.0 與 Lenis 1.3.26 驗證的。請固定版本，升級後重新試片。
- 絕對不要把
overflow: hidden放在.frame的祖先元素上，這會讓 sticky 失效；請改用overflow: clip。 - 其他技術棧也行。在 React、Next 或 Astro 裡，保留這套模型（釘住畫格的場景、單一捲動驅動的時間軸、真實的 DOM 文案、任何畫格可重現），把 kit 的想法移植過去，而不是搬它的檔案。
使用 kit 之前請先讀 kit/README.md；它列出了 API，以及讓畫格保持確定性的幾條規則。