Create Ppt

Guidelines for creating professional, visually distinctive presentations via python-pptx. Modern, dark-first design with full creative freedom — build rich, substantive slides that communicate clearly.

Reference Files

Read from /tmp/skills/ppt/references/ when you need implementation details. Load them before the relevant work

0. Interactive Design Brief — Ask Before You Build

This step is mandatory. Before creating any slides, gather the user's design preferences through a short, focused set of questions. This ensures every deck feels tailored rather than generic.

0.1 When to Ask

Ask the design brief questions immediately after understanding what the presentation is about — i.e., once you know the topic, audience, and rough scope, pause and ask design questions before writing any code.

Skip the brief only if: the user explicitly says something like "just pick whatever looks good", "surprise me", "use defaults", or "I don't care about styling." In that case, choose a theme that fits the topic (see the mapping in 0.4) and proceed.

0.2 The Questions

Present these as a single, friendly message. Do NOT ask them one at a time — group them so the user can answer in one shot. Frame them as quick choices, not open-ended essays.

Here's the message template (adapt the tone naturally, don't copy verbatim):

Before I start building, a few quick design questions so this feels like yours:

1. Color vibe — Any specific brand colors (hex codes welcome) I should use? Or pick a direction:

• Cool & techy (blues, indigos, cyans)
• Warm & energetic (oranges, ambers, roses)
• Nature & growth (greens, teals, emeralds)
• Bold & creative (violets, fuchsias, pinks)
• Corporate & neutral (slate blues, grays)
• Or name any colors you like — "dark teal and gold", "red and black", etc.

2. Light or dark? — Dark backgrounds feel modern and immersive. Light backgrounds feel clean and corporate. Which do you prefer? (Default: dark)

3. Personality — What should this deck feel like?

• Data-driven & analytical
• Bold & punchy (high contrast, big statements)
• Clean & modern (structured, professional)
• Editorial (image-heavy, magazine-like)
• Storytelling (narrative flow, emotive)
• Minimal & elegant (lots of whitespace)

4. Content style — Should it lean heavier on charts/data, imagery, or text-driven narrative?

5. Anything else? — Specific font you love? A particular style you've seen and want to emulate? Company branding guidelines? Anything goes here.

0.3 Handling Answers

Users will give answers ranging from very specific ("use #1A2B3C and #FF6B35, dark mode, data-heavy") to very vague ("something professional"). Here's how to handle the spectrum:

Specific brand colors provided → Build a custom palette around them. Use the provided colors as accents. Pick a complementary neutral family. Validate contrast.

# Example: user gives brand colors #2563EB and #F59E0B
# Map to closest families or use directly
BRAND_PRIMARY = '#2563EB'   # close to blue-600
BRAND_SECONDARY = '#F59E0B' # close to amber-400
palette = compose_palette('slate', 'blue', dark_mode=True)
set_palette(palette)
# Override accents with exact brand colors
ACCENT_1 = BRAND_PRIMARY
ACCENT_2 = BRAND_SECONDARY

Color direction chosen (e.g., "warm & energetic") → Select a matching pre-composed theme and triad from the color system.

Vague or partial answers → Fill gaps with smart defaults based on the topic (see 0.4), but honor whatever the user did specify.

User says "surprise me" → Pick something that fits the topic but isn't deep_indigo every time. Rotate through the full theme catalog. Favor less common themes like earthy_amber, luxe_purple, lime_energy, calm_teal when the topic fits.

0.4 Topic → Default Theme Mapping

When the user doesn't specify colors, use the topic to pick a theme. Do not always default to deep_indigo. Use this mapping as a starting point, then vary within the category:

Variety rule: If you've used a theme recently in the conversation, pick a different one from the same category. If the category has only one option that fits, vary the accent triad instead.

0.5 Typography Selection

Default is still Inter, but use the user's answers to inform font choice:

0.6 Confirming the Brief

After the user answers, briefly confirm the design direction in one sentence before you start building. This lets them course-correct early:

"Got it — I'll go with a dark theme using teal and cyan accents, clean modern feel, data-heavy with charts. Building it now."

Then proceed to Section 1 onward.

1. Design Philosophy

1.1 Core Rules

Every slide should be rich and substantive — clean does not mean sparse. A slide with just a chart and nothing else, or a few words of tiny text, is an incomplete slide.

Dark-first by default. Dark backgrounds (slate-950, indigo-950) with light text and bright accents. Default for tech, science, data, product, and creative topics. Reserve light themes for corporate finance, healthcare, education, or when the user explicitly requests it.

60/30/10 color distribution. 60% neutral (backgrounds, body text), 30% complementary (card fills, borders, muted text), 10% accent (key numbers, highlights). If accent color covers more than ~10% of a slide, you've over-saturated.

Typographic hierarchy only. Size > Weight > Color > Space — these four tools create all visual hierarchy. No decorative indicators, badges, or embellishments.

Rounded shape language. Cards use visibly rounded corners. Sharp-cornered small elements look dated.

Borders over shadows. Separate elements with subtle 0.75pt borders (slate-700 on dark, neutral-200 on light) rather than heavy fills or drop shadows.

Two font weights only. Regular for body, Bold for headings and emphasis. No light, no extra-bold.

Flat and subtle. Cards defined by thin borders or very subtle background shifts, not heavy colored fills or gradients.

One typeface per deck. Differentiate through size and weight, not by switching font families.

Gradient depth. Use gradient background washes on 30–50% of slides for subtle depth variation.

1.2 Banned Decorative Elements

Do NOT use any of these — they clutter the design without adding information:

• Small colored circle/dot indicators next to card titles or list items
• Badge/tag labels above headings (the badge() function, pill shapes for categories)
• Accent bars on cards or accent underlines on titles
• Divider lines between sections — use white space instead
• Heavy colored card fills or gradient fills on cards
• Multiple font families in one deck

The only acceptable rect() uses: full-height accent bar on a slide edge (structural), background zone fills, timeline rail line, and cards via card().

1.3 Slide Richness

Each slide should deliver substantive content:

• Chart slides always include: an insight-driven title, the chart itself, AND a takeaway sentence or callout stat. A bare chart alone is never a finished slide.
• Data slides combine key metrics with supporting context — numbers tell what happened, text tells why it matters.
• Content slides have meaningful body text with clear visual hierarchy, not just a few words in tiny font.
• Use tables when presenting comparisons, specifications, feature matrices, pricing tiers, or any structured data. Read references/tables.md.
• Multi-element compositions — combine charts + callout cards, tables + narrative text, metrics + explanatory context. Single-element slides are often too sparse.

1.4 Visual Variety

No two consecutive slides should share the same layout structure. Vary your approach: full-width compositions, split layouts, card grids, full-bleed images, hero numbers, tables, charts with callouts.

Build 1–2 "surprise" slides per deck that break the pattern — a big number on pure dark, a full-bleed image, or a single provocative statement in large type.

2. Color System

The color system provides 9 neutral and 17 chromatic families, each with 11 shades (50–950). All colors accessed via c(family, shade) from ppt_colors.py.

Read references/colors.md for full shade-usage scales, multi-accent triads, and pre-composed themes.

Quick setup:

palette = theme_palette('deep_indigo', dark_mode=True)
set_palette(palette)
validate_palette_contrast()
init_chart_style(primary=c('indigo', 400),
                 series=chart_series_multi('indigo', 'violet', 'cyan', 'emerald'))

Important: The palette and accent choices must reflect the user's answers from the Design Brief (Section 0). Do not hardcode deep_indigo — use the theme selected during the brief.

3. Typography

Use a modern, geometric or neo-grotesque sans-serif. One font family per deck.

Fonts (preference order): Inter, DM Sans, Plus Jakarta Sans, IBM Plex Sans, Segoe UI (safe), Calibri (fallback). Use ensure_fonts() at session start. Select based on the personality chosen in the Design Brief (Section 0.5).

