xinetzone/SpecWeave / .agents/skills/pptx
pptx
VerifiedPresentation creation, editing, and analysis. When you need to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks
PPTX Skill
Quick Reference
| Task | Guide |
|---|---|
| Read/analyze content | python3 -m markitdown presentation.pptx |
| Edit or create from template | Read editing.md — QA: validate_layout.py + markitdown |
| Create from scratch | 1. Plan content → 2. Pre-generate assets → 3. Read pptxgenjs.md |
| Prevent overflow by design | Read pptxgenjs.md |
| Generate design system | python3 skills/pptx/scripts/design/search.py "<topic>" --design-system |
| Post-generation fix | python3 scripts/fix_pptx.py output.pptx |
| Layout QA (critical first) | python3 scripts/validate_layout.py presentation.pptx |
Reading Content
# Text extraction
python3 -m markitdown presentation.pptx
# Raw XML
python3 scripts/unpack.py presentation.pptx unpacked/
Editing Workflow
Read editing.md for full details.
- Analyze template with
markitdown - Unpack + style-layer check + Theme & Style alignment plan
- Manipulate slides → edit content → clean → pack
- ⚠️ Layout QA (mandatory gate):
python3 scripts/validate_layout.py output.pptx --slides <edited_slide_numbers> - ⚠️ Content QA (mandatory):
python3 -m markitdown output.pptx
Creating from Scratch
Read pptxgenjs.md for full details.
Use when no template or reference presentation is available.
Required Slide Structure (From-Scratch Only)
When creating a presentation from scratch, you MUST follow this structure:
- Slide 1: Cover page
- Slide 2: Table of contents (agenda)
- Slide 3 onward: Content sections in the exact order listed on Slide 2
- Final slide: Closing/thank-you page
Do not skip the table of contents slide. Do not place content slides before the table of contents.
⚠️ No Blank Slides Allowed
Every slide MUST contain at least one visible element (addText, addShape, addImage, addChart, or addTable) inside the slide. A slide with only a background color and no content elements is a generation defect.
Common causes of blank slides:
- Forgetting to add content to section divider / transition slides
- Token truncation mid-generation leaving some slides empty
- Assuming slide layout or master will auto-fill content (they won't — pptxgenjs creates minimal layouts with no inherited shapes)
If you intend a slide as a section divider, you MUST explicitly add elements — e.g., a large section number, title text, and/or decorative shapes.
⚠️ REQUIRED: Pre-Generation Planning
Before writing any code, you MUST complete these planning steps:
Step 1: Output Content Design Plan
Present a structured plan covering:
-
Overall Theme & Style
- Color palette choice (reference "Design Ideas" section)
- Typography pairing
- Visual motif to carry across slides
-
Slide-by-Slide Outline
Slide 1: Cover - Layout type, key elements Slide 2: Table of contents - Ordered section list Slide 3: [Section 1 from TOC] - Layout type, key elements, insight plan (if visual) ... Slide N: Closing / Thank You - Layout type, key elements ... -
Visual Elements Inventory
- List all images, icons, charts, and diagrams needed
- Mark each as:
[Built-in](pptxgenjs shapes/charts) or[External](needs pre-generation)
Example planning output:
## Presentation Plan
**Theme:** Ocean Gradient palette (065A82, 1C7293, 21295C)
**Fonts:** Georgia (headings) + Calibri (body)
**Motif:** Rounded cards with left accent border
### Slides:
1. Cover Slide - Centered title, gradient background
2. Table of Contents - Overview / Architecture / Metrics / Timeline
3. [Section 1 from TOC] - Layout type, key elements, insight plan (if visual)
...
n. Thank You - Closing statement + contact
Step 2: Pre-Generate External Assets
For figures marked [External], generate them BEFORE writing pptxgenjs code.
⚠️ CRITICAL: Color Consistency
All generated diagrams and charts MUST use the same color palette as the presentation. Define colors at the top of your generation script based on your chosen theme.
Option A: Native Shapes/Charts First (REQUIRED default)
ALL architecture diagrams, flowcharts, process diagrams, org charts, and relationship diagrams MUST be built with pptxgenjs native shapes (RECTANGLE, OVAL, LINE, connectors + addText). See pptxgenjs.md "Building Diagrams with Native Shapes" for patterns and examples.
- Use a strong template slide (process, comparison, 2-column, icon grid) when it fits
- Use pptxgenjs native shapes (boxes/arrows/lines + text) for flows, architectures, and hierarchies
- Use pptxgenjs charts for simple data charts (bar, pie, line, etc.)
Only fall back to matplotlib for complex statistical charts (heatmaps, scatter plots, box plots) that pptxgenjs charts cannot handle. Only fall back to Mermaid when the diagram is too complex for native shapes AND involves many cross-links.
Option B: Matplotlib/Python Charts
Define color palette at the start to match your PPT theme:
import matplotlib.pyplot as plt
import matplotlib.colors as mcolors
# ============================================================
# COLOR PALETTE - Match your PPT theme
# ============================================================
# Example: "Ocean Gradient" theme
COLORS = {
'primary': '#065A82',
'secondary': '#1C7293',
'accent': '#21295C',
'background': '#F0F7FA',
'text': '#21295C',
'light': '#E8F4F8',
}
# Color cycle for multiple data series
COLOR_CYCLE = [COLORS['primary'], COLORS['secondary'], COLORS['accent'], '#4A90A4', '#2D5A6B']
# Apply theme globally
plt.rcParams.update({
'axes.prop_cycle': plt.cycler(color=COLOR_CYCLE),
'axes.facecolor': 'none',
'axes.edgecolor': COLORS['text'],
'axes.labelcolor': COLORS['text'],
'text.color': COLORS['text'],
'xtick.color': COLORS['text'],
'ytick.color': COLORS['text'],
'figure.facecolor': 'none',
'font.family': 'sans-serif',
'font.size': 12,
})
# ============================================================
# Create chart with theme colors
fig, ax = plt.subplots(figsize=(8, 5), dpi=150)
bars = ax.bar(['Q1', 'Q2', 'Q3', 'Q4'], [25, 40, 35, 50],
color=[COLORS['primary'], COLORS['secondary'], COLORS['primary'], COLORS['secondary']],
edgecolor=COLORS['accent'], linewidth=1.5)
ax.set_title('Quarterly Revenue', fontsize=16, fontweight='bold', color=COLORS['text'])
ax.set_ylabel('Revenue ($M)', color=COLORS['text'])
ax.spines['top'].set_visible(False)
ax.spines['right'].set_visible(False)
plt.tight_layout()
width_px, height_px = int(8 * 150), int(5 * 150)
plt.savefig(f'chart_{width_px}x{height_px}.png', dpi=150, transparent=True)
plt.close()
Matplotlib palette templates:
# Midnight Executive
COLORS = {'primary': '#1E2761', 'secondary': '#CADCFC', 'accent': '#FFFFFF', 'text': '#1E2761'}
# Forest & Moss
COLORS = {'primary': '#2C5F2D', 'secondary': '#97BC62', 'accent': '#F5F5F5', 'text': '#2C5F2D'}
# Coral Energy
COLORS = {'primary': '#F96167', 'secondary': '#F9E795', 'accent': '#2F3C7E', 'text': '#2F3C7E'}
# Warm Terracotta
COLORS = {'primary': '#B85042', 'secondary': '#E7E8D1', 'accent': '#A7BEAE', 'text': '#B85042'}
# Teal Trust
COLORS = {'primary': '#028090', 'secondary': '#00A896', 'accent': '#02C39A', 'text': '#028090'}
Use for:
- Complex statistical charts (bar, line, pie, scatter, radar, etc.)
- Custom visualizations not supported by pptxgenjs
- Heatmaps, scatter plots, box plots
⚠️ Do NOT use matplotlib for:
- Architecture diagrams
- Flowcharts / process diagrams
- Org charts / hierarchy diagrams
- Network topology diagrams
- Any diagram that primarily shows relationships between components
These MUST be built with pptxgenjs native shapes so they render as editable PPT objects — not raster images.
matplotlib - Charts with CJK Support
When creating charts/graphs with matplotlib that include Chinese text, you MUST configure the font:
import os
import platform
import matplotlib.pyplot as plt
import matplotlib
def setup_matplotlib_cjk():
"""Configure matplotlib to support CJK characters"""
system = platform.system()
if system == "Darwin": # macOS
font_names = ['Arial Unicode MS', 'PingFang SC', 'Heiti SC', 'STHeiti']
elif system == "Windows":
font_names = ['Microsoft YaHei', 'SimHei', 'SimSun']
else: # Linux
font_names = ['Noto Sans CJK SC', 'WenQuanYi Zen Hei', 'Droid Sans Fallback']
# Find available font
available_fonts = [f.name for f in matplotlib.font_manager.fontManager.ttflist]
for font_name in font_names:
if font_name in available_fonts:
plt.rcParams['font.sans-serif'] = [font_name] + plt.rcParams['font.sans-serif']
plt.rcParams['axes.unicode_minus'] = False # Fix minus sign display
return font_name
return None
# Setup CJK font before creating charts
cjk_font = setup_matplotlib_cjk()
# Create a bar chart with Chinese labels
categories = ['第一季度', '第二季度', '第三季度', '第四季度']
values = [120, 135, 142, 158]
plt.figure(figsize=(10, 6))
plt.bar(categories, values, color='steelblue')
plt.title('季度销售数据 Quarterly Sales', fontsize=16)
plt.xlabel('季度 Quarter', fontsize=12)
plt.ylabel('销售额 Sales', fontsize=12)
plt.tight_layout()
plt.savefig('chart.png', dpi=150)
plt.close()
Option C: Web Search for Images
Search for relevant images when:
- Stock photos or illustrations are needed
- Icons or logos are required
- Reference images for concepts
Option D: Mermaid Diagrams (Last Resort)
Use only when the diagram cannot be represented cleanly with native shapes/layout, and keep it consistent with the deck:
# Install if needed: npm install -g @mermaid-js/mermaid-cli
Create a theme config file matching your PPT palette:
// mermaid-config.json - Example for "Ocean Gradient" theme
{
"theme": "base",
"themeVariables": {
"primaryColor": "#065A82",
"primaryTextColor": "#FFFFFF",
"primaryBorderColor": "#21295C",
"secondaryColor": "#1C7293",
"secondaryTextColor": "#FFFFFF",
"secondaryBorderColor": "#065A82",
"tertiaryColor": "#E8F4F8",
"tertiaryTextColor": "#21295C",
"lineColor": "#21295C",
"textColor": "#21295C",
"mainBkg": "#E8F4F8",
"nodeBorder": "#065A82",
"clusterBkg": "#F0F7FA",
"titleColor": "#21295C",
"edgeLabelBackground": "#FFFFFF"
}
}
cat > diagram.mmd << 'EOF'
graph LR
A[Client] --> B[API Gateway]
B --> C[Service A]
B --> D[Service B]
EOF
# Prefer high resolution export for PPT usage
mmdc -i diagram.mmd -o diagram.png -c mermaid-config.json -b white -w 1600 --scale 2
Step 3: Image Naming Convention (REQUIRED)
All generated images MUST include dimensions in the filename:
{name}_{width}x{height}.png
Examples:
architecture_800x600.png- 800px wide, 600px talltimeline_1200x400.png- 1200px wide, 400px tallchart_600x600.png- 600px square
When saving images, always include dimensions:
# Matplotlib example
fig, ax = plt.subplots(figsize=(8, 5), dpi=150)
# ... create chart ...
width_px = int(8 * 150) # 1200
height_px = int(5 * 150) # 750
plt.savefig(f'chart_{width_px}x{height_px}.png', dpi=150, transparent=True)
# Generic example - check output dimensions after generation
input="diagram_temp.png"
# Get actual dimensions and rename
dims=$(file "$input" | grep -oE '[0-9]+ x [0-9]+' | tr -d ' ')
mv "$input" "diagram_${dims/x/_x_}.png"
Step 4: Verify Assets Before Proceeding
# Confirm all external assets exist with dimensions in filename
ls -la *_*x*.png *_*x*.jpg 2>/dev/null
# Verify dimensions match filename
for f in *_*x*.png; do
echo "$f: $(file "$f" | grep -oE '[0-9]+ x [0-9]+')"
done
Only proceed to code generation after:
- Content plan is complete and approved
- All
[External]assets are generated - Asset files exist with
{name}_{width}x{height}.pngnaming - Filename dimensions match actual image dimensions
⚠️ CRITICAL: Slide Dimensions (REQUIRED FIRST)
Before adding ANY elements, you MUST declare slide dimensions as constants at the top of your script. This prevents layout overflow.
// ============================================================
// SLIDE DIMENSIONS - DECLARE FIRST, USE EVERYWHERE
// ============================================================
// Choose ONE layout and define its dimensions:
pres.layout = 'LAYOUT_16x9';
const SLIDE_W = 10; // inches
const SLIDE_H = 5.625; // inches
// Define safe content area (with margins)
const MARGIN = 0.5;
const CONTENT_X = MARGIN;
const CONTENT_Y = MARGIN;
const CONTENT_W = SLIDE_W - (2 * MARGIN); // 9 inches
const CONTENT_H = SLIDE_H - (2 * MARGIN); // 4.625 inches
// Common layout helpers
const CENTER_X = SLIDE_W / 2; // 5 inches
const CENTER_Y = SLIDE_H / 2; // 2.8125 inches
// ============================================================
Available layouts and their dimensions:
| Layout | Width | Height | Content Area (with 0.5" margins) |
|---|---|---|---|
LAYOUT_16x9 | 10" | 5.625" | 9" × 4.625" |
LAYOUT_16x10 | 10" | 6.25" | 9" × 5.25" |
LAYOUT_4x3 | 10" | 7.5" | 9" × 6.5" |
USE these constants for ALL positioning:
// ❌ WRONG: Hardcoded values risk overflow
slide.addText("Title", { x: 0.5, y: 0.5, w: 9, h: 0.8 });
// ✅ CORRECT: Use dimension constants
slide.addText("Title", { x: CONTENT_X, y: CONTENT_Y, w: CONTENT_W, h: 0.8 });
// ✅ CORRECT: Calculate positions relative to dimensions
const cardW = (CONTENT_W - 0.3) / 2; // Two cards with gap
slide.addShape(pres.shapes.RECTANGLE, { x: CONTENT_X, y: 1.5, w: cardW, h: 2 });
slide.addShape(pres.shapes.RECTANGLE, { x: CONTENT_X + cardW + 0.3, y: 1.5, w: cardW, h: 2 });
⚠️ CRITICAL: Container System (REQUIRED)
Add this code at the beginning of EVERY pptxgenjs script (after dimension constants). It provides:
- Text overflow protection - auto-adds
autoFit: trueandfit: "shrink"to all text - Nested containers - add elements inside shapes using relative coordinates
- Automatic z-ordering - child elements render on top of parents
// ============================================================
// CONTAINER SYSTEM WITH TEXT OVERFLOW PROTECTION - REQUIRED
// ============================================================
// Image scaling helper - extracts dimensions from filename and calculates
// position/size to fit within target bounds while preserving aspect ratio
function parseImageDimensions(path) {
const match = path.match(/_(\d+)x(\d+)\.(png|jpg|jpeg|gif|webp)$/i);
if (match) return { width: parseInt(match[1]), height: parseInt(match[2]) };
return null;
}
function calculateScaledImageOpts(opts) {
const { path, w: targetW, h: targetH, x = 0, y = 0, ...rest } = opts;
if (!path || !targetW || !targetH) return opts;
const dims = parseImageDimensions(path);
if (!dims) return opts;
const imgAspect = dims.width / dims.height;
const targetAspect = targetW / targetH;
let scaledW, scaledH, offsetX = 0, offsetY = 0;
if (imgAspect > targetAspect) {
scaledW = targetW;
scaledH = targetW / imgAspect;
offsetY = (targetH - scaledH) / 2;
} else {
scaledH = targetH;
scaledW = targetH * imgAspect;
offsetX = (targetW - scaledW) / 2;
}
return {
path,
x: x + offsetX,
y: y + offsetY,
w: scaledW,
h: scaledH,
...rest
};
}
function createVirtualNode(type, data, parentX = 0, parentY = 0) {
const opts = data.opts || {};
const node = {
type, data,
absX: parentX + (opts.x || 0),
absY: parentY + (opts.y || 0),
w: opts.w || 0, h: opts.h || 0,
children: []
};
node.addShape = function(shapeType, opts = {}) {
const child = createVirtualNode('shape', { shapeType, opts }, node.absX, node.absY);
node.children.push(child);
return child;
};
node.addText = function(text, opts = {}) {
const safeOpts = { fit: "shrink", ...opts };
const bulletRe = /^(?:[\u2022\u2023\u25E6\u2043\u2219\u00B7\u25CF\u25CB\u2013\u2014]\s*|\-\s+)/;
if (Array.isArray(text)) {
text = text.map(item => {
if (item && item.options && item.options.bullet && typeof item.text === 'string') {
return { ...item, text: item.text.replace(bulletRe, '') };
}
return item;
});
}
const child = createVirtualNode('text', { text, opts: safeOpts }, node.absX, node.absY);
node.children.push(child);
return child;
};
node.addImage = function(opts = {}) {
const scaledOpts = calculateScaledImageOpts(opts);
const child = createVirtualNode('image', { opts: scaledOpts }, node.absX, node.absY);
node.children.push(child);
return child;
};
node.addTable = function(tableData, opts = {}) {
const child = createVirtualNode('table', { tableData, opts }, node.absX, node.absY);
node.children.push(child);
return child;
};
return node;
}
function flattenNode(node, realSlide, pres) {
const absOpts = { ...node.data.opts, x: node.absX, y: node.absY };
if (node.type === 'shape') realSlide.addShape(node.data.shapeType, absOpts);
else if (node.type === 'text') realSlide.addText(node.data.text, absOpts);
else if (node.type === 'image') realSlide.addImage(absOpts);
else if (node.type === 'table') realSlide.addTable(node.data.tableData, absOpts);
node.children.forEach(child => flattenNode(child, realSlide, pres));
}
const originalAddSlide = pres.addSlide.bind(pres);
pres.addSlide = function(options) {
const realSlide = originalAddSlide(options);
const virtualSlide = {
children: [],
_realSlide: realSlide,
set background(val) { realSlide.background = val; },
get background() { return realSlide.background; },
addShape: function(shapeType, opts = {}) {
const node = createVirtualNode('shape', { shapeType, opts }, 0, 0);
this.children.push(node);
return node;
},
addText: function(text, opts = {}) {
const safeOpts = { fit: "shrink", ...opts };
const node = createVirtualNode('text', { text, opts: safeOpts }, 0, 0);
this.children.push(node);
return node;
},
addImage: function(opts = {}) {
const scaledOpts = calculateScaledImageOpts(opts);
const node = createVirtualNode('image', { opts: scaledOpts }, 0, 0);
this.children.push(node);
return node;
},
addTable: function(tableData, opts = {}) {
const node = createVirtualNode('table', { tableData, opts }, 0, 0);
this.children.push(node);
return node;
},
addChart: function(chartType, data, opts = {}) {
realSlide.addChart(chartType, data, opts);
},
render: function() {
this.children.forEach(child => flattenNode(child, realSlide, pres));
}
};
return virtualSlide;
};
// ============================================================
How to Use Containers
// Create a card as a container
let card = slide.addShape(pres.shapes.RECTANGLE, {
x: 1, y: 2, w: 4, h: 2.5,
fill: { color: "FFFFFF" }
});
// Add content INSIDE the card - coordinates relative to card's top-left
card.addText("Title", { x: 0.2, y: 0.2, w: 3.6, h: 0.4, fontSize: 18 });
card.addText("Description", { x: 0.2, y: 0.7, w: 3.6, h: 1.5, fontSize: 12 });
// Nested containers work too
let iconBg = card.addShape(pres.shapes.OVAL, { x: 0.2, y: 1.8, w: 0.5, h: 0.5 });
iconBg.addText("✓", { x: 0, y: 0, w: 0.5, h: 0.5, align: "center" });
// ⚠️ REQUIRED: Call render() at end of each slide
slide.render();
For multi-line text that should wrap, explicitly disable overflow protection:
slide.addText("Long paragraph...", {
x: 1, y: 2, w: 8, h: 3,
autoFit: false, // Override the default
fit: "none" // Allow normal wrapping
});
How to Use Images (Aspect Ratio Preserved)
Don't create boring slides. Plain bullets on a white background won't impress anyone. Consider ideas from this list for each slide. Images are automatically scaled to fit within the target bounds while preserving aspect ratio. The image is centered in the target area with transparent margins.
Generate Design System (Recommended)
Requirements:
- Image filename MUST include dimensions:
{name}_{width}x{height}.png - Specify target
wandhin the options
For professional presentations, generate a comprehensive design system tailored to your topic:
// Image is 800x600 pixels (4:3 aspect ratio)
// Target area is 4" x 4" (1:1 aspect ratio)
// Result: Image scaled to 4" x 3", centered vertically with 0.5" margin top/bottom
slide.addImage({
path: "assets/architecture_800x600.png",
x: 1,
y: 1,
w: 4, // target width in inches
h: 4 // target height in inches
});
python3 skills/pptx/scripts/design/search.py "<topic> <industry> <keywords>" --design-system -p "Presentation Name"
// Inside a container - relative positioning
let card = slide.addShape(pres.shapes.RECTANGLE, { x: 0.5, y: 1, w: 5, h: 3 });
card.addImage({
path: "assets/chart_1200x750.png",
x: 0.2, y: 0.2, // relative to card
w: 4.6, h: 2.6 // target bounds
});
Example:
python3 skills/pptx/scripts/design/search.py "fintech blockchain startup pitch" --design-system -p "CryptoVenture Pitch"
This gives you:
- Recommended style (glassmorphism, minimalism, etc.)
- Color palette with primary, secondary, accent colors
- Typography with font pairings
- Visual effects (gradients, shadows, etc.)
- Anti-patterns to avoid
For additional design details:
# Get more color palette options
python3 skills/pptx/scripts/design/search.py "fintech crypto" --domain color
# Get typography alternatives
python3 skills/pptx/scripts/design/search.py "professional modern" --domain typography
# Get chart recommendations for data slides
python3 skills/pptx/scripts/design/search.py "comparison trend" --domain chart
Before Starting
- Pick a bold, content-informed color palette: The palette should feel designed for THIS topic. If swapping your colors into a completely different presentation would still "work," you haven't made specific enough choices.
- Dominance over equality: One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent. Never give all colors equal weight.
- Dark/light contrast: Dark backgrounds for title + conclusion slides, light for content ("sandwich" structure). Or commit to dark throughout for a premium feel.
- Commit to a visual motif: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles, thick single-side borders. Carry it across every slide.
Color Palettes
Choose colors that match your topic — don't default to generic blue. Use these palettes as inspiration:
| Theme | Primary | Secondary | Accent |
|---|---|---|---|
| Midnight Executive | 1E2761 (navy) | CADCFC (ice blue) | FFFFFF (white) |
| Forest & Moss | 2C5F2D (forest) | 97BC62 (moss) | F5F5F5 (cream) |
| Coral Energy | F96167 (coral) | F9E795 (gold) | 2F3C7E (navy) |
| Warm Terracotta | B85042 (terracotta) | E7E8D1 (sand) | A7BEAE (sage) |
| Ocean Gradient | 065A82 (deep blue) | 1C7293 (teal) | 21295C (midnight) |
| Charcoal Minimal | 36454F (charcoal) | F2F2F2 (off-white) | 212121 (black) |
| Teal Trust | 028090 (teal) | 00A896 (seafoam) | 02C39A (mint) |
| Berry & Cream | 6D2E46 (berry) | A26769 (dusty rose) | ECE2D0 (cream) |
| Sage Calm | 84B59F (sage) | 69A297 (eucalyptus) | 50808E (slate) |
| Cherry Bold | 990011 (cherry) | FCF6F5 (off-white) | 2F3C7E (navy) |
For Each Slide
Every slide needs a visual element — image, chart, icon, or shape. Text-only slides are forgettable.
Layout options:
- Two-column (text left, illustration on right)
- Icon + text rows (icon in colored circle, bold header, description below)
- 2x2 or 2x3 grid (image on one side, grid of content blocks on other)
- Half-bleed image (full left or right side) with content overlay
Data display:
- Large stat callouts (big numbers 60-72pt with small labels below)
- Comparison columns (before/after, pros/cons, side-by-side options)
- Timeline or process flow (numbered steps, arrows)
Chart merge guidance (comparison/synergy):
- Merge charts only when they answer the same question
- Prefer simple combinations: bar+line (scale + trend) or side-by-side bars (direct comparison)
- Keep the same basis for comparison: shared time axis, units, and metric definition
- Limit to 2-3 series and highlight one key takeaway
Insight guidance for slides with visuals:
- For any slide containing a chart/diagram, perform an explicit insight decision; default to adding insights unless the visual is purely decorative
- If insights are needed, add an appropriate number of short insight lines on the same slide (near the visual), written as conclusions instead of neutral descriptions
- Make each insight specific and data-tied (trend/change/comparison/exception), not generic statements
- Keep insights visually secondary to the chart title and chart itself (clear hierarchy, no clutter)
Visual polish:
- Icons in small colored circles next to section headers
- Italic accent text for key stats or taglines
Typography
Title fonts MUST be serif. Cover title, slide titles, and subtitles (if present) must use a serif font. Only fall back to sans-serif if no serif font is available in the environment.
Recommended serif fonts for titles:
- Latin: Georgia, Cambria, Palatino Linotype, Garamond, Times New Roman
- CJK: Songti SC, SimSun, Noto Serif CJK SC, Source Han Serif SC
Font pairing — pair a serif header font with a clean sans-serif body font:
| Header Font (serif) | Body Font |
|---|---|
| Georgia | Calibri |
| Cambria | Calibri |
| Cambria | Calibri Light |
| Palatino Linotype | Calibri |
| Palatino | Garamond |
| Garamond | Calibri Light |
| Times New Roman | Arial |
| Element | Size | charSpacing |
|---|---|---|
| Cover title | 36-44pt bold, serif | — |
| Slide title | 28-36pt bold, serif | — |
| Subtitle | 18-24pt, serif | — |
| Section header | 20-24pt bold | — |
| Body text | 14-16pt | — |
| Captions | 10-12pt muted | — |
Serif font charSpacing rule — apply charSpacing based on font size to prevent cramped text:
| Font size | charSpacing |
|---|---|
| ≥ 36pt | 2.5 pt |
| 24-35pt | 1.5 pt |
| 18-23pt | 1 pt |
| 12-17pt | 0.5 pt |
| < 12pt | 0 (default) |
Spacing
- 0.5" minimum margins
- 0.3-0.5" between content blocks
- Leave breathing room—don't fill every inch
Avoid (Common Mistakes)
- ⚠️ Don't forget to declare slide dimension constants FIRST — see "CRITICAL: Slide Dimensions" section above; define
SLIDE_W,SLIDE_H,CONTENT_W,CONTENT_Hat the start of EVERY script - ⚠️ Don't hardcode coordinates — use dimension constants (
CONTENT_X,CONTENT_W, etc.) for ALL positioning to prevent overflow - ⚠️ Don't forget to add the container system code — see "CRITICAL: Container System" section above; add it after dimension constants
- ⚠️ Don't forget to call
slide.render()— required at the end of each slide to flatten virtual nodes - Don't repeat the same layout — vary columns, cards, and callouts across slides
- Don't center body text — left-align paragraphs and lists; center only titles
- Don't skimp on size contrast — titles need 36pt+ to stand out from 14-16pt body
- Don't default to blue — pick colors that reflect the specific topic
- Don't mix spacing randomly — choose 0.3" or 0.5" gaps and use consistently
- Don't style one slide and leave the rest plain — commit fully or keep it simple throughout
- Don't create text-only slides — add images, icons, charts, or visual elements; avoid plain title + bullets
- Don't forget text box padding — when aligning lines or shapes with text edges, set
margin: 0on the text box or offset the shape to account for padding - Don't use low-contrast elements — icons AND text need strong contrast against the background; avoid light text on light backgrounds or dark text on dark backgrounds
- NEVER use horizontal lines to seperate title and body — use whitespace or background color instead
- ⚠️ Don't leave slides blank — every
addSlide()call must be followed by at least oneaddText/addShape/addImageand aslide.render(). A slide with onlybackgroundset and no elements is a P0 defect that will be caught byvalidate_layout.py
Layout Safety (Required Before QA)
Fixing overflow only in QA is too late. Prevent it in code first.
- Pick layout by required Y-range:
LAYOUT_16x9height = 5.625LAYOUT_16x10height = 6.25LAYOUT_4x3height = 7.5LAYOUT_WIDEheight = 7.5
- Define margins before placing elements:
- Default:
left/right/top/bottom = 0.5
- Default:
- Build every element inside content frame:
contentX = marginLeftcontentY = marginTopcontentW = slideW - marginLeft - marginRightcontentH = slideH - marginTop - marginBottom
- Enforce boundary rule for every shape/text/image/chart:
x >= marginLefty >= marginTopx + w <= slideW - marginRighty + h <= slideH - marginBottom
- For uncertain text lengths, reserve vertical slack:
- Keep at least
0.3"gap between stacked blocks - Leave
>= 0.4"extra bottom slack in text-heavy slides
- Keep at least
If your design requires y + h > 5.625, do not use LAYOUT_16x9.
QA (Required)
Assume there are problems. Your job is to find them.
Your first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.
Layout QA (MANDATORY — Run After Every Build)
⚠️ This is a mandatory gate. You MUST pass this before declaring the presentation complete.
From-scratch (pptxgenjs) — fix and validate all slides:
python3 scripts/fix_pptx.py output.pptx
python3 scripts/validate_layout.py output.pptx
Template editing — validate only edited slides:
python3 scripts/validate_layout.py output.pptx --slides 3,5,8
Rules:
- If the report shows
Issues: 0→ pass. - If
Issues: > 0→ fix only the affected slides, rebuild, then re-run. Repeat until 0 issues. blank_slideis a generation defect — NEVER skip it. A blank slide means your code failed to add content to that slide. Fix by adding the intended content (text, shapes, images). Do NOT dismiss it as "a known limitation" or "section divider that the validator can't see" — if the validator says it's blank, it IS blank.- Maximum 3 retry rounds. If issues persist after 3 rounds of fixes, report the remaining issues to the user and proceed — do not loop indefinitely.
- Do NOT skip the first run. Do NOT declare success while issues remain (unless retry limit reached).
For debugging details:
python3 scripts/validate_layout.py output.pptx --verbose
Content QA
python3 -m markitdown output.pptx
Check for missing content, typos, wrong order.
Also verify insight coverage:
- For each slide with chart/diagram content, confirm an explicit insight decision exists
- If the visual carries analytical meaning, ensure insight text is present on-slide (not only in speaker notes)
When using templates, check for leftover placeholder text:
python3 -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|this.*(page|slide).*layout"
Windows (PowerShell): Use
python3 -m markitdown output.pptx | Select-String -Pattern "xxxx|lorem|ipsum|this.*(page|slide).*layout"sincegrepis not available on Windows.
If grep returns results, fix them before declaring success.
Overlap Prevention
- Text vs Text: Ensure text boxes have
autoFitor fixed height. If height is dynamic, calculate Y for the next element based on previous text length. - Text vs Image: Never place text directly over images without a semi-transparent background shape or high-contrast overlay.
- Chart Legends: Legends often grow. Reserve 20% more width than expected or place legends at the bottom.
- Table Content: Long words in narrow columns will wrap and increase row height, pushing lower content off-slide.
Dependencies
pip install "markitdown[pptx]"- text extractionpip install Pillow- thumbnail gridsnpm install pptxgenjs- project dependency for creating from scratch
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |