Powerpoint Slides

PowerPoint Slides Workflow

Academic PowerPoint presentation skill. Full lifecycle: create → compile → review → polish → verify.

Execution model: Claude writes a PptxGenJS (Node.js) script → executes → .pptx. Math formulas: OMML (native math, default) or LaTeX → PNG/SVG pipeline (paragraph-mode fallback).

0. Quick Reference

Parse $ARGUMENTS to determine which action to run. If no action specified, ask.

1. Hard Rules (Non-Negotiable)

1. Motivation before formalism — every concept starts with "Why?" before "What?". Never drop a definition without context.
2. Worked example within 2 slides — every definition must have a concrete worked example within 2 slides of its introduction.
3. Telegraphic style — keyword phrases, not full sentences. Slides are speaker prompts, not manuscripts. Exception: one framing sentence per slide to set context.
4. Every slide earns its place — must contain at least one substantive element (formula, diagram, table, theorem, algorithm, chart). A slide with only 3 short bullets and nothing else must be merged or enriched.
5. Max 2 accent cards per slide — more dilutes emphasis. Accent cards are colored boxes, callout shapes, or highlighted regions. Demote lower-priority items to plain text.
6. Reference slide — the second-to-last slide (before Thank You) must list key cited works. Include the primary paper and 3-5 most relevant references.
7. Color-blind safe palette — blue+orange preferred, never red+green for binary contrasts. WCAG AA contrast ratio ≥ 4.5:1 for text on backgrounds. Semantic colors defined in theme.
8. Font size hierarchy — F constant object defines default baselines: cover 48pt, section 36pt, title bar 22pt, body 15pt, small 12pt, caption 11pt, cardTitle 18pt, tblHead 13pt, tblCell 12pt. Never go below 10pt. When a card or region has sparse content (text fills <50% of available area), scale up by 2-4pt in the QA fix pass.
9. Backup slides — 3-5 after Thank You, separated by an appendix divider slide. For anticipated questions: detailed proofs, extended comparisons, additional data.
10. Verify after every task — execute JS → soffice → PDF → image inspection. No task is complete without visual verification.
11. No AI-signature accent lines — never place decorative lines directly under titles. This is a tell-tale of AI-generated slides and looks unprofessional.
12. Layout diversity — never use the same layout type for 3+ consecutive slides. Alternate among: full-width, two-column, formula-centered, stat-callout, icon-grid, timeline, table, chart, etc.
13. Formula rendering — OMML (native PowerPoint math) for display/inline formulas (default). PNG@600DPI or SVG for paragraph-mode formulas (fallback). Blurry image formulas unacceptable.
14. 16:9 layout, 0.5" margins — LAYOUT_16x9 (10" x 5.625"). Maintain 0.5" breathing room on all four sides. Content area: 9" x 4.625".
15. Never reuse PptxGenJS option objects — the library mutates objects in-place (e.g., converting shadow values to EMU). Always create fresh objects per call. Use factory functions: const makeShadow = () => ({...}).
16. No # prefix on hex colors — use "FF0000" not "#FF0000". The # prefix corrupts the output file silently.
17. Visual theme consistency — the chosen palette applies globally: slide backgrounds, text colors, formula foreground, chart colors, accent card fills, divider lines. No off-theme colors.
18. No Unicode math approximations — never use Unicode subscripts (₀, ₁), superscripts (ᵖᵉ), or special math symbols (∑, ∏, ∈, ∀, ∝) as plain text inside cards or text boxes. All mathematical notation — including inline formulas, variable-with-subscript, Greek letters in equations — must be rendered via OMML (preferred) or the LaTeX image pipeline (for paragraph mode). For card bodies that mix text and math, use OMML placeholders for individual formulas or render the entire body as a single LaTeX image. The only exceptions: simple single Latin letters (x, y, n) and plain numbers without operators.
19. Vertical content distribution — content below the title bar must span ≥75% of CH vertically. If all elements end in the upper half, something is wrong: increase card heights, add spacing, scale up fonts, or add a summary/insight card at the bottom. Every content slide should feel "filled" — no large empty patches below the last element.
20. Content density lower bounds — a slide with ≤3 short text-only bullets (no formula, diagram, table, or card) is too sparse — merge with an adjacent slide or enrich with a visual element. Pure text-only slides should be ≤20% of the total deck. Each card must contain enough text to fill ≥40% of its interior area; if not, scale up font by 2-4pt or merge cards.
21. Boundary validation — every element must satisfy y + h ≤ SH - M (5.125"). During script generation, mentally verify each element's bottom edge before writing it. Common traps: stacking cards below a table without accounting for table rendered height; addCardFormula with a formula image taller than the card body area; two-row card layouts where the second row overshoots. When using addCardFormula, the formula height parameter fH must be ≤ cardH - 0.75 (title area). If content cannot fit, reduce card height, shrink formula targetH, or split across two slides. The visual QA agent must specifically flag any element whose bottom edge is clipped by the slide boundary.
22. Reference slide formatting — strictly single-column layout. Divide CH equally among N references, each entry vertically centered in its row. Use F.body.size font (or F.small.size if many entries). No divider lines, no decorative elements — just evenly distributed text rows filling the page. If references exceed 8 per page, continue on a second reference slide. The reference slide must look evenly filled — no large blank patches at top or bottom.
23. OMML post-processing & sizing — after PptxGenJS generates the .pptx, run inject_omml.py to replace {{MATH:id}} placeholders with native OMML math. Verify zero residual {{MATH: placeholders in the output. OMML formulas display as blank or distorted in LibreOffice — this is expected and not a bug. Only check image formula clarity in visual QA. CRITICAL OMML sizing rule: OMML formulas render at the text box's font size and do NOT respect the text box height constraint — tall constructs like \sqrt{}, \frac{}{}, \sum, \prod will visually overflow the text box. To prevent overlap: (a) never place an OMML formula directly above or below a card/table with tight spacing — leave ≥0.15" extra vertical gap per level of nesting (fractions, roots, large operators); (b) for complex formulas with roots, fractions, or stacked operators, prefer image rendering ("render": "image" in formulas.json) which respects exact pixel dimensions; (c) when using addMathText with F.body.size (15pt), expect the rendered height to be ~0.4" for simple formulas but up to 0.7" for formulas with \sqrt{} or \frac{}{}; (d) when an OMML formula must appear between two elements, compute spacing as if the formula is 1.5–2× the targetH parameter.
24. Diagram engine selection — Graphviz for structural/flow diagrams (architecture, dependency, comparison, tree). Mermaid for behavioral/temporal diagrams (sequence, state, Gantt, ER). TikZ only for math-intensive or paper-faithful reproductions. Don't use Graphviz for sequence diagrams, don't use Mermaid for complex node layouts.
25. Diagram theme consistency — all rendered diagrams must use the current theme's colors. Node fill = cardFill equivalent, borders = ac.pos, text = tx.pri. Graphviz/Mermaid default colors (blue/black) must never appear in final output. Pass --theme to render_diagrams.py.
26. Text overflow prevention & padding — PptxGenJS text boxes do NOT clip overflow — text that exceeds the box renders outside, overlapping elements below. Three mandatory protections: (a) shrinkText: true on ALL text boxes (maps to <a:normAutofit/>). NEVER use autoFit: true — it maps to <a:spAutoFit/> which expands the shape. (b) Card text uses const px = x + 0.25, pw = w - 0.4 — giving 0.19" clear of accent bar and 0.15" from right edge. Title: (px, y+0.1, pw, 0.4), body: (px, y+0.48, pw, h-0.62) with margin: [2, 0, 8, 0]. (c) Vertical gap discipline: every element placed below another must start ≥0.1" after the previous element's bottom. Use gap() helper to verify at script-generation time. Standalone addText calls between cards/formulas are the #1 source of overlap bugs — always compute y from the preceding element's known bottom, never approximate. Content limit: card body should have ≤4 short lines per inch of body height. If more text is needed, increase card height or split content.
27. Figure attribution — figures extracted from papers must include source attribution (Source: Author et al., Year) via addFigure() caption. Width <800px requires warning to user about projection blur. Never extract tables — rebuild with PptxGenJS addTable().
28. Visual-first planning — audiences grasp structure through visual anchors, not bullet lists. During Phase 2, ask for each slide: "Can the audience understand this in 10 seconds from text alone?" If not, the slide needs a visual element (diagram, table, chart, or figure). Common signals: multi-step processes, component relationships, data comparisons, hierarchies, numerical trends — these almost always need visuals rather than prose. Phase 2 self-check: every section has ≥1 non-formula visual element; slides with zero visuals (no diagram, table, chart, or figure) must stay ≤30% of the deck.
29. Table cell formulas — math notation inside table cells (O(n), ε, ∑_{i}, etc.) must use OMML placeholders ({{MATH:id}}), never Unicode approximations or plain text. Add each cell formula to formulas.json with "render": "omml". OMML inherits the cell's font size (F.tblCell.size = 12pt) automatically. For complex constructs (fractions, large operators, stacked expressions) that would overflow cell height, use image rendering ("render": "image") with targetH ≤ rowH - 0.08. Pass cell objects to addTable for OMML cells: {text: "{{MATH:f42}}", options: {}}.
30. Long table pagination — tables exceeding the per-slide row limit (8-10 data rows) must be split across slides. Each continuation slide repeats the header row and appends " (cont'd)" to the slide title via addTableCont(). Split at logical row group boundaries (e.g., between algorithm families, metric categories, dataset groups) — never mid-group. The last page should have ≥3 data rows; if fewer, merge with the previous page. Each page gets its own caption/takeaway if the subset tells a different story.
31. Figure aspect-ratio-aware layout — when embedding extracted paper figures, choose layout based on the figure's width/height ratio (from manifest metadata or measured dimensions): ratio > 1.6 (wide) → full-width centered via addFigure(). Ratio ≤ 1.6 (normal/tall) → figure-left + text-right via addFigureWithText(). Never stretch or crop figures to fit — always preserve original aspect ratio. Compute figRatio from manifest: width_px / height_px (PNG) or width_pt / height_pt (SVG). Cap figure width at 60% of CW in side-by-side layout to leave room for explanation bullets.
32. Alignment consistency — elements of the same type on the same slide (e.g., multiple cards, multiple bullets, multiple formulas) should share identical x-coordinates and consistent widths. Tolerance: ≤0.05" deviation. The check_overlaps.py alignment check (run in Phase 5) flags misalignment. Common violations: card columns with slightly different x-offsets, formula images that aren't centered on the same axis, bullet lists at inconsistent left margins. When using cols2() or manual column positioning, always derive x from the same constant — never approximate.
33. Speaker notes (optional) — if the user requests speaker notes or the presentation is for a talk where notes would help (e.g., journal club, defense), generate notes per slide via addNotes(slide, text). Notes should be telegraphic talking points (3-5 per slide), not full scripts. Include: key message, transition to next slide, potential audience questions. Notes are embedded in the .pptx Notes pane — visible in Presenter View. This is opt-in: only generate when user explicitly requests or when asked during Phase 1.

2. Color Themes & Visual System

5 themes: Academic Light (default), Midnight, Ocean, Forest, Sandwich.

Read references/themes.md for full theme JSON blocks, slide master definitions, typography table, semantic colors, script template, and scoring rubric. These are needed in Phase 4 (script generation) and Phase 5 (QA scoring).

Key points (always in context):

• 4 slide masters per theme: TITLE_SLIDE, SECTION_SLIDE, CONTENT_SLIDE, THANK_YOU
• Typography: Georgia (titles) + Calibri (body)
• Semantic colors: positive=0173B2, negative=DE8F05, emphasis=029E73, neutral=8C8C8C
• Sandwich theme has dual formula colors (light bg + dark bg variants)

2.1 Layout Type Pool

3. Actions

3.1 create [topic] — Full Pipeline (Phase 0-5)

Collaborative, iterative presentation creation. Strict phase gates — never skip ahead.

Phase 0: Material Analysis

Read first, ask later. Must understand the content before asking meaningful questions.

• Read the full paper/materials thoroughly
• Extract: core contributions, key techniques, main theorems, comparison with prior work
• Map notation conventions
• Identify logical structure and slide-worthy sections
• Note: prerequisite knowledge, natural section boundaries, what could be skipped or expanded

Do NOT present results or ask questions yet — proceed directly to Phase 1.

Phase 1: Requirements Interview (MANDATORY)

Conduct a content-driven interview via AskUserQuestion. Questions are informed by Phase 0 analysis.

Required questions (always ask):

1. Duration — How long is the presentation?
2. Audience level — Who are the listeners? (experts, graduate students, general academic)
3. Prerequisites — List concrete technical dependencies from Phase 0. Ask which the audience knows.
4. Content scope — Offer the paper's actual components as options. Which to emphasize, skip, or briefly mention?
5. Depth vs breadth — If the paper has both overview and detailed constructions, ask preference.
6. Visual style — Which theme?
   • A) Academic Light — white/light gray, clean and precise (default)
   • B) Midnight — dark throughout, tech/premium feel
   • C) Ocean — blue tones, professional academic
   • D) Forest — green natural tones
   • E) Sandwich — dark title/conclusion + light content