Type scale — 4 sizes, 2 weights:

Left-align body text. Center only display titles and hero text. Line spacing 1.3–1.4 for body text. Muted text (slate-400 on dark, neutral-500 on light) is a key hierarchy tool.

4. Script Toolkit

4.1 Loading

import sys
sys.path.insert(0, '/tmp/skills/ppt/scripts')
from ppt_fonts import ensure_fonts
ensure_fonts()

from ppt_core import *
from ppt_colors import c, compose_palette, theme_palette, chart_series, chart_series_multi, list_themes
from ppt_charts import init_chart_style, create_bar_chart, create_line_chart, create_pie_chart, create_donut_chart, create_horizontal_bar, create_stacked_bar
from ppt_images import download_image, prepare_background, add_full_bleed_bg, safe_add_picture, create_gradient_background
from ppt_qa import full_audit, render_slides, render_thumbnail_grid

4.2 Module Reference

4.3 Building Approach

Build slides from scratch using blank_slide() + primitives (add_text(), add_multiline_text(), card(), rect(), slide_background(), safe_add_picture()). This gives full creative control over every element's position, size, and styling.

ppt_layouts functions are optional convenience shortcuts — make_title_slide() and make_closing_slide() can save time for bookend slides. For content slides, building custom layouts is the default.

4.4 New Deck Workflow

# 0. Apply choices from the Design Brief
#    THEME_NAME, DARK_MODE, FONT, TRIAD, PERSONALITY — all set from user answers

# 1. Choose palette, validate, configure charts
palette = theme_palette(THEME_NAME, dark_mode=DARK_MODE)
set_palette(palette)
validate_palette_contrast()
init_chart_style(primary=c(TRIAD[0], 400),
                 series=chart_series_multi(*TRIAD))

# 2. Define constants from brief
ACCENT_1, ACCENT_2, ACCENT_3 = c(TRIAD[0], 400), c(TRIAD[1], 400), c(TRIAD[2], 400)
DARK_BG = c('slate', 950)
TEXT_WHITE = c('slate', 50)
TEXT_BODY = c('slate', 200)
TEXT_MUTED = c('slate', 400)

# 3. Create gradient backgrounds for variety
create_gradient_background('/tmp/grad1.png',
    hex_to_rgb(c('slate', 950)), hex_to_rgb(c(TRIAD[0], 950)))
create_gradient_background('/tmp/grad2.png',
    hex_to_rgb(c('slate', 950)), hex_to_rgb(c(TRIAD[1], 950)))

# 4. Build slides with creative freedom
prs = init_presentation()
# ... build slides ...

# 5. Save + QA — read references/qa-workflow.md for full process
prs.save('/tmp/output.pptx')
issues = full_audit('/tmp/output.pptx')
render_thumbnail_grid('/tmp/output.pptx', '/tmp/grid.png', cols=3)

4.5 Modifying Existing Deck

from ppt_analyzer import analyze_template, read_all_text
from ppt_modifier import replace_text, update_font_globally, update_colors
report = analyze_template('/tmp/input.pptx')
replace_text('/tmp/input.pptx', '/tmp/v2.pptx', 'DRAFT', 'FINAL')
update_font_globally('/tmp/v2.pptx', '/tmp/v3.pptx', new_font='Inter')
full_audit('/tmp/v3.pptx')

4.6 API Quick Reference — Coordinate Convention

CRITICAL: All helper functions accept raw float values in inches. They call Inches() internally. Do NOT pass Inches() objects — this causes double-wrapping and element positions in the millions of inches, triggering overflow audit errors.

# ✓ CORRECT — raw floats
add_text(slide, 0.8, 1.7, 11.0, 0.5, "Hello", size=28, bold=True, color='#FFFFFF')
card(slide, 0.8, 1.7, 5.0, 3.0, fill_color='#1e293b', border=True)
rect(slide, 0, 0, 13.333, 7.5, fill_color='#020617')
safe_add_picture(slide, '/tmp/img.png', 1.0, 1.7, 10.0, 5.0)

