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是共享的核心库（时间轴折叠 hook、主题上下文、颜色计算）。大多数 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 文件（完整属性、示例、所有使用/不使用注意事项）。不要读取每个文件。
| 分类 | 层级 | 组件 |
|---|---|---|
| 文字与标题 | Animation | text-reveal、type-morph、text-swell、text-highlight、text-swap、text-build、text-rewrite、text-select、word-flip、punch-lines、word-gather、word-wheel |
| 字幕 | Animation | word-captions、karaoke-captions |
| AI 聊天输入 | Animation | prompt-send、search-typing、prompt-zoom、answer-stream、answer-highlight、agent-steps |
| 屏幕与设备 | Animation | phone-frame、laptop-frame、terminal-simulator、screen-recording、cursor-track |
| 标志 | Animation | logo-assemble、logo-flicker、logo-collapse、logo-drift、block-wordmark、wordmark-cut |
| 场景 | Animation | 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 |
| 社交证明 | Animation | follower-rush、channel-thread |
| 特效 | Animation | pulsing-border |
| UI 原语 | snap-cn-ui | input、caret（+ snap-cn-ui，共享核心库） |
使用实时组件索引确认哪些名称是可安装的。下面的参考资料包括旧名称及其替代品。
组件模式
不同层级的约定不同——不要在 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>。 - 打开/关闭/激活状态是时间轴的纯函数（关键帧预设）。
- 通过触发元素组合模态层原语（dialog、alert-dialog、drawer）—— 参见每个组件的示例。
动画 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。
注意事项（Imgcli 特有）
- 不提供转场组件 —— 场景切换使用来自
@remotion/transitions的<TransitionSeries.Transition>，而不是 Imgcli 组件。text-swap交换的是一行文字，而不是场景。 - 终端滚动是瞬间的 —— 阶跃函数
translateY，永远不要对滚动使用 spring 或 ease。 - 分割布局上使用
overflow: hidden—— 防止在宽度动画期间内容溢出。 - 光标闪烁是确定性的 ——
Math.floor(frame / 15) % 2 === 0，不使用间隔。 - 静态文件放在
public/目录下 —— 通过staticFile('cursor.svg')加载，而不是通过导入。 - 社交卡片离线渲染 ——
avatarUrl=""/coverUrl=""会回退到渐变；不进行网络请求。
通用的 Remotion 规则（不使用 Math.random()、不使用 setInterval、动画化 transform 而不是 top/left、在渲染前加载字体）位于 Remotion 自己的技能中，不在此技能中：npx skills add remotion-dev/skills。
组成一个视频
不要随意堆放组件——要讲述一个故事。当被要求构建一个完整视频（“制作产品演示”、“更新日志视频”、“为我的落地页制作介绍”）时：
- 决定策略 —— 使用现成模板 vs 从组件组合 vs 构建新组件。参见
references/anatomy.md§1。 - 遵循节拍 —— 一个产品演示是：Hook → 定位 → 产品展示 → 功能 → 证明 → CTA（最后两个可选）。参见
references/anatomy.md§2。 - 使用配方 ——
references/archetypes/index.md路由到按原型构建的指南：内容合约（推断 → 询问 → 占位符）、时长变体、节拍到组件槽位，以及一个完整的<TransitionSeries>骨架示例。 - 为每个节拍选择一个组件 —— 从
references/components/index.md中选择；将vibe标签与品牌匹配，并根据其自然长度为每个<Sequence durationInFrames>进行预算。 - 检查质量标杆 —— 一个强调色、句子大小写的动态排版、真实内容、无发光光环、无功能列表枚举、无装饰性渐变背景。参见
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—— 组成完整视频：策略（模板/组合/新建）、产品演示节拍、以及高质量与低质量内容的分界线。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—— 常见生成错误及其修复方法。