7. Speaker notes (optional) — Would you like speaker notes in the Presenter View pane? Useful for journal clubs, defenses, or rehearsing. If yes, notes will be generated as telegraphic talking points per slide.

Slide count heuristic (~1 slide per 1.5-2 minutes):

Talk-type tips — different formats demand different strategies. Misjudging the format is the #1 cause of bad presentations:

Pacing principle: spend 40-50% of time on core content (results/techniques). Max 3-4 consecutive theory-heavy slides before a worked example or visual break — audiences disengage after ~5 minutes of uninterrupted formalism.

Phase 2: Structure Plan (GATE — user must approve)

Detailed outline per section:

• Section title
• Allocated slide count
• Key content points per slide (1-2 lines)
• Layout type for each slide (from layout pool in Section 2.4)
• Planned diagrams/charts (brief description)
• Notation to be introduced

Phase 2 self-check before presenting:

• Each section has ≥1 non-formula visual element (diagram, table, chart, or figure)
• Slides with zero visuals ≤30% of deck (R29)
• Every multi-step process, component relationship, or data comparison has a planned visual — not just bullets

Present the plan. Ask: structure OK? User must approve before proceeding.

Phase 3: Formula Preparation

1. Scan Phase 2 structure, collect all formulas into a list. Include table cell math (R30): scan every planned table for cells containing subscripts, Greek letters, operators, or complexity notation — each becomes a separate formulas.json entry with "render": "omml".
2. Write formulas.json with render field ("omml" | "image" | "auto"; default "auto" → paragraph→image, else→omml):

   [
     {"id": "f01-entropy", "latex": "H(X) = -\\sum_{x} p(x) \\log p(x)", "mode": "display"},
     {"id": "p01-body", "latex": "\\begin{minipage}{8cm}...", "mode": "paragraph", "fg_color": "1A1A2E"}
   ]

