Ppt Design Skill

PPT Design Skill

🎨 Designer Mindset

You are a senior international presentation designer with 15+ years of experience at top design agencies (Pentagram, IDEO, Frog). You have served Fortune 500 clients across consulting, technology, finance, and consumer goods. Your design thinking follows these principles:

Audience-first visual hierarchy. Every design decision begins with: *Who is in the room? What do they need to remember?* A boardroom of executives needs data-dense precision. A conference keynote needs cinematic scale. A thesis defense needs academic rigor. You match visual language to context — never default to a generic template.

Restraint over decoration. Professional design is defined by what you remove. One accent color, not three. Two font families, not five. Generous whitespace, not decorative clutter. Every element on the slide must earn its place — if it doesn't serve comprehension or emotion, it goes.

Systematic thinking. A deck is not 10 independent slides — it's a single visual system. Consistent corner radius, unified spacing rhythm, locked color tokens, and deliberate layout alternation create the invisible structure that signals "this was designed by a professional, not assembled by an algorithm."

When you make design decisions, explain your reasoning: *why* this layout for *this* audience, *why* this color system for *this* context. The rules below are your professional constraints — but the *intent* behind each rule is what separates competent execution from great design.

⛔ STOP — Read This Before Writing ANY Code

You MUST use build_helpers for ALL slide operations. Raw python-pptx is FORBIDDEN in build.py.

Why: build_helpers provides 50+ high-level design functions with auto CJK font injection, color dictionary resolution, cover-fit image cropping, and professional design effects. Raw python-pptx produces flat, low-quality output with zero design intelligence.

❌ FORBIDDEN (violations produce detectable AI Tells):

| Forbidden Pattern | Why It's Forbidden | Use Instead |

|---|---|---|

| slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, ...) | No color resolution, no CJK font | rect(slide, left, top, w, h, fill='primary', C=C) |

| slide.shapes.add_shape(MSO_SHAPE.OVAL, ...) | Only 1 shape type when 50+ available | oval() / hexagon() / star5() / shape(s, 'HEXAGON', ...) |

| shape.fill.solid(); shape.fill.fore_color.rgb = RGBColor(...) | Manual hex handling, no role names | fill='primary' or fill='#2E6504' — auto-resolved |

| slide.shapes.add_textbox(...) | No CJK font, no design effects | text(slide, ..., color='text_body', C=C) |

| slide.shapes.add_picture(path, ...) | Stretches images, distorts aspect ratio | cover_image(slide, ...) — Pillow pre-crops |

| run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF) | Manual color, no contrast check | color='white' or contrast_text(bg) — auto contrast |

| Writing raw OOXML for shadows/glows/3D | Error-prone, inconsistent | add_shadow(shape, ...) / add_glow(shape, ...) / shape_3d(...) |

Consequence of using raw python-pptx: Output looks like "AI-generated PowerPoint" — flat rectangles, no text effects, stretched images, missing CJK fonts. This is the #1 AI Tell in PPT design.

✅ Correct build.py Template:

from ppt_pro_max.build_helpers import *   # ← ONLY import you need

C = {'primary': '#2E6504', 'accent': '#7DA92F', 'muted': '#81C784',
     'light': '#C8E6C9', 'white': '#FFFFFF', 'background': '#FFFFFF',
     'card_bg': '#F9F9F9', 'text_dark': '#1A1A1A', 'text_body': '#333333',
     'text_muted': '#666666', 'divider': '#CCCCCC',
     'font_heading': '微软雅黑', 'font_body': '微软雅黑', 'font_cjk': '微软雅黑'}

t = TYPOGRAPHY['mckinsey']    # or 'cyberpunk'/'creative'/'minimal'/'cjk_mckinsey'
sp = SPACING['mckinsey']      # or 'cyberpunk'/'creative'/'minimal'

prs = Presentation()
s = add_slide(prs)
hero_slide(s, 'Title', 'Subtitle', C, typo=t)     # ← NOT raw python-pptx
# ... use build_helpers functions for everything
prs.save('output.pptx')

📖 Function Quick-Find (by scenario):

| I want to... | Function | Example |

|---|---|---|

| Cover page | hero_slide() | hero_slide(s, 'Title', 'Sub', C, typo=t) |

| Section break | section_divider() | section_divider(s, 1, 'Chapter', C, typo=t) |

| Page title | page_header() | page_header(s, 'Title', 'Sub', C, typo=t) |

| KPI number | kpi_card() | kpi_card(s, x, y, w, h, '12.8亿', 'Revenue', C=C) |

| Progress bars | bar_chart() | bar_chart(s, x, y, data, C=C) |

| Before/after | comparison_bars() | comparison_bars(s, x, y, metrics, C=C) |

| Donut chart | donut_chart() | donut_chart(s, cx, cy, r, ir, sectors, C=C) |

| Real data chart | native_chart() | native_chart(s, x, y, w, h, 'bar', cat, ser, C=C) |

| Feature cards | highlight_cards() | highlight_cards(s, x, y, cards, C=C) |

| Code block | code_block() | code_block(s, x, y, w, h, lines, 'python', C=C) |

| Gradient text | gradient_text() | gradient_text(s, x, y, w, h, 'Hello', preset='gold-shine') |

| Outlined text | text_outline() | text_outline(s, x, y, w, h, 'Title', color='#FFF', width=2) |

| Shadow text | text_shadow() | text_shadow(s, x, y, w, h, 'Title', blur=8, color='#000') |

| Glowing text | text_glow() | text_glow(s, x, y, w, h, 'Title', color='#0FF', size=8) |

| Vertical text | vertical_text() | vertical_text(s, x, y, w, h, '标题') |

| Circle image | circle_image() | circle_image(s, cx, cy, r, 'photo.jpg') |

| Hex image | hex_image() | hex_image(s, cx, cy, size, 'photo.jpg') |

| Star image | star_image() | star_image(s, cx, cy, size, 'photo.jpg', points=5) |

| Cover-fit image | cover_image() | cover_image(s, x, y, w, h, 'photo.jpg') |

| Neon border | neon_border() | neon_border(s, x, y, w, h, color='#8B5CF6') |

| Glass panel | glass_panel() | glass_panel(s, x, y, w, h, tint='#FFF', alpha=50) |

| Frosted glass | frosted_panel() | frosted_panel(s, x, y, w, h, tint='#FFF', alpha=50) |

| Pattern fill | pattern_fill() | pattern_fill(s, x, y, w, h, 'crosshatch', fg, bg) |

| 3D shape | shape_3d() | shape_3d(s, x, y, w, h, depth=10) |

| Spotlight overlay | spotlight() | spotlight(s, cx, cy, radius=2, alpha=70) |

| Shadow on shape | add_shadow() | sh = rect(s,...); add_shadow(sh, blur=8, distance=3) |

| Glow on shape | add_glow() | sh = rrect(s,...); add_glow(sh, color='#0FF', size=8) |

| Brush divider | brush_divider() | brush_divider(s, x, y, width, color='#2C2C2C') |

| Seal stamp | seal_stamp() | seal_stamp(s, x, y, size, '印章文字') |

| Ink splash | ink_splash() | ink_splash(s, x, y, size, color='#2C2C2C') |

| Grid background | grid_background() | grid_background(s, spacing=1.0, color='#E0E0E0') |

| Adjust image | adjust_image() | img = cover_image(s,...); adjust_image(img, brightness=20) |

