snapcn

snapcn

适用于 Remotion 视频的复制粘贴组件。组件通过 shadcn 安装，放在 components/snap-cn/ 中——代码由你掌控。

安装

前提条件：一个 Remotion 项目（npx create-video@latest）。

# Add any component (namespaced shadcn registry)
shadcn add @snapcn/text-reveal

# Component lands at 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 是共享核心库（timeline-fold hook、主题上下文、颜色计算）。 大多数 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 开始——这里有一个按以下类别分组的路由表，并为每个组件提供 Use for／Avoid for 指引。浏览表格，选出候选组件，然后只打开你需要的 references/components/<name>.md 文件（完整属性、示例，以及所有适用／不适用说明）。不要阅读每个文件。

类别	层级	组件
文字与标题	snapcn	text-reveal、type-morph、text-swell、text-highlight、text-swap、text-build、text-rewrite、text-select、word-flip、punch-lines、word-gather、word-wheel
字幕	snapcn	word-captions、karaoke-captions
AI 聊天输入	snapcn	prompt-send、search-typing、prompt-zoom、answer-stream、answer-highlight、agent-steps
屏幕与设备	snapcn	phone-frame、laptop-frame、terminal-simulator、screen-recording、cursor-track
徽标	snapcn	logo-assemble、logo-flicker、logo-collapse、logo-drift、block-wordmark、wordmark-cut
场景	snapcn	announce-title、hero-launch、orbit-gallery、moodboard-reveal、status-cycle、count-grid、roster-grant、orb-swarm、reel-collage、card-rail
社交证明	snapcn	follower-rush、channel-thread
效果	snapcn	pulsing-border
UI 基元	snap-cn-ui	input、caret（以及共享核心库 snap-cn-ui）

这就是免费注册表的全部内容——共 47 项（实时列表见 https://snapcn.dev/llms.txt?ref=skill-snapcn；另有 50 项 Pro 组件，见下文）。其中没有着色器、独立转场 组件、图表或社交卡片组件，也没有 input 和 caret 之外的 shadcn 基元。如果场景需要这些内容，请自行构建（references/anatomy.md §1）——不要为 此表中不存在的名称生成 shadcn add 命令。references/components/index.md 列出了已无法安装的 旧名称。

组件模式

不同层级的约定各不相同——不要假定基元支持动画层级的属性。

动画层级（snapcn）

• 每个组件都有命名的 Props 接口（例如 TextRevealProps）。
• speed?: number — 全局时间倍率（默认值为 1），应用方式为 frame * speed。
• 文本组件：fontSize、color、fontWeight。
• 场景间转场不在此注册表中 — 请在 <TransitionSeries> 内使用 Remotion 自带的 @remotion/transitions（slide、wipe、fade、flip）。
• 根元素上提供 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 } });

// Deterministic randomness (NEVER 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 中的 Length 列（以及各文件中的 Natural 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。

注意事项（snapcn 专属）

• 不提供转场组件 — 场景切换应使用来自 @remotion/transitions 的 <TransitionSeries.Transition>， 而非 snapcn 组件。text-swap 替换的是一行文本，而非场景。
• 终端滚动是瞬时的 — 使用阶跃函数 translateY，切勿对滚动使用弹簧／缓动效果。
• 分栏布局使用 overflow: hidden — 避免宽度动画期间内容错位。
• 光标闪烁是确定性的 — 使用 Math.floor(frame / 15) % 2 === 0，而非间隔计时器。
• 静态文件放在 public/ 中 — 通过 staticFile('cursor.svg') 加载，不要使用导入。
• 社交卡片离线渲染 — avatarUrl=""／coverUrl="" 会回退到渐变背景；不会发起请求。

Remotion 的通用规则（不使用 Math.random()、不使用 setInterval、动画使用 transform 而非 top／left、 渲染前加载字体）位于 Remotion 自带的 skills 中，而非此 skill： npx skills add remotion-dev/skills。

