Imgcli

Imgcli 是做什麼的？

專為 Remotion 影片設計的可複製貼上元件。元件透過 shadcn 安裝，會放置於 components/imgcli/ 目錄下 — 您可以完全擁有這些程式碼。

安裝

前置需求：一個 Remotion 專案（npx create-video@latest）。

# 從 Imgcli 套件庫安裝
npx shadcn@latest add https://imgcli.com/r/text-reveal.json

# 元件會放置在 components/imgcli/text-reveal.tsx

若想使用較短的 @imgcli/<name> 格式，請在 components.json 中將 @imgcli 對應至 https://imgcli.com/r/{name}.json。有關專案設定的詳細說明，請參閱 安裝指南。

相依性會自動安裝

許多元件會透過 registryDependencies 引入其他元件 — shadcn 會遞迴地安裝它們。 例如，安裝 search-typing 也會一併安裝 snap-cn-ui、input 和 caret。

• @imgcli/snap-cn-ui 是共享的核心函式庫（時間軸摺疊鉤子、主題上下文、色彩運算）。 大多數 UI 原件都依賴它。您通常不需要直接安裝它。

兩個層級

Imgcli 有兩種元件 — 它們具有不同的 API：

• 動畫層（場景和動畫）— 文字動畫、轉場、背景、UI 模擬、品牌/社交卡片、完整組合。基於影格驅動。共用屬性：speed（時間倍率）、文字類別有 fontSize、color、fontWeight。
• UI 原件（snap-cn-ui）— 時間軸驅動的 shadcn 風格原件。目前提供兩種：input 和 caret。基於狀態的屬性（state、style、size、theme）— 開啟/打字狀態是時間軸的純函數。沒有 speed 屬性。 建構於 @imgcli/snap-cn-ui。

元件類別

根據您要建構的內容來選擇。目錄按照 references/components/ 下的每個元件一個檔案來拆分。從 references/components/index.md 開始 — 這是一個路由器表格，按以下類別分組，並為每個元件提供「適用於」/「避免用於」的提示。瀏覽它，挑選候選元件，然後只開啟您需要的 references/components/<name>.md 檔案（完整屬性、範例、所有使用/不使用注意事項）。不要讀取每個檔案。

類別	層級	元件
文字與標題	動畫	text-reveal、type-morph、text-swell、text-highlight、text-swap、text-build、text-rewrite、text-select、word-flip、punch-lines、word-gather、word-wheel
字幕	動畫	word-captions、karaoke-captions
AI 聊天輸入	動畫	prompt-send、search-typing、prompt-zoom、answer-stream、answer-highlight、agent-steps
螢幕與裝置	動畫	phone-frame、laptop-frame、terminal-simulator、screen-recording、cursor-track
標誌	動畫	logo-assemble、logo-flicker、logo-collapse、logo-drift、block-wordmark、wordmark-cut
場景	動畫	announce-title、hero-launch、orbit-gallery、moodboard-reveal、status-cycle、count-grid、roster-grant、orb-swarm、reel-collage、card-rail、cut-lockup、bloom-lockup、gather-lockup、sky-lockup
社交證明	動畫	follower-rush、channel-thread
特效	動畫	pulsing-border
UI 原件	snap-cn-ui	input、caret（+ snap-cn-ui，共享核心函式庫）

使用線上元件索引來確認哪些名稱是可安裝的。以下參考資料包含舊名稱及其替代名稱。

元件模式

不同層級的慣例不同 — 不要假設動畫層的屬性適用於原件。

動畫層（場景和動畫）

• 每個元件都有名為 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（以及每個檔案的 Natural length）中的 Length 欄位。預算不足會導致動畫被截斷；預算過多則會留下空白時間。
• 風格匹配： 每個目錄項目都帶有一個 vibe 標籤（tech/premium/data/clean/playful/social）— 選擇風格符合品牌的元件。
• 調色板與字型： 請保持在函式庫的權杖範圍內（references/design.md → tokens），以便您自己的元素不會與之衝突。

設計預設值 — 避免 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。

注意事項（Imgcli 專屬）

• 沒有內建轉場元件 — 場景變換應使用來自 @remotion/transitions 的 <TransitionSeries.Transition>，而非 Imgcli 元件。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。

組合影片

不要只是堆疊元件 — 要講述一個故事。當被要求建立完整影片時（「製作產品展示」、「更新日誌影片」、「為我的登陸頁面製作介紹」）：

1. 決定策略 — 使用現成模板 vs 從元件組合 vs 建立新元件。請參閱 references/anatomy.md 第 1 節。
2. 遵循節奏 — 產品展示的節奏是：鉤子 → 定位 → 產品揭露 → 功能 → 證明 → 行動呼籲（後兩項可選）。請參閱 references/anatomy.md 第 2 節。
3. 使用食譜 — references/archetypes/index.md 會導向每個典型模式的建構方法：內容合約（推斷 → 詢問 → 佔位符）、時長變體、節奏→元件對應表，以及一個完整的 <TransitionSeries> 骨架範例。
4. 為每個節奏挑選元件 — 從 references/components/index.md 中選擇；將 vibe 標籤與品牌匹配，並根據其自然長度為每個 <Sequence durationInFrames> 設定預算。
5. 檢查品質標準 — 一個強調色、句子大小寫的動態文字、真實內容、無發光光暈、無功能列表列舉、無在文字後方使用裝飾性漸層。請參閱 references/anatomy.md 第 3 節。

工作流程

對於整部影片，請在可用時使用匹配的工作流程技能。每個技能都會逐個節奏地組合 Imgcli 元件，並在 Remotion 中檢查結果。代理指南涵蓋了安裝與公開元件探索。

• remotion-launch-video 適用於發佈影片、公告、Product Hunt / X 推廣。
• remotion-product-demo 適用於基於真實螢幕錄製的逐步示範、CLI 和 AI 應用展示。
• remotion-motion-graphics 適用於動態文字、標誌片段、統計資料和短開場。
• remotion-kinetic-typography 適用於動畫文字和標題卡片。
• remotion-logo-animation 適用於標誌揭露、開場和結尾片段。
• remotion-explainer-video 適用於附帶燒錄字幕的旁白解說影片。

參考資料

• references/anatomy.md — 組合完整影片：策略（模板/組合/新建）、產品展示的節奏，以及好品質 vs AI 味 的品質標準。
• references/archetypes/index.md — 導向每個典型模式建構食譜的路由器（產品展示旗艦 + 更新日誌、功能公告、開源展示、CLI 工具展示、見證影片、年度回顧、定價揭露、標誌保險槓）：內容合約、時長變體、節奏→元件對應表。
• references/components/index.md — 路由器表格（所有元件，按類別分組，附帶「適用於」/「避免用於」提示）。開啟 references/components/<name>.md 可查看單一元件的完整屬性、範例以及使用/不使用注意事項。
• references/design.md — 反 AI 味設計預設值（應做/避免）+ 設計權杖（調色板、字型、畫布）。
• references/motion-principles.md — 為 Imgcli + Remotion 改編的動態設計原則。
• references/anti-patterns.md — 常見的生成錯誤及其修正方法。