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 开始——这是一个路由器表格，按这些类别分组，并为每个组件提供 Use for / Avoid for 信号。浏览它，挑选候选组件，然后只打开你需要的 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 |
| Logo | 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>。 - 打开/关闭/活动状态是时间线的纯函数（关键帧预设）。
- 使用触发器元素组合模态层原语（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="用 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，永远不要对滚动使用 spring 或缓动。 - 分割布局使用
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。
组合一个视频
不要倾倒组件——组合一个故事。当被要求构建一个完整的视频时（“做一个产品演示”、“更新日志视频”、“我的着陆页的片头”）：
- 决定策略 —— 使用现成模板、从组件组合、还是构建新组件。参见
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—— 组合完整视频：策略（模板/组合/新建）、产品演示的节拍，以及好设计与低质量设计的质量标准。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—— 常见的自动生成错误及其修复方法。