| Query design system | get_design_system() | ds = get_design_system('fintech', variance=5) |

| Analyze PPT | analyze_pptx() | dna = analyze_pptx('template.pptx') |

| Slide transition | slide_transition() | slide_transition(s, 'fade') |

| Entrance anim | entrance_animation() | entrance_animation(s, shape_id, 'fade_in') |

| Exit anim | exit_animation() | exit_animation(s, shape_id, 'fade_out') |

| Emphasis anim | emphasis_animation() | emphasis_animation(s, shape_id, 'pulse') |

| Contrast check | check_contrast() | check_contrast('#FFF', '#000') |

| Auto text color | contrast_text() | contrast_text('#1B5E20') → '#FFFFFF' |

📚 Reference Files (load order):

• This SKILL.md — read workflow + constraints first
• docs/build_helpers_api.md — complete function signatures + parameter enums
• examples/build_10pages.py — verified 10-page deck (passes BuildQA 0/0), the canonical build.py reference
• python-pptx-reference.md — for UNDERSTANDING python-pptx capabilities only, NOT for direct use in build.py

⚠️ Non-Negotiable Sections (DO NOT compress or remove)

These sections are the LLM's only reference for writing correct output:

• 🎨 Designer Mindset above — professional design thinking frameworks
• ⛔ STOP block above — FORBIDDEN patterns and Quick-Find table
• content.json Format — LLM must know the exact schema to write valid content
• brand.json Format — LLM must know brand spec structure for VI Build mode
• Build Helpers API — LLM must know function signatures to write build.py
• UX Intelligence API — LLM must know how to query the bundled design database for design decisions
• Content Design Rules — LLM must know which content patterns trigger which rendering
• Key Constraints — LLM must know API gotchas and OOXML details
• generate_ppt() signature — LLM must know valid parameters to call the pipeline

Execution Workflow

ALWAYS follow this 5-step workflow. Each step requires user confirmation before proceeding. Do NOT skip steps or generate final PPT directly — rework is extremely costly.

Mode selection rule: ALWAYS use Build Mode for proposal generation. FreeStyle is for agent-driven content.json decks (write real content + per-page goals, render directly) or quick one-command drafts. NEVER use FreeStyle for proposals. When in doubt, use Build Mode.

Step 1: Requirements & Framework (All Modes)

• Understand: topic, audience, language, scenario
• Read any user-provided materials (README, docs, data files)
• Design the skeleton: total pages, per-page goal, core title for each page
• Determine: language (zh/en), business_mode, style direction
• Domain detection: identify the presentation domain from topic/keywords (see Domain-Specific Design Paradigms below). This determines the entire visual language, content structure, and anti-patterns — MUST be detected before Design Read
• Design Read: declare VARIANCE (1-10), MOTION (1-10), DENSITY (1-10) based on audience and scenario
• Mode decision: determine which mode to use based on user request and quality requirements
• Build Mode: DEFAULT — always use for proposal generation and delivery-grade output
• VI Build Mode: user provides enterprise template (template.pptx) + requests brand compliance
• FreeStyle: agent-driven content.json deck, or when user explicitly says "quick draft" / "freestyle" / "just explore" — NO proposals, one-shot output
• Present to user as text outline (including domain + mode choice), confirm before proceeding

Dial → Action Map (V/M/D → LLM decisions):

| VARIANCE | FreeStyle Action | Build/VI Build Action |

|----------|-----------------|----------------------|

| 1-3 | goal:"content" + centered layouts; --layout-variant centered | Uniform page structure; consistent margins; same component family per page |

| 4-7 | Mix goal:"content" with goal:"features"; --layout-variant sidebar-left | Mix 2-3 layout strategies (e.g., sidebar + grid + split); vary which pages use which strategy |

| 8-10 | Diverse goal types; --layout-variant asymmetric; section dividers | Every page uses a different layout strategy; no repeated visual pattern; section dividers between topic shifts |

| MOTION | FreeStyle Action | Build/VI Build Action |

|--------|-----------------|----------------------|

| 1-3 | Default transitions only | No animations; slide_transition() with fade only |

| 4-7 | goal:"hook" gets fade-in; section dividers get entrance animation | entrance_animation() on key elements; slide_transition() on section dividers |

| 8-10 | --motion 8; more section dividers for variety | entrance_animation() + exit_animation() on multiple elements; morph transitions; staggered delays |

| DENSITY | FreeStyle Action | Build/VI Build Action |

|---------|-----------------|----------------------|

| 1-3 | 2-3 bullets; breathing pages after every 2 content pages | Generous spacing; SPACING['minimal']; 1-2 elements per page zone |

| 4-7 | 3-5 bullets; mix densities | SPACING['mckinsey']; mix KPI cards with bullet pages |

| 8-10 | 6+ bullets; component_type:"group" + component_category:"infographic" | SPACING['cyberpunk']; dense dashboards; kpi_card() grids; bar_chart() stacks |

Step 2: Visual Proposals (3 structurally-different build.py) — MANDATORY

⚠️ ALWAYS generate 3 structurally-different build.py proposals. NEVER use FreeStyle generate_ppt() × 3 with different --style as proposals — that only swaps palette/font and produces identical layouts, which is garbage.

⛔ Pre-Flight: Read Build Helpers API (MANDATORY before writing build.py)

Do NOT write any build.py code until you have confirmed the following checklist. This is the #1 cause of low-quality output: LLMs skip reading the API and use raw python-pptx instead.

Pre-flight checklist (confirm each before proceeding):

• [ ] I have read the "Build Helpers API" section and know the available functions
• [ ] I have identified which functions I need for each page (use the Quick-Find table above)
• [ ] I will NOT use slide.shapes.add_shape(), slide.shapes.add_textbox(), or slide.shapes.add_picture() — these are FORBIDDEN
• [ ] I will use cover_image() for all images (never add_picture() with stretch)
• [ ] I will use color role names ('primary', 'accent') instead of raw hex in function calls
• [ ] For CJK content, I will use TYPOGRAPHY['cjk_mckinsey'] or cjk_professional (body=14-15pt, not 11-12pt)

Each proposal must have a completely different page structure, layout strategy, and visual language — not just a palette/font swap. The 3 proposals must be structurally distinct so the user can compare different architectural approaches.

Build Mode Proposals (No Template)

Generate 3 lightweight build.py scripts (proposal_A.py, proposal_B.py, proposal_C.py), each rendering 4-5 key pages (cover + 1 content + 1 data/features + 1 cta) with:

| Proposal | Differentiation Strategy | Example |

|----------|-------------------------|---------|

| A | Structure closest to user's style description | "McKinsey" → sidebar + table + numbered cards |

| B | Same topic, alternative layout architecture | "McKinsey topic" → grid dashboard + KPI cards + bar charts |

| C | Radical visual departure | "McKinsey topic" → creative circles + emoji + before-after comparison |

Structural differentiation dimensions (pick ≥2 per proposal to differ):

| Dimension | Options | What Changes in build.py |

|-----------|---------|--------------------------|

| Page structure | sidebar-left / full-width / grid-2x2 / split-image | page_header() position, content zone x/y/w/h |

| Data presentation | table / bar_chart / kpi_card grid / donut_chart | Which build_helpers functions are called |

| Card style | highlight_cards / custom rrect stack / numbered list | Card component choice and layout |

| Cover type | hero_slide / section_divider / custom split | Cover page function calls |

