ppt-review

name	ppt-review
description	Review a generated Slidev deck for visual, structural, and interaction issues. Use when user triggers /ppt-review or when completing the ppt-creator pipeline.

PPT Review

When to Use

• After slides are built and preview URL is available
• When user explicitly triggers /ppt-review
• As Phase 7 of the /ppt-creator pipeline

Review Checklist

For each slide, check the following categories:

1. Overflow & Layout

• No content overflows the 980x552px canvas
• Mermaid diagrams fully contained (no clipping, no overlapping cards)
• Two-column layouts balanced (neither side overflows independently)
• Cards do not overlap or bleed into adjacent elements
• Code blocks with >10 lines have {maxHeight:'200px'}

2. 信息密度与画布使用

• 普通内容页没有明显只使用半屏以下（cover、section、quote、end、强视觉 hero 除外）
• 不存在“标题 + 一句短话”“单个孤立小卡片”“1-2 条 bullet 且无视觉支撑”的意外空泛页面
• standard 页面至少包含 3 个有效信息块，或 1 个主视觉 + 2 个支撑块
• dense 页面至少包含 4 个有效信息块，或数据/代码/图表 + 明确解读
• 页面内容充分体现 outline 的 key_message、content、content_budget
• 连续 3 页 light 不应造成叙事空泛；如不是刻意节奏页，应合并或补充信息
• 修复空泛页面时，优先补充证据、案例、对比、影响、行动建议，或改用 Bento 高信息密度模板

3. Mermaid Diagram Specific

• Every Mermaid has explicit {scale: ...} set
• Full-width Mermaid: {scale: 0.45-0.6}
• Mermaid in two-col layout: {scale: 0.3-0.4}
• Node text <= 8 Chinese chars / 15 English chars
• Mermaid with >8 nodes occupies its own dedicated slide
• Mermaid does NOT coexist with bullet list + another element on same slide
• Mermaid wrapped in height-constrained container if sharing slide with other content

4. Typography

• No title wraps to a second line with only 1-2 characters (shorten or rephrase)
• Chinese titles <= 16 characters
• English titles <= 40 characters
• Heading hierarchy consistent (# for page title, content below)
• Key terms highlighted with accent color, not overused

5. Animation & Interaction

• Max 2 reveal effects per slide
• Adjacent slides use different transitions
• Section dividers use fade, content slides use slide-left
• v-clicks only used when sequential reveal adds comprehension value
• Single-element slides (e.g. one diagram) should NOT have v-click on the only element
• Lists with <= 3 items do not need v-clicks (show all at once)

6. Visual Consistency

• Colors match the selected token set throughout
• Glass-card style consistent (border, radius, padding)
• Icon-box style consistent
• Spacing between cards >= 20px

7. Content Quality

• Every slide has presenter notes
• No placeholder text remaining
• Claims backed by research evidence

8. Narrative & Structure

• CTA (Call to Action) exists on final or near-final slide
• Red thread: each slide's key_message logically connects to next
• Terminology matches audience level (no unexplained jargon for non-technical audience)
• Outline key_messages are reflected in actual slide content (compare with outline.json)
• Story arc follows archetype's narrativePhases progression

9. Factual Accuracy

• Spot-check 3 data claims: find the evidence_ref in presenter notes, trace back to research-report.md finding ID
• No unsourced statistics or percentages
• Dates and version numbers are current (not outdated)
• Company/product names are spelled correctly

10. Design System Compliance

• Headmatter imports global-tokens.css and page-classes.css
• No raw hex color values (all colors via CSS variables var(--ppt-*))
• No raw Tailwind color classes (e.g., text-blue-500) -- use var(--ppt-primary) instead
• Page-classes used where appropriate (.glass-card, .icon-box, .section-bar, etc.)
• Font sizes use design system scale (.ppt-h1 through .ppt-caption)

11. Accessibility

• Text contrast meets 4.5:1 minimum against backgrounds
• Images/diagrams have descriptive alt-text or presenter note description
• Animation count per slide <= 2 (from token maxRevealPerSlide)
• v-motion initial positions are within visible canvas area
• Content is fully readable in PDF export (no information lost to animation sequence)

12. Animation Compliance

• v-mark colors match token accent palette (not arbitrary colors)
• magic-move has <= 3 steps, each step's code diff <= 30%
• frontmatter transition: follows the decision tree in animation-strategy.md
• Presenter notes [click] count matches page's v-click count
• Adjacent slides use different transitions (no repeated transition)

Rebuild Checklist

After applying fixes:

1. List all changes made (slide number + what was fixed)
2. Rebuild: npx slidev build
3. Re-run review on fixed slides to confirm PASS
4. Return updated preview URL

Process

1. Read the slides-<topic>.md file.
2. Walk through each slide separator (---), applying the checklist above.
3. If browser tools are available, open the preview URL and visually inspect.
4. Collect all issues as a structured list:
   • slide: slide number or title
   • category: overflow / density / mermaid / typography / animation / visual / content
   • issue: what is wrong
   • fix: suggested change
5. If issues found:
   • Apply fixes directly to the slides file
   • Rebuild preview (npx slidev build + restart server)
   • Re-check fixed slides
6. If no issues: report "Review passed" with preview URL.

Output

Report format:

## Review Result: [PASS / X issues found]

### Issues Fixed
- Slide 3: Mermaid scale adjusted from 0.5 to 0.35 (was in two-col layout)
- Slide 7: Title shortened from 19 to 14 characters to prevent line wrap

### Remaining Concerns (if any)
- Slide 12: Complex diagram may benefit from splitting into two slides (manual decision)

### Preview URL
http://127.0.0.1:3045/

Standalone Usage

User can trigger /ppt-review at any time on an existing slides file:

/ppt-review slides-<topic>.md

Agent will:

1. Read the file
2. Run the full checklist
3. Fix what it can
4. Rebuild and return updated preview URL