AgentCompany/builtin-skills/document-process/pptx-generator/references/pitfalls.md

QA Process & Common Pitfalls

QA Process

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.

Content QA

python -m markitdown output.pptx

Check for missing content, typos, wrong order.

Check for leftover placeholder text:

python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|placeholder|this.*(page|slide).*layout"

If grep returns results, fix them before declaring success.

Verification Loop

1. Generate slides -> Extract text with python -m markitdown output.pptx -> Review content
2. List issues found (if none found, look again more critically)
3. Fix issues
4. Re-verify affected slides — one fix often creates another problem
5. Repeat until a full pass reveals no new issues

Do not declare success until you've completed at least one fix-and-verify cycle.

Per-Slide QA (for from-scratch creation)

python -m markitdown slide-XX-preview.pptx

Check for missing content, placeholder text, missing page number badge.

---

Common Mistakes to Avoid

• 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: 0 on 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
• NEVER use accent lines under titles — these are a hallmark of AI-generated slides; use whitespace or background color instead
• NEVER use "#" with hex colors — causes file corruption in PptxGenJS
• NEVER encode opacity in hex strings — use the opacity property instead
• NEVER use async/await in createSlide() — compile.js won't await
• NEVER reuse option objects across PptxGenJS calls — PptxGenJS mutates objects in-place

---

Critical Pitfalls — PptxGenJS

NEVER use async/await in createSlide()

// WRONG - compile.js won't await
async function createSlide(pres, theme) { ... }

// CORRECT
function createSlide(pres, theme) { ... }

NEVER use "#" with hex colors

color: "FF0000"      // CORRECT
color: "#FF0000"     // CORRUPTS FILE

NEVER encode opacity in hex strings

shadow: { color: "00000020" }              // CORRUPTS FILE
shadow: { color: "000000", opacity: 0.12 } // CORRECT

Prevent text wrapping in titles

// Use fit:'shrink' for long titles
slide.addText("Long Title Here", {
  x: 0.5, y: 2, w: 9, h: 1,
  fontSize: 48, fit: "shrink"
});

NEVER reuse option objects across calls

// WRONG
const shadow = { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 };
slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });

// CORRECT - factory function
const makeShadow = () => ({ type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 });
slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });