anima

anima 是做什麼的？

概述

一個作品 = 短篇品牌動態產物：片頭 / 預告 / 公告影片、單張動態插畫或動畫主視覺。HyperFrames 負責動態；anima 讓它看起來像 PageFly。 這是一個設計系統，而非範本庫：可重複使用的不是某個 index.html，而是三個可獨立組合的層級——品牌色板 (references/brand.css，共享識別位於 _pf-brand/)、動態設計準則 (references/style-guide.md)，以及一組品牌動態區塊 (components/)——在 templates/canvas.html 上依個案自由組合。Page Checkup 片頭是第一個實際範例 (examples/before-after/)。與 illustra 採用相同模型（元件庫 + 自由組合 + 設計準則 + 治理機制），但從靜態藝術移植到動態。anima 和 illustra 保持獨立技能——anima 在需要靜態 PNG 時呼叫 illustra；兩者互不兼併。

協調 HyperFrames —— 非重新發明

影片機制（組合結構、時間軸合約、場景轉場、lint/inspect/validate、渲染）：遵循 hyperframes 技能。本技能僅添加：品牌 preset (references/brand.css)、動態設計準則 (references/style-guide.md)、元件庫 (components/)。

此處不重複任何 HyperFrames 創作規則（DRY —— 避免因 HF 升級而不同步）。

使用時機

• 製作短篇 PageFly 品牌動態作品：

  • 片頭 / 預告 / 公告（「PageFly 新功能：…」），
  • 單張動態插畫（一個概念動起來），
  • 動畫主視覺（動態的 Hero 區塊），或
  • 實拍片段：品牌標題卡接著一段真實錄製內容（螢幕錄影、產品示範）。

  前三種是 1600x900 的無縫循環。實拍片段為 1920x1080 且為線性 —— 請在創作前參閱 references/style-guide.md → 實拍片段。

• 個案具有明確拍點：開場停頓、可選的前後對比變形、單一功能停頓。對於動態插畫 / 動畫主視覺，開場標題卡（場景 1）通常可省略。

不適用於： 靜態行銷圖片（請使用 illustra / feature-demo）；非 PF 品牌（請更換 references/brand.css —— 引擎是品牌中立的，PF 僅是預設 preset）。

先決條件（兩個層級）

• 渲染 / 重新換膚已完成的範例： npm hyperframes（透過 npx，首次運行自動取得）+ Node >= 22 + FFmpeg。第一步： 執行 npx hyperframes doctor 並回報任何缺少的依賴，然後再繼續。
• 創作全新的作品： 另外需要 hyperframes 技能家族（創作知識 —— 時間軸合約、轉場、QA）。這些技能位於使用者全域的 ~/.claude/skills/，未包含在此 repo 中 —— 複製 PageFly 不會同時取得它們。anima 攜帶了足夠的 PF 慣例以在沒有它們的情況下進行，但它將所有機制規則委派給它們，因此如果缺少它們，創作品質會急劇下降。

在新機器上首次設定

每台機器執行一次。可安全重新執行 —— 所有步驟都是冪等的。

npx hyperframes doctor                                   # 1. Node >= 22, FFmpeg, Chrome, memory
cd /tmp && npx hyperframes init hf-bootstrap \
             --example blank --non-interactive           # 2. 安裝 HF 技能家族
ls ~/.claude/skills/hyperframes                          # 3. 驗證：SKILL.md + references/
rm -rf /tmp/hf-bootstrap                                 # 4. 用完即棄的 scaffold，刪除它

注意事項：

