rbrown101010/codex-marketing-skills

HyperFrames

HTML 是影片的唯一真實來源。一個組合是一個帶有 data-* 屬性（用於時間控制）、GSAP 時間軸（用於動畫）和 CSS（用於外觀）的 HTML 檔案。此框架負責處理片段的可見性、媒體播放和時間軸同步。

方法

在撰寫 HTML 之前，請先以高層次思考：

1. 什麼 — 觀眾應該體驗到什麼？識別敘事弧線、關鍵時刻和情感節奏。
2. 結構 — 有多少個組合，哪些是子組合或內聯，哪些音軌承載什麼內容（影片、音訊、疊加層、字幕）。
3. 時間 — 哪些片段決定持續時間，轉場落在哪裡，節奏如何。
4. 佈局 — 先建立最終狀態。請參閱下方的「先佈局後動畫」。
5. 動畫 — 然後使用下方規則加入動態效果。

對於小幅度編輯（修正顏色、調整時間、新增一個元素），請直接跳到規則部分。

視覺識別閘門

按此順序檢查：

1. 專案中存在 DESIGN.md？ → 讀取它。使用其中指定的顏色、字型、動畫規則和「禁止事項」限制。
2. 存在 visual-style.md？ → 讀取它。套用其中的 style_prompt_full 和結構化欄位。（注意：visual-style.md 是專案專用檔案。visual-styles.md 是包含 8 個命名預設的樣式庫 — 是不同的檔案。）
3. 使用者指定了樣式名稱（例如「Swiss Pulse」、「dark and techy」、「luxury brand」）？→ 讀取 visual-styles.md 中的 8 個命名預設。產生一個精簡的 DESIGN.md，包含：## Style Prompt（一個段落）、## Colors（3-5 個十六進位色碼及其用途）、## Typography（1-2 個字型家族）、## What NOT to Do（3-5 個反模式）。
4. 以上皆非？ → 在撰寫任何 HTML 前，先問 3 個問題：
   • 情緒是什麼？（爆炸性 / 電影感 / 流暢 / 技術性 / 混亂 / 溫暖）
   • 深色還是淺色畫布？
   • 有任何特定的品牌顏色、字型或視覺參考嗎？ 然後根據回答產生一個精簡的 DESIGN.md。

每個組合都必須將其色票和字型追溯到 DESIGN.md、visual-style.md 或使用者的明確指示。如果你正在使用 #333、#3b82f6 或 Roboto — 你就跳過了這個步驟。

對於動畫預設值、尺寸、進場模式和緩動函數 — 請遵循 house-style.md。house style 處理「如何」移動。DESIGN.md 處理「看起來像什麼」。

先佈局後動畫

將每個元素放在其最顯眼時刻的位置 — 也就是它完全進入、正確放置且尚未退出的影格。先將其寫成靜態的 HTML+CSS。暫不使用 GSAP。

為何這很重要： 如果你將元素放在其動畫起始狀態（螢幕外、縮放為 0、透明度 0），然後將其補間到你認為它們應該到達的位置，你是在猜測最終佈局。重疊問題在影片渲染前是看不到的。透過先建立最終狀態，你可以在加入任何動態效果之前，發現並修復佈局問題。

流程

1. 找出每個場景的主要影格 — 也就是最多元素同時可見的時刻。這就是你要建立的佈局。
2. 為該影格撰寫靜態 CSS。.scene-content 容器必須使用 width: 100%; height: 100%; padding: Npx; 配合 display: flex; flex-direction: column; gap: Npx; box-sizing: border-box 來填滿整個場景。使用 padding 將內容向內推 — 絕不要對內容容器使用 position: absolute; top: Npx。絕對定位的內容容器在內容高於剩餘空間時會溢出。僅為裝飾性元素保留 position: absolute。
3. 使用 gsap.from() 加入進場動畫 — 從螢幕外/不可見動畫到 CSS 定義的位置。CSS 位置是真實狀態，補間則描述了到達那裡的旅程。
4. 使用 gsap.to() 加入退場動畫 — 從 CSS 位置動畫到螢幕外/不可見。

範例

/* scene-content 填滿場景，padding 定位內容 */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* 容器填滿任何場景尺寸（1920x1080, 1080x1920 等）。
   Padding 定位內容。Flex + gap 處理間距。 */

錯誤 — 硬編碼尺寸和絕對定位：

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

