Cinematic UI 2.0EN

文件 / 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，以及讓畫格保持確定性的幾條規則。