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.