pptx-slides

PPTX Slides — Programmatic PowerPoint Generation

Generate professional, editable PowerPoint presentations using PptxGenJS (Node.js). Produces OOXML-compliant .pptx files with precise layout, text measurement, and overlap validation.

Bundled Helpers

Every PPTX generation script imports the bundled TypeScript helper modules via bun:

import pptxgen from 'pptxgenjs';
import * as h from '${CLAUDE_PLUGIN_ROOT}/skills/pptx-slides/scripts/main.ts';
const pptx = new pptxgen();
pptx.layout = 'LAYOUT_16x9'; // 10" × 5.625"

Run generation scripts with bun (no build step needed):

npx -y bun ${CLAUDE_PLUGIN_ROOT}/skills/pptx-slides/scripts/main.ts theme list

Dependencies (skia-canvas, fontkit, linebreak, prismjs) are auto-installed by bun on first run — no manual install step needed.

Module Summary

Module	Key Exports	Purpose
text	autoFontSize(), calcTextBoxHeightSimple(), scale()	Font-aware text measurement via skia-canvas, adaptive sizing
theme	createTheme(), PRESETS, sectionBackground()	Design token system with 12 curated presets
layout	warnIfSlideHasOverlaps(), alignSlideElements(), distributeSlideElements()	Overlap detection, bounds checking, positioning
layout_builders	addFeatureGrid(), addCardRow(), addTimeline(), addMetricsRow(), addComparisonTable()	High-level component builders
decorative	addStaircase(), addSectionBadge(), addProgressBar(), addSlideNumber()	Visual personality elements
validation	validateDeck()	Consolidated pre-save quality validation
code	codeToRuns()	Prism.js syntax highlighting to PptxGenJS text runs
image	getImageDimensions(), imageSizingCrop(), imageSizingContain()	Binary dimension detection and aspect-ratio sizing
svg	svgToDataUri()	SVG sanitization and base64 data URI encoding
util	safeOuterShadow(), normalizeColor(), inchesToEmu()	Shadow effects, color/unit conversion

Theme Selection

Pick a curated preset or create a custom theme:

// Use a preset
const theme = h.createTheme(h.PRESETS.darkMonospace);

// Or customize
const theme = h.createTheme({
  accent: 'ff6b35',
  font: { heading: 'Poppins', body: 'Inter' },
});

Available presets: darkMonospace, swissModern, boldSignal, darkBotanical, cleanCorporate, neonCyber, warmMinimal, vintageEditorial, terminalGreen, gradientWave, midnightBlue, paperInk.

For mixed-background decks, define a section map:

const sectionMap = { '0': 'brand', '1-3': 'light', '4-8': 'default' };
const colors = { brand: theme.accent, light: theme.bg.secondary, default: theme.bg.primary };
slide.background = { color: h.sectionBackground(slideIndex, sectionMap, colors) };

Adaptive Font Sizing

Use scale() instead of hardcoded font sizes — the PPTX equivalent of CSS clamp():

const titleSize = h.scale(theme.size.title.min, theme.size.title.max, { bullets: 0, textLength: title.length });
const bodySize = h.scale(theme.size.body.min, theme.size.body.max, { bullets: 5, textLength: 800 });

For precise text box fitting, use autoFontSize() with skia-canvas measurement:

const opts = h.autoFontSize('Long paragraph text...', 'Arial', { w: 8, h: 3, minFontSize: 14, maxFontSize: 28 });
slide.addText(text, { x: 1, y: 1.5, ...opts });

Generation Workflow

1. Plan layout — Map content outline to slide types from references/slide-patterns.md
2. Select theme — Pick preset or define custom theme tokens
3. Generate slides — Build with helpers: addFeatureGrid(), addCardRow(), etc.
4. Validate — Run h.validateDeck(pptx) before saving
5. Fix issues — Adjust based on validation report, re-validate
6. Deliver — Provide .pptx file with speaker notes on every content slide

Core Design Rules

Typography

• Minimum body text: 18pt (24-28pt preferred). Use scale() for adaptive sizing.
• Title text: 36-44pt
• Caption/footnote: 14-16pt minimum (absolute floor: 14pt)
• Font families: Use h.resolveFont(theme, 'heading') for proper fallback chains

Layout

• Slide dimensions: 10" × 5.625" (widescreen 16:9)
• Safe margins: 0.5" from all edges (theme.spacing.margin)
• White space: Target 40-50% empty space per slide
• Alignment: Use h.alignSlideElements() and h.distributeSlideElements() for precision

Color & Accessibility

• Contrast ratio: WCAG AA minimum (4.5:1 body, 3:1 large text)
• Color-blind safe: Wong or IBM palettes for data visualization
• Theme tokens: Always use theme.text.primary, theme.accent — never hardcode colors

Validation Workflow

Run h.validateDeck(pptx) before saving every deck. It checks:

• Element overlaps on every slide
• Elements within slide boundaries
• Font sizes above 14pt minimum
• Bullet count per slide (max 6)
• Speaker notes presence

Anti-Patterns

• Text smaller than 14pt anywhere
• More than 6 bullets per slide
• Elements extending beyond slide boundaries
• Hardcoded colors instead of theme tokens
• Hardcoded font sizes instead of scale() or autoFontSize()
• Skipping validateDeck() before saving
• Missing speaker notes on content slides
• Using PptxGenJS fit or autoFit instead of h.autoFontSize()

Editability Guidance

Design for editability — recipients must be able to modify the deck:

• Native text boxes — Click and edit directly. Never flatten text into images.
• Group related elements — Card layouts move as a unit.
• Native shapes — Use rounded rectangles, circles, lines instead of embedded SVG where possible.
• Speaker notes — Add talking points via slide.addNotes('...') on every content slide.
• Master layouts — For template decks, define slide layouts for consistent new slides.

Architecture Diagrams with Shapes

Build architecture diagrams using PptxGenJS native shapes rather than images:

• Rectangles for services/components: slide.addShape('rect', { ... })
• Lines and arrows for connections: slide.addShape('line', { ... })
• Color coding: Use theme.accent for active components, theme.text.secondary for inactive
• Progressive revelation: Build the same diagram across 2-3 slides, adding complexity

Reference Files

• references/pptxgenjs-helpers.md — Full API reference for bundled helper modules
• references/slide-patterns.md — Detailed slide type patterns with dimensions and positioning

Script Files

• scripts/main.ts — TypeScript CLI entry point and library re-exports (run via npx -y bun)
• scripts/types.ts — Shared TypeScript interfaces for all helper modules
• scripts/theme.ts — 12 curated theme presets with createTheme() and resolveFont()
• scripts/text.ts — Font-aware text measurement via skia-canvas, autoFontSize(), scale()
• scripts/layout.ts — Overlap detection, element alignment, bounds checking
• scripts/layout_builders.ts — addFeatureGrid(), addCardRow(), addTimeline(), etc.
• scripts/decorative.ts — addStaircase(), addSectionBadge(), addProgressBar()
• scripts/validation.ts — validateDeck() pre-save quality validation
• scripts/code.ts — Prism.js syntax highlighting to PptxGenJS text runs
• scripts/image.ts — Binary dimension detection and aspect-ratio sizing
• scripts/svg.ts — SVG sanitization and base64 data URI encoding
• scripts/util.ts — Shadow effects, color normalization, unit conversion