编排视频

不要堆砌组件，而要编排一个完整故事。收到制作完整视频的请求（“制作产品演示视频”“更新日志视频”“为我的着陆页制作开场视频”）时：

1. 确定策略——使用现成模板、用组件编排，还是构建新组件。参见 references/anatomy.md §1。
2. 遵循节拍——产品演示视频的结构是 Hook → 定位 → 产品亮相 → 功能 → 证明 → CTA（最后两项可选）。参见 references/anatomy.md §2。
3. 使用配方——references/archetypes/index.md 会指向各类视频的构建方案：内容约定（推断 → 询问 → 占位）、时长变体、节拍→组件槽位，以及完整的 <TransitionSeries> 骨架示例。
4. 为每个节拍选择组件——从 references/components/index.md 中挑选；让 vibe 标签与品牌相匹配，并根据组件的自然时长设置每个 <Sequence durationInFrames> 的时长。
5. 检查质量标准——使用一种强调色、采用句首字母大写的动态文字、使用真实内容，不要添加光晕，不要罗列功能，也不要在文字背后铺设装饰性渐变。参见 references/anatomy.md §3。

工作流

制作完整视频时，请安装适用于该任务的工作流技能。每个技能都会逐个节拍编排这些组件，并确保合成内容通过类型检查且能够渲染：

• npx skills add snapcndev/snapcn --skill remotion-launch-video：产品发布影片、公告、Product Hunt / X 宣传视频。
• npx skills add snapcndev/snapcn --skill remotion-product-demo：基于真实屏幕录制的演示、CLI 和 AI 应用演示。
• npx skills add snapcndev/snapcn --skill remotion-motion-graphics：动态文字、Logo 短动画、数据展示和简短开场。
• npx skills add snapcndev/snapcn --skill remotion-kinetic-typography：动画文字和标题卡片。
• npx skills add snapcndev/snapcn --skill remotion-logo-animation：Logo 揭示、开场和收尾短动画。
• npx skills add snapcndev/snapcn --skill remotion-explainer-video：带有内嵌字幕的旁白解说视频。

snapcn Pro

还包含 50 个组件（version-drop、library-flight、read-through、focus-pull、tap-through、checkout-push、comment-storm、tally-rise 等）、模板，以及 snapcn MCP；它可以让你的 Agent 搜索注册表并查看每个组件的实际属性。只要 components.json 中提供了密钥，Pro 组件的安装方式就和免费组件一样（在 https://snapcn.dev/account?ref=skill-snapcn 上只需三行）；MCP 命令为 claude mcp add snapcn -- npx -y @snapcn/mcp@latest SNAPCN_API_KEY=YOUR_KEY。套餐： https://snapcn.dev/docs/pricing?ref=skill-snapcn

还没准备好使用 Pro？确认邮箱后，即可免费使用一个 Pro 组件 Manifesto： https://snapcn.dev/docs/pricing?ref=skill-snapcn#free

参考资料

• references/anatomy.md — 如何编排完整视频：策略（模板/编排/新建）、产品演示的节拍，以及优质与粗制滥造内容的质量标准。
• references/archetypes/index.md — 各类视频构建配方的索引（产品演示旗舰版 + 更新日志、功能公告、开源项目展示、CLI 工具演示、用户评价集锦、年度回顾、定价揭晓、Logo 片头）：内容约定、时长变体、节拍→槽位映射。
• references/components/index.md — 索引表（按类别分组的所有组件，包含 Use for / Avoid for）。打开 references/components/<name>.md 查看某个组件的完整属性、示例和适用/不适用说明。
• references/design.md — 避免粗制滥造的默认设计规范（建议/避免事项）和设计令牌（配色、字体、画布）。
• references/motion-principles.md — 适用于 snapcn + Remotion 的动态设计原则。
• references/anti-patterns.md — 常见生成错误及其修正方法。