snapcn 是做什麼的？
Remotion 影片的複製-貼上元件。這些元件透過 shadcn 安裝，並存放在 components/snap-cn/ 中——你擁有完整的程式碼。
安裝
前置要求：一個 Remotion 專案 (npx create-video@latest)。
# 加入任何元件（使用命名空間的 shadcn 註冊表）
shadcn add @snapcn/text-reveal
# 元件會放置在 components/snap-cn/text-reveal.tsx
@snapcn/<name> 是規範的命名空間形式。它不需要 registries 條目——命名空間已經存在於 shadcn 註冊表目錄中。直接使用註冊表 URL https://snapcn.dev/r/<name>.json 也可以。
相依項目會自動安裝
許多元件會透過 registryDependencies 拉取其他元件——shadcn 會遞迴安裝它們。例如，shadcn add @snapcn/search-typing 也會同時拉取 @snapcn/snap-cn-ui、@snapcn/input 和 @snapcn/caret。
@snapcn/snap-cn-ui是共享的核心函式庫（時間軸折疊鉤子、主題上下文、色彩計算）。大多數 UI 基礎元件都依賴它。你很少會直接安裝它。
兩個層級
snapcn 有兩種元件——它們具有不同的 API：
- 動畫層級 (
snapcn)——文字動畫、轉場、背景、UI 區塊模擬、品牌/社交卡片、完整合成。基於影格驅動。共用屬性：speed（時間倍數），以及用於文字的：fontSize、color、fontWeight。 - UI 基礎元件 (
snap-cn-ui)——基於時間軸驅動的 shadcn 風格基礎元件。目前提供兩種：input和caret。基於狀態的屬性（state、style、size、theme）——開啟/輸入狀態是時間軸的純函數。沒有speed屬性。 建構於@snapcn/snap-cn-ui之上。
元件類別
根據你要建構的內容來選擇。目錄按照每個元件一個檔案的方式拆分，放在 references/components/。從 references/components/index.md 開始——這是一個路由表，按以下類別分組，並為每個元件提供「用於」/「避免用於」訊號。掃描它，挑選候選元件，然後只開啟你需要的 references/components/<name>.md 檔案（包含完整屬性、範例、所有使用/不使用注意事項）。不要讀取每個檔案。
| 類別 | 層級 | 元件 |
|---|---|---|
| 文字與標題 | snapcn | text-reveal, text-swell, text-highlight, text-swap, text-build, word-flip |
| 字幕 | snapcn | word-captions, karaoke-captions |
| AI 聊天輸入 | snapcn | search-typing, prompt-zoom, answer-stream |
| 螢幕與裝置 | snapcn | phone-frame, laptop-frame, terminal-simulator |
| 標誌 | snapcn | logo-assemble, logo-flicker, block-wordmark |
| 場景 | snapcn | announce-title, hero-launch, orbit-gallery, moodboard-reveal, status-cycle |
| 社交證明 | snapcn | follower-rush |
| 特效 | snapcn | pulsing-border |
| UI 基礎元件 | snap-cn-ui | input, caret (+ snap-cn-ui，共享核心函式庫) |
以上就是整個註冊表——共 27 個項目。 沒有著色器、沒有獨立轉場元件、沒有圖表或社交卡片元件、也沒有除了 input 和 caret 之外的 shadcn 基礎元件。如果某個場景需要一個，請自行建構（references/anatomy.md §1）——不要為這個表格中沒有的名稱執行 shadcn add。references/components/index.md 記錄了舊名稱的對應關係。
元件模式
不同層級的慣例不同——不要在基礎元件上使用動畫層級的屬性。
動畫層級 (snapcn)
- 每個元件都有命名的
Props介面（例如TextRevealProps）。 speed?: number——全域時間倍數（預設1），以frame * speed的形式套用。- 文字元件：
fontSize、color、fontWeight。 - 場景之間的轉場不在這個註冊表中——請使用 Remotion 自己的
@remotion/transitions（slide、wipe、fade、flip），並放在<TransitionSeries>內部。 - 根元素上可設定
className?: string。
UI 基礎元件 (snap-cn-ui)
- 基於狀態，不是基於
speed：state（例如"open"/"closed"）、style、variant、size、theme?: Partial<SnapCnTheme>。 - 開啟/關閉/啟動狀態是時間軸的純函數（關鍵幀預設）。
- 透過觸發元素組合模態層基礎元件（對話框、警示對話框、抽屜）——請參閱每個元件的範例。
動畫 API
import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
const scale = spring({ fps, frame, config: { damping: 12, mass: 1, stiffness: 100 } });
// 確定性隨機（永遠不要用 Math.random()）
import { random } from "@remotion/random";
const jitter = random(`seed-${frame}`);
合成結構
import { Sequence, Series } from "remotion";
<Sequence from={30} durationInFrames={60}>
<TextReveal text="Ship it in React" />
</Sequence>
<Series>
<Series.Sequence durationInFrames={60}><SceneA /></Series.Sequence>
<Series.Sequence durationInFrames={60}><SceneB /></Series.Sequence>
</Series>
畫布與時間
- 畫布標準：
1280×720 @ 30fps。元件以此尺寸設計。 - 將每個 Sequence 的預算設定在元件的自然長度附近——請參考
components/index.md中的「長度」欄位（以及每個檔案的「自然長度」）。預算不足會裁切動畫；預算過多會產生空白的停頓。 - 風格匹配： 每個目錄項目都帶有一個
vibe標籤（tech/premium/data/clean/playful/social）——選擇與品牌風格相符的元件。 - 調色板與字型： 保持在函式庫的標記範圍內（
references/design.md→ 標記），以便你自己的元素不會衝突。
設計預設——避免 AI 俗套
當你撰寫自己的文字、場景裝飾或卡片時（不包括預建元件），請保持克制：
- 不要在你新增的主體/標題文字上使用裝飾性的
letter-spacing。 - 不要使用
text-transform: uppercase/ 全大寫的預設——偏好句子大小寫（Launch，而不是LAUNCH）。 - 不要使用漸層文字填充或裝飾性漸層暈染——漸層僅作為有意的背景使用。
- 不要使用發光 / 彩色投影或大的模糊半徑（
blur > ~24px、擴散、多層）——僅使用微妙的 1px 立體感。
例外： 永遠不要從那些本質上就是特效的元件中移除這些效果——word-flip 的漸層文字、block-wordmark 的色彩面板、announce-title 的發光效果、pulsing-border 本身，以及字幕預設中的粗輪廓都是合理的。這些規則管轄的是你新增的內容，而不是函式庫本身。
完整的「做/避免」範例：references/design.md。關於動作品質（時間、預期、分級、緩動），請參閱 references/motion-principles.md。
注意事項（snapcn 專用）
- 沒有提供轉場元件——場景變更應使用
@remotion/transitions的<TransitionSeries.Transition>，而不是 snapcn 元件。text-swap交換的是一行文字，而不是場景。 - 終端機捲動是即時的——使用階梯函數
translateY，永遠不要用 spring 或 ease 來捲動。 - 分割佈局上使用
overflow: hidden——防止在寬度動畫期間內容斷裂。 - 游標閃爍是確定性的——使用
Math.floor(frame / 15) % 2 === 0，而不是間隔計時器。 - 靜態檔案放在
public/——透過staticFile('cursor.svg')載入，而不是使用 import。 - 社交卡片離線渲染——
avatarUrl=""/coverUrl=""會回退到漸層；不進行網路請求。
一般的 Remotion 規則（避免 Math.random()、避免 setInterval、使用 transform 動畫而非 top/left、在渲染前載入字型）位於 Remotion 自己的技能中，而不是這裡：
npx skills add remotion-dev/skills
創作影片
不要只是堆疊元件——創作一個故事。當被要求建立一部完整的影片時（例如「製作一個產品展示」、「更新日誌影片」、「為我的登陸頁面製作開場」）：
- 決定策略——使用現成模板 vs 從元件組合 vs 建立新元件。請參閱
references/anatomy.md§1。 - 遵循節奏——產品展示的節奏是：鉤子 → 定位 → 產品展示 → 功能 → 證明 → 行動呼籲（最後兩個可選）。請參閱
references/anatomy.md§2。 - 使用配方——
references/archetypes/index.md會路由到每個原型的建構方法：內容契約（推斷 → 詢問 → 佔位符）、時長變體、節奏→元件對應，以及一個完整的<TransitionSeries>骨架範例。 - 為每個節奏挑選元件——從
references/components/index.md中選擇；將vibe標籤與品牌匹配，並將每個<Sequence durationInFrames>的預算設定在其自然長度附近。 - 檢查品質標準——一個重點色、句子大小寫的動態文字、真實內容、沒有發光光暈、沒有功能列表列舉、沒有在文字後方放置裝飾性漸層暈染。請參閱
references/anatomy.md§3。
參考資料
references/anatomy.md——創作完整影片：策略（模板/組合/新建）、產品展示的節奏，以及好影片 vs 俗套的品質標準。references/archetypes/index.md——路由到每個原型的建構配方（產品展示旗艦版 + 更新日誌、功能公告、開源專案展示、CLI 工具展示、見證集錦、年度回顧、定價揭露、標誌預告）：內容契約、時長變體、節奏→插槽對應。references/components/index.md——路由表（所有元件，按類別分組，附帶「用於」/「避免用於」訊號）。開啟references/components/<name>.md查看單一元件的完整屬性、範例以及使用/不使用注意事項。references/design.md——反俗套設計預設（做/避免）+ 設計標記（調色板、字型、畫布）。references/motion-principles.md——針對 snapcn + Remotion 調整的動態設計原則。references/anti-patterns.md——常見的生成錯誤及其修正方法。