powerpoint-builder

name	powerpoint-builder
description	Build polished, human-looking PowerPoint decks with python-pptx from an already-defined outline plus provided figures/tables/text. Use when asked to generate or update a .pptx programmatically with a consistent visual system, template-driven layout, and no generic AI-deck smell.

Skill: Build polished, human-looking PowerPoint decks with python-pptx

This skill covers PowerPoint creation only: turning an already-defined outline + provided assets (figures/tables/text) into a non-generic, human-looking .pptx using Python.

---

Mission

Generate a .pptx that looks like a thoughtful human made it:

• clear hierarchy and intentional layout
• consistent visual system (not default templates)
• zero "AI smell" (generic structure, filler icons, repetitive wording)
• deterministic, reproducible generation

---

Primary stack

Library: python-pptx (create/read/update .pptx without PowerPoint installed)

Preferred strategy:

• Populate a real template template.pptx (slide master, theme fonts/colors, placeholders) with code.
• Only fall back to "from-scratch" slides if no template exists.

---

Required inputs (content is provided, not discovered)

1. deck_plan.md (or JSON/YAML) specifying:

   • slide order
   • slide type (layout)
   • assertion title text (already written)
   • bullets (already written)
   • image/table paths (already available)
   • speaker notes (already written, if needed)

2. assets/ directory:

   • assets/figures/*.png (preferred) or .jpg
   • assets/tables/*.csv or pre-rendered table images
   • optional logo/icons (curated, consistent style)

3. Optional: template.pptx

---

Outputs (required)

• deck.pptx — final presentation
• assets_manifest.json — slide# → assets used (local path only, no sourcing logic)
• build_log.txt — warnings: missing assets, overflow risks, font fallbacks

---

What makes a deck look AI-generated (avoid these)

AI smell

• Same layout every slide (title + 6 bullets + icon).
• Default Office template typography and colors.
• Vague headers: "Introduction", "Problem", "Solution", "Benefits".
• Bullets that read like an essay or marketing fluff.
• Decorative icons/photos with no information value.
• Random gradients, blobs, and generic stock imagery.
• Overcrowded slides, tiny fonts, inconsistent spacing.

Countermeasures

• Use assertion titles (already provided): "X improves Y by Z under condition C."
• Intentionally vary layouts: figure-first, split, comparison, key-number, process.
• Use whitespace and alignment as primary "design."
• Keep slide text lean; move detail into speaker notes.
• Prefer real figures/charts; annotate with callouts instead of adding icons.

---

Quality bars (non-negotiable)

Layout discipline

• Use a grid: consistent margins, gutters, alignment anchors.
• Consistent title position and typographic scale across slides.
• No shape overlaps, no clipped text, no off-grid drifting.

Typography

• Readable from distance (avoid tiny body text).
• Consistent capitalization style (Title Case or sentence case; pick one).
• Bullet parallelism (same grammatical form).

Visuals

• No stretched images. Ever.
• High-resolution charts; crop intentionally.
• Captions (optional) are consistent style and placement.

---

Workflow (PowerPoint creation)

1) Choose template strategy

Best: populate a template

• Load template.pptx
• Add slides using the template's layouts
• Fill placeholders (title/body/image) instead of creating ad-hoc textboxes
• Let the template handle master elements (logo/footer)

Fallback: generate from scratch

• Define strict theme tokens in code (fonts, palette, spacing)
• Implement reusable slide builder functions
• Expect more QA

---

Standard slide builders (keep to 6–10)

Implement a small set of high-quality functions; do not freestyle per slide.

Recommended:

• add_title_slide(title, subtitle, meta)
• add_section_divider(title, kicker=None)
• add_bullets_slide(title, bullets, note=None)
• add_figure_slide(title, image_path, caption=None)
• add_figure_with_text_slide(title, image_path, bullets, side="right")
• add_comparison_slide(title, left, right, verdict=None)
• add_table_slide(title, df_or_image, note=None)
• add_key_number_slide(title, big_number, qualifier=None)
• add_process_slide(title, steps)

---

Implementation standards (python-pptx)

Units

• Always use pptx.util.Inches and pptx.util.Pt.
• Centralize slide geometry: margins, gutters, common coordinates.

Determinism

• Same inputs → same deck.
• No randomness. No "auto layout" that depends on content length unless bounded.

Layouts & placeholders

• Prefer prs.slide_layouts[...] from the template.
• Fill placeholders by name/index; if missing, fail loudly (log + raise).

Text rules

• Avoid paragraphs on slides. Use bullets or short statements.
• Explicitly set:
  • font name
  • font size
  • line spacing
  • paragraph spacing (before/after)
• Limit bullets per slide; if too many, split the slide.

Image handling

• Implement aspect-preserving fit:
  • contain (letterbox) or cover (crop), but never distort
• Validate image exists; validate expected aspect ratio when known.
• Prefer PNG for charts/plots.

Tables

• If table is dense: split across slides or convert to image.
• Right-align numeric columns; consistent significant figures (if provided).
• Use subtle separators; avoid heavy gridlines.

---

QA checks (mandatory)

Automate these checks and log warnings:

• Missing assets (path not found)
• Text overflow risk (heuristic by char count + textbox size)
• Font fallback (requested font missing)
• Image distortion (non-uniform scaling)
• Inconsistent title x/y across slides (beyond tolerance)

Manual final scan:

• alignment looks consistent
• no clipped elements
• no "default PowerPoint" vibe

---

Project structure (recommended)

project/
├── deck_plan.md              # provided outline (no research here)
├── template.pptx             # preferred
├── assets/
│   ├── figures/
│   ├── tables/
│   └── icons/
├── src/
│   ├── build_deck.py
│   ├── theme.py                # tokens: fonts/colors/spacing
│   ├── layouts.py              # slide builders
│   ├── geometry.py             # fit/center helpers
│   └── qa.py                   # checks + logging
└── output/
    ├── deck.pptx
    ├── assets_manifest.json
    └── build_log.txt

---

Acceptance checklist (must pass)

• Deck uses a coherent template/brand system.
• Slide titles are specific assertions (provided) and positioned consistently.
• No tiny fonts, no overflow, no overlaps.
• Layout variety is intentional (not repetitive).
• Images are sharp and not distorted.
• No decorative fluff icons/photos.
• Exported .pptx opens cleanly in PowerPoint/Google Slides.