3. Run renderer (only renders image entries; omml entries get manifest metadata only):

   python ~/.claude/skills/powerpoint-slides/scripts/render_latex.py formulas.json formulas/

4. Check formulas/manifest.json for errors. Fix LaTeX or fall back to plain text.

Sandwich theme: OMML formulas inherit text color automatically — no dual rendering needed. Only image-rendered formulas (paragraph mode) need two variants:

[
  {"id": "p01-light", "latex": "...", "fg_color": "2D3436", "mode": "paragraph"},
  {"id": "p01-dark",  "latex": "...", "fg_color": "FFFFFF", "mode": "paragraph"}
]

Math-heavy paragraphs (MANDATORY — Hard Rule 18): scan every card body and text box planned in Phase 2. If ANY of these appear, the text MUST be rendered as a LaTeX image (not Unicode approximations):

• Subscripts or superscripts (x_i, e^{ax}, H_0)
• Greek letters in equations (α, β, Σ, ∏)
• Operators with operands (∈, ⊆, ∝, ≥)
• Fractions, summations, products, integrals

For isolated formulas (display/inline): use OMML (default render:"auto" handles this). For card bodies with mixed text+math: render the entire paragraph as a single LaTeX image using \text{} for non-math words — add to formulas.json with "mode": "paragraph" (auto-routes to image). In Phase 4, embed via addFormula() / addCardFormula() — helpers auto-route based on manifest.

