Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
orca-ppt-skill
做一份翻页时看得见连续运动的演示稿。成品是一个 HTML 文件。
两种模式
| 模式 | 适合 | 读哪些规范 |
|---|---|---|
| 汇报稿 | 工作汇报、产品介绍、数据复盘。页面由文字、数字、面板组成 | references/visual-spec.md + references/transitions.md |
| 故事稿 | 讲演变、讲历史。一页一张照片，靠照片里形状的呼应串起来 | references/story-mode.md + references/transitions.md 的「核心原则」「自检标准」 |
用户要某种配色、字体风格时（「米色纸面加墨绿」「像杂志」「换成浅色」）， 读 references/themes.md：先看有没有现成主题，没有就按规范新建一个。不要在稿子里改颜色。
页面里要放一段视频时（引一段实拍素材、把别处录好的片段放进稿子）， 读 references/visual-spec.md 的「整页视频」：素材要先转成 1920×1080 @30fps， 录制时由 capture.mjs 逐帧 seek，不靠真实播放。
页面里要有场景内部的 MG 动画时（成片格子亮起、卡片弹出、拼字、数字滚动，产品概念片）， 用 orca-motion-skill 写场景，本 skill 只管场景之间的转场。场景怎么放进页面见那个 skill 的 references/integration.md。
用户用剪辑软件里的转场名提需求时（推、交叉缩放、圆形划像、溶解、百叶窗……）， 先读 references/premiere-mapping.md，按他想要的感觉选手法，不要照着复刻效果。
产品分栏动画案例
用户要“四栏产品依次切换，最后展开全屏”，或要用内置案例学习共享元素时，读 references/product-showcase.md。演示在 examples/drink-showcase/index.html，分步播放和可复制提示词在 tutorial.html。这个案例用五页状态实现，无需 Remotion 或额外 motion skill；局部字阶、配色、画外待命和时长例外仅限该案例配置。
流程（按顺序，不许跳）
- 装依赖：本 skill 根目录下没有
node_modules/时，先在根目录跑npm install（页面引用里面的 reveal.js 和 GSAP，录制要用 playwright-core）。 - 读规范：按上表读。
- 列内容：每页一个主角。故事稿先写出这一期要推的一个论点。
- 选页面类型：按
visual-spec.md的「先看内容，再选页面类型」挑，先有内容再挑版式。
那张表有一列「严禁用」，撞上了就换一种，不要把内容硬塞进不合适的形状 —— 没有大小关系的东西进图表、不对等的两项并排、凑不满的格子硬撑， 读者看出来的关系都是假的。
- 写转场计划：每次翻页一行，先写两页的「关系」，再选手法。计划作为 HTML 注释放进文件。
- 写页面：汇报稿从
templates/starter.html开始，故事稿从templates/story-starter.html开始，把{{ROOT}}换成
这份 HTML 到本 skill 根目录的相对路径。用主题时，在 tokens.css 后面引入两个文件， 顺序不能反：runtime/themes/<主题>.css 再 runtime/palettes/<配色>.css。 主题只给字体和圆角，颜色全在配色文件里 —— 只引主题不引配色，整份稿子会退回 tokens.css 的默认深底橙色，字体对了颜色全错，而且不报错（示例稿踩过一次）。 配色用主题头里写的「默认配色」，或者换任意一套（九套通用，任意配色配任意主题）。 先读主题和配色文件开头的注释（可以互变的颜色、新增的类）。
- 核版式：
node <skill>/scripts/check-deck.mjs <deck>.html核的是 visual-spec.md 里那些写死了数值的规则 —— 安全区、强调色面积、一页最多一个 .t-metric、强调块上的文字有没有加 .t-on-accent、大数字压在面板上有没有加 .t-on-surface。它不管你把东西放在哪，只核放完之后对不对得上；✗ 要修，· 是提醒。
- 录制：
node <skill>/scripts/capture.mjs <deck>.html -o <deck>.mp4输出末尾「页面报告的问题」必须为空。有报错先修。
工具要解析结果时加 --json <报告>.json：同样的内容（页面自报的问题、每页的转场帧区间 和时长），但是机器可读的。别去解析 stdout —— 那是给人看的，措辞随时会改。
- 看视频：先按正常速度完整看一遍（抽帧拼图代替不了这一步，太快的转场在拼图里看着是连续的）。
再按 capture 打印的「转场帧」区间抽帧，逐条对照 transitions.md 末尾的「自检标准」。 有问题回第 5 步改。
自己没法播放视频时，用帧差量运动：每次转场里，画面变化明显的帧应该连续占满转场区间的大部分， 而不是集中在一两帧。
匹配剪辑（`match-cut`）不适用这一条 —— 它是硬切，本来就没有转场帧。 它只能这样验：取切点前后两帧，确认锚的轮廓完全重合、而画面上其余东西都换了。
放映
浏览器直接打开 HTML，方向键翻页。只有往后翻会播转场，往回翻是直接切。 转场没放完就按下一页，会先把剩下的快进放完再翻，不会跳帧；嵌进别的应用放映时，往前翻调 window.__orcaAdvance()，别直接调 Reveal.next()。
观众里有人会晕、给长辈看、用户说「动得太厉害」时，打开减少动效：URL 加 ?calm，或者 <body data-motion="calm">。整页推近、放大进元素、推近匹配会换成短淡化，运动模糊关掉， 其余手法照旧。默认不开，也不跟系统的「减少动效」设置走 —— 细节见 references/transitions.md 的「减少动效」。
本 skill 带了什么
| 路径 | 内容 |
|---|---|
runtime/tokens.css | 设计变量和样式类（默认主题）。不要改，也不要在稿子里覆盖 |
runtime/themes/ | 其他主题，只覆盖设计变量。可以按 references/themes.md 新建 |
runtime/palettes/ | 配色，只给那 10 个颜色变量。任意配色配任意主题，在主题之后引入 |
runtime/pairs.json | 颜色配对表（哪个类压在哪个类上），check-palettes.mjs 读它 |
runtime/engine.js | reveal 初始化 + 各种转场的实现 + 录制接口 |
scripts/capture.mjs | 逐帧录视频（系统 Chrome，不下载浏览器），打印每次转场的帧区间；--json 出机器可读报告 |
scripts/check-deck.mjs | 核稿子有没有违反 visual-spec.md 里写死数值的规则（npm run deck） |
scripts/check-palettes.mjs | 核配色的对比度（npm run palettes），新建配色必须跑 |
templates/starter.html | 汇报稿起始文件 |
templates/story-starter.html | 故事稿起始文件 |
examples/story-circle/ | 故事模式示例（电话 → 相机 → 电视） |
examples/editorial-forest/ | 主题 + 「整页 ↔ 卡片」示例（封面 → 目录 → 数据页） |
examples/soft-editorial/ | 主题 + 形态变换换布局 + 多合一示例（洞察卡 → 数据面板 → 图表卡） |
示例怎么用
示例是给你看手法和分寸的，不是版式模板。本 skill 没有版式模板，这是有意的 —— 一份稿子的好坏在于每页的构图贴不贴它自己的内容，而模板给的是「填空位」。 要填空位的话，直接用 Keynote 或 PowerPoint 的预设主题就好了，那是它们更擅长的事； 本 skill 的全部价值在页与页之间的连续运动上，而那恰恰是母版格式表达不了的 —— 母版描述一页的结构，它的数据模型里没有「这一页的深蓝方块是下一页的整页底色」这种东西。
所以看示例时，分清两样东西：
| 照着抄 | 不要抄 |
|---|---|
做转场锚的元素的位置 —— 共享元素、形态变换、匹配剪辑的两页必须对得上，visual-spec.md「为转场预留」给的标准位置就是为这个 | 整页的构图。换了内容还照搬坐标，出来的是「别人的页面填了你的字」 |
| 手法怎么选：两页什么关系 → 用哪种转场 | 具体的文案长度、条目个数、面板比例 |
锚点怎么命名、data-* 怎么配对 | 颜色和字号的具体搭配（那是主题和配色的事） |
构图自由是有边界的，边界由 node scripts/check-deck.mjs 核（流程第 6 步）—— 它不管你把东西放在哪，只核放完之后对不对得上。能被事后核的约束，就不必事前锁死构图。
不许做的
- 不许写自己的
<style>，不许在 style 里写颜色和字号。 - 不许自己写 GSAP 或 CSS 动画。转场只用规范里的属性。
- 不许改
runtime/和scripts/下的文件，唯一的例外是按themes.md在runtime/themes/下新建主题。觉得有 bug 就报告。