• 沒有專門的「安裝技能」指令。init 會建立一個專案 並安裝技能 —— 根據其 --skip-skills 說明文字，「init 總是會將 AI 技能與 GitHub 進行比對」（已在 CLI v0.7.108 上驗證；設定 HYPERFRAMES_SKIP_SKILLS=1 可退出）。因此需要一個臨時目錄。請勿在此 repo 內部執行 init —— 它會將 scaffold 散佈到技能樹中。
• init 接受一個專案名稱，而非路徑 —— 請先 cd 到上層目錄，如上所示。
• 它會一次安裝約 15 個技能：hyperframes、hyperframes-cli、hyperframes-media、hyperframes-registry，以及動畫庫適配器（gsap、animejs、css-animations、lottie、three、typegpu、waapi、tailwind）和 website-to-hyperframes。
• HyperFrames 並非 Claude 外掛 —— 請勿在市場中尋找它。
• 渲染需要網路連線。 GSAP 在 templates/canvas.html 和每個範例中都是從 cdn.jsdelivr.net（固定版本 3.14.2）載入的，與上游 hyperframes 模式一致。離線渲染會失敗。

工作流程

1. 了解意圖（先問，再規劃）。 在生成之前，先向成員詢問簡短的重點 —— 哪一種類型（預告 / 動態插畫 / 動畫主視覺）、哪些場景 / 拍點、佈局、轉場 —— 然後呈現一段話的計畫供確認。如果他們說「直接試試看」，就跳過詢問直接進行。開場標題卡（場景 1）是可選的 —— 對於動態插畫 / 動畫主視覺，除非個案需要「PageFly 新功能」的框架，否則可省略。
2. 了解個案 -> 訊息 + 需要哪些拍點（片頭？前後對比變形？單一功能？）。用一句話陳述：什麼是新的，以及為什麼重要。
3. 從舞台開始。 自由形式的新個案 -> 複製 templates/canvas.html（空白品牌 1600x900 舞台，內嵌 brand.css，循環遮罩已接線但未啟用）。前後對比 -> 改從 examples/before-after/ 開始。將工作檔案儲存為個案目錄中的 index.html（HF CLI 會執行目錄下的 index.html；保持已提交的 canvas.html 純淨）。
4. 選擇區塊 從 components/（索引：references/component-catalog.md）。將每個區塊的標記貼到一個場景中，並將其 <!-- Timeline recipe --> 貼到單一的 tl 時間軸中，將偏移量重新設定為該場景的進入時間。注意任何你必須建立的客製部分。顯示素材的區塊（logo-lockup、before-after-card）預期你的 index.html 旁邊有一個 assets/ 目錄 —— 建立它，並從 examples/before-after/assets/pf-logo.svg 複製 PF 標誌，再加上你自己的螢幕截圖裁剪。
5. 套用設計準則 (references/style-guide.md)：緩動函數（每個場景至少變化 3 種）、呼吸發光、循環接縫遮罩、節奏 / 拍點錨點。標籤、眉毛和徽章遵循共享元件庫（_pf-brand/label-rules.md + _pf-brand/badges.html）—— Poppins 字型、句子大小寫、透過 var(--badge-*) 的柔和徽章；絕不使用全大寫的眉毛或金屬藥丸。將結構性和時間軸規則委派給 hyperframes 技能。
6. QA： npx hyperframes lint && npx hyperframes validate && npx hyperframes inspect。修正溢色、對比度和 H.264 條帶。使用 npx hyperframes inspect --at 4.6,5.3 來鎖定特定拍點。
7. 渲染： npx hyperframes render。然後收集可重複使用的部分 —— 執行下面的治理掃描。

嚴格規則

與 references/style-guide.md 保持一致；將完整的影片機制列表委派給 hyperframes 技能。