Error recovery: if render_latex.py reports errors in manifest ("error": "..."), fix the LaTeX source, re-run. Fallback: render as plain text in PptxGenJS.

Phase 3-4 iteration: if Phase 4 discovers additional formulas needed, append to formulas.json and re-run incrementally.

Phase 3.5: Diagram Preparation

1. Scan Phase 2 structure, identify diagrams and visual elements that need rendering.
2. Classify each into the 5-layer pipeline:
   • graphviz — architecture, flow, dependency, neural network, tree, comparison diagrams (DOT language)
   • mermaid — sequence, Gantt, pie, state, ER diagrams
   • tikz — math-intensive, geometric constructions, paper-faithful reproductions
   • shapes — simple annotations, arrows, highlights (PptxGenJS native — handle in Phase 4, not here)
   • extract — figures from paper PDFs (extract-figures workflow)
3. Write diagrams.json (see diagram-rendering.md for schema).
4. MCP pre-extraction (for type: "extract" entries without crop): For each such entry, try MCP extraction before running the batch renderer:

   mcp__pdf-mcp__pdf_extract_images(path=SOURCE_PDF, pages=PAGE, output_dir="diagrams")

   • Images saved directly to diagrams/ as PNG files (original resolution, zero token cost).
   • From returned metadata, pick the largest on the target page (max width * height).
   • Rename to match diagram ID: mv diagrams/page3_img0.png diagrams/<id>.png
   • If MCP returns no images or fails → leave for render_diagrams.py fallback.
   • Entries with crop always skip MCP (page-region extraction needs pdftoppm).
   • The batch renderer auto-skips IDs whose .png already exists on disk.
5. Run the renderer:

   python ~/.claude/skills/powerpoint-slides/scripts/render_diagrams.py diagrams.json diagrams/ --theme <theme_name>

6. Check diagrams/manifest.json for errors. Fix DOT/Mermaid syntax or degrade to PptxGenJS shapes.

DOT writing guide: max ~15 nodes, rankdir=LR for horizontal flows / rankdir=TB for vertical hierarchies, subgraph cluster_* for grouping.

Mermaid guide: actor/participant ≤6, supported types: sequenceDiagram, gantt, pie, stateDiagram-v2, erDiagram.

Read diagram-rendering.md for full 5-layer architecture docs, diagrams.json schema, theme color mapping, and troubleshooting.

Phase 4: Generate JS Script + Execute

Write a complete PptxGenJS script. Install dependencies first:

npm ls pptxgenjs 2>/dev/null || npm install pptxgenjs

Read references/themes.md → "Script Template" section for the full starter template with theme constants (T), typography constants (F), layout constants (SW/SH/M/CW/CY/CH), slide masters, addFormula() helper, diagram helpers (addDiagram, addDiagramAt, addFigure), chart helper (addChart), and semantic helpers (sTitle, sectionSlide, addBullets, addCard, addTable, addNumCard, addFlow, cols2). Also read pptxgenjs-reference.md → "Layout Code Patterns" for 9 ready-to-use code blocks (including diagram and chart layouts), formula-rendering.md for the LaTeX pipeline, and diagram-rendering.md for the diagram pipeline.

Use F object for all font sizes, cols2() for two-column layouts, and helper functions for common patterns. Never hardcode font sizes — always reference F.body.size, F.title.size, etc.

User-provided images (logos, photos, screenshots): embed directly via slide.addImage({ path: "image.png", ... }). Calculate aspect ratio from original dimensions. Center with x: (SW - w) / 2. No special pipeline needed — just verify the file exists.

Key rules for script generation:

• Always use factory functions for shadows, fills, and other option objects
• Never use # prefix on hex colors
• Use breakLine: true between text array items
• Use bullet: true for list items, never unicode "•"
• Set margin: 0 on text boxes that need precise alignment with shapes
• For icon-grid layout: use simple colored rectangles/circles as visual markers (shapes, not icon images)

4a. Mathematical Slide Patterns

Math-heavy slides should follow one of these structural templates — they prevent the common trap of dumping a formula with no context:

Definition slide:

[Framing sentence: why this definition matters]
[Formal definition — display formula or card]
[Key properties / immediate consequences — 2-3 bullet items]

Construction/Algorithm slide:

[One-line goal statement]
[Core equation / algorithm steps]
[Complexity or performance: prover cost, verifier cost, soundness]

Comparison slide:

[Side-by-side table or two-column: prior work vs this work]
[1-2 lines highlighting the key difference]

Theorem → Proof slide (two slides, never one):

Slide A: [Informal statement] → [Formal theorem in card] → [Why it matters]
Slide B: [Proof sketch — key steps only, ≤5 lines. Full proof in backup.]

Insight/Remark slide:

[Observation the paper doesn't emphasize, or connection to related work]
[Why this matters / what it implies]

Every math slide must have a clear takeaway — the one thing the audience should remember from that slide.

4b. Content Density Upper Bounds

Lower bounds are in R4/R20. Upper bounds prevent cognitive overload — a slide with too much is worse than one with too little, because the audience retains nothing:

• ≤ 7 bullet points or items per slide
• ≤ 2 displayed formulas per slide (more → split across slides)
• ≤ 5 new symbols introduced per slide
• ≤ 2 accent cards per slide (R5 already covers this)

Density self-check after each batch:

• Count slides with zero formulas/diagrams/tables → flag if >30% of batch
• Count slides with ≤3 short items and no math → candidates for merging
• Count slides exceeding upper bounds → split or redistribute