PPTX creation, editing, and analysis

Creating from Topic (Content-First)

For generating complete decks from a topic, document, or brief, use the content-first workflow built on the Pyramid Principle (conclusion, reasons, evidence):

1. Intake: Use questionnaire at references/content-workflow/INTAKE.md
2. Follow 9-stage workflow: references/content-workflow/WORKFLOW.md
3. Score with rubric (must reach 75+): references/content-workflow/RUBRIC.md

Content-First Reference Files

Chart Generation

For data-driven charts, use chartkit:

Supported chart types: line, area, bar, barh, scatter, hist, waterfall

Reading and analysing content

Text extraction

To read text contents, convert the document to markdown:

Raw XML access

Raw XML access is needed for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. Unpack the presentation and read its raw XML contents.

Note: The unpack.py script is at skills/pptx/ooxml/scripts/unpack.py relative to the project root. If the script is not at this path, use find . -name "unpack.py" to locate it.

Typography and colour extraction

When given an example design to emulate: Analyse the presentation's typography and colours first:

1. Read theme file: Check ppt/theme/theme1.xml for colours (<a:clrScheme>) and fonts (<a:fontScheme>)
2. Sample slide content: Examine ppt/slides/slide1.xml for actual font usage (<a:rPr>) and colours
3. Search for patterns: Use grep to find colour (<a:solidFill>, <a:srgbClr>) and font references across all XML files

Creating a new presentation without a template

Use the html2pptx workflow to convert HTML slides to PowerPoint with accurate positioning.

Design Approach

Before creating any presentation, analyse the content and choose appropriate design elements:

1. Identify the subject matter: What is this presentation about? What tone, industry, or mood does it suggest?
2. Check for branding: If the user mentions a company or organisation, use their brand colours and identity
3. Match palette to content: Select colours that reflect the subject
4. State your approach: Explain your design choices before writing code

Requirements:

• State your content-informed design approach before writing code
• Use web-safe fonts only: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact
• Create clear visual hierarchy through size, weight, and colour
• Check readability: strong contrast, appropriately sized text, clean alignment
• Repeat patterns, spacing, and visual language across slides

Design Resources

For colour palettes and visual design elements, read:

• references/color-palettes.md - 18 curated colour schemes
• references/design-elements.md - Geometric patterns, typography, layouts

Layout Tips

When creating slides with charts or tables:

• Two-column layout (preferred): Use a header spanning the full width, then two columns below -- text/bullets in one column and the featured content in the other. Use flexbox with unequal column widths (e.g., 40%/60% split)
• Full-slide layout: Let the featured content take up the entire slide for maximum readability
• Do not vertically stack: Do not place charts/tables below text in a single column -- this causes poor readability and layout issues

Workflow

1. Read references/html2pptx-guide.md completely from start to finish before proceeding
2. Create an HTML file for each slide with proper dimensions (e.g., 720pt x 405pt for 16:9)
   • Use <p>, <h1>-<h6>, <ul>, <ol> for all text content
   • Use class="placeholder" for areas where charts/tables will be added (render with grey background for visibility)
   • Rasterise gradients and icons as PNG images first using Sharp, then reference in HTML
   • For slides with charts/tables/images, use either full-slide layout or two-column layout
3. Create and run a JavaScript file using the html2pptx.js library to convert HTML slides to PowerPoint and save the presentation
   • Use the html2pptx() function to process each HTML file
   • Add charts and tables to placeholder areas using PptxGenJS API
   • Save the presentation using pptx.writeFile()
4. Visual validation: Generate thumbnails and inspect for layout issues

   python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
   

   Creates: workspace/thumbnails.jpg grid for visual validation
   • Read and examine the thumbnail image for:
     • Text cutoff: Text being cut off by header bars, shapes, or slide edges
     • Text overlap: Text overlapping with other text or shapes
     • Positioning issues: Content too close to slide boundaries or other elements
     • Contrast issues: Insufficient contrast between text and backgrounds
   • If issues found, adjust HTML margins/spacing/colours and regenerate the presentation
   • Repeat until all slides are visually correct

Editing an existing presentation

Work with the raw Office Open XML (OOXML) format: unpack the .pptx file, edit the XML content, and repack it.

Workflow

1. Read references/ooxml-reference.md (~500 lines) completely from start to finish before any editing
2. Unpack the presentation:

   python ooxml/scripts/unpack.py presentation.pptx unpacked/
   

3. Edit the XML files (primarily ppt/slides/slide{N}.xml and related files)
4. Validate immediately after each edit:

   python ooxml/scripts/validate.py unpacked/ --original presentation.pptx
   

5. Pack the final presentation:

   python ooxml/scripts/pack.py unpacked/ output.pptx
   

Creating a presentation using a template

Read references/template-workflow.md completely from start to finish. It covers the full 7-step process:

1. Extract template text and create visual thumbnail grid
2. Analyse template and save inventory to a file
3. Create presentation outline based on template inventory
4. Duplicate, reorder, and delete slides using rearrange.py
5. Extract all text using inventory.py
6. Generate replacement text and save to JSON
7. Apply replacements using replace.py

Creating Thumbnail Grids

Features:

• Creates: thumbnails.jpg (or thumbnails-1.jpg, thumbnails-2.jpg, etc. for large decks)
• Default: 5 columns, max 30 slides per grid (5x6)
• Custom prefix: python scripts/thumbnail.py template.pptx my-grid
  • Note: The output prefix should include the path if you want output in a specific directory (e.g., workspace/my-grid)
• Adjust columns: --cols 4 (range: 3-6, affects slides per grid)
• Grid limits: 3 cols = 12 slides/grid, 4 cols = 20, 5 cols = 30, 6 cols = 42
• Slides are zero-indexed (Slide 0, Slide 1, etc.)

Use cases:

• Template analysis: Quickly understand slide layouts and design patterns
• Content review: Visual overview of entire presentation
• Navigation reference: Find specific slides by their visual appearance
• Quality check: Verify all slides are properly formatted

Combine options: custom name, columns

python scripts/thumbnail.py template.pptx analysis --cols 4

</example>

## Converting Slides to Individual Images

For cases where you need individual slide images rather than a grid:

<example>
```bash
# Step 1: Convert PPTX to PDF
soffice --headless --convert-to pdf template.pptx

# Step 2: Convert PDF pages to JPEG images
pdftoppm -jpeg -r 150 template.pdf slide

Creates: slide-1.jpg, slide-2.jpg, etc.

Options: -r 150 (DPI), -jpeg or -png (format), -f N -l N (page range)

Code Style Guidelines

When generating code for PPTX operations, write concise code. Avoid verbose variable names, redundant operations, and unnecessary print statements.

Dependencies

Required dependencies (should already be installed):