Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(animations): guide motion choices by slide semantics

hugohe3d9614aac076b
diff --git a/docs/animations.md b/docs/animations.md
index cfc80487..850a45fa 100644
--- a/docs/animations.md
+++ b/docs/animations.md
@@ -30,13 +30,30 @@ Changing animation settings does not require regenerating the slides. Rerun `svg
| Auto-advance every 5 seconds | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5` |
| Enable automatic element reveals | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto` |
| Use one entrance effect throughout | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation entrance_fade` |
-| Use one native emphasis effect | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation emphasis_spin` |
-| Use one native motion path | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation path_circle` |
-| Use one native exit effect | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation exit_fade` |
| Reveal elements on click | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger on-click` |
| Animate all elements together | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger with-previous` |
| Slow the reveal sequence | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-duration 0.5 --animation-stagger 0.8` |
+## Choose a Page Transition
+
+| Relationship between adjacent slides | Start with |
+|---|---|
+| Ordinary continuation within one section | `fade` |
+| Immediate change with no continuity to preserve | `none` or `cut` |
+| Directional steps, timeline, or visible layer progression | `push`, `wipe`, `cover`, or `uncover` with a meaningful direction |
+| The same object or scene changes position, size, crop, or appearance | `morph` |
+| Section opening, key reveal, or marked state boundary | A selective `split`, `reveal`, `shape`, `flash`, or `random_bars` |
+| A repeated collection advances through one spatial frame | `pan`, `conveyor`, or `ferris_wheel`; use Morph when individual objects must retain identity |
+| The viewpoint travels around or through a continuous space | `rotate`, `window`, `orbit`, or `fly_through` |
+| The theme supports a stage, paper, or physical-page metaphor | A selective `fall_over`, `drape`, `curtains`, `wind`, `prestige`, `peel_off`, `page_curl`, `airplane`, `origami`, or `doors` |
+| A disruptive beat represents breakage, collapse, or dispersal | A selective `fracture`, `crush`, `dissolve`, `vortex`, or `shred` |
+| A marked reveal benefits from a geometric, timed, or textured pattern | A selective `checkerboard`, `blinds`, `clock`, `ripple`, `honeycomb`, `glitter`, or `comb` |
+| A card, panel, gallery, or viewpoint visibly turns or changes face | A selective `switch`, `flip`, `gallery`, `cube`, `box`, or `zoom` |
+
+Keep `fade` or `none` when no other transition adds meaning. Do not change
+effects merely to create variety; `random` is appropriate only when
+unpredictability is itself intentional.
+
The 48 canonical transition keys cover all three sections in the current
PowerPoint gallery:
@@ -75,18 +92,19 @@ an explicitly configured auto-advance timer.
`--recorded-narration` does not support `on-click`; use `after-previous` or `with-previous` for narrated or video-ready output.
-## Choose an Effect
+## Choose an Object Animation
-| Choice | Use it when |
-|---|---|
-| `auto` | You want PPT Master to choose a generic entrance from each content group's role; this is the recommended automatic opt-in |
-| A native `entrance_*` key | You want one of PowerPoint's 53 native entrance presets |
-| A native `emphasis_*` key | An already visible object should draw attention or change appearance |
-| A native `path_*` key | An object should follow one of PowerPoint's 64 motion paths |
-| A native `exit_*` key | An object should leave the slide during the sequence |
-| `mixed` | You need deterministic variation across the canonical entrance pool |
-| `random` | You want seeded variation from the same canonical entrance pool |
-| `none` | You want to disable element animation |
+Start with `none`. When object motion has a communication job, choose its
+lifecycle before its visual effect:
+
+| Communication job | Choice | Boundary |
+|---|---|---|
+| Reveal information in reading or narration order | `auto` or a native `entrance_*` key | This is the usual object-animation case |
+| Redirect attention to an already visible object | An explicit `emphasis_*` key | Do not use it as the object's first reveal |
+| Show meaningful spatial or causal movement | An explicit `path_*` key, or Morph across adjacent slides | The path itself should carry meaning; deliberate background ambience is an advanced exception |
+| Remove, replace, or make room for content on the same slide | An explicit `exit_*` key | A normal slide change already removes the old page |
+| Add deterministic or seeded variation to generic entrances | `mixed` or `random` | These modes still select entrance effects only |
+| No clear motion task | `none` | Keep the slide static |
The canonical registry contains 203 PowerPoint-native keys: 53 entrance, 33
emphasis, 64 motion path, and 53 exit presets. New selections, sidecars,
diff --git a/docs/zh/animations.md b/docs/zh/animations.md
index a702aac3..ca266584 100644
--- a/docs/zh/animations.md
+++ b/docs/zh/animations.md
@@ -28,13 +28,29 @@ OOXML,而不是嵌入视频。对象动画包括进入、强调、动作路径
| 每 5 秒自动翻页 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5` |
| 开启自动元素入场 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto` |
| 全部使用同一种入场效果 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation entrance_fade` |
-| 全部使用同一种原生强调效果 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation emphasis_spin` |
-| 全部使用同一种原生动作路径 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation path_circle` |
-| 全部使用同一种原生退出效果 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation exit_fade` |
| 单击逐个揭示元素 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger on-click` |
| 所有元素同时入场 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger with-previous` |
| 放慢逐步揭示节奏 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-duration 0.5 --animation-stagger 0.8` |
+## 选择页间切换
+
+| 相邻页面关系 | 优先考虑 |
+|---|---|
+| 同一章节内的普通连续叙述 | `fade` |
+| 无需保留连续性的直接切换 | `none` 或 `cut` |
+| 有明确方向的步骤、时间线或可见层级推进 | 按语义方向使用 `push`、`wipe`、`cover` 或 `uncover` |
+| 同一对象或场景的位置、尺寸、裁切或外观发生变化 | `morph` |
+| 章节开场、关键揭示或明显状态边界 | 少量使用 `split`、`reveal`、`shape`、`flash` 或 `random_bars` |
+| 重复内容在同一空间框架中连续推进 | `pan`、`conveyor` 或 `ferris_wheel`;单个对象需要保持身份时使用 Morph |
+| 视点围绕或穿越一个连续空间 | `rotate`、`window`、`orbit` 或 `fly_through` |
+| 主题适合舞台、纸张或实体翻页隐喻 | 少量使用 `fall_over`、`drape`、`curtains`、`wind`、`prestige`、`peel_off`、`page_curl`、`airplane`、`origami` 或 `doors` |
+| 破坏性节点表达断裂、坍塌或消散 | 少量使用 `fracture`、`crush`、`dissolve`、`vortex` 或 `shred` |
+| 关键揭示适合几何、计时或纹理图案 | 少量使用 `checkerboard`、`blinds`、`clock`、`ripple`、`honeycomb`、`glitter` 或 `comb` |
+| 卡片、面板、图库或视角发生可见翻面 | 少量使用 `switch`、`flip`、`gallery`、`cube`、`box` 或 `zoom` |
+
+没有其他切换能增加表达意义时,保留 `fade` 或 `none`。不要只为制造变化而
+更换效果;只有“不确定性”本身就是意图时才使用 `random`。
+
48 个规范页间切换标识已经覆盖当前 PowerPoint 效果库的三个完整分组:
- 细微:平滑 `morph`、淡入/淡出 `fade`、推入 `push`、擦除 `wipe`、
@@ -71,18 +87,19 @@ OOXML,而不是嵌入视频。对象动画包括进入、强调、动作路径
`--recorded-narration` 不支持 `on-click`;带旁白或用于视频导出的 deck 应使用 `after-previous` 或 `with-previous`。
-## 选择动画效果
+## 选择对象动画
-| 选择 | 适用场景 |
-|---|---|
-| `auto` | 让 PPT Master 根据内容组角色选择通用进入效果;这是自动开启元素动画时的推荐选项 |
-| 原生 `entrance_*` | 使用 PowerPoint 的 53 个原生进入预设之一 |
-| 原生 `emphasis_*` | 让已显示对象获得关注或改变外观 |
-| 原生 `path_*` | 让对象沿 PowerPoint 的 64 条动作路径之一移动 |
-| 原生 `exit_*` | 让对象在动画序列中退出页面 |
-| `mixed` | 在规范进入预设池中确定性轮换 |
-| `random` | 从同一规范进入预设池中按固定种子生成变化 |
-| `none` | 关闭元素动画 |
+从 `none` 开始。只有对象运动承担明确沟通任务时,才先选择生命周期,再选择
+视觉效果:
+
+| 沟通任务 | 选择 | 使用边界 |
+|---|---|---|
+| 按阅读或旁白顺序揭示信息 | `auto` 或原生 `entrance_*` | 这是最常见的对象动画场景 |
+| 让已经可见的对象重新获得关注 | 显式 `emphasis_*` | 不用于对象第一次出现 |
+| 表达有意义的空间或因果移动 | 显式 `path_*`,或在相邻页间使用 Morph | 路径本身应承载意义;刻意设计的背景氛围运动属于高级例外 |
+| 在同一页移除、替换内容或腾出空间 | 显式 `exit_*` | 普通翻页已经会移走旧页面 |
+| 为通用进入效果增加确定性或固定种子变化 | `mixed` 或 `random` | 两种模式仍只选择进入效果 |
+| 没有明确的运动任务 | `none` | 保持静态 |
规范注册表包含 203 个 PowerPoint 原生标识:53 个进入、33 个强调、64 条
动作路径、53 个退出。现在新选择、sidecar、自动决策、转换轨迹和示例都只使用
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index 6cf91fea..284fba05 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -242,6 +242,33 @@ The generated names follow Microsoft's
## 3. Page Transitions
+**Reference — not a constraint**: choose a transition from the relationship
+between adjacent pages, not from gallery coverage. Run this playbook before
+selecting a canonical key:
+
+| Pass | Decision |
+|---|---|
+| Relate | Decide whether the destination continues the same object or space, advances in a meaningful direction, opens a new section, or intentionally breaks continuity. |
+| Diagnose | Name the transition's job: neutral continuity, immediate cut, directional progress, object/state continuity, spatial movement, or a deliberate thematic beat. |
+| Select | Use the smallest family that performs that job; keep `fade` when no stronger relationship exists. |
+| Coordinate | Align direction, duration, and recurrence with reading order, narration, and the deck's established motion language. |
+| Stop | Keep `fade` or `none` when another effect adds no meaning; never vary transitions for catalog coverage. |
+
+| Page relationship | Candidate family |
+|---|---|
+| Ordinary continuation within one section | `fade` |
+| Immediate change with no continuity to preserve | `none` or `cut` |
+| Directional steps, timeline, or layer progression | `push` / `wipe`; use `cover` / `uncover` when an overlay relationship is visible |
+| The same semantic object or scene changes across adjacent pages | `morph`; use §2.1 pairs when identity must be deterministic |
+| Section opening, key reveal, or marked state boundary | Selective `split` / `reveal` / `shape` / `flash` / `random_bars` |
+| A repeated collection advances through one spatial frame | `pan` / `conveyor` / `ferris_wheel`; use the §4.2 Morph carousel when individual cards need deterministic identity |
+| The viewpoint travels around or through a continuous space | `rotate` / `window` / `orbit` / `fly_through` |
+| The narrative or theme supports a stage, paper, or physical-page metaphor | Selective `fall_over` / `drape` / `curtains` / `wind` / `prestige` / `peel_off` / `page_curl` / `airplane` / `origami` / `doors` |
+| A disruptive beat represents breakage, collapse, or dispersal | Selective `fracture` / `crush` / `dissolve` / `vortex` / `shred` |
+| A marked reveal benefits from a geometric, timed, or textured pattern | Selective `checkerboard` / `blinds` / `clock` / `ripple` / `honeycomb` / `glitter` / `comb` |
+| A card, panel, gallery, or viewpoint visibly turns or changes face | Selective `switch` / `flip` / `gallery` / `cube` / `box` / `zoom` |
+| Unpredictability is itself the requested behavior | `random`; never use it merely to create variety |
+
```bash
# Pick a different effect
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6
@@ -338,11 +365,22 @@ PowerPoint's separate **Trigger → On Click of** behavior uses row-specific
`trigger_shape`. It links that row to another top-level group while unlinked
rows keep the slide Start mode; it is not a fourth deck-wide Start mode.
-**Lifecycle-first selection**: classify semantic `initial → action → end`
-before choosing an effect: `enter→entrance_*`,
-`emphasize→emphasis_*`, `move→path_*` or Morph, `exit→exit_*`, and
-`static→` no row (or legacy `effect: none` to suppress inheritance). A unit may
-use several ordered `effects[]` rows. There is no category quota.
+**Mandatory — lifecycle before effect selection**: start from `static`, then
+classify semantic `initial → action → end` before choosing an effect. Generic
+staged reveals normally use `enter`; narrower communication jobs select their
+matching lifecycle instead.
+
+| Duty | State contract | Use when | Effect family |
+|---|---|---|---|
+| `static` | present → hold as reference → present | Motion adds no clarity or intended feeling | No row; legacy `effect: none` only suppresses inheritance |
+| `enter` | absent → introduce → present | Information should be withheld, ordered, or revealed with narration | `entrance_*`; modes only for generic reveal |
+| `emphasize` | present → redirect attention → present/altered | An already visible object must regain attention or show a local change; never substitute for its first reveal | Explicit `emphasis_*` |
+| `move` | state/position A → progress → state/position B | The trajectory carries spatial or causal meaning, or §4.1 adopts subordinate ambient motion; use Morph for cross-page continuity | Explicit `path_*`, or endpoint pages + Morph |
+| `exit` | present → retire → absent | The same slide must remove, replace, or make room for content; an ordinary page change needs no object exit | Explicit `exit_*` |
+
+Entrance is the common opt-in family for staged information, not a deck or
+category quota. A unit may use several ordered `effects[]` rows only when it
+has several real lifecycle duties.
The registry exposes two layers:
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 3c32927e..03dc42e6 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -12,7 +12,7 @@
"skills/ppt-master/templates/schemas/*.json"
],
"exclude": [],
- "max_tokens": 393375
+ "max_tokens": 394495
},
"file_budgets": {
"AGENTS.md": 2400,
@@ -186,7 +186,7 @@
"skills/ppt-master/references/svg-effects.md",
"skills/ppt-master/references/native-shape-authoring.md"
],
- "max_tokens": 53040
+ "max_tokens": 53348
},
"route.generate.quick-generate.topic-research": {
"description": "Quick Generate with gap-targeted factual research before direct resource preparation and SVG authoring.",
@@ -196,7 +196,7 @@
"stage.generate.topic-research"
],
"files": [],
- "max_tokens": 54540
+ "max_tokens": 54848
},
"route.generate.quick-generate.icon": {
"description": "Quick Generate with project-local bundled icon selection and synchronization.",
@@ -207,7 +207,7 @@
"files": [
"skills/ppt-master/templates/icons/README.md"
],
- "max_tokens": 54940
+ "max_tokens": 55248
},
"route.generate.quick-generate.in-hand-image": {
"description": "Quick Generate with supplied, extracted, or placeholder image resources prepared before SVG authoring.",
@@ -217,7 +217,7 @@
"stage.generate.executor.image"
],
"files": [],
- "max_tokens": 62925
+ "max_tokens": 63233
},
"route.generate.quick-generate.formula": {
"description": "Quick Generate with manifest-driven formula rendering and formula-image realization.",
@@ -229,7 +229,7 @@
"files": [
"skills/ppt-master/scripts/docs/image.md"
],
- "max_tokens": 66100
+ "max_tokens": 66408
},
"route.generate.quick-generate.ai-two-types": {
"description": "Quick Generate with AI resource preparation, representative rendering inputs, and two local image types.",
@@ -240,7 +240,7 @@
"stage.generate.executor.image"
],
"files": [],
- "max_tokens": 86025
+ "max_tokens": 86333
},
"route.generate.quick-generate.web-image": {
"description": "Quick Generate with web resource preparation, provenance, attribution, and image execution.",
@@ -251,7 +251,7 @@
"stage.generate.executor.web-image"
],
"files": [],
- "max_tokens": 70675
+ "max_tokens": 70983
},
"route.generate.planning-image": {
"description": "Generate-PPTX planning context after a non-none image source is proposed or confirmed, including the compact layout math and vocabulary.",
@@ -702,7 +702,7 @@
"skills/ppt-master/scripts/docs/pptx-transitions.md",
"skills/ppt-master/scripts/docs/svg-pipeline.md"
],
- "max_tokens": 30490
+ "max_tokens": 31302
},
"stage.generate.video-motion-plan": {
"description": "Conditional resolved animation-to-video handoff contract.",
@@ -718,7 +718,7 @@
"files": [
"skills/ppt-master/references/animations.md"
],
- "max_tokens": 7175
+ "max_tokens": 8021
},
"stage.shared.generate-audio": {
"description": "Shared narration-audio stage.",
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index 7e2b31a8..7d588632 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -42,6 +42,23 @@ enable any ordinary capability when the request or deck benefits; use its
normal inputs, flags, and prerequisites without asking for approval. Quick
never creates or reads a Design Spec or lock to enable it.
+**Mandatory — discover motion before deciding whether to load it**: scan this
+compact gate once; do not load the full execution reference when the defaults
+already fit.
+
+| Signal | Action |
+|---|---|
+| The same semantic object or scene continues across adjacent pages | Load [`animations.md`](../../references/animations.md) before SVG authoring; prepare both visible endpoints and use its Morph contract |
+| Page- or object-specific reveal, renewed emphasis, meaningful movement, or same-page removal clarifies the message | Load [`animations.md`](../../references/animations.md) before SVG authoring; preserve the required units/states, then run [`customize-animations`](../stages/customize-animations.md) after the final checker |
+| One deck-wide entrance policy supplies all required staged reveal | Load [`animations.md`](../../references/animations.md) before export and use an exporter flag such as `-a auto`; do not run the custom stage |
+| A directional/section boundary benefits from a non-default transition | Load [`animations.md`](../../references/animations.md) before export and select from its §3 playbook |
+| No earlier signal applies | Keep `fade` transitions and object animation `none`; do not load the motion reference |
+
+This gate activates capability discovery, not motion coverage. Keep the
+defaults when no row supplies a concrete communication job. When several
+signals apply, perform every required action and use the earliest required load
+point; a before-authoring signal always overrides a before-export-only timing.
+
---
## 2. Source and Resource Preparation
diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.md
index 1f93cfb8..d3ef68e2 100644
--- a/skills/ppt-master/workflows/stages/customize-animations.md
+++ b/skills/ppt-master/workflows/stages/customize-animations.md
@@ -140,10 +140,12 @@ There is no target group count. Granularity follows the page's actual claims,
comparisons, sequence, causality, and narration beats.
After any regrouping, rerun the final SVG quality gate because `svg_output/`
-changed:
+changed. Use the owning route's checker form; Quick Generate must add its
+lockless profile flag:
```bash
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path> --stage final --json
+# Quick Generate: insert --quick-generate before --stage.
```
Then list the **post-regroup** anchors:
@@ -195,19 +197,11 @@ relevant transition, object effects, order, and timing. Use
`design_spec.md` for slide role, `spec_lock.md` for rhythm and visual style,
speaker notes for narration order, and SVG group ids for target validity.
-**Mandatory — lifecycle before effect selection**:
-
-| Duty | State contract | Effect family |
-|---|---|---|
-| `enter` | absent → introduce → present | `entrance_*`; modes only for generic reveal |
-| `emphasize` | present → redirect attention → present/altered | Explicit `emphasis_*` |
-| `move` | state/position A → progress → state/position B | Explicit `path_*`, or endpoint pages + Morph |
-| `exit` | present → retire → absent | Explicit `exit_*` |
-| `static` | present → hold as reference → present | Omit; use legacy `effect: none` only to suppress inheritance |
-
-A unit may carry several duties as ordered `effects[]` rows. There is no
-category quota; never reverse-engineer a communication job from an available
-effect.
+**Mandatory — select from meaning, not catalog coverage**: run the
+page-relationship and lifecycle selection playbooks in
+[`animations.md`](../../references/animations.md) §3 and §4 before choosing any
+specific effect. Their candidates are recall aids, not coverage targets; this
+stage binds the selected duties to real targets.
**Title motion decision**: when a title participates, classify its lifecycle,
then choose immediate, delayed, synchronized, post-hero, or narration-cued
@@ -392,12 +386,18 @@ run:
python3 skills/ppt-master/scripts/animation_config.py validate <project_path>
```
-After validation succeeds, return to
-[`generate-pptx.md`](../generate-pptx.md) Step 7.1. Generate owns note
-splitting, `finalize_svg.py`, native export, and the published postflight
-receipt; Step 7.3 reads `<project_path>/animations.json` automatically. If §2
-changed `svg_output/`, complete its required final SVG quality rerun before
-returning. Do not finalize or export independently from this stage.
+After validation succeeds, return to the owning export path:
+
+- Default Generate → [`generate-pptx.md`](../generate-pptx.md) Step 7.1, which
+ owns note splitting, `finalize_svg.py`, native export, and the published
+ postflight receipt.
+- Quick Generate → [`quick-generate.md`](../profiles/quick-generate.md) §4,
+ which skips finalization and exports with `--quick-generate`.
+
+Both exporters read `<project_path>/animations.json` automatically. If §2
+changed `svg_output/`, complete the owning route's required final SVG quality
+rerun before returning. Do not finalize or export independently from this
+stage.
**Validation**: The later native export must reflect the per-slide and
per-object overrides. `--animation none` still disables all per-element