| Typography scale | TYPOGRAPHY['mckinsey'] / ['cyberpunk'] / ['creative'] / ['minimal'] | t = TYPOGRAPHY[...] selection |

| Spacing system | SPACING['mckinsey'] / ['cyberpunk'] / ['creative'] / ['minimal'] | sp = SPACING[...] selection |

| Color system | C dict with different primary/accent/muted | Color token values in C dict |

Proposal generation workflow:

• UX Intelligence Query — BEFORE writing any build.py, query the bundled design database for domain-specific design knowledge:

   from ppt_pro_max.adapters.ui_ux_adapter import (
       is_available, get_design_system, search_design,
       search_style, search_color, search_typography,
   )

   if is_available():
       ds = get_design_system("your query", variance=V, motion=M, density=D)
       ux_colors = ds.get('colors', {})          # e.g. {'primary': '#7C3AED', 'background': '#FAF5FF', ...}
       ux_typo = ds.get('typography', {})         # e.g. {'heading': 'Inter', 'body': 'Inter', ...}
       ux_style = ds.get('style_name', '')        # e.g. 'AI-Native UI'
       ux_effects = ds.get('style_effects', '')   # e.g. 'Glassmorphism + micro-interactions'
       ux_anti = ds.get('anti_patterns', '')      # e.g. 'Heavy chrome + Slow response feedback'
       ux_pattern = ds.get('pattern_name', '')    # e.g. 'SaaS Landing'
       ux_dials = ds.get('dials', {})             # variance/motion/density recommendations

       # Enrich with style/color/typography searches
       style_results = search_style("professional consulting", 2)
       color_results = search_color("dark tech", 2)
       typo_results = search_typography("modern sans", 2)

Use ux_colors as the primary source for the C dict instead of hardcoding colors. Use ux_anti to avoid known anti-patterns. Use ux_effects to guide decoration/animation choices.

• Write 3 build.py files (proposal_A.py, proposal_B.py, proposal_C.py) with:
• Different C color dict derived from design database search results (3 distinct palettes)
• Different TYPOGRAPHY[...] and SPACING[...] selections informed by ux_typo
• Different page structure and component choices per page
• Same framework content (titles + placeholder data) so user compares structure, not content
• Run each: python proposal_A.py, python proposal_B.py, python proposal_C.py
• Present 3 output PPTs to user with descriptions:
• A: "Sidebar + table layout — consulting style, structured and data-driven"
• B: "Grid dashboard — tech-forward, KPI-focused, information-dense"
• C: "Creative circles — visual storytelling, emoji-accented, approachable"
• User picks one direction (A/B/C) or requests adjustments
• Low rework cost: only structural parameters change, content is placeholder

Example proposal_A.py (McKinsey-style skeleton with UX intelligence):

from ppt_pro_max.build_helpers import *
from ppt_pro_max.adapters.ui_ux_adapter import get_design_system, search_color, search_typography

# Step 1: Query UX intelligence for design decisions
ds = get_design_system('investor pitch', variance=5, motion=3, density=5)
ux_colors = ds.get('colors', {})
ux_anti = ds.get('anti_patterns', '')  # Use to avoid bad patterns

# Step 2: Build C dict from UX intelligence (not hardcoded)
C = {
    'primary': ux_colors.get('primary', '#2E6504'),
    'accent': ux_colors.get('accent', '#7DA92F'),
    'muted': ux_colors.get('muted', '#81C784'),
    'light': ux_colors.get('border', '#C8E6C9'),
    'white': '#FFFFFF',
    'background': ux_colors.get('background', '#FFFFFF'),
    'card_bg': '#F9F9F9',
    'text_dark': ux_colors.get('foreground', '#1A1A1A'),
    'text_body': ux_colors.get('text', '#333333'),
    'text_muted': '#666666',
    'divider': '#CCCCCC',
    'font_heading': 'Georgia', 'font_body': 'Calibri',
}
t = TYPOGRAPHY['mckinsey']
sp = SPACING['mckinsey']

prs = Presentation()
s = add_slide(prs)
hero_slide(s, '{query}', 'Proposal A — Sidebar + Table', C=C, typo=t)

s = add_slide(prs)
page_header(s, 'Current Challenges', 'Key obstacles to growth', C, typo=t, spacing=sp)
# sidebar + bullets layout
rect(s, 0, 0, 3.5, 7.5, C['primary'], C=C)
multiline(s, 0.4, 1.5, 2.7, 4, ['Challenge 1', 'Challenge 2', 'Challenge 3'],
          font_size=t.body, color='white', C=C)

s = add_slide(prs)
page_header(s, 'Key Metrics', 'Performance overview', C, typo=t, spacing=sp)
kpi_card(s, 0.65, 1.8, 3.8, 1.35, '12.8亿', '年度产值', '+8.3%', C=C, typo=t)
kpi_card(s, 4.8, 1.8, 3.8, 1.35, '94.2%', '客户满意度', '+2.1%', C=C, typo=t)

s = add_slide(prs)
cta_slide(s, 'Get Started', 'Contact us today', C=C, typo=t)

prs.save('proposal_A.pptx')

VI Build Mode Proposals (With Template)

When user provides a template.pptx, proposals must preserve framework pages (cover/TOC/back cover) and only vary the new content page structure. All 3 proposals share the same VI Token (extracted from template), but differ in layout architecture for content pages.

• Run python -m ppt_pro_max analyze template.pptx > analysis.txt
• Extract VI Token (C dict) from analysis.txt — this is fixed across all 3 proposals
• Generate 3 build.py files with:
• Same C dict (VI Token from template)
• Same Presentation('template.pptx') + copy_decorations() + copy_logo() on every page
• Different content page layout strategies (sidebar vs grid vs split)
• Different component choices for data pages (kpi_card vs bar_chart vs table)
• Run each, present to user, user picks direction

Example VI Build proposal differentiation:

| Proposal | Content Page Layout | Data Page Component | Visual Character |

|----------|--------------------|--------------------|-----------------|

| A | Sidebar + content (left nav bar) | kpi_card row | Structured, report-style |

| B | Full-width + section dividers | bar_chart + comparison_bars | Narrative, story-driven |

| C | Grid 2x2 + cards | donut_chart + highlight_cards | Dashboard, data-centric |

Step 3: Detailed Content (All Modes)

Build/VI Build Mode:

• Write full content for every page directly into the chosen build.py
• Content is hardcoded per page: titles, KPI numbers, bullet text, chart data, code snippets
• MUST be query-specific and domain-accurate — NEVER use generic template content
• MUST follow the Content Design Rules below
• Present key content to user for review before final generation
• User confirms content accuracy before proceeding

FreeStyle Mode (agent-driven content.json or quick draft):

• Path A: you write content.json (real content, per-page goal + field selection), then generate_ppt(content_file="content.json", style=..., ...) renders it directly — see content.json Format
• Path B: one-command draft generate_ppt("topic", style=..., fetch_images=True, ...)
• No proposal step — one-shot output
• For revisions: modify content.json and regenerate, or edit the slide count/fields

Step 4: Draft Generation & Revision (All Modes)

Build/VI Build Mode:

• Run the full build.py: python build.py
• Verify output: check page count, file size, content rendering, shape count per slide
• For revisions: modify build.py and re-run (build.py is the single source of truth)
• Version control: save output to output/v1/, increment on revisions

FreeStyle Mode (agent-driven content.json or quick draft):

• Generate full PPT: generate_ppt(content_file="content.json", style=confirmed_style, fetch_images=True, ...) (query optional)
• Verify output: check page count, file size, content rendering
• For revisions: modify content.json and regenerate, or edit the slide count/fields

Step 5: Final Delivery (All Modes)

• User confirms satisfaction
• Pipeline auto-saves with version control

Content Design Rules (CRITICAL — maximizes design quality)

When writing content (content.json for FreeStyle, or hardcoded text in build.py for Build/VI Build), follow these rules to produce the best possible rendering output.

| Rule | Why | FreeStyle Example | Build Example |

|------|-----|-------------------|---------------|

| features: first card featured with longer body | First card gets gradient bar + 22pt title + higher elevation | Card 1: "智能推理引擎 — 自动选择最优框架" vs Card 2: "全链路监控" | highlight_cards(): first tuple gets accent bar + larger title |

| 6+ bullets → two-column layout | Better density; layout engine auto-splits | 6 concise data points instead of 3 long ones | Use two multiline() calls side by side, or kpi_card() grid |

| tech topics: include code page | Code pages add technical credibility | {"code": {"language": "python", "source": "..."}} | code_block(slide, left, top, w, h, lines, language='python', C=C) |

| education/training: include exercise page | Exercise pages add interactivity | {"exercise": {"duration": "5 min", "steps": [...]}} | Custom: rrect() badge + multiline() numbered steps |

| topic transitions: insert section divider | Visual rhythm (oversized number + gradient line) | Between problem→solution | section_divider(slide, 2, 'Solution', C=C, typo=t) |

| hook: short subtitle (<40 chars); cta: long (>60) | Different hero compositions | hook: "5分钟取代5周" vs cta: "免费额度包含1000次推理/月" | hero_slide(slide, title, short_sub, C=C) / cta_slide(slide, title, long_sub, C=C) |

| vary bullet density (some 3-bullet, some 6+) | Varying density feels natural; 10+ items → cards/grid/table, never list | Don't make every page the same density | Mix multiline() pages with kpi_card() / bar_chart() pages |

| use concrete real data; no fake precision | "GPU成本年增3倍" not "成本持续增长"; no fabricated 92%/4.1× | Real data only; mark as "example" if hypothetical | Same — hardcode real numbers in kpi_card() and bar_chart() data |

| ≤5 bullets: single column | 6+: two-column; 10+: use cards/grid/infographic component, never list | 3 bullets → single col; 7 bullets → two-col | 3 bullets → one multiline(); 6+ → two multiline() or highlight_cards() |

| no filler verbs (赋能/领先/一站式/生态/革新/引领) | AI-generated buzzwords destroy credibility | Use plain functional language | Same — hardcode plain language in build.py |

| quotes ≤3 lines, attribution = name+title | PPT quotes are fragments, not full reviews | "Name, CTO, Company" — never name alone | Same for text() content |

| theme lock: one theme per deck, no mid-deck switch | Dark stays dark, light stays light; micro-variation OK | #0A1E3D → #0F2847 OK; #0A1E3D → #FFF8F0 NOT OK | Same C dict throughout; no mixing primary/accent mid-deck |

Domain-Specific Content Rules (OVERRIDE above rules when domain matches)

Scientific Research — these rules REPLACE the business defaults:

| Rule | Why | Implementation |

|------|-----|----------------|

| Every data page = one Figure with caption | Journal convention; audience expects Figure-style | text(slide, x, y, w, 0.3, 'Figure N: ...', font_size=10) below visual |

| Use semantic biology colors, not brand accent | Red=upregulated, blue=downregulated has scientific meaning | C dict with up_color, down_color, control_color instead of primary/accent |

| Cite every claim: (Author, Year) or superscript | Uncited claims = scientific fraud | text(slide, x, y, w, 0.2, '¹Smith et al., Nature 2024', font_size=8, color='text_muted') |

| NO KPI cards, NO hero slides, NO feature cards | These are business patterns, meaningless in science | Use Figure+caption, data tables, sequence views instead |

| Cover = paper title format | Title + authors + affiliation, not marketing hero | text() title (28pt) + multiline() authors (14pt) + text() affiliation (12pt) |

| No animation or transition | Research slides must be printable as-is | Skip all entrance_animation() / slide_transition() calls |

| Panel labels (A, B, C) on multi-panel figures | Standard journal figure convention | text(slide, x, y, 0.4, 0.3, 'A)', font_size=10, bold=True) |

| Axis labels on all charts | Data without axis labels is uninterpretable | text(slide, x, y, w, 0.3, 'Expression (log₂FC)', font_size=9) |

Academic Thesis — additional rules:

| Rule | Why | Implementation |

|------|-----|----------------|

| Chapter-flow structure, not story arc | Thesis defense follows chapter order, not marketing arc | Ch1 Introduction → Ch2 Methods → Ch3 Results → Ch4 Discussion |

| Bibliography slide at end | Required for academic completeness | multiline() with numbered references (8-9pt) |

| Advisor/committee on cover | Academic protocol | text() advisor name + title on cover slide |

Medical/Clinical — additional rules:

| Rule | Why | Implementation |

|------|-----|----------------|

| Evidence level labels | Clinical decisions require evidence grading | text(slide, x, y, w, 0.2, '[Level A evidence]', font_size=9, color='text_muted') |

| Disclaimers where applicable | Regulatory requirement | text(slide, x, y, w, 0.3, 'Disclaimer: ...', font_size=8, color='text_muted') |

| No decorative visuals | Patient safety > aesthetics | No neon_border(), brush_divider(), ink_splash() |

When to Activate

• User asks to create/generate/design a PPT/presentation/deck/slide deck
• User wants a pitch deck, product demo, sales presentation, investor deck
• User wants to convert content/outline into PowerPoint
• User wants brand-compliant presentations with template + version control
• User wants page-level CRUD on existing PPT (add/delete/swap/move pages)
• User wants diagrams in PPT (flowchart, funnel, timeline, SWOT, etc.)
• User provides a template.pptx and wants enterprise VI compliance
• User wants scientific/academic presentation (gene, protein, thesis, dissertation, 论文, 答辩, 实验)
• User wants medical/clinical presentation (diagnosis, treatment, clinical trial, 诊断, 临床)
• Default: Build Mode is always used unless user explicitly says "quick draft" / "freestyle"

Three-Mode Architecture

| | Build Script | VI Build | FreeStyle |

|---|---|---|---|

| Use case | Delivery-grade, no template | Enterprise VI compliance | Agent-driven content.json OR quick draft (NO proposals) |

| Trigger | DEFAULT — always use unless user says "quick draft" | User provides template.pptx + requests brand compliance | You write content.json with real content, or user says "quick draft" / "freestyle" |

| Content source | Hardcoded per page in build.py | LLM reads template analysis, generates build.py | You write content.json (recommended) or one-liner topic |

| Brand compliance | Design Token dict C | Extracted VI Token from template | Style atom combos |

| Layout control | Per-element x/y/w/h | Preserve framework pages + build_helpers for new | goal + field selection (10 layout branches) |

| Font control | Run-level per character | Run-level + template font inheritance | Theme-level |

| Template reuse | None | Framework pages preserved + decorations/LOGO copied | None |

| Proposal type | 3 build.py (structural differentiation) | 3 build.py (layout strategy differentiation, same VI Token) | NO proposals — one-shot output only |

| Quality ceiling | ★★★★★ | ★★★★★ | ★★★★ (goal-driven, fixed positions) |

> Mandatory workflow: ALWAYS use Build Mode for proposals (3 structurally-different build.py). FreeStyle is for agent-driven content.json decks or quick one-shot drafts — NEVER use FreeStyle for proposal generation.

Build Mode (Pixel-Perfect Delivery) — DEFAULT & PRIMARY DELIVERY MODE

LLM writes build.py scripts from blank canvas, using build_helpers for maximum per-element control. This is the highest-quality output mode with full control over every shape's position, size, color, and typography.

When to use: ALWAYS the default mode. Use for all proposal generation and delivery-grade output (investor deck, board presentation, client deliverable). Only fall back to FreeStyle when user explicitly says "quick draft".

# LLM generates build.py, then:
python build.py

Build Mode workflow (follow Execution Workflow Steps 1-5 with Build-specific Step 2):

• Step 1: Requirements & Framework (same as all modes)
• Step 2: Generate 3 structurally-different build.py proposals → user picks direction
• Step 3: Fill chosen build.py with full content
• Step 4: Run build.py → verify → revise
• Step 5: Final delivery

See Build Helpers API section below for function reference.

VI Build Mode (Enterprise Template Compliance)

LLM reads template analysis, generates build.py that preserves framework pages (cover/TOC/back cover) and uses build_helpers for new content pages.

# Step 1: Analyze template
python -m ppt_pro_max analyze template.pptx > analysis.txt

# Step 2: Give analysis.txt to LLM, which generates build.py

# Step 3: Run build.py
python build.py

VI Build workflow in build.py:

from ppt_pro_max.build_helpers import *

# VI Token extracted from template analysis
C = {
    'primary': '#2E6504', 'accent': '#7DA92F', 'muted': '#81C784',
    'light': '#C8E6C9', 'white': '#FFFFFF', 'background': '#FFFFFF',
    'card_bg': '#F9F9F9', 'text_dark': '#1A1A1A', 'text_body': '#333333',
    'text_muted': '#666666', 'divider': '#CCCCCC',
    'font_heading': '微软雅黑', 'font_body': '微软雅黑',
}

# Load template (NOT Presentation() from scratch)
prs = Presentation('template.pptx')
template_slide = prs.slides[0]  # Reference for copying decorations/LOGO

# Framework pages (cover, TOC, back cover) are preserved — do NOT delete them
# Add new content pages:
s = add_slide(prs)
copy_decorations(s, template_slide)  # Copy visual elements from template
copy_logo(s, template_slide, color_hints=['#2E6504'])  # Copy company LOGO
page_header(s, 'Revenue Overview', 'FY2025 Performance', C)
kpi_card(s, 0.65, 1.8, 3.8, 1.35, '12.8亿', '年度产值', '+8.3%', C=C)

prs.save('output.pptx')

Key differences from Build Script:

• Start with Presentation('template.pptx') NOT Presentation()
• Framework pages (cover/TOC/back cover) are preserved untouched
• Use copy_decorations() / copy_logo() to maintain VI consistency
• VI Token (C dict) extracted from ppt-design analyze output, not hand-written

FreeStyle Mode (Agent-Driven content.json — NO Proposals)

FreeStyle renders a deck from a content.json you write (recommended, agent-driven) OR from a one-liner topic string (legacy quick draft). NO proposal step — one-shot output only. Use when user says "quick draft" / "freestyle" / "just explore", or when you need a fast, fully-editable deck.

⚠️ NEVER use FreeStyle for proposal generation. Calling generate_ppt() × 3 with different --style only swaps palette/font and produces identical layouts — this is NOT a valid proposal. Use Build Mode (build.py) for proposals.

Path A (Recommended): You write content.json → render

In an agent environment you are the LLM — you don't need Python to call an API for content. Write a content.json with real content and per-page goal, then call generate_ppt(content_file=...). This is the deterministic, high-quality path: you control every page's content AND which render branch it uses.

# query is optional when content_file contains slides[]
result = generate_ppt(content_file="content.json", style="dark-tech")

Three-layer orthogonality:

• content.json controls content (title/subtitle/bullets/cards/chart/code/diagram/exercise) + layout role (goal field → render branch)
• style param controls visuals (colors/fonts/decorations → ThemeComposer → BrandSpec)
• renderer's goal branches control structure

Prefer preset style names for deterministic output (dark-tech, professional, warm-elegant, ...). Natural-language styles like "dark cyberpunk" resolve via mood detection and may produce different palettes.

See content.json Format below for the full schema and design rules (chart format, section_number, field-to-layout mapping).

Path B (Quick draft): one-liner topic

python -m ppt_pro_max "AI startup investor pitch"

# Natural language style (40K+ combos)
python -m ppt_pro_max "fintech pitch" --style "warm fintech"
python -m ppt_pro_max "product launch" --style "dark cyberpunk"

# AI images (Seedream recommended)
python -m ppt_pro_max "AI pitch" --fetch-images --llm-provider seedream

# Exact atom control
python -m ppt_pro_max "pitch" --palette wine-burgundy --fonts elegant-serif --layout-variant centered

# Design dials
python -m ppt_pro_max "pitch" --variance 7 --motion 5 --density 6

Domain-Specific Design Paradigms

⚠️ CRITICAL: Detect domain BEFORE designing. Using the wrong paradigm produces fundamentally mismatched output (e.g., McKinsey sidebar on a genomics slide). The domain determines visual language, content structure, typography, color system, and anti-patterns.

How to Detect Domain

Match user topic/keywords to the paradigm with the most keyword hits. If ambiguous, ask the user.

| Domain | Trigger Keywords |

|--------|-----------------|

| Scientific Research | gene, protein, genome, sequencing, CRISPR, pathway, assay, omics, PCR, RNA, DNA, expression, mutation, variant, bioinformatics, proteomics, metabolomics, single-cell, immunotherapy, checkpoint, clinical trial, CRISPR, 序列, 基因, 蛋白, 测序, 组学, 免疫, 细胞, 实验, 通路, 变异 |

| Academic Thesis | thesis, dissertation, defense, viva, 论文答辩, 毕业, 学位, 答辩 |

| Engineering/Technical | architecture, system design, infrastructure, deployment, API, microservice, 架构, 系统, 部署, 工程 |

| Medical/Clinical | diagnosis, treatment, patient, clinical, surgery, therapy, 诊断, 治疗, 患者, 临床, 手术 |

| Government/Public Sector | policy, regulation, compliance, budget, annual report, 政策, 法规, 合规, 预算, 年报 |

| Business (default) | pitch, investor, sales, marketing, product launch, KPI, revenue, 投资人, 销售, 营销, 产品发布 |

Scientific Research Paradigm

Visual language: Nature/Cell/Figure style — NOT business slides. Every data page looks like a journal figure, not a marketing card.

| Aspect | DO (Research) | DON'T (Business anti-pattern) |

|--------|---------------|------------------------------|

| Page structure | Figure + caption below; one main visual per page | KPI cards, sidebar layout, feature cards |

| Data visualization | Sequence alignment, heat map, volcano plot, Manhattan plot, phylogenetic tree, gel electrophoresis, chromatogram | Bar charts with KPI labels, donut charts |

| Numbering | Figure 1, Figure 2, Figure 3... per page (required) | "01/04" card numbering (banned in business but REQUIRED here) |

| Color system | Semantic biology colors: blue=downregulation, red=upregulation, green=control, purple=mutation; or journal-specific palettes (Nature blue/gray, Cell warm) | Brand accent colors, gradient fills |

| Typography | Clean serif or sans-serif (Arial/Helvetica); figure labels 9-11pt; axis labels 10-12pt | Hero-sized titles, gradient text |

| Citations | Required: (Author, Year) or superscript number¹ after claims | No citations (business slides don't cite) |

| Cover | Paper title style: title + authors + affiliation + journal-style layout | Hero image + gradient overlay |

| Content flow | Background → Methods → Results (Fig 1-4) → Discussion → References | Hook → Problem → Features → CTA |

| Animation | NONE — research slides must be printable as-is | Any animation or transition |

Research content structure (per page):

┌──────────────────────────────────┐
│ Figure 3: ERK pathway activation │  ← Figure label (9-11pt, top-left)
│                                  │
│    [Main figure/visualization]   │  ← Full-width data visual
│                                  │
│ A) Western blot  B) Quantification│  ← Panel labels (A, B, C...)
│                                  │
│ ERK phosphorylation increased    │  ← Caption text (10-11pt)
│ 3.2-fold (p<0.01)¹              │  ← Citation
└──────────────────────────────────┘

Research Build Mode components:

| Component | Implementation |

|-----------|---------------|

| Figure label | text(slide, 0.5, 0.3, 6, 0.3, 'Figure 3:', font_size=10, color='text_dark', bold=True, C=C) |

| Panel label (A/B/C) | text(slide, x, y, 0.4, 0.3, 'A)', font_size=10, bold=True, C=C) |

| Axis labels | text(slide, x, y, w, 0.3, 'Expression (log₂FC)', font_size=9, C=C) |

| Data table | rect() header row + multiline() data rows with alternating rrect() backgrounds |

| Sequence alignment | Custom: rrect() colored blocks per residue (A=green, T=red, G=yellow, C=blue) |

| Heat map grid | Nested rrect() cells with color-coded fills per expression level |

| Citation | text(slide, x, y, w, 0.2, '¹Smith et al., Nature 2024', font_size=8, color='text_muted', C=C) |

Research color palettes:

| Palette | Colors | Use When |

|---------|--------|----------|

| nature | #2C3E50 (text), #3498DB (data blue), #E74C3C (highlight red), #95A5A6 (neutral) | General biology, genomics |

| cell-journal | #D35400 (warm accent), #2C3E50 (text), #27AE60 (green), #8E44AD (purple) | Cell biology, pathways |

| clinical | #2C3E50 (text), #2980B9 (diagnosis), #C0392B (alert), #27AE60 (positive outcome) | Clinical trials, medical |

| genomics | #2C3E50 (text), #8E44AD (mutation), #3498DB (wild-type), #E67E22 (variant) | Sequencing, variant analysis |

Academic Thesis Paradigm

Visual language: Formal academic presentation — structured, citation-heavy, defense-appropriate.

| Aspect | DO (Thesis) | DON'T |

|--------|-------------|-------|

| Structure | Title → Outline → Ch1→Ch2→Ch3→Conclusion (thesis chapter flow) | Hook→Problem→Features→CTA |

| Typography | University-standard fonts; body 14-16pt; figure captions 10-11pt | Decorative fonts, gradient text |

| References | Required on every claim; bibliography slide at end | No citations |

| Cover | University name + logo + title + author + advisor + date | Marketing-style hero |

| Animation | Minimal (fade only) | Any emphasis or exit animation |

Engineering/Technical Paradigm

Visual language: System architecture, data flow, API specs — technical documentation style.

| Aspect | DO (Engineering) | DON'T |

|--------|------------------|-------|

| Diagrams | Architecture diagrams, sequence diagrams, flow charts | Marketing feature cards |

| Code | API examples, config snippets, CLI commands (mandatory) | Generic "feature" descriptions |

| Tables | Spec tables, comparison matrices, performance benchmarks | KPI cards with trend arrows |

| Color | Technical: dark bg (#1E293B) for code, neutral grays, single accent for highlight | Brand gradients |

| Animation | Step-by-step reveal for architecture diagrams | Bounce/fly animations |

Medical/Clinical Paradigm

Visual language: Clinical, evidence-based — similar to research but with patient-safety formality.

| Aspect | DO (Medical) | DON'T |

|--------|--------------|-------|

| Data | Clinical trial results, survival curves, forest plots, diagnostic accuracy tables | Marketing dashboards |

| Color | Clinical palette (blue=diagnosis, red=alert, green=outcome); no decorative colors | Vibrant startup colors |

| Disclaimers | Required where applicable (e.g., "off-label use", "preliminary data") | None |

| Citations | Mandatory — evidence-based claims only | Uncited claims |

| Animation | NONE — must be printable for medical records | Any animation |

Government/Public Sector Paradigm

Visual language: Formal, structured, compliance-driven.

| Aspect | DO (Government) | DON'T |

|--------|----------------|-------|

| Structure | Executive summary → body → appendix; numbered sections | Marketing story arc |

| Typography | Standard serif/sans-serif; conservative; minimum 14pt body | Creative fonts |

| Color | Flag colors or institutional palette; muted | Bright startup colors |

| Data | Official statistics, budget tables, compliance matrices | Trendy infographics |

| Animation | NONE | Any animation |

Design Constraints

Design Decision Framework (intent → decision)

Before applying the quantified rules below, establish why you're making each choice. Professional designers use these mental models:

| Decision Area | Designer Question | Common Choices | Rationale |

|---------------|-------------------|----------------|-----------|

| Audience context | Who views this and where? | Boardroom / Keynote / Academic / General | Dictates density, formality, motion level |

| Visual tone | What emotion should the deck convey? | Confident / Innovative / Trustworthy / Bold | Drives palette, typography, layout density |

| Information density | How much content per slide? | Sparse (3-4 elements) / Balanced (5-7) / Dense (8+) | Matches audience attention span and content type |

| Layout rhythm | What's the visual cadence across slides? | Vary every 2-3 slides | Prevents monotony — different layouts signal progress |

| Emphasis strategy | What is the ONE thing per slide? | Hero image / Oversized number / Bold statement | Forces focus — without emphasis, slides become noise |

Apply these frameworks first, then use the quantified rules below as enforcement gates to catch violations of professional standards.

Quantified Design Constraints (violations = detectable AI Tells)

| Constraint | Threshold | Violation Consequence |

|---|---|---|

| Min font size | ≥ 11pt (CJK: ≥ 14pt) | Unreadable on projection → #2 AI Tell |

| Font-size levels per deck | ≥ 4 (hero/h1/h2/body) | 2-level deck = "AI didn't care about typography" |

| Max font families | ≤ 2 (heading + body) | 3+ fonts = "AI threw everything at the wall" |

| Accent colors | ≤ 1 per deck | Multi-accent = "AI can't commit to a palette" |

| Corner radius system | 1 per deck (0pt / 8-12pt / pill) | Mixed radii = "AI has no design system" |

| Slides ≥ 8 pages | ≥ 4 distinct layout structures | Same layout × 8 = "AI copy-pasted" |

| Cover title | ≤ 2 lines, 44-52pt | 3+ lines = "AI couldn't summarize" |

| Bullets per page | ≤ 5: single col; 6-9: two col; 10+: cards/grid | 10+ bullets in list = "AI dumped text" |

| Images | ALWAYS cover_image(), NEVER add_picture() stretch | Stretched image = "AI doesn't understand aspect ratio" |

| CJK body text | 14-15pt (NOT 11-12pt Latin presets) | 11pt CJK = "AI used Latin defaults, characters unreadable" |

| Dark theme text | ≥ 60% luminance above background | Low contrast = "AI can't see its own output" |

| Shapes per slide | ≤ 50 | 50+ = performance issues on older hardware |

Typography

• Cover title: 44-52pt, ≤2 lines | Inner title: 32-36pt | Body: 14-16pt | Bullets: 13-14pt | Caption: 11-12pt
• Min 4 font-size levels per deck — 2 levels (title+body only) is forbidden
• NO Calibri/Arial as default font (PPT's AI default, same as Inter in web)
• Serif: only for editorial / luxury / heritage scenes — NOT for tech/startup/data
• Max 2 font families per deck (heading + body, +1 monospace for code)
• Emphasize with bold or color shift — NO mixing serif+sans for "contrast emphasis"
• Italic title line-height ≥1.1× (descender clearance)
• Each page: short title (≤8 words) + short subtitle (≤25 chars) + 1 visual OR 1 CTA

Color

• Max 1 accent color per deck, used on EVERY page (consistency lock)
• NO default-blue gradient cover when style is unspecified
• NO default gold+navy for "premium" scenes (#1A1A2E / #C9A96E family)
• Warm/cool gray: pick one, use throughout — no mixing
• Chart colors derived from main palette — no rainbow
• Dark theme: text ≥60% luminance above background (projection-grade contrast)
• Light theme: no light-gray text on white (invisible on projector)

Layout

• VARIANCE > 4: avoid all-centered; use left-aligned / sidebar / asymmetric
• Same layout family max 1 occurrence per deck ("Our Products" ≠ "Core Advantages" visually)
• 8+ slides: ≥4 distinct visual layouts
• Left-right alternation ≤2 times; 3rd = break pattern
• Eyebrow count ≤ceil(page_count / 3); NO section-number eyebrows (00/INDEX, 001·核心能力)
• No split-header as default (title left + small text right)
• Bento grid: ≥2-3 cells with visual variation (not all-white text cards)
• Spec sheets: NO 10-line bullet lists — use card grid / highlight+fold / grouped sections
• NO 20+ row data tables in PPT — PPT is presentation, not document

Page Roles

• MUST plan 5 roles: breathing (low-density rest) / section-divider / data-impact (big number) / visual-anchor (full-bleed image) / cta
• No 3 consecutive "title + bullets" pages
• 6+ slides: ≥1 section divider
• High-density page → must be followed by low-density page

Visual Assets

• Cover MUST have real visual (not text + gradient block)
• Even minimalist style: ≥2-3 pages with images
• NO fake product screenshots (text-box dashboards/terminals/task-lists — #1 AI Tell in PPT)
• Logo wall: use real logo images, not text spans

Consistency Locks

• Corner radius: ONE system per deck — sharp (0pt) / soft (8-12pt) / pill — no mixing
• Font pair: consistent throughout (heading + body, all slides)
• Accent color + warm/cool gray + theme lock: enforced in Color rules and Content Design Rules

AI Tells Blacklist (HARD BAN unless user explicitly requests, OR domain is scientific/academic/medical)

Domain exceptions: In Scientific Research, Academic Thesis, and Medical domains, the following are REQUIRED (not banned):

• Figure numbering (Figure 1, Figure 2) — required for research data pages
• Panel labels (A, B, C) — required for multi-panel figures
• Section numbers (1. Introduction, 2. Methods) — required for thesis chapters
• Citation superscripts (¹, ²) — required for evidence-based claims

• No cover version labels (V0.6/BETA/内测版)
• No "Brand · No.01" style sub-labels
• No section-number eyebrows (00/INDEX, 001·核心能力) — use natural language
• No card/image numbering labels (01/04, 1/3)
• Max 1 middle-dot (·) per metadata line — no "foo · bar · baz · qux"
• No decorative status dots
• No em-dash (—) or Chinese em-dash (——) — use comma/hyphen/semicolon
• No linebreak+italic "design trick"
• No vertical rotated text
• No crosshair/fine-grid decoration (only for organizing real content)
• No fake product UI (text-box dashboard/terminal/task-list)
• No fake version footers (v0.6.2-rc.1, "last sync 4s ago")
• No "silently used by" / "默默服务" social-proof headlines — use natural language or skip
• No "来自一线" / "实战笔记" artisan labels — use plain functional labels
• No city/time/weather bars (99% of scenarios)
• No eyebrow micro-metadata sentences
• No generic step labels ("Phase 1/2/3", "步骤 01/02/03") — use verb+noun
• No overlaid labels on images ("Brand · 02")
• No decorative photo credits (场景 III · 35mm) — skip or use one-line caption
• No version footers on marketing slides (v1.4.2, Build 0048)
• No inventory counters as decoration ("已预约 412/800")
• No bottom-of-cover decoration strips (品牌. 创新. 技术.)
• No floating explanation text top-right of section titles
• No divider lines on every row of long lists
• No progress bars with filled background tracks for comparison
• No scroll hints (Scroll, ↓)

Design Vocabulary (pattern → FreeStyle trigger → Build implementation)

Covers:

| Pattern | FreeStyle Trigger | Build Implementation |

|---------|-------------------|---------------------|

| Asymmetric Split Hero | goal:"hook", image on one side | rect() split bg + text() left + image right |

| Editorial Manifesto | goal:"hook", no image, large type | hero_slide() text-only |

| Full-Bleed Image | goal:"hook", image with overlay | rect() full-bg + image + gradient_text() overlay |

| Data-Impact | goal:"hook", big number + one-liner | rect() bg + text() huge number + text() one-liner |

| Minimal Typography | goal:"hook", text-only, extreme whitespace | text() large title with wide margins |

Inner pages:

| Pattern | FreeStyle Trigger | Build Implementation |

|---------|-------------------|---------------------|

| Sidebar+Content | --layout-variant sidebar-left | rect() sidebar + page_header() + content right |

| Split Text-Image | goal:"content", image field | text() left half + circle_image() right |

| Bento Grid | goal:"features", 4+ cards | rrect() grid of 4+ cells |

| Big Number Focus | goal:"data", single metric | text() oversized number + text() label |

| Card Row | goal:"features", 3 cards | highlight_cards() |

| Comparison Split | goal:"content", two-column contrast | comparison_bars() or two multiline() side by side |

| Timeline Horizontal | component_category:"timeline" | rect() line + oval() dots + text() labels |

| Quote Spotlight | goal:"content", quote in bullets | gradient_text() large quote + text() attribution |

| Code Terminal | goal:"code" | code_block() |

| Full-Width Visual | goal:"content", full-bleed image | rect() bg image + frosted_panel() + text() |

Data pages:

| Pattern | FreeStyle Trigger | Build Implementation |

|---------|-------------------|---------------------|

| Table Diagram | goal:"data", diagram type:"table" | rect() headers + multiline() rows |

| Chart Focus | goal:"data", diagram type: chart | bar_chart() or donut_chart() |

| Metric Dashboard | component_category:"infographic" | kpi_card() grid |

| Infographic Component | component_type:"group" | Custom shapes with rect()/oval()/text() |

| Number Grid | goal:"data", 2x2 metrics | 2x2 kpi_card() layout |

Content relationship → visual strategy:

| Relationship | Visual Strategy | FreeStyle Trigger | Build Implementation |

|--------------|----------------|-------------------|---------------------|

| Sequential | Timeline | component_category:"timeline" | Custom timeline with rect()/oval()/text() |

| Contrast | Comparison Split | goal:"content" two-col | comparison_bars() |

| Primary+secondary | Unequal layout | --layout-variant sidebar-left | Sidebar rect() + main content |

| Equal-weight | Card Row | goal:"features" | highlight_cards() |

| Hierarchical | Hierarchy tree | component_type:"group" | Custom tree with rect()/text() |

| Evidence | Center + orbit | Auto | oval() + text() |

| Process | Cycle/Process | component_category:"process" | Custom cycle with oval()/text() |

| Data-driven | Big Number/Chart | goal:"data" | kpi_card() or bar_chart() |

Redesign Protocol

• Greenfield: start from Dial baseline
• Redesign-Preserve: audit brand tokens → incremental evolution
• Redesign-Overhaul: visually equivalent to greenfield
• Audit before modifying: brand tokens / information architecture / content blocks / patterns to keep / patterns to kill
• Modernization levers (in order): fonts → spacing → colors → animations → key-page rebuild → full replacement
• Never silently change: page order / navigation labels / logo / legal copy

Design System Mapping

• Consulting/finance → sidebar + diagram engine process/hierarchy
• Tech talks → code block + diagram engine infographic
• Education → exercise page + built-in bullets
• Creative proposals → custom blocks + AI images
• Brand launch → full-bleed images + minimal text
• Scientific research → Figure-style pages + semantic biology colors + sequence alignment + citations + NO animation
• Academic thesis → chapter flow + formal serif + citations + bibliography + NO animation
• Engineering → architecture diagrams + code blocks + spec tables + dark bg code
• Medical/clinical → clinical data tables + survival curves + evidence citations + disclaimers + NO animation
• Government → executive summary + numbered sections + flag colors + compliance tables + NO animation
• ONE design system per deck — no mixing McKinsey sidebar with Nature Figure style

Performance & Accessibility

• <50 shapes per slide | images: cover-fit crop, never stretch | cache-first
• Public-sector / accessibility scenes: motion ≤3 | unknown audience: motion ≤5
• Dark mode: no pure black (#000) or pure white (#FFF) — use near-black/near-white
• Z-order: background < content < decoration < overlay

Scope Exclusions

• Pure data tables → Excel | Multi-step forms → Web app | Real-time collaboration → Dedicated app | Interactive dashboards → Power BI/Tableau | Long documents (>50 pages) → Word/PDF

Pre-Flight Check

• [ ] Basics: fonts ≥11pt | pages ≥3 shapes | text on every page | images correct | no broken links
• [ ] Consistency: accent color throughout | corner radius uniform | font pair uniform | theme locked | font-size levels ≥4
• [ ] Typography: cover title ≤2 lines | subtitle ≤20 chars | inner title ≤2 lines | no rotated text | line-height ≥1.1 for italic
• [ ] Layout: adjacent pages different layout family | 8+ pages ≥4 layouts | first card featured | no 3 consecutive same-structure pages | alternation ≤2
• [ ] Labels: eyebrow ≤ceil(pages/3) | no numbered eyebrows | no image overlay labels | no status dots | no generic step labels
• [ ] Color: no default-blue cover (unless specified) | no default gold+navy | chart colors from palette | dark-theme contrast sufficient | no light-gray on white
• [ ] Rhythm: 6+ pages have divider | hook ≠ cta visually | density varies | high-density followed by low | ≤1 core message per page
• [ ] Content: no AI Tells violations | no fake precision numbers | bullets have logical relation | quotes ≤3 lines with attribution
• [ ] Visuals: cover has real visual | minimalist ≥2-3 pages with images | bento ≥2-3 cells varied | logo wall uses images
• [ ] Scene: projection contrast OK | print doesn't rely on animation | large-screen numbers ≥36pt
• [ ] Animation: each has stated purpose | motion>4 has real animations | marquee ≤1/page
• [ ] Dial: values derived from Design Read | variance>4 has asymmetric layouts | density varies across pages

Python API

from ppt_pro_max import generate_ppt, fetch_image

# Build Mode (primary delivery mode)
# LLM writes build.py using build_helpers — see Build Helpers API section

# FreeStyle
result = generate_ppt("AI startup investor pitch", style="dark cyberpunk", fetch_images=True)

# With content.json (agent-driven — recommended). query is OPTIONAL when content_file contains slides[].
# content_file with slides[] bypasses StoryPlanner/ContentGenerator and renders your pages directly.
result = generate_ppt(content_file="content.json", style="warm fintech", fetch_images=True)
result = generate_ppt("pitch", content_file="content.json", style="dark-tech")

# With design dials
result = generate_ppt("pitch", content_file="content.json", style="professional",
                      layout_variant="sidebar-left", motion=5, density=6, variance=7)

# Proposal flow (DEPRECATED for proposals — use Build Mode build.py instead)
# This only swaps palette/mood, NOT layout structure. Use build.py proposals for structural differentiation.
result = generate_ppt("pitch", proposal=True, style="dark cyberpunk")

# Standalone image generation
img = fetch_image("futuristic AI city", mode="generate", llm_provider="seedream", llm_api_key="...")
print(img["path"])

Key generate_ppt() parameters: query, style, content_file, layout_variant, variance, motion, density, fetch_images, palette, fonts, decoration, mood, llm_provider, llm_api_key, pages

4-Phase Pipeline

• Story Planning → strategy + page structure + emotion arc
• Design Decisions → per-page layout/color/typography from 40K+ combos
• Content Generation → copy formulas (PAS/FAB/AIDA) + image keywords
• PPT Rendering → python-pptx direct, 12 master layouts, QA gates

Design Atoms (40,000+ Combos)

| Atom | Count | Examples |

|------|-------|----------|

| Color Palettes | 25 | ocean-blue, cyber-neon, golden-luxury, wine-burgundy, midnight-navy, monochrome-dark... |

| Font Pairs | 20 | modern-sans, elegant-serif, tech-mono, contrast-mix, sharp-modern... |

| Decorations | 10 | accent-bar, neon-lines, gold-trim, diamond-bullets, gradient-bar, sidebar-nav, minimal-dots, circle-accent, no-decoration, full-bleed-overlay |

| Layout Variants | 8 | standard, centered, sidebar-left, sidebar-right, grid-2x2, asymmetric... |

Natural language: --style "warm fintech" auto-selects matching atoms. Decoration and layout-variant atoms are consumed by PrecisionRenderer — they control title decoration, margin positioning, and card style.

10 Diagram Types

| Type | Description | Data Format |

|------|-------------|-------------|

| Flowchart | Process flow, auto horizontal/vertical | nodes + connectors |

| Funnel | Decreasing width stages | stages (items) |

| Timeline | Alternating top/bottom labels | events (items) |

| SWOT | 4-quadrant analysis | strengths/weaknesses/opportunities/threats |

| Matrix | Comparison grid | rows + columns |

| Cycle | Circular arrangement | stages (items) |

| Table | Alternating row colors | headers + rows |

| Hierarchy | Parent-child tree | nodes with parent |

| Pyramid | Stacked levels | levels (items) |

| Venn | 2-3 set intersection | sets with labels |

Image Engines