// 步驟 3：動畫進入這些位置
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// 步驟 4：從這些位置動畫退出
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

當元素在時間上共享空間時

如果元素 A 在元素 B 進入同一區域之前退出，兩者都應在其各自的主要影格中具有正確的 CSS 位置。時間軸順序確保它們永遠不會在視覺上共存 — 但如果你跳過佈局步驟，你就不會發現因時間錯誤而導致的意外重疊情況。

什麼是「有意的重疊」

分層效果（文字後的輝光、陰影元素、背景圖案）和 z 軸堆疊設計（卡片堆疊、深度圖層）是有意的。佈局步驟是為了捕捉非預期的重疊 — 兩個標題疊在一起、一個統計數字蓋住標籤、內容溢出畫面邊界。

資料屬性

所有片段

屬性	必要	值
id	是	唯一識別碼
data-start	是	秒數或片段 ID 參考（"el-1"、"intro + 2"）
data-duration	必要（img/div/組合）	秒數。影片/音訊預設為媒體持續時間。
data-track-index	是	整數。相同音軌的片段不可重疊。
data-media-start	否	來源的剪輯偏移量（秒）
data-volume	否	0-1（預設為 1）

data-track-index 不影響視覺層級 — 請使用 CSS z-index。

組合片段

屬性	必要	值
data-composition-id	是	唯一的組合 ID
data-start	是	開始時間（根組合：使用 "0"）
data-duration	是	優先於 GSAP 時間軸持續時間
data-width / data-height	是	像素尺寸（1920x1080 或 1080x1920）
data-composition-src	否	外部 HTML 檔案的路徑

組合結構

透過 data-composition-src 載入的子組合使用 <template> 包裝。獨立組合（主 index.html）不使用 <template> — 它們將 data-composition-id 的 div 直接放在 <body> 中。在獨立檔案上使用 <template> 會將所有內容隱藏起來，破壞瀏覽器渲染。

子組合結構：

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- 內容 -->
    <style>
      [data-composition-id="my-comp"] {
        /* 作用域樣式 */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // 補間...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

在根組合中載入：<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

影片與音訊

影片必須是 muted playsinline。音訊始終是獨立的 <audio> 元素：

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

時間軸契約

• 所有時間軸以 { paused: true } 開始 — 播放器控制播放
• 註冊每個時間軸：window.__timelines["<composition-id>"] = tl
• 框架會自動嵌套子時間軸 — 請勿手動添加
• 持續時間來自 data-duration，而非 GSAP 時間軸長度
• 切勿建立空的補間來設定持續時間

規則（不可協商）

確定性： 禁止使用 Math.random()、Date.now() 或基於時間的邏輯。如果需要偽隨機值（例如 mulberry32），請使用已播種的 PRNG。

GSAP： 僅動畫視覺屬性（opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、變換）。請勿動畫 visibility、display，或呼叫 video.play() / audio.play()。

動畫衝突： 切勿同時從多個時間軸對同一元素的同一屬性進行動畫。

禁止 repeat: -1： 無限重複的時間軸會破壞捕捉引擎。請根據組合持續時間計算精確重複次數：repeat: Math.ceil(duration / cycleDuration) - 1。

同步時間軸建構： 切勿在 async / await、setTimeout 或 Promise 內部建構時間軸。捕捉引擎在頁面載入後同步讀取 window.__timelines。字型由編譯器嵌入，因此立即可用 — 無需等待字型載入。

切勿執行以下操作：

1. 忘記註冊 window.__timelines
2. 使用影片代替音訊 — 始終使用靜音影片 + 獨立的 <audio>
3. 將影片嵌套在計時 div 內 — 使用非計時包裝器
4. 使用 data-layer（請使用 data-track-index）或 data-end（請使用 data-duration）
5. 對影片元素的尺寸進行動畫 — 請對包裝 div 進行動畫
6. 呼叫媒體的 play/pause/seek — 框架擁有播放控制權
7. 建立沒有 data-composition-id 的頂層容器
8. 在任何時間軸或補間上使用 repeat: -1 — 始終使用有限重複
9. 非同步建構時間軸（在 async、setTimeout、Promise 內部）
10. 對後續場景的片段元素使用 gsap.set() — 這些元素在頁面載入時不存在於 DOM 中。請在該片段的 data-start 時間或之後，在時間軸內部使用 tl.set(selector, vars, timePosition)。
11. 在內容文字中使用 <br> — 強制折行