# ✗ WRONG — Inches() objects will be double-wrapped
add_text(slide, Inches(0.8), Inches(1.7), Inches(11.0), ...)
card(slide, Inches(0.8), Inches(1.7), ...)

Function signatures (all positions are raw floats in inches):

Parameter conventions:

• size — plain number in points, not Pt(). E.g. size=28, not size=Pt(28). Alias font_size also accepted.
• align — string: 'left', 'center', 'right'. Also accepts PP_ALIGN enum values. Alias alignment also accepted.
• color / fill_color — hex string '#RRGGBB' or RGBColor object.
• border — must be True to show a border; defaults to False (invisible line).

Chart function signatures:

Note: series is a dict {'label': [values]} for multi-series charts. create_horizontal_bar takes a flat values list instead.

5. Spatial Awareness

Read references/spatial-rules.md for complete positioning rules. Key boundaries:

Content zone: Title at y≈0.7 (28–32pt bold). Content starts y≈1.7, ends y≈7.0 (5.30" usable height). Content slide titles must be 28–32pt — using 36pt+ pushes into the content zone.

Margins: Minimum 0.5" from all slide edges. 0.3–0.5" between content blocks.

Text boxes: One text box per content block — stacking separate boxes creates invisible overlaps. Use \n\n for paragraph breaks within a single box.

6. Charts

Read references/charts.md before creating any chart.

Every chart slide communicates an insight, not just data. Include: insight-driven title, the chart, and a takeaway sentence or callout stat.

Charts use transparent backgrounds by default. To use an opaque background instead, pass background='#FFFFFF' (or any hex color) to init_chart_style().

7. Tables

Read references/tables.md before creating any table. Tables are a first-class content element for structured data, comparisons, and specifications.

from pptx.util import Inches, Pt
rows, cols = 5, 4
table_shape = slide.shapes.add_table(rows, cols,
    Inches(0.8), Inches(1.8), Inches(11.7), Inches(4.5))
table = table_shape.table
# See tables.md for dark-theme styling

8. Images

Sourcing: tavily_search(query="high quality [topic] photo", include_images=True). Download with download_image().

Background prep: prepare_background(input, output, darkness=0.5-0.65, tint_color=(r,g,b), blur=1-2) — crops to 16:9, darkens, tints, blurs. Place with add_full_bleed_bg(slide, path).

Content images: Use safe_add_picture() for bounding-box constrained placement. For template-based presentations, use add_picture_constrained().

Gradient backgrounds: create_gradient_background(output, (r1,g1,b1), (r2,g2,b2)). Use on 30–50% of slides.

9. Accessibility & Contrast

WCAG minimums: Normal text (<18pt): 4.5:1. Large text (≥18pt or ≥14pt bold): 3:1.

Dark-first safe combos: body (slate-200) on bg (slate-950), muted (slate-400) on bg for large text only (slate-300 for small), accents (indigo/violet/cyan-400) on bg, card text (slate-50) on card (slate-900).

Light-mode safe combos: body (neutral-700/800) on white, muted (neutral-500) on white, accents (chromatic 600+) on white.

Avoid chromatic shades 300 and below as text. Never use color as sole information channel. After set_palette(), call validate_palette_contrast() and fix flagged issues before building.

10. QA Workflow

Assume there are problems. Read references/qa-workflow.md for the full process.

Minimum required: Run full_audit() after saving. Render with render_thumbnail_grid(). Visually inspect. Fix issues and re-render at least once before finishing.

prs.save('/tmp/output.pptx')
issues = full_audit('/tmp/output.pptx')
grid = render_thumbnail_grid('/tmp/output.pptx', '/tmp/grid.png', cols=3)
# Inspect → Fix → Re-render → Verify

11. Dependencies

Required packages (pre-installed in the standard environment):

# Verify at session start if needed
import pptx           # python-pptx — slide generation
import matplotlib     # Chart rendering
from PIL import Image # Image processing
import requests       # Image downloading

12. Quick Reference