diff --git a/skills/pptx/SKILL.md b/skills/pptx/SKILL.md index b93b875fe..2fc9f02d1 100644 --- a/skills/pptx/SKILL.md +++ b/skills/pptx/SKILL.md @@ -10,6 +10,18 @@ license: Proprietary. LICENSE.txt has complete terms A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks. +## Choosing Your Approach + +| Task | Approach | When to use | +|------|----------|-------------| +| Read/analyze | markitdown or XML | Extract text, inspect structure | +| Create from scratch | html2pptx | Standard layouts, HTML/CSS handles positioning | +| Create from scratch | Direct PptxGenJS | Fine-grained control, calculated positions, algorithmic layouts | +| Edit existing | OOXML | Modify XML directly | +| Create from template | rearrange → inventory → replace | Follow existing design | + +**html2pptx vs Direct PptxGenJS:** Start with html2pptx. If it fights your layout or you need precise coordinate control, drop down to direct PptxGenJS. See [Direct PptxGenJS Reference](references/direct-pptxgenjs.md). + ## Reading and analyzing content ### Text extraction @@ -63,6 +75,13 @@ When creating a new PowerPoint presentation from scratch, use the **html2pptx** - ✅ Ensure readability: strong contrast, appropriately sized text, clean alignment - ✅ Be consistent: repeat patterns, spacing, and visual language across slides +**Design Constraints** (apply to all creation workflows): +- **Stay on-palette**: Extract colors from template theme, don't introduce new ones +- **Stay on-font**: Use template fonts or web-safe fallbacks that won't substitute +- **Minimize objects**: One rich object beats layered simple objects (text box with border, not shape + text overlay) +- **Validate visually**: Render thumbnails to catch overlap/cutoff problems coordinates won't reveal +- **Internal harmony**: When consolidating objects, ensure properties work together (e.g., `inset` keeps text off borders) + #### Color Palette Selection **Choosing colors creatively**: @@ -95,51 +114,7 @@ When creating a new PowerPoint presentation from scratch, use the **html2pptx** #### Visual Details Options -**Geometric Patterns**: -- Diagonal section dividers instead of horizontal -- Asymmetric column widths (30/70, 40/60, 25/75) -- Rotated text headers at 90° or 270° -- Circular/hexagonal frames for images -- Triangular accent shapes in corners -- Overlapping shapes for depth - -**Border & Frame Treatments**: -- Thick single-color borders (10-20pt) on one side only -- Double-line borders with contrasting colors -- Corner brackets instead of full frames -- L-shaped borders (top+left or bottom+right) -- Underline accents beneath headers (3-5pt thick) - -**Typography Treatments**: -- Extreme size contrast (72pt headlines vs 11pt body) -- All-caps headers with wide letter spacing -- Numbered sections in oversized display type -- Monospace (Courier New) for data/stats/technical content -- Condensed fonts (Arial Narrow) for dense information -- Outlined text for emphasis - -**Chart & Data Styling**: -- Monochrome charts with single accent color for key data -- Horizontal bar charts instead of vertical -- Dot plots instead of bar charts -- Minimal gridlines or none at all -- Data labels directly on elements (no legends) -- Oversized numbers for key metrics - -**Layout Innovations**: -- Full-bleed images with text overlays -- Sidebar column (20-30% width) for navigation/context -- Modular grid systems (3×3, 4×4 blocks) -- Z-pattern or F-pattern content flow -- Floating text boxes over colored shapes -- Magazine-style multi-column layouts - -**Background Treatments**: -- Solid color blocks occupying 40-60% of slide -- Gradient fills (vertical or diagonal only) -- Split backgrounds (two colors, diagonal or vertical) -- Edge-to-edge color bands -- Negative space as a design element +For design inspiration (geometric patterns, borders, typography, charts, layouts, backgrounds), see [Visual Details Options](references/visual-details-options.md). ### Layout Tips **When creating slides with charts or tables:** diff --git a/skills/pptx/references/direct-pptxgenjs.md b/skills/pptx/references/direct-pptxgenjs.md new file mode 100644 index 000000000..023c4e145 --- /dev/null +++ b/skills/pptx/references/direct-pptxgenjs.md @@ -0,0 +1,173 @@ +# Direct PptxGenJS Reference + +When html2pptx doesn't give you enough control, work directly with PptxGenJS coordinates. + +## When to Use Direct Control + +| Situation | Use html2pptx | Use Direct PptxGenJS | +|-----------|---------------|----------------------| +| Standard text layouts | ✓ | | +| Bullet lists, tables | ✓ | | +| Precise coordinate placement | | ✓ | +| Algorithmic/calculated positions | | ✓ | +| Collision detection needed | | ✓ | +| html2pptx fighting your layout | | ✓ | + +## Core Principle: Object Minimization + +**Prefer fewer, richer objects over layered simple objects.** + +```javascript +// ✗ WORSE - two objects, alignment can drift +slide.addShape(pptx.shapes.ROUNDED_RECTANGLE, { + x: 1, y: 1, w: 3, h: 1, + fill: { color: 'FFFFFF' }, + line: { color: 'F5D76E', width: 0.75 } +}); +slide.addText('Quote text', { x: 1, y: 1, w: 3, h: 1 }); + +// ✓ BETTER - single object with all properties +slide.addText('Quote text', { + x: 1, y: 1, w: 3, h: 1, + fill: { color: 'FFFFFF' }, + line: { color: 'F5D76E', width: 0.75 }, + rectRadius: 0.04, // rounded corners + inset: 0.08 // internal padding +}); +``` + +One object means: +- User can select/edit as a unit in PowerPoint +- No alignment drift between layers +- Cleaner XML, smaller file +- Simpler to position programmatically + +When you consolidate to a single object, ensure internal properties work together (e.g., `inset` keeps text from touching the border). + +## API Gotchas + +### Internal Padding: Use `inset`, Not `margin` + +```javascript +// ✗ WRONG - fails silently, no padding applied +slide.addText(text, { margin: 0.1 }); + +// ✓ CORRECT - 0.1 inches padding on all sides +slide.addText(text, { inset: 0.1 }); +``` + +PowerPoint UI calls these "internal margins" but PptxGenJS uses `inset`. + +### Text AutoFit Options + +| PowerPoint Setting | PptxGenJS Property | Behavior | +|-------------------|-------------------|----------| +| Do not Autofit | (default) | Text may overflow | +| Shrink text on overflow | `shrinkText: true` | Reduces font size to fit | +| Resize shape to fit text | `autoFit: true` | Expands box to fit content | + +```javascript +// Shrink text if it overflows +slide.addText(longText, { shrinkText: true, ...position }); + +// Expand box to fit text +slide.addText(longText, { autoFit: true, ...position }); +``` + +### Borders on Text Boxes + +Use `line` property for borders, `rectRadius` for rounded corners: + +```javascript +slide.addText('Bordered text', { + x: 1, y: 1, w: 4, h: 1, + fill: { color: 'FFFFFF' }, + line: { color: 'C5A880', width: 1 }, // 1pt gold border + rectRadius: 0.05, // rounded corners (inches) + inset: 0.1 // keep text off the border +}); +``` + +## Text Dimension Estimation + +To size boxes before PowerPoint's autofit, estimate text dimensions: + +```javascript +// Approximate character width (Georgia font) +const charWidth = fontSize * 0.007; // inches per character + +// Estimate lines needed +const charsPerLine = Math.floor(boxWidth / charWidth); +const linesNeeded = Math.ceil(text.length / charsPerLine); + +// Line height +const lineHeight = fontSize * 0.017; // inches per line +const estimatedHeight = linesNeeded * lineHeight; +``` + +These are rough estimates - use `autoFit: true` or `shrinkText: true` to let PowerPoint adjust. + +## Visual Validation Workflow + +Coordinates don't reveal overlap or cutoff problems. Always validate visually: + +```bash +# Generate thumbnail grid +python scripts/thumbnail.py output.pptx workspace/check --cols 4 + +# Then read and inspect the image +``` + +The feedback loop: **code → render → look → adjust** + +For complex coordinate work, prototype in SVG first (see below). + +## SVG Prototyping Pattern + +For algorithmic layouts, prototype in SVG before converting to PptxGenJS: + +1. **Write algorithm generating SVG** - faster iteration than regenerating .pptx +2. **Render to PNG**: `rsvg-convert -w 1280 -h 720 input.svg -o /tmp/test.png` +3. **Inspect and iterate** until layout works +4. **Port to PptxGenJS** - convert pixels to inches: `px / 96` + +SVG iteration is ~10x faster than PPTX generation. Once the algorithm works, translating to PptxGenJS is mechanical. + +## Example: Calculated Placement with Collision Detection + +```javascript +const pptxgen = require('pptxgenjs'); +const pptx = new pptxgen(); + +// Track placed objects for collision detection +const placed = []; + +function overlaps(a, b, padding = 0.1) { + return !(a.x + a.w + padding < b.x || + b.x + b.w + padding < a.x || + a.y + a.h + padding < b.y || + b.y + b.h + padding < a.y); +} + +function placeBox(slide, text, preferredX, preferredY, w, h) { + const box = { x: preferredX, y: preferredY, w, h }; + + // Adjust if overlapping existing boxes + for (const existing of placed) { + if (overlaps(box, existing)) { + box.y = existing.y + existing.h + 0.2; // Move below + } + } + + placed.push(box); + + slide.addText(text, { + x: box.x, y: box.y, w: box.w, h: box.h, + fill: { color: 'FFFFFF' }, + line: { color: 'F5D76E', width: 0.75 }, + inset: 0.08, + fontSize: 10, + valign: 'middle' + }); +} +``` diff --git a/skills/pptx/references/visual-details-options.md b/skills/pptx/references/visual-details-options.md new file mode 100644 index 000000000..d15a07d68 --- /dev/null +++ b/skills/pptx/references/visual-details-options.md @@ -0,0 +1,49 @@ +# Visual Details Options + +Design options to spark creativity when creating presentations. + +## Geometric Patterns +- Diagonal section dividers instead of horizontal +- Asymmetric column widths (30/70, 40/60, 25/75) +- Rotated text headers at 90° or 270° +- Circular/hexagonal frames for images +- Triangular accent shapes in corners +- Overlapping shapes for depth + +## Border & Frame Treatments +- Thick single-color borders (10-20pt) on one side only +- Double-line borders with contrasting colors +- Corner brackets instead of full frames +- L-shaped borders (top+left or bottom+right) +- Underline accents beneath headers (3-5pt thick) + +## Typography Treatments +- Extreme size contrast (72pt headlines vs 11pt body) +- All-caps headers with wide letter spacing +- Numbered sections in oversized display type +- Monospace (Courier New) for data/stats/technical content +- Condensed fonts (Arial Narrow) for dense information +- Outlined text for emphasis + +## Chart & Data Styling +- Monochrome charts with single accent color for key data +- Horizontal bar charts instead of vertical +- Dot plots instead of bar charts +- Minimal gridlines or none at all +- Data labels directly on elements (no legends) +- Oversized numbers for key metrics + +## Layout Innovations +- Full-bleed images with text overlays +- Sidebar column (20-30% width) for navigation/context +- Modular grid systems (3×3, 4×4 blocks) +- Z-pattern or F-pattern content flow +- Floating text boxes over colored shapes +- Magazine-style multi-column layouts + +## Background Treatments +- Solid color blocks occupying 40-60% of slide +- Gradient fills (vertical or diagonal only) +- Split backgrounds (two colors, diagonal or vertical) +- Edge-to-edge color bands +- Negative space as a design element