TellMotion

TellMotion — 创意 → 主题 → 动画

一个可重复的流程，令牌消耗低。适用于任何适合2D的主题：图表、流程、架构、算法、时间线、概念。（不适用于3D或实景视频。）

本技能布局：themes/（theme.json 目录）· tools/（Node，无依赖）· assets/base（Motion Canvas 模板，包含场景配方）· assets/packs/（可选组件包）· scripts/new-project.sh· references/。

1. 简要说明（一轮对话，仅询问缺失信息）

如果用户已经提供了内容/结构，则不再询问。使用 AskUserQuestion（最多4个问题）询问缺失信息：

1. 主题和内容（如果没有：提出一个虚构的主题并说明）。
2. 时长/节奏（默认：平缓节奏，场景20-60秒）和帧率（默认预览30 / 渲染60）。
3. 设计 — 始终提供以下三个选项：
   • 模板：从目录中使用主题。运行 node tools/list-themes.mjs（紧凑列表）并询问 ID；要可视化浏览，运行 node tools/build-catalog.mjs <tmpdir> 并打开 gallery.html（使用 node tools/serve.mjs <tmpdir> 提供服务）。
   • 自定义设计：编写3个对比鲜明的 theme.json 提案（参见 references/theme-format.md），渲染预览并让用户选择（第2步）。
   • 自带设计：用户提供品牌颜色/字体或 Figma 文件 → 从中派生 theme.json。
4. 组件包：从主题推断，除非不清楚否则不询问，仅添加自定义场景将使用的组件：cloud（架构）、algorithms（排序、树）、charts（数据）、flowchart（流程）、timeline（历史/路线图）、code（编程、CLI）、typography（介绍、引用、A vs B）、science（周期、层级、波浪）、math（方程、函数）、ui（产品演示、用户流程）、maps（地点、旅程）。可自由组合；references/packs.md 列出每个组件。

2. 自定义设计（选择模板时跳过）

1. 在临时文件夹中编写3个 theme.json 提案（复制最接近的目录主题并更改令牌；不同的风格系列，例如技术/趣味/编辑）。
2. 为每个提案运行 node tools/validate.mjs <file>，然后运行 node tools/build-catalog.mjs <out> --themes <folder>。
3. 显示预览：在浏览器窗格中打开 <out>/gallery.html（serve.mjs）或发送 SVG。等待用户选择。
4. 可选的高保真 Figma 路线（仅当用户想要且 Figma 连接器存在时）：references/figma.md。
5. 将选定的主题保存为 <project>/theme.custom.json（并提出将其贡献到目录）。

3. 故事板（在任何动画制作前需经用户批准）

重写动画代价高昂；重写场景列表则不然。仅当是单个场景或用户要求时跳过此步骤。

1. 阅读 references/storyboard.md 和 references/recipes.md，然后编写 storyboard.json：每个场景一个条目，包含其配方（或 custom）、显示内容、时长和实际文本。
2. 运行 node tools/storyboard.mjs validate <file>，然后运行 node tools/storyboard.mjs preview <file> --theme <id|file> --out <tmpdir>。使用浏览器窗格（serve.mjs）显示页面，并在聊天中列出场景。
3. 等待用户批准。修改故事板，而非代码，直到他们同意。之后停止预览服务器。

批准后，自主工作直至交付。

4. 项目

bash <skill>/scripts/new-project.sh <name> --theme <id|path.json> [--pack a,b|all] [--demos]

（--demos 复制每个组件的演示场景：便于学习 API，然后删除演示场景。） 从应包含项目的文件夹运行。每个主题一个项目；为新视频向其添加场景。它会复制模板、应用主题（src/theme.ts、src/fonts.ts）、安装依赖项并在 .claude/launch.json 中注册项目。稍后更改主题：运行 node <skill>/tools/apply-theme.mjs <theme> <project>，然后运行 npm install。

5. 场景

node tools/storyboard.mjs generate <file> <project> 写入每个场景和 src/project.ts。配方场景已完成。每个 custom 场景是一个带有标题、说明和时长的运行占位符：编写其动画，保留这些元素。为此，请阅读 references/motion-guide.md（核心 API、布局配方、陷阱）和 references/packs.md（组件包组件）。重新运行 generate 会保留您编辑过的场景。固定规则：

• 每个块一个场景，位于 src/scenes/ 中，在 src/project.ts 中注册（每个场景附带 .meta 文件）。
• 使用 prepareScene(view, title)；首先调用 enter()，最后调用 leave()；通过 sub.say(text) 实现字幕。
• 文本 ≥ 28 px（1920x1080）；字幕 ≤ 85 字符；每类元素一种类别颜色 + src/config.ts 中的图例（LEGEND）。
• 每个场景仅显示所需内容；使用 glow() 高亮活动元素，使用 dim() 淡化其余元素。
• 可编辑文本、时序和颜色作为每个场景顶部的常量（EDITABLE TEXT 注释）；全局速度在 PACE 中。
• 使用 connect(root, a, b) 连接片段。请求和事件使用 send(root, arrow.points, {shape: 'dot' | 'diamond', to: piece}) 传递，因此形状可区分它们，并且片段在到达时做出反应。
• 切勿在场景中硬编码颜色或字体：使用 config.ts 中的 C、S、FONT、fs()，以便主题可交换。

6. 验证（低成本）

1. 在项目中运行 npm run typecheck，然后运行 node tools/storyboard.mjs duration <project>：如果某个场景与批准的计划相差甚远，则修复它或告知用户。
2. preview_start（项目名称来自 .claude/launch.json）、resize_window 1700x950，然后点击时间线并在 [215,0,800,330] 上 zoom；在一次 browser_batch 中批量执行多次点击+缩放。在时间线上 scroll right 以到达后续场景。
3. 完成后：resize_window 预设 desktop、preview_stop。除非被要求，否则不渲染 mp4。

7. 渲染（被要求时）

在项目中运行 npm run render 写入 output/<name>/<name>.mp4 和 render.json（每个场景的时长、文件大小），而不打开编辑器。选项（在 npm run render -- 后）：

• --format mp4,webm,gif· --thumb 或 --thumb-at <seconds>· --fps <n>· --scale <n>。WebM 编码速度较慢（几分钟）：仅在需要时请求。
• --aspect 9:16,1:1：将视频放入主题背景中并带有横条（--pad-color 覆盖）；不会重新布局场景，因此文本缩小到约 56%。请将此告知用户。
• --draft：30 fps，一半大小，位于 output/<name>-draft/。用于审查。
• --info：每个场景的时长，不进行渲染。成本低：优先使用它而非渲染来检查节奏。
• --dry-run：根据渲染样本估算每个文件的大小范围，不保存任何内容。在进行大型渲染或用户担心大小时使用。

需要 Chrome、Edge 或 Chromium（CHROME 覆盖路径）。在此脚本之前创建的项目：node <skill>/tools/render.mjs <project>。源代码位于 tools/render.mjs。

8. 交付

列出场景（名称 → 显示内容）、如何运行（npm start）、如何渲染（npm run render）、如何更改节奏（PACE）、文本（每个场景的常量）、主题（apply-theme.mjs）。说明未验证的内容。如果工作区有 CLAUDE.md，则将新项目添加到其中。

令牌节省技巧

• 不要重新读取刚写入的文件；使用 Edit。
• 使用 list-themes.mjs 而非读取主题 JSON 文件；仅在自定义时读取单个主题。
• 批处理截图/缩放；避免全页捕获。
• 重用 assets/ 而非重新生成组件。