1. 僅使用品牌變數。 絕不硬編碼品牌顏色 / 圓角 / 陰影 —— 一律使用 var(--...)；透過 color-mix(in srgb, var(--token) N%, transparent) 從實色 token 推導出 alpha 色調（發光 token 已預先內建），因此更換 brand.css 即可重新品牌化。字面例外（根據設計準則）：字型 "Poppins" / "JetBrains Mono"（渲染器無法解析 var(--font-*)）；GSAP 顏色補間；SVG stroke；中性色。
2. 每個場景都是 navy 不透明底色。 無跳接剪輯 —— 場景間是透過不透明 --bg 的模糊交叉淡出（hyperframes 嚴格規則）。
3. 僅有入場動畫，除非是最後一個拍點。每個元素都進行入場動畫（gsap.from / fromTo）；退場補間僅存在於循環尾部。
4. 無表情符號。 圖標是手繪的 —— CSS 圓點、繪製的 SVG 勾選路徑、綠色藥丸 —— 絕不使用 emoji 字元。
5. 確定性。 無 Math.random() / Date.now()；僅限有限次數重複（絕不使用 repeat: -1）—— 渲染必須可重現。
6. 無縫循環（僅循環作品）。 對於預告 / 動態插畫 / 動畫主視覺：發光效果初始隱藏，#loopveil 在接近 T 結尾時淡入到 navy，使最後一幀等於第 0 幀。實拍片段是線性的，非循環 —— 它仍然以遮罩結束以獲得乾淨的尾部，但第 0 幀和最後一幀無需匹配。

檔案對應表

路徑	角色
.claude/skills/_pf-brand/	品牌識別 token + 徽章色板 + 標籤規則的真實來源（brand-identity.css、badges.html、label-rules.md）。它是同級技能目錄，而非 anima 的子目錄 —— 本技能中所有裸 _pf-brand/ 參考都解析到此路徑。Layer A + 徽章從此處同步到 references/brand.css。如今由 anima 使用；illustra 仍保留自己的 fork 於 illustra/references/brand.css，不會讀取此檔案。
references/brand.css	品牌 preset：Layer A 識別 + 徽面色板（從 _pf-brand/ 同步）+ Layer B 影片表面色板。更換以重新品牌化。
references/style-guide.md	動態設計準則：節奏、緩動、發光、循環接縫、轉場、標籤 / 徽章、注意事項。訓練記錄 —— 每次優化都附加於此。
references/component-catalog.md	元件庫索引 + 推廣治理 + 已建構部件的記錄。
components/*.html	自包含的動態區塊（pf- 前綴）：引導註解 + 作用域 <style> + 標記 + 一個 <!-- Timeline recipe -->。貼入個案時間軸。
templates/canvas.html	空白品牌 1600x900 HF 舞台；內嵌 brand.css，循環遮罩已就緒。自由形式個案從此開始。
examples/before-after/	Page Checkup 片頭 = 實際範例，透過 data-composition-variables 參數化。前後對比個案從此開始。

渲染直接使用 npx hyperframes render —— 無需自訂渲染腳本（不同於 illustra 用於 Playwright PNG 的 render.mjs）。

治理 —— 訓練模型（「每次不要重做」）

每次優化都融入共享層，而非棄置檔案：

• 調整品牌顏色 / 發光 -> references/brand.css（識別 + 徽面色板位於 _pf-brand/）
• 更改標籤 / 徽章品味 -> _pf-brand/label-rules.md + _pf-brand/badges.html
• 鎖定新的緩動 / 節奏 / 技巧（「現代 PF」） -> references/style-guide.md
• 一個區塊被手動建構了第二次 -> 將其提升到 components/，透過建議 + 核准。

每個作品完成後，根據 3 個標準掃描你手動建構的部分：

1. 可重複使用 —— 一個通用的動態概念，而非特定於此個案的內容。（「我是否合理地在不同功能上再次建構這個？）」
2. 自包含且可參數化 —— 自有標記 + 作用域 CSS + 清晰的時間軸配方；接受文字 / 顏色 / 大小。
3. 符合品牌且乾淨 —— 僅使用 var，遵循設計準則。

全部 3 項符合 -> 提議提升它：一個新的 components/<name>.html + 一個 component-catalog.md 的已建構部件列（向成員請示是 / 否；絕不自動新增，絕不要求他們判斷技術細節）。 強烈信號： 第二次建構的部件幾乎總是會提升。保持元件庫精簡（YAGNI）—— 在實際個案需要之前不要預先建立部件。每次使用都會充實元件庫 + 設計準則，使得下一個作品的工作量更少。預設關卡 = 建議 + 核准。