Ppt Creator

PPT Creator

Goal: Transform a simple topic into a presentation-ready, high-quality slide deck. When key information is missing, use the minimal intake form (references/INTAKE.md) to gather context or apply safe defaults. Then follow the workflow (references/WORKFLOW.md) to produce an outline, slide drafts, charts, and speaker notes. After generation, self-evaluate using the rubric (references/RUBRIC.md); if the score is < 75, automatically refine up to 2 iterations until ≥ 75 before delivery. See Deliverables section for final output structure.

When to Use This Skill

Use this skill when the user requests:

• "Make a presentation/deck/PPT/slides" on any topic
• "Improve/optimize a presentation/pitch/demo"
• Converting scattered materials into a structured, persuasive slide deck
• Creating presentations with data visualization and speaker notes
• Building decks for business reviews, product pitches, educational content, or reports

Quick Start

1. Gather Intent: If critical information is missing, ask the 10 Minimal Questions (references/INTAKE.md). If the user doesn't respond after 2 prompts, use the safe default for each item and clearly note assumptions in speaker notes.

2. Structure the Story: Apply the Pyramid Principle to establish "one conclusion → 3-5 top-level reasons → supporting evidence." Each slide uses assertion-style headings (complete sentences), with body content providing evidence (charts/tables/diagrams/data points). Templates are in references/TEMPLATES.md

3. Choose Charts: Use the Chart Selection Dictionary in references/VIS-GUIDE.md to pick the most appropriate visualization for each point. If the user provides data (tables/CSV), optionally call scripts/chartkit.py to generate PNG charts; otherwise, create placeholder diagrams with a list of required data fields.

4. Layout & Style: Follow references/STYLE-GUIDE.md for font sizes, line spacing, white space, contrast ratios, color palettes, and accessibility (WCAG AA compliance).

5. Speaker Notes: Generate 45-60 second speaker notes for each slide, structured as: opening → core assertion → evidence explanation → transition.

6. Self-Check & Score: Use references/CHECKLIST.md for a pre-flight check, then score with references/RUBRIC.md If total score < 75, identify the weakest 3 items and refine; repeat scoring (max 2 iterations).

7. Deliverables (all saved to /output/):

• /output/slides.md: Markdown slides (Marp/Reveal.js compatible), with assertion-style headings + bullet points/chart placeholders + notes
• /output/assets/*.png: Generated charts (if applicable)
• /output/notes.md: Full speaker notes and delivery outline
• /output/refs.md: Citations and data sources
• /output/presentation.pptx: If python-pptx is available, export to PPTX; otherwise, keep Markdown and include instructions for "one-click conversion to PPTX" in the first screen (does not block delivery)

Orchestration Mode (End-to-End Automation)

When the user requests a "complete" or "presentation-ready" deliverable, ppt-creator automatically orchestrates the full pipeline: content creation → data synthesis → chart generation → dual-path PPTX creation (Marp + document-skills:pptx) → chart insertion. This typically delivers TWO complete PPTX files with different styling for user comparison.

Activation: Phrases like "complete PPTX", "final deliverable", "ready for presentation" Duration: 4-6 minutes (parallel execution) Output: presentation_marp_with_charts.pptx + presentation_pptx_with_charts.pptx

For orchestration details, see references/ORCHESTRATION_OVERVIEW.md (start here), then navigate to specialized guides as needed.

Core Principles (Must Follow)

• Information Organization: Conclusion first, then evidence (Pyramid Principle). Each slide conveys only 1 core idea. Headings must be testable assertion sentences, not topic labels.
• Evidence-First: Use charts/tables/evidence blocks instead of long paragraphs; limit to 3-5 bullet points per slide.
• Data Visualization: Chart selection and labeling (axes/units/sources) must comply with references/VIS-GUIDE.md If data is insufficient, provide "placeholder chart + list of missing fields."
• Accessibility: Color and text contrast must meet AA standards (see STYLE-GUIDE). Provide alt/readable descriptions for charts and images.
• Reusability: Use consistent naming, stable paths, reproducible output. Do not hard-code random numbers in code.
• Safety & Dependencies: Do not scrape the web without permission. Only run scripts when user provides data. If matplotlib/pandas are unavailable, fall back to text + placeholder diagram instructions.

Workflow Overview

Stage 0 - Archive Input: Record user's original request, defaults used, and assumptions made.

Stage 1 - Structure Goals: Rewrite the goal into "who takes what action when" (clear CTA).

Stage 2 - Storyline: Use Pyramid Principle to define "one-sentence conclusion → 3-5 first-level reasons → evidence."

Stage 3 - Outline & Slide Titles: Create a 12-15 slide chapter skeleton. Each slide has one assertion-style heading.

Stage 4 - Evidence & Charts: Use the Chart Selection Dictionary from VIS-GUIDE. If data is provided, call chartkit.py to generate PNGs; otherwise, create placeholder + required field list.

Stage 5 - Layout & Accessibility: Apply STYLE-GUIDE for font sizes, spacing, contrast ratios, color palettes; unify units and decimal places.

Stage 6 - Speaker Notes: Generate 45-60 second notes per slide: opening → assertion → evidence explanation → transition.

Stage 7 - Self-Check & Scoring: Run CHECKLIST; score with RUBRIC. If score < 75, focus on weakest 3 items, refine, re-score (max 2 iterations).

Stage 8 - Package Deliverables: Generate /output/ directory with slides.md / notes.md / refs.md / assets/*.png. If python-pptx is available, export PPTX.

Stage 9 - Reuse Instructions: Append a "5-step guide to replace data/colors with your own" at the end of notes.md.

Resources

references/INTAKE.md

Minimal 10-Item Questionnaire (use defaults if missing): 1. Who is the audience? (Default: general public) 2. Core objective? (Default: "understand and accept" a proposition) 3. Desired action/decision? (Default: agree to move to next step after the meeting) 4. Duration & slide count limit? (Default: 15-20 min, 12-15 slides) 5. Tone & style? (Default: professional, clear, friendly) 6. Topic scope & boundaries? (Default: given topic + 1 layer related) 7. Must-include points/taboos? (Default: none) 8. Available data/tables? (Default: none; can generate structure placeholder + list required fields) 9. Brand & visual constraints? (Default: built-in neutral theme) 10. Deliverable format preference? (Default: slides.md + optional PNG charts; export PPTX if available)

references/WORKFLOW.md

Detailed step-by-step process from "topic" to "presentation-ready output."

references/TEMPLATES.md

Slide Template Library (assertion-evidence style):

• Cover, Table of Contents, Problem Statement, Opportunity/Goal, Solution Overview, Evidence 1-3, Risk & Mitigation, Case Study/Comparison, Roadmap/Timeline, Conclusion & Actions, Backup Slides
• Micro-templates: Comparison (A vs B), Pyramid Summary, Process 4-Step, KPI Dashboard, Geographic Distribution, Funnel, Pareto, Sensitivity, Cost Structure (Waterfall), Contribution (Stacked)

references/VIS-GUIDE.md

Data Visualization Selection & Labeling Standards:

• Chart Selection Dictionary (common questions → chart types)
• Labeling & units (axes, units, data scope, time range; source in footer)
• Accessibility & contrast (WCAG 2.1 AA: text vs background ≥ 4.5:1; UI elements ≥ 3:1)
• Assertion-Evidence writing tips

references/STYLE-GUIDE.md

Layout & Style (neutral theme, supports brand replacement):

• Canvas: 16:9; safe margins ≥ 48px; grid column spacing 24px
• Fonts: Chinese (Source Han Sans/PingFang/Hiragino Sans), English (Inter/Calibri)
• Font sizes: Heading 34-40, Subheading 24-28, Body 18-22, Footer 14-16
• Line spacing: Heading 1.1, Body 1.3; bullet spacing ≥ 8px
• Color palette (AA compliant): Dark ink #1F2937 / Background #FFFFFF / Accent #2563EB / Emphasis #DC2626
• Components: unified 6-8px border radius; charts and images with 8px padding
• Images: add brief alt descriptions for screen readers
• Page density: ≤ 70 words per slide (excluding captions)

references/RUBRIC.md

PPT Quality Scoring Rubric (100 points; ≥ 75 to deliver): Each item scored 0-10: 1. Goal Clarity: Audience, objective, CTA well-defined 2. Story Structure: Pyramid structure complete, hierarchy clear 3. Slide Assertions: Headings are "assertion sentences" supported by evidence 4. Evidence Quality: Data/cases/citations sufficient, credible, consistent calibration 5. Chart Fit: Correct selection, complete labeling, readable 6. Visual & Accessibility: Contrast, font size, white space, color compliance 7. Coherence & Transitions: Natural chapter and page transitions 8. Speakability: 45-60 sec per slide, natural language 9. Deliverables Complete: slides.md / notes.md / refs.md / (optional) assets/.png 10. Robustness*: Gaps explicitly marked, fallback plan & next steps provided

Self-evaluation process: Run CHECKLIST first, then score each item and write top 3 low-scoring items + improvement actions. If total < 75, apply actions and re-score (max 2 iterations).

references/CHECKLIST.md

Pre-flight checklist for final quality assurance before delivery.

references/EXAMPLES.md

Two Usage Examples:

• Example A: Ultra-simple topic ("coffee") → trigger minimal questionnaire, generate 12-page framework with placeholder charts
• Example B: Small business monthly review with attached CSV → parse data, select charts per VIS-GUIDE, call chartkit.py, refine 1-2 iterations if score < 75

scripts/chartkit.py

Minimal chart renderer for ppt-creator.

Usage:

python scripts/chartkit.py \
  --data path/to/data.csv \
  --type line \
  --x date \
  --y sales profit \
  --out output/assets \
  --filename kpi_trend.png \
  --title "Monthly KPIs"

Notes:

• Requires: pandas, matplotlib
• Fallback: If packages unavailable, print instruction message and exit(0)
• Uses matplotlib defaults for readability (no hard-coded brand colors)

Advanced Tips

• This skill complements (not conflicts with) Anthropic's built-in PowerPoint generation capabilities. Use this skill to produce "high-quality structure & content," then optionally invoke system capabilities to export the final PPTX file.
• For complex data analysis needs, combine with other skills (e.g., data analysis, charting) before invoking ppt-creator.
• The skill is designed to be forgiving: missing information triggers safe defaults rather than blocking progress.

Pre-Flight Checklist

Purpose: Final quality assurance before delivery. Use this checklist before running the full RUBRIC.md scoring. This ensures all required elements are present and obvious issues are caught early.

---

How to Use This Checklist

1. When: Run this checklist after completing WORKFLOW Stage 7 (before final scoring) 2. Method: Go through each section; check ✓ or note issues 3. Threshold: All items in sections 1-5 must be ✓ before delivery; section 6-7 are optional enhancements 4. Time: ~5-10 minutes for a 12-15 slide deck

---

Section 1: Content Completeness

Slide Count & Structure

• [ ] Total slide count matches target range (typically 12-15 slides for 15-20 min presentation)
• [ ] Cover slide present with title, subtitle, date, presenter
• [ ] Table of Contents present and matches actual sections
• [ ] Main content slides (evidence/argument slides) present
• [ ] Conclusion slide present with clear call-to-action (CTA)
• [ ] Backup slides (if needed) clearly marked "Backup—not presented"

If any unchecked: Add missing slides or adjust scope.

---

Intake & Assumptions

• [ ] INTAKE.md questions answered or defaulted (all 10 items)
• [ ] Assumptions documented in /output/notes.md (if defaults were used)
• [ ] User's original request recorded in archive.txt or notes

If any unchecked: Review INTAKE.md and document assumptions.

---

Section 2: Story & Structure

Pyramid Principle

• [ ] Main conclusion stated on cover slide (assertion sentence)
• [ ] 3-5 first-level reasons identified and each has a section
• [ ] Evidence slides support each reason (2-3 slides per reason)
• [ ] Logical flow: Conclusion → Reasons → Evidence (not evidence → conclusion)

If any unchecked: Revise structure per WORKFLOW Stage 2.

---

Slide Headings (Assertion-Evidence)

• [ ] All slide headings are assertion sentences (testable claims, not topic labels)
• ✅ Example: "Finer grind size extracts flavors faster"
• ❌ Counter-example: "Grind Size" or "Background"
• [ ] Headings are complete sentences (subject + verb + object)
• [ ] Headings match the evidence shown on the slide

Quick Test: Can you agree or disagree with each heading? (If no → it's a topic label, needs revision)

If any unchecked: Convert topic labels to assertion sentences (see TEMPLATES.md).

---

Section 3: Evidence & Data

Evidence for Claims

• [ ] Every assertion slide has supporting evidence (chart, table, example, case study, or diagram)
• [ ] No unsupported claims (all "X is true" statements backed by data/citations)
• [ ] Placeholder charts (if data unavailable) include:
• Chart type (e.g., "line chart", "bar chart")
• Axes and variables (e.g., "X: month, Y: revenue")
• Required data fields (e.g., "Need: month, revenue_usd")

If any unchecked: Add evidence or create detailed placeholders.

---

Charts & Visualizations

• [ ] Chart type matches message (verified against VIS-GUIDE.md Chart Selection Dictionary)
• Trend over time → line/area chart
• Comparison → horizontal bar chart
• Composition → stacked bar / treemap
• Correlation → scatter plot
• [ ] All charts have axis labels (X-axis and Y-axis labeled with units)
• [ ] All charts have data sources cited in footer (e.g., "Source: XYZ, 2024")
• [ ] All charts have alt text for screen readers (brief description of insight)
• [ ] Chart colors are colorblind-friendly (avoid red+green; use blue+orange)

If any unchecked: Fix chart selection, labeling, or add missing elements.

---

Section 4: Visual Design & Accessibility

Typography

• [ ] Heading font size ≥ 34pt
• [ ] Body font size ≥ 18pt
• [ ] Footer font size ≥ 14pt (but not smaller)
• [ ] Line spacing: Headings 1.1×, body 1.3-1.5×
• [ ] Fonts consistent across all slides (same family for headings, same for body)

If any unchecked: Adjust font sizes per STYLE-GUIDE.md.

---

Color & Contrast

• [ ] Text contrast ≥ 4.5:1 against background (normal text <18pt)
• [ ] Large text contrast ≥ 3:1 (headings ≥18pt or ≥14pt bold)
• [ ] UI elements contrast ≥ 3:1 (chart bars, icons, dividers)
• [ ] Not relying on color alone (patterns/labels added for charts with multiple series)

How to check: Use WebAIM Contrast Checker or browser DevTools.

If any unchecked: Adjust colors to meet WCAG AA standards (see STYLE-GUIDE.md).

---

Layout & Spacing

• [ ] Safe margins ≥ 48px on all sides (content within safe zone)
• [ ] Bullet points limited to 3-5 per slide (not 8-10)
• [ ] Word count ≤ 70 words per slide (excluding chart labels and footer)
• [ ] White space ~40-50% of each slide (not crammed full)
• [ ] Consistent alignment: Headings and body text left-aligned (unless intentionally centered)

If any unchecked: Increase margins, reduce text, or split into multiple slides.

---

Images & Alt Text

• [ ] All images have alt text (descriptive, 1-2 sentences)
• [ ] All charts have alt text (includes key insight, e.g., "Line chart showing 35% revenue growth Jan-Dec 2024")
• [ ] Images not stretched or distorted (maintain aspect ratio)

If any unchecked: Add alt text or fix image formatting.

---

Section 5: Speaker Notes & Timing

Speaker Notes Quality

• [ ] Every slide has speaker notes (except backup slides)
• [ ] Notes are 45-60 seconds per slide (read aloud to verify)
• [ ] Notes use natural spoken language (not bullet points or written prose)
• [ ] Notes follow structure: Opening → Core Assertion → Evidence Explanation → Transition
• [ ] Notes include transitions to next slide (e.g., "This leads us to...")

If any unchecked: Revise notes per WORKFLOW Stage 6.

---

Total Timing

• [ ] Total presentation time matches target (e.g., 15 min = ~15 slides × 60 sec)
• [ ] Timing buffer included (5-10% slack for questions/pauses)

Quick Calc: Count slides (excluding cover, TOC, backup) × 60 sec = estimated time.

If any unchecked: Adjust slide count or speaker notes length.

---

Section 6: Deliverables (Output Files)

Required Files

• [ ] /output/slides.md exists and is properly formatted (Markdown with YAML frontmatter)
• [ ] /output/notes.md exists with full speaker script
• [ ] /output/refs.md exists with all citations and sources
• [ ] /output/assets/ directory exists (even if empty)
• [ ] /output/README.md exists explaining file structure

If any unchecked: Generate missing files per WORKFLOW Stage 8.

---

Optional Files (If Applicable)

• [ ] /output/assets/*.png charts generated (if data was provided and chartkit.py was used)
• [ ] /output/presentation.pptx exported (if python-pptx is available)
• If not available: Instructions for PPTX conversion included in notes.md

If any unchecked: Generate charts or add conversion instructions.

---

Section 7: Polish & Enhancements (Optional but Recommended)

Consistency Checks

• [ ] Number formatting consistent: Same decimal places for same metric (e.g., all percentages to 1 decimal)
• [ ] Units consistent: All currency in $ or all in €; don't mix
• [ ] Date format consistent: All "Jan 2024" or all "2024-01" (pick one)
• [ ] Capitalization consistent: Heading case for all slide titles

---

Branding (If Applicable)

• [ ] Brand colors applied (if provided in INTAKE question 9)
• [ ] Logo added to cover slide and/or footer (if applicable)
• [ ] Brand fonts used (if specified)

If unchecked and brand was specified: Apply per STYLE-GUIDE customization section.

---

Reuse Guide

• [ ] "5-Step Reuse Guide" appended to notes.md (helps user customize later)
• [ ] chartkit.py usage examples included (if charts were generated)
• [ ] Markdown-to-PPTX conversion instructions included (if PPTX not auto-generated)

If any unchecked: Add per WORKFLOW Stage 9.

---

Section 8: Final Sanity Checks

Links & References

• [ ] All internal links work (e.g., references to "See backup slide 14")
• [ ] All chart/image paths correct (no broken image links in slides.md)
• [ ] All citations complete (author, year, source name)

---

Spelling & Grammar

• [ ] Spell-check run on all text (slides + notes)
• [ ] Grammar checked (especially speaker notes, which are full sentences)
• [ ] Consistent terminology (e.g., don't switch between "users" and "customers")

Tool suggestions: Grammarly, LanguageTool, or built-in spell-checker.

---

Edge Cases

• [ ] Long words or URLs broken or shortened (avoid overflow)
• [ ] Special characters (©, ®, ™, °, etc.) display correctly
• [ ] Non-English text (if any) uses correct fonts and displays properly

---

Checklist Summary

Count your checks:

• Section 1 (Content): ___ / 9 items ✓
• Section 2 (Structure): ___ / 8 items ✓
• Section 3 (Evidence): ___ / 9 items ✓
• Section 4 (Design): ___ / 18 items ✓
• Section 5 (Notes): ___ / 7 items ✓
• Section 6 (Deliverables): ___ / 7 items ✓
• Section 7 (Polish): ___ / 7 items ✓ (optional)
• Section 8 (Sanity): ___ / 6 items ✓

TOTAL: ___ / 64 core items (sections 1-6)

PASSING CRITERIA:

• Sections 1-6: All items ✓ (64/64 required)
• Section 7-8: Nice-to-have but not required for delivery

---

What to Do If Items Are Unchecked

Minor Issues (1-5 unchecked in sections 1-6)

Action: Fix the specific items now before moving to RUBRIC scoring.

Example:

• Missing alt text on 2 charts → Add alt text
• One topic-label heading → Convert to assertion sentence
• Font size 16pt on one slide → Increase to 18pt

---

Moderate Issues (6-15 unchecked in sections 1-6)

Action: Prioritize the most impactful fixes first: 1. Structure issues (Section 2): Fix pyramid structure, convert headings 2. Evidence gaps (Section 3): Add missing charts or citations 3. Accessibility (Section 4): Fix contrast, font sizes 4. Speaker notes (Section 5): Revise timing or add transitions

Estimated Time: 15-30 minutes of fixes before re-running checklist.

---

Major Issues (16+ unchecked in sections 1-6)

Action: Return to WORKFLOW Stage 3-4 and rebuild:

• If structure is broken (Section 2): Restart from Stage 3 (Outline)
• If evidence is weak (Section 3): Restart from Stage 4 (Evidence & Charts)
• If design is poor (Section 4): Apply STYLE-GUIDE systematically

Estimated Time: 1-2 hours of rework.

---

After Checklist: Next Steps

Once all core items (Sections 1-6) are ✓:

1. Proceed to RUBRIC.md for detailed scoring (0-10 per item, total 100) 2. If RUBRIC score ≥ 75: Package deliverables and deliver 3. If RUBRIC score < 75: Apply top 3 improvements and re-score (max 2 iterations)

---

Quick Reference: Most Common Issues

Based on typical PPT creation, here are the top 10 most common checklist failures:

1. ❌ Slide headings are topic labels (not assertion sentences) → Fix: Convert to testable claims 2. ❌ Missing source citations on charts → Fix: Add "Source: XYZ, 2024" in footer 3. ❌ Font sizes too small (body <18pt) → Fix: Increase to 18-22pt 4. ❌ No alt text on charts → Fix: Add brief description with key insight 5. ❌ Poor contrast (<4.5:1) → Fix: Darken text or lighten background 6. ❌ Too many bullets (>5 per slide) → Fix: Split into 2 slides or reduce 7. ❌ No speaker notes on some slides → Fix: Write 45-60 sec script per slide 8. ❌ Assumptions not documented (if defaults used) → Fix: Add to notes.md 9. ❌ Chart type mismatch (e.g., pie chart for 7 categories) → Fix: Use bar chart instead 10. ❌ Inconsistent number formatting (mixing "1.2M" and "850,000") → Fix: Use same abbreviation style

---

Checklist Completion Log

Presentation: [Title] Date: [YYYY-MM-DD] Checked by: Claude Status: [PASS / FAIL]

Issues Found: [Number] Issues Fixed: [Number] Remaining: [Number]

Notes:

• [List any issues not yet fixed]
• [Next steps or blockers]

---

Next Steps: After all checklist items are ✓, proceed to RUBRIC.md for full scoring.

Usage Examples

Purpose: Demonstrate the full ppt-creator workflow with two realistic scenarios—one ultra-simple topic with no data, and one business scenario with data. These examples show how the skill handles minimal input, applies defaults, generates placeholders, and delivers ≥75 score presentations.

---

Example A: Ultra-Simple Topic (No Data)

User Input

User: "Make me a presentation about coffee"

What's Missing:

• Audience
• Goal/objective
• Duration
• Data
• Style/brand
• Everything except the topic

---

Step 1: Minimal Intake (INTAKE.md)

Assistant's Response:

I'd love to help! To create the best presentation for you, I have a few quick questions:

1. Who is your audience? (e.g., coffee shop customers, barista trainees, general coffee enthusiasts)
2. What's your main goal? (e.g., educate about brewing methods, convince them to buy premium beans)
3. What action should they take afterward? (e.g., try a new brew method, visit your shop)
4. How long will you present? (e.g., 5 minutes, 15 minutes, 30 minutes)
5. Do you have any data or tables to include? (e.g., sales numbers, survey results, flavor profiles)

If you're not sure about any of these, no problem—I'll use sensible defaults and we can adjust later!

User Reply:

User: "It's for coffee enthusiasts, about 10 minutes, and I want them to improve their home brewing. No data."

Intake Summary:

---

Step 2: Structure Goals (WORKFLOW Stage 1)

One-Sentence Goal:

After this 10-minute presentation, coffee enthusiasts will try at least one new brewing technique within the next week.

CTA:

Pick one technique from today's session and try it with your next cup.

---

Step 3: Storyline (Pyramid Principle)

Main Conclusion:

Mastering three variables—grind size, water temperature, and brew time—unlocks consistently great coffee at home.

3 First-Level Reasons (Chapters): 1. Grind size controls extraction rate

• Evidence: Grind scale diagram, extraction comparison

2. Water temperature affects flavor balance

• Evidence: Temperature vs. compound extraction chart, cold brew example

3. Brew time determines strength and flavor

• Evidence: Method timing chart, troubleshooting guide

Supporting Reason: 4. Simple equipment upgrades improve consistency

• Evidence: Burr vs. blade grinder comparison, tool recommendations

---

Step 4: Slide Outline (12 Slides)

1. COVER: Mastering Three Variables Unlocks Consistently Great Coffee at Home
2. TABLE OF CONTENTS: Grind Size • Water Temperature • Brew Time • Equipment
3. PROBLEM: Inconsistent home coffee wastes premium beans and disappoints drinkers daily
4. Finer grind size extracts flavors faster and more completely
5. Grind size must match your brewing method to avoid over- or under-extraction
6. Water between 195-205°F produces balanced, full-bodied coffee
7. Cold brew demonstrates how low temperature requires extended time
8. Brew time determines coffee strength and flavor balance
9. Each brewing method has an optimal time window for best results
10. Simple equipment upgrades—burr grinder, thermometer, scale—ensure consistency
11. CONCLUSION: Pick one technique from today and try it with your next cup
12. BACKUP: Troubleshooting guide (problem → cause → fix)

---

Step 5: Evidence & Charts (With Placeholders)

Slide 3 (Problem):

• Chart Type: Bar chart
• Placeholder:

  Bar chart showing top 3 home brewing complaints:
  - "Can't replicate good results": 68%
  - "Inconsistent flavor": 52%
  - "Wastes expensive beans": 41%
  X-axis: Complaint type
  Y-axis: % of respondents
  Data required: complaint_type (string), percentage (numeric)
  Source: [National Coffee Association, 2024 Home Brewing Survey] (placeholder citation)

Slide 4 (Grind Size):

• Chart Type: Horizontal scale diagram
• Placeholder:

  Horizontal scale showing 5 grind sizes from fine to coarse:
  1. Espresso: fine powder (0.3-0.5mm)
  2. Pour-over: sand texture (0.7-1.0mm)
  3. Drip: table salt (1.0-1.5mm)
  4. French press: coarse salt (1.5-2.0mm)
  5. Cold brew: peppercorns (2.0-3.0mm)
  Each labeled with particle size range and visual icon.
  No data required (illustrative diagram).

Slide 6 (Temperature):

• Chart Type: Stacked area chart
• Placeholder:

  Stacked area chart: Temperature (°F) vs. Extraction %
  X-axis: Temperature 160-212°F
  Y-axis: Compound extraction %
  Three layers:
  - Acids (peak at 185°F)
  - Sugars (peak at 200°F)
  - Bitter compounds (peak at 210°F)
  Optimal zone highlighted: 195-205°F
  Data required: temperature_f (numeric), acid_pct (numeric), sugar_pct (numeric), bitter_pct (numeric)
  Source: [Coffee Chemistry Research, placeholder]

---

Step 6: Speaker Notes Sample (Slide 4)

SLIDE 4 SPEAKER NOTES (60 seconds):

[OPENING—10 sec]
"Now that we've seen the problem with inconsistent coffee, let's dive into the first variable: grind size. [CLICK]

[CORE ASSERTION—15 sec]
The key insight here is that finer grind size extracts flavors faster and more completely. Think of it like dissolving sugar: powdered sugar dissolves instantly, while sugar cubes take forever. Same principle.

[EVIDENCE EXPLANATION—25 sec]
This diagram shows five common grind sizes. On the far left, espresso grind looks like fine powder—tons of surface area, so water can extract all the flavors in just 25-30 seconds. On the far right, cold brew grind looks like peppercorns—much less surface area, so you need 12-24 hours to extract the same flavors. Pour-over is right in the middle: looks like sand, brews in 3-4 minutes. Each method needs its grind size. [PAUSE]

[TRANSITION—10 sec]
But here's the catch: you can't just use any grind size with any method. Let's see why matching grind to method is absolutely critical. [CLICK]"

---

Step 7: Self-Check & Scoring (RUBRIC.md)

Initial Scorecard:

1. Goal Clarity: 9/10 ✓ (audience, goal, CTA clear)
2. Story Structure: 9/10 ✓ (pyramid structure applied)
3. Slide Assertions: 9/10 ✓ (all headings are assertion sentences)
4. Evidence Quality: 7/10 ⚠️ (placeholders detailed but no real data)
5. Chart Fit: 8/10 ✓ (chart types match message)
6. Visual & Accessibility: 9/10 ✓ (neutral theme, WCAG AA compliant)
7. Coherence & Transitions: 8/10 ✓ (smooth flow, transitions in notes)
8. Speakability: 9/10 ✓ (natural language, 45-60 sec per slide)
9. Deliverables Complete: 9/10 ✓ (all files present)
10. Robustness: 9/10 ✓ (placeholders detailed, assumptions documented)
────────────────────────
TOTAL: 86/100 ✓✓ (exceeds threshold, ready to deliver)

Note: Score is high despite lack of real data because placeholders are detailed and assumptions are clearly documented.

---

Step 8: Deliverables

Output Directory:

/output/
├── slides.md (12 slides, 180 lines, Markdown with YAML)
├── notes.md (Full speaker script ~1,200 words + assumptions section)
├── refs.md (Placeholder citations: "NCA 2024 Survey [to be verified]")
├── assets/
│   └── README.txt ("No charts generated; placeholders in slides.md describe required data")
├── README.md (Explains file structure and next steps)
└── presentation.pptx (Not generated; instructions in notes.md for Marp conversion)

Assumptions Section in notes.md:

## Assumptions & Limitations

The following defaults and assumptions were used due to missing information:

1. **Tone & Style**: Professional, clear, friendly (user did not specify)
2. **Brand**: Neutral theme (#2563EB blue, #DC2626 red) - no brand guidelines provided
3. **Data**: No data provided; all charts are placeholders with detailed descriptions and required field lists
4. **Citations**: Placeholder sources used (e.g., "NCA 2024 Survey") - user should verify or replace with actual sources
5. **Format**: Markdown slides (slides.md) delivered; PPTX export requires Marp or pypandoc (see conversion guide below)

**Impact**: Presentation is structurally sound and ready to present, but user should:
- Replace placeholder charts with real data (if available)
- Verify/update citations in refs.md
- Customize colors/fonts per brand guidelines (if applicable)

---

Delivery Message

✅ Presentation ready!

TOPIC: Coffee brewing techniques for enthusiasts
DURATION: 10 minutes (12 slides)
SCORE: 86/100 (threshold: 75) ✓✓

DELIVERABLES:
- /output/slides.md (Markdown deck, 12 slides)
- /output/notes.md (Speaker script + assumptions)
- /output/refs.md (Placeholder citations)
- /output/README.md (File structure guide)

NEXT STEPS:
1. Review speaker notes and adjust for your personal style
2. Replace placeholder charts with real data (optional):
   - Slide 3: Home brewing complaints survey data
   - Slide 6: Temperature vs. extraction data
   - Slide 8: Brew time comparison data
3. Convert to PowerPoint:
   - Option A: Use Marp (https://marp.app/) to convert slides.md → PPTX
   - Option B: Use pypandoc: `pypandoc -o presentation.pptx slides.md`
4. Customize colors/fonts (see STYLE-GUIDE.md)

The presentation is structurally sound and ready to use as-is, or you can enhance with real data later!

---

Example B: Business Monthly Review (With Data)

User Input

User: "Make a PPT for my coffee shop's monthly review. Here's the sales data."
[Attaches CSV file: monthly_sales.csv]

CSV Content:

month,revenue_usd,cost_usd,customers,avg_order
Jan,12500,8200,420,29.76
Feb,13200,8500,450,29.33
Mar,15800,9200,530,29.81
Apr,14200,8900,475,29.89
May,16500,9500,560,29.46
Jun,18200,10200,615,29.59
Jul,19800,11000,670,29.55
Aug,18500,10500,625,29.60
Sep,20100,11200,680,29.56
Oct,21500,11800,725,29.66

---

Step 1: Minimal Intake (Partial)

Assistant's Response:

I see you have sales data for Jan-Oct. To create the best monthly review presentation, a few quick questions:

1. Who is your audience? (e.g., business partners, investors, staff meeting)
2. What's the main goal? (e.g., celebrate growth, identify issues, plan Q4)
3. What action should they take? (e.g., approve budget, adjust strategy)
4. How long? (e.g., 10 min, 20 min)

User Reply:

User: "It's for my business partner, 15 minutes, we need to decide on Q4 budget allocation."

Intake Summary:

---

Step 2: Data Analysis

Quick Analysis of CSV:

• Revenue: $12.5K (Jan) → $21.5K (Oct) = +72% growth
• Customers: 420 (Jan) → 725 (Oct) = +73% growth
• Avg Order: ~$29.50 (stable, ±0.5%)
• Margin: ~35-45% (cost/revenue ratio improving)

Key Insights: 1. Strong revenue and customer growth (Q3 acceleration) 2. Average order value stable (good retention) 3. Margin improving (cost growth slower than revenue)

---

Step 3: Storyline

Main Conclusion:

Jan-Oct performance exceeded plan by 15%, driven by customer growth and stable spending—Q4 budget should focus on capacity expansion.

3 Reasons: 1. Revenue grew 72% YTD with Q3 acceleration

• Evidence: Revenue trend line, Q3 growth rate

2. Customer count drove growth; avg order remained stable

• Evidence: Customers vs. revenue bar chart, avg order trendline

3. Improving margins create room for Q4 investment

• Evidence: Margin waterfall chart, cost vs. revenue comparison

---

Step 4: Slide Outline (14 Slides)

1. COVER: Jan-Oct Performance Exceeded Plan by 15%—Time to Invest in Q4 Capacity
2. TABLE OF CONTENTS: Revenue Growth • Customer Trends • Margins • Q4 Plan
3. EXECUTIVE SUMMARY: Three key wins and one opportunity
4. Revenue grew 72% from Jan ($12.5K) to Oct ($21.5K), with sharp Q3 acceleration
5. Q3 monthly growth averaged 8%, double the Q1-Q2 pace of 4%
6. Customer count increased 73%, closely tracking revenue growth
7. Average order value remained stable at ~$29.50, showing strong retention
8. Improving cost efficiency drove margins from 34% to 45%
9. Margin expansion of 11 points creates $3K/month reinvestment capacity
10. OPPORTUNITY: Q4 budget should prioritize capacity (staff, inventory, equipment)
11. RECOMMENDATION: Allocate $10K Q4 budget: 40% staff, 30% inventory, 30% equipment
12. CONCLUSION & CTA: Approve Q4 budget to sustain momentum into 2025
13. BACKUP: Detailed cost breakdown by category
14. BACKUP: Q4 budget line-item details

---

Step 5: Charts Generated (chartkit.py)

Slide 4 (Revenue Trend):

python scripts/chartkit.py \
  --data monthly_sales.csv \
  --type line \
  --x month \
  --y revenue_usd \
  --out output/assets \
  --filename revenue_trend.png \
  --title "Monthly Revenue (Jan-Oct 2024)"

Output: /output/assets/revenue_trend.png (line chart with upward trend, Q3 spike annotated)

Slide 6 (Customers + Revenue):

python scripts/chartkit.py \
  --data monthly_sales.csv \
  --type bar \
  --x month \
  --y customers revenue_usd \
  --out output/assets \
  --filename customers_revenue.png \
  --title "Customer Count & Revenue Growth"

Output: /output/assets/customers_revenue.png (grouped bar chart)

Slide 8 (Margin Waterfall):

• Manual annotation (chartkit.py doesn't do waterfall natively):
• Start: 34% margin (Jan)
• +11 points improvement (Jan → Oct)
• End: 45% margin (Oct)
• Placeholder description + "Consider using Excel or specialized tool for waterfall; data available in CSV"

---

Step 6: Speaker Notes Sample (Slide 4)

SLIDE 4 SPEAKER NOTES (55 seconds):

[OPENING—10 sec]
"Let's start with the headline: revenue. [CLICK]

[CORE ASSERTION—15 sec]
As you can see, revenue grew 72% from January—when we brought in $12,500—to October, when we hit $21,500. That's nearly double in 10 months. But what's really interesting is when this growth happened.

[EVIDENCE EXPLANATION—20 sec]
Notice the slope change in July. From January to June, we were growing steadily at about 4% per month—solid, but predictable. Then in July, August, September, we jumped to 8% monthly growth. That Q3 spike is what pushed us past our annual plan by 15%. [PAUSE]

[TRANSITION—10 sec]
Now, the question is: what drove this? Was it more customers, or were people spending more per visit? Let's break that down on the next slide. [CLICK]"

---

Step 7: Self-Check & Scoring

Initial Scorecard:

1. Goal Clarity: 10/10 ✓
2. Story Structure: 9/10 ✓
3. Slide Assertions: 9/10 ✓
4. Evidence Quality: 9/10 ✓ (real data, sources cited)
5. Chart Fit: 9/10 ✓ (line for trend, bar for comparison)
6. Visual & Accessibility: 9/10 ✓
7. Coherence & Transitions: 8/10 ✓
8. Speakability: 9/10 ✓
9. Deliverables Complete: 10/10 ✓
10. Robustness: 9/10 ✓
────────────────────────
TOTAL: 91/100 ✓✓✓ (excellent, ready to deliver)

---

Step 8: Deliverables

Output Directory:

/output/
├── slides.md (14 slides, 220 lines)
├── notes.md (Full speaker script ~1,500 words)
├── refs.md (Source: "Internal sales database, Jan-Oct 2024")
├── assets/
│   ├── revenue_trend.png
│   ├── customers_revenue.png
│   ├── avg_order_trend.png
│   ├── margin_comparison.png
│   └── (4 PNG charts total)
├── README.md
└── presentation.pptx (If python-pptx available; else conversion instructions)

---

Delivery Message

✅ Monthly review presentation ready!

TOPIC: Coffee shop Jan-Oct performance + Q4 budget
AUDIENCE: Business partner
DURATION: 15 minutes (14 slides)
SCORE: 91/100 (threshold: 75) ✓✓✓

DELIVERABLES:
- /output/slides.md (Markdown deck, 14 slides)
- /output/notes.md (Speaker script with data assumptions)
- /output/refs.md (Data source: Internal sales database)
- /output/assets/ (4 PNG charts generated from your CSV)
- /output/README.md

KEY INSIGHTS:
- Revenue +72% (Jan $12.5K → Oct $21.5K)
- Q3 acceleration: 8% monthly growth vs. 4% in Q1-Q2
- Customer count +73%; avg order stable ~$29.50
- Margins improved 34% → 45% (11-point gain)

RECOMMENDATION: Approve $10K Q4 budget (40% staff, 30% inventory, 30% equipment)

NEXT STEPS:
1. Review slides and notes
2. Adjust Q4 budget breakdown if needed (currently in slide 11)
3. Rehearse with notes (15 min total timing)
4. Export to PPTX if needed (instructions in README)

---

Key Takeaways from Examples

Example A (No Data):

• Works with minimal input: Just "coffee" → 12-slide deck
• Defaults applied smartly: Professional tone, neutral theme, 10-min duration
• Placeholders are detailed: Not just "add chart here" but specific field lists
• High score despite no data: 86/100 because structure, assertions, and accessibility are solid
• User can enhance later: Replace placeholders with real data anytime

Example B (With Data):

• Data drives insights: CSV analysis → 3 key insights → storyline
• Charts auto-generated: chartkit.py creates 4 PNGs in minutes
• Higher evidence score: 9/10 vs. 7/10 because real data > placeholders
• Business-ready: 91/100 score, ready to present without further edits
• Actionable CTA: "Approve Q4 budget" with specific allocation

---

Comparison Table

---

When to Use Which Approach

Use "No Data" Approach (Example A) When:

• User has a topic but no supporting data yet
• Presentation is educational/conceptual (not data-driven)
• User wants structure first, will add data later
• Timeline is tight (need deck in < 1 hour)

Use "With Data" Approach (Example B) When:

• User provides CSV, Excel, or JSON files
• Presentation is business/analytical (reviews, reports, pitches)
• Data-driven insights are core to the message
• User wants polished, presentation-ready output immediately

---

Next Steps: Use these examples as templates for your own presentations. Adjust storyline, charts, and speaker notes to fit your specific topic and audience.

Minimal Intake Questionnaire (10 Items)

Purpose: Gather essential context to produce a high-quality presentation. If the user doesn't provide information after 2 prompts, use the safe default for each item and clearly document the assumption in speaker notes.

---

1. Who is the audience?

Question: Who will be viewing/listening to this presentation?

Examples:

• Executive leadership team
• Technical engineers
• General public / consumers
• Sales prospects
• Students / trainees
• Board members
• Investors

Default if missing: General public (educated adults with no specialized background)

Impact: Determines technical depth, jargon usage, and evidence types.

---

2. What is the core objective?

Question: What do you want the audience to understand, believe, or feel?

Examples:

• Understand a new product feature
• Accept a proposal or recommendation
• Learn how to use a tool
• Appreciate the severity of a problem
• Gain confidence in a solution

Default if missing: "Understand and accept" the main proposition

Impact: Shapes the storyline and emphasis throughout the deck.

---

3. What is the desired action or decision?

Question: What specific action should the audience take after this presentation?

Examples:

• Approve budget allocation
• Agree to pilot/trial
• Provide feedback by [date]
• Adopt a new process
• Make a purchase decision
• Schedule a follow-up meeting

Default if missing: Agree to move to the next step after the meeting

Impact: Defines the call-to-action (CTA) on the closing slide.

---

4. What is the presentation duration and slide count limit?

Question: How long will you present, and are there any slide count constraints?

Examples:

• 5-minute pitch (5-7 slides)
• 15-minute review (12-15 slides)
• 30-minute workshop (20-25 slides)
• 60-minute lecture (30-40 slides)

Default if missing: 15-20 minutes, 12-15 slides

Impact: Controls depth per slide and total slide count.

---

5. What tone and style should the presentation have?

Question: How should the presentation feel and sound?

Examples:

• Professional and formal
• Friendly and conversational
• Inspirational and aspirational
• Technical and precise
• Urgent and persuasive

Default if missing: Professional, clear, and friendly

Impact: Affects language choice, speaker notes tone, and visual style.

---

6. What is the topic scope and boundaries?

Question: What should be included and what should be excluded?

Examples:

• Focus only on Q1 results, not Q2 projections
• Cover product features but not pricing
• Technical implementation only, no business case
• High-level overview, no detailed specs

Default if missing: The given topic name plus one layer of directly related context

Impact: Prevents scope creep and ensures focused messaging.

---

7. Are there must-include points or forbidden topics?

Question: Are there specific messages you must convey or topics you must avoid?

Examples:

• Must mention: regulatory compliance requirement
• Must avoid: competitor names, unannounced features, sensitive financial data
• Required disclaimer: "Subject to board approval"

Default if missing: None (no mandatory inclusions or exclusions)

Impact: Ensures compliance and strategic messaging alignment.

---

8. Do you have data or tables available?

Question: Can you provide data files (CSV, Excel, JSON) or tables for visualization?

Examples:

• Sales data by month
• User survey results
• Cost breakdown by category
• Performance metrics over time

Default if missing: No data available; generate placeholder charts with a list of required data fields

Impact: Determines whether to generate actual charts (via chartkit.py) or placeholders.

---

9. Are there brand or visual constraints?

Question: Are there specific colors, fonts, logos, or templates you must use?

Examples:

• Company brand colors: #FF5733, #33A1FF
• Required logo placement: top-right corner
• Mandatory template: [template file]
• Font restrictions: Arial only

Default if missing: Built-in neutral theme (dark ink #1F2937, accent #2563EB, emphasis #DC2626)

Impact: Affects color palette and visual components in STYLE-GUIDE.

---

10. What deliverable format do you prefer?

Question: How do you want to receive the final presentation?

Options:

• Markdown slides (Marp/Reveal.js compatible)
• PowerPoint (.pptx)
• Google Slides export
• PDF for print
• All of the above

Default if missing: slides.md (Markdown) + optional PNG charts; export to PPTX if python-pptx is available

Impact: Determines final export step in Stage 8.

---

Usage Instructions

1. First pass: Ask all 10 questions in a user-friendly format (e.g., "I have a few quick questions to help me create the best presentation for you...")

2. Second prompt: If critical items (1, 2, 3, 4, 8) are still missing, ask again with examples.

3. Apply defaults: If still no response, use the safe default for each missing item.

4. Document assumptions: In /output/notes.md, include a "Assumptions & Limitations" section listing all defaults used and their potential impact.

---

Example Interaction

User: "Make me a presentation about coffee."

Assistant: "I'd love to help! To create the best presentation for you, I have a few quick questions:

1. Who is your audience? (e.g., coffee shop customers, barista trainees, general coffee enthusiasts) 2. What's your main goal? (e.g., educate about brewing methods, convince them to buy premium beans, explain coffee origins) 3. What action should they take afterward? (e.g., try a new brew method, visit your shop, change their coffee habits) 4. How long will you present? (e.g., 5 minutes, 15 minutes, 30 minutes) 5. Do you have any data or tables to include? (e.g., sales numbers, survey results, flavor profiles)

If you're not sure about any of these, no problem—I'll use sensible defaults and we can adjust later!"

User: "It's for coffee enthusiasts, about 10 minutes, and I want them to improve their home brewing. No data."

Assistant: "Perfect! I'll create a 10-minute presentation (about 10-12 slides) for coffee enthusiasts focused on improving home brewing techniques. I'll use a friendly, educational tone and aim for them to try new methods at home. Since you don't have data, I'll include helpful diagrams and placeholder charts where data would be useful (like extraction curves or flavor profiles). Let me get started!"

[Proceeds to Stage 0 of WORKFLOW.md with documented assumptions]

---

Safe Defaults Summary Table

---

Next step: Once intake is complete, proceed to WORKFLOW.md Stage 0.

ORCHESTRATION_DATA_CHARTS.md

Purpose: Detailed specifications for Stage 8b (Data Synthesis) and Stage 8c (Chart Generation) in orchestration mode.

>

Navigation: ← Back to Overview | Next: PPTX Creation →

---

Stage 8b: Data Synthesis

When to Synthesize Data

Generate synthetic data when: 1. refs.md contains data specifications (e.g., "Solar LCOE: $0.38/kWh → $0.05/kWh") 2. User did NOT upload CSV/Excel files 3. Charts require data to render (not just conceptual diagrams)

Data Synthesis Guidelines

Source of Truth: Use refs.md data specifications

Example refs.md content:

## Chart 1: Renewable Energy Cost Trends (2010-2024)

Data source: IRENA Renewable Power Generation Costs 2024
- Solar PV LCOE: $0.38/kWh (2010) → $0.05/kWh (2024), -87% decline
- Onshore Wind LCOE: $0.09/kWh (2010) → $0.04/kWh (2024), -56% decline
- Coal baseline (comparison): $0.11/kWh (stable)

Required CSV: data/cost_trend.csv
Columns: year, solar_pv_cost, onshore_wind_cost, coal_cost

Python Code Pattern (generate CSV):

import pandas as pd
import numpy as np

# Synthesize cost_trend.csv
years = list(range(2010, 2025))
solar_costs = np.linspace(0.38, 0.05, len(years))  # -87% decline
wind_costs = np.linspace(0.09, 0.04, len(years))   # -56% decline
coal_costs = [0.11] * len(years)                   # stable baseline

df = pd.DataFrame({
    'year': years,
    'solar_pv_cost': solar_costs,
    'onshore_wind_cost': wind_costs,
    'coal_cost': coal_costs
})
df.to_csv('output/data/cost_trend.csv', index=False)

Key Principles:

• Match refs.md specifications exactly (start/end values, trends)
• Add realistic noise (±3-5%) to avoid straight lines
• Use authoritative source calibration (IRENA/IEA/IPCC/WHO/World Bank)
• Document assumptions in data file headers or README

File Organization:

/output/data/
  ├── cost_trend.csv
  ├── capacity_growth.csv
  ├── employment.csv
  ├── solar_roi.csv
  └── README.md (documents synthesis methodology)

---

Stage 8c: Chart Generation

Chart Generation Script Pattern

Create a comprehensive generate_charts.py script that reads CSV data and generates all PNG charts.

Template Structure:

#!/usr/bin/env python3
"""Generate all charts for presentation"""
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib
matplotlib.use('Agg')  # Non-interactive backend

# Chinese font configuration
plt.rcParams['font.sans-serif'] = ['SimHei', 'Arial Unicode MS', 'DejaVu Sans']
plt.rcParams['axes.unicode_minus'] = False

def create_chart_1():
    """Cost Trend Line Chart"""
    df = pd.read_csv('data/cost_trend.csv')

    fig, ax = plt.subplots(figsize=(10, 6))
    ax.plot(df['year'], df['solar_pv_cost'], marker='o', label='太阳能光伏', linewidth=2)
    ax.plot(df['year'], df['onshore_wind_cost'], marker='s', label='陆上风能', linewidth=2)
    ax.plot(df['year'], df['coal_cost'], linestyle='--', label='煤电(对比)', linewidth=2, alpha=0.7)

    ax.set_xlabel('年份', fontsize=12)
    ax.set_ylabel('平准化度电成本 ($/kWh)', fontsize=12)
    ax.set_title('可再生能源成本趋势 (2010-2024)', fontsize=14, fontweight='bold')
    ax.legend(fontsize=11)
    ax.grid(True, alpha=0.3)

    plt.tight_layout()
    plt.savefig('assets/cost_trend.png', dpi=180, bbox_inches='tight')
    plt.close()
    print("✓ Generated: assets/cost_trend.png")

# Call all chart generation functions
if __name__ == "__main__":
    create_chart_1()
    create_chart_2()
    # ... (all charts)
    print("\n✅ All charts generated successfully")

Execution Pattern:

# Background execution to avoid blocking
cd /output
python generate_charts.py

# OR using uv if dependencies unavailable
uv run --with pandas --with matplotlib generate_charts.py

Quality Standards:

• DPI: 180 (presentation-quality)
• Size: 10×6 inches (fits 16:9 slide with margins)
• File format: PNG with transparency
• Color palette: Use colorblind-friendly colors from STYLE-GUIDE.md
• Labels: Chinese/English matching slide language
• Source citation: Add footnote to chart (e.g., "数据来源: IRENA 2024")

---

Navigation: ← Back to Overview | Next: PPTX Creation →

ORCHESTRATION_OVERVIEW.md

Purpose: Enable ppt-creator to act as an end-to-end workflow coordinator, automatically managing data synthesis, chart generation, PPTX creation, and chart insertion to deliver complete, presentation-ready PowerPoint files with real visualizations.

>

Note: This document provides the orchestration overview. For detailed implementation, see the specialized guides below.

---

Table of Contents

1. When to Use Orchestration Mode 2. Orchestration Workflow 3. Stage 8b-8c: Data & Charts → See ORCHESTRATION_DATA_CHARTS.md 4. Stage 8d-8e: PPTX Creation & Chart Insertion → See ORCHESTRATION_PPTX.md

---

When to Use Orchestration Mode

Activation Triggers

Orchestration mode activates when user request includes ANY of these patterns:

Explicit Requests:

• "Generate complete PPTX with real charts"
• "Create final deliverable ready for presentation"
• "Export to PowerPoint with all visualizations"
• "Deliver presentation-ready file with data"

Implicit Indicators:

• User uploads reference documents + requests "presentation"
• Request mentions "final deliverable" or "ready to present"
• User asks for "all assets generated"
• Context suggests this is for actual delivery (meeting/pitch/review)

Decision Tree

User Request
  │
  ├─ Contains "Markdown only" → Manual Mode
  ├─ Contains "slides.md" only → Manual Mode
  ├─ Contains "complete PPTX" → Orchestration Mode ✓
  ├─ Contains "final deliverable" → Orchestration Mode ✓
  ├─ Contains "presentation-ready" → Orchestration Mode ✓
  └─ Ambiguous → Ask user: "Should I create complete PPTX with charts (orchestration mode) or Markdown only (manual mode)?"

User Communication

When activating orchestration mode, inform user explicitly:

🎯 Activating end-to-end orchestration mode to deliver complete PPTX with real charts.

Pipeline stages:
  ✓ Stage 1-7: Content creation (slides.md, notes.md, refs.md)
  ⏳ Stage 8b: Data synthesis (generating CSV files from refs.md specs)
  ⏳ Stage 8c: Chart generation (matplotlib rendering)
  ⏳ Stage 8d: Dual-path PPTX creation (Marp + document-skills:pptx in parallel)
  ⏳ Stage 8e: Dual-path chart insertion (2 final PPTX versions)

📦 Will deliver TWO versions:
  - presentation_marp.pptx (Marp CLI export, native Marp styling)
  - presentation_pptx.pptx (document-skills:pptx, reveal.js styling)

Estimated time: 4-6 minutes

---

Orchestration Workflow

Complete Pipeline (Stages 8b-8e)

After standard content creation (Stages 0-7 → slides.md/notes.md/refs.md), orchestration extends Stage 8:

Stage 8: Package Deliverables
  │
  ├─ 8a: Package Markdown deliverables ✓ (baseline)
  │     └─ Output: /output/slides.md, /output/notes.md, /output/refs.md
  │
  ├─ 8b: Synthesize Data (if needed)
  │     ├─ Check: Does refs.md specify data requirements?
  │     ├─ Check: Did user provide data files?
  │     └─ If no user data: Generate synthetic CSV files
  │           → Output: /output/data/*.csv
  │
  ├─ 8c: Generate Charts
  │     ├─ Read: /output/refs.md (chart specifications)
  │     ├─ Read: /output/data/*.csv (generated or user-provided)
  │     ├─ Execute: Python/matplotlib chart generation
  │     └─ Output: /output/assets/*.png (180 DPI, optimized)
  │
  ├─ 8d: Create PPTX
  │     ├─ Tool: Task (subagent_type: document-skills:pptx)
  │     ├─ Input: /output/slides.md content
  │     ├─ Action: Convert Markdown to PPTX structure
  │     └─ Output: /output/presentation.pptx (with placeholder chart text)
  │
  └─ 8e: Insert Charts
        ├─ Tool: Task (subagent_type: document-skills:pptx editing)
        ├─ Input: /output/assets/*.png + slide mapping
        ├─ Action: Replace placeholder text with chart images
        └─ Output: /output/presentation_with_charts.pptx ✓ FINAL

Coordination Approach

Use sequential execution with quality gates:

• Stages 8b-c can run in parallel (data synthesis + chart generation)
• Stage 8d waits for 8c completion (PPTX needs chart list)
• Stage 8e waits for 8d completion (insertion needs PPTX file)

---

Stage 8b: Data Synthesis

When to Synthesize Data

Generate synthetic data when: 1. refs.md contains data specifications (e.g., "Solar LCOE: $0.38/kWh → $0.05/kWh") 2. User did NOT upload CSV/Excel files 3. Charts require data to render (not just conceptual diagrams)

Data Synthesis Guidelines

Source of Truth: Use refs.md data specifications

Example refs.md content:

## Chart 1: Renewable Energy Cost Trends (2010-2024)

Data source: IRENA Renewable Power Generation Costs 2024
- Solar PV LCOE: $0.38/kWh (2010) → $0.05/kWh (2024), -87% decline
- Onshore Wind LCOE: $0.09/kWh (2010) → $0.04/kWh (2024), -56% decline
- Coal baseline (comparison): $0.11/kWh (stable)

Required CSV: data/cost_trend.csv
Columns: year, solar_pv_cost, onshore_wind_cost, coal_cost

Python Code Pattern (generate CSV):

import pandas as pd
import numpy as np

# Synthesize cost_trend.csv
years = list(range(2010, 2025))
solar_costs = np.linspace(0.38, 0.05, len(years))  # -87% decline
wind_costs = np.linspace(0.09, 0.04, len(years))   # -56% decline
coal_costs = [0.11] * len(years)                   # stable baseline

df = pd.DataFrame({
    'year': years,
    'solar_pv_cost': solar_costs,
    'onshore_wind_cost': wind_costs,
    'coal_cost': coal_costs
})
df.to_csv('output/data/cost_trend.csv', index=False)

Key Principles:

• Match refs.md specifications exactly (start/end values, trends)
• Add realistic noise (±3-5%) to avoid straight lines
• Use authoritative source calibration (IRENA/IEA/IPCC/WHO/World Bank)
• Document assumptions in data file headers or README

File Organization:

/output/data/
  ├── cost_trend.csv
  ├── capacity_growth.csv
  ├── employment.csv
  ├── solar_roi.csv
  └── README.md (documents synthesis methodology)

---

Stage 8c: Chart Generation

Chart Generation Script Pattern

Create a comprehensive generate_charts.py script that reads CSV data and generates all PNG charts.

Template Structure:

#!/usr/bin/env python3
"""Generate all charts for presentation"""
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib
matplotlib.use('Agg')  # Non-interactive backend

# Chinese font configuration
plt.rcParams['font.sans-serif'] = ['SimHei', 'Arial Unicode MS', 'DejaVu Sans']
plt.rcParams['axes.unicode_minus'] = False

def create_chart_1():
    """Cost Trend Line Chart"""
    df = pd.read_csv('data/cost_trend.csv')

    fig, ax = plt.subplots(figsize=(10, 6))
    ax.plot(df['year'], df['solar_pv_cost'], marker='o', label='太阳能光伏', linewidth=2)
    ax.plot(df['year'], df['onshore_wind_cost'], marker='s', label='陆上风能', linewidth=2)
    ax.plot(df['year'], df['coal_cost'], linestyle='--', label='煤电(对比)', linewidth=2, alpha=0.7)

    ax.set_xlabel('年份', fontsize=12)
    ax.set_ylabel('平准化度电成本 ($/kWh)', fontsize=12)
    ax.set_title('可再生能源成本趋势 (2010-2024)', fontsize=14, fontweight='bold')
    ax.legend(fontsize=11)
    ax.grid(True, alpha=0.3)

    plt.tight_layout()
    plt.savefig('assets/cost_trend.png', dpi=180, bbox_inches='tight')
    plt.close()
    print("✓ Generated: assets/cost_trend.png")

# Call all chart generation functions
if __name__ == "__main__":
    create_chart_1()
    create_chart_2()
    # ... (all charts)
    print("\n✅ All charts generated successfully")

Execution Pattern:

# Background execution to avoid blocking
cd /output
python generate_charts.py

# OR using uv if dependencies unavailable
uv run --with pandas --with matplotlib generate_charts.py

Quality Standards:

• DPI: 180 (presentation-quality)
• Size: 10×6 inches (fits 16:9 slide with margins)
• File format: PNG with transparency
• Color palette: Use colorblind-friendly colors from STYLE-GUIDE.md
• Labels: Chinese/English matching slide language
• Source citation: Add footnote to chart (e.g., "数据来源: IRENA 2024")

---

ORCHESTRATION_PPTX.md

Purpose: Comprehensive specifications for Stage 8d (Dual-Path PPTX Creation) and Stage 8e (Chart Insertion) in orchestration mode.

>

Navigation: ← Back to Overview | ← Data & Charts

>

Note: This is a comprehensive reference (650 lines) covering both Marp CLI and document-skills:pptx paths with complete implementation details, quality gates, error handling, and examples.

---

Stage 8d: Dual-Path PPTX Creation (Parallel Execution)

Strategy: Launch TWO parallel sub-agents to generate PPTX files using different technologies. This preserves existing Marp capabilities while adding document-skills:pptx support.

Why Dual-Path?

Problem: ppt-creator internally uses Marp-formatted Markdown (with Marp-specific YAML frontmatter and directives), but document-skills:pptx uses reveal.js/HTML and cannot properly parse Marp syntax.

Solution: Support BOTH paths simultaneously:

• Path A (Marp CLI): Native Marp export → preserves Marp themes, directives, and styling
• Path B (document-skills:pptx): Strip Marp directives → convert to PowerPoint → reveal.js-style output

Both paths run in parallel (single message with two Task calls), delivering whichever succeeds (or both for user choice).

---

Path A: Marp CLI Export

Purpose: Export slides.md to PPTX using official Marp CLI, preserving native Marp styling

Task Invocation:

Tool: Task
subagent_type: general-purpose
description: Marp CLI PPTX generation
prompt: |
  Generate PPTX from Marp-formatted slides using Marp CLI.

  CRITICAL: This path preserves Marp-specific features (themes, directives, styling).

  Steps:
  1. Check Marp CLI installation:
     which marp || npm list -g @marp-team/marp-cli

  2. If Marp CLI not found, install it:
     npm install -g @marp-team/marp-cli

     If npm fails:
     - Try: brew install marp-cli (macOS)
     - Document error and skip to fallback

  3. Export slides.md to PPTX:
     cd output
     marp slides.md -o presentation_marp.pptx --allow-local-files --html

     Options explained:
     - --allow-local-files: Enable chart image embedding
     - --html: Preserve HTML directives (speaker notes)

  4. Quality checks:
     - File exists: /output/presentation_marp.pptx
     - File size: 200-500KB (12-15 slides with embedded fonts)
     - No "ERROR" in marp output

  5. If successful, report:
     "✓ Path A complete: presentation_marp.pptx (Marp-styled, [FILE_SIZE]KB)"

  Fallback: If any step fails, document error in /output/README.md and exit gracefully

Expected Output:

• File: /output/presentation_marp.pptx (~200-500KB)
• Styling: Marp theme from YAML frontmatter (e.g., theme: default, custom CSS)
• Charts: Text placeholders initially (will be replaced in Stage 8e-A)
• Notes: Speaker notes from <!-- NOTES: ... --> comments
• Font embedding: Marp auto-embeds fonts

Marp Installation Verification:

# Check if Marp CLI is available
which marp
# OR
npm list -g @marp-team/marp-cli

# Expected output:
/usr/local/bin/marp
# OR
@marp-team/marp-cli@3.x.x

Installation Methods (if not found):

# Method 1: npm (preferred)
npm install -g @marp-team/marp-cli

# Method 2: Homebrew (macOS)
brew install marp-cli

# Method 3: Docker (fallback)
docker run --rm -v ${PWD}:/workspace marpteam/marp-cli slides.md -o presentation_marp.pptx

Common Marp Errors & Fixes:

Fallback: If Marp CLI unavailable after installation attempts:

• Skip Path A
• Document in /output/README.md: "Marp CLI unavailable, delivered document-skills:pptx version only"
• Proceed with Path B only

---

Path B: document-skills:pptx Export

Purpose: Convert Markdown to PPTX using Anthropic's official PowerPoint skill (reveal.js-based)

Pre-Processing Required: Since slides.md contains Marp-specific syntax, we must strip it before passing to document-skills:pptx:

Marp Syntax to Remove:

---
marp: true
theme: default
paginate: true
---

<!-- _class: lead -->
<!-- _backgroundColor: #f4f4f4 -->

Task Invocation:

Tool: Task
subagent_type: general-purpose (with document-skills:pptx access)
description: document-skills:pptx PPTX generation
prompt: |
  Use document-skills:pptx skill to create PowerPoint from slides.md content.

  CRITICAL: Pre-process slides.md to remove Marp-specific syntax.

  Steps:
  1. Read /output/slides.md content

  2. Pre-process content (remove Marp syntax):
     - Remove YAML frontmatter block (--- ... ---)
     - Remove HTML comments with Marp directives: <!-- _class: ... -->, <!-- _backgroundColor: ... -->
     - Keep speaker notes: <!-- NOTES: ... --> (convert to PowerPoint notes)
     - Keep standard Markdown: #, ##, bullets, bold, italics

  3. Convert to document-skills:pptx compatible format:
     - # → Title slide
     - ## → Content slide heading (large, bold)
     - ### → Subheading (if used)
     - Bullet points → PowerPoint bullet lists
     - **[占位图表]**: description → Text box placeholder "[CHART: description]"

  4. Create PPTX using document-skills:pptx:
     - File: /output/presentation_pptx.pptx
     - Layout: 16:9 (default)
     - Theme: document-skills default (reveal.js-based)
     - Embed speaker notes from <!-- NOTES: ... -->

  5. Quality checks:
     - File exists: /output/presentation_pptx.pptx
     - Slide count matches slides.md (±1 acceptable)
     - No Markdown artifacts visible (no "---", no "<!-- -->")
     - Headings rendered correctly

  6. If successful, report:
     "✓ Path B complete: presentation_pptx.pptx (document-skills styled, [FILE_SIZE]KB)"

  Fallback: If document-skills:pptx unavailable, document in README.md and exit gracefully

Expected Output:

• File: /output/presentation_pptx.pptx (~200-300KB)
• Styling: document-skills:pptx default theme (reveal.js-based, clean/modern)
• Charts: Text placeholders initially (will be replaced in Stage 8e-B)
• Notes: Speaker notes embedded in PowerPoint notes section
• Font: System defaults (Calibri/Arial)

Fallback: If document-skills:pptx unavailable:

• Skip Path B
• Document in /output/README.md: "document-skills:pptx unavailable, delivered Marp version only"
• Proceed with Path A only

---

Parallel Execution Pattern

Implementation: Use a single message with TWO Task tool calls to execute both paths simultaneously.

Pseudo-code:

# In ppt-creator's response, invoke BOTH agents at once:

1. Call Task tool with Path A prompt (Marp CLI)
2. Call Task tool with Path B prompt (document-skills:pptx)

Both agents run in parallel (non-blocking).

Wait for both to complete, then:
- If both succeed → deliver both PPTX files
- If one succeeds → deliver that one + document other's failure
- If both fail → fallback to Markdown + conversion instructions

User Communication:

🎯 Launching dual-path PPTX generation in parallel...

Path A: Marp CLI → presentation_marp.pptx (native Marp styling)
Path B: document-skills:pptx → presentation_pptx.pptx (reveal.js styling)

Estimated time: 2-3 minutes (parallel execution)

---

Quality Checks for Stage 8d

After both paths complete, verify:

Path A (Marp) Success Criteria:

• ✓ File exists: /output/presentation_marp.pptx
• ✓ File size: 200-500KB (fonts embedded, reasonable size)
• ✓ Slide count: 12-15 slides (matches slides.md)
• ✓ No error logs from Marp CLI

Path B (document-skills:pptx) Success Criteria:

• ✓ File exists: /output/presentation_pptx.pptx
• ✓ File size: 200-300KB
• ✓ Slide count: matches slides.md (±1 slide acceptable)
• ✓ No Markdown artifacts visible

Delivery Matrix:

---

Stage 8e: Dual-Path Chart Insertion (Parallel Execution)

Strategy: Insert generated PNG charts into BOTH PPTX files (if both exist) using path-specific methods.

Chart-to-Slide Mapping

Common Mapping Strategy (applies to both paths): 1. Parse slides.md to identify chart placeholders:

• Pattern: **[占位图表]**: or **[Chart]**:

2. Extract chart filename from placeholder description 3. Map to slide number (skip title/TOC, typically start from slide 3)

Example Mapping:

chart_mapping = [
    {"slide": 3, "chart": "assets/cost_trend.png", "title_contains": "成本"},
    {"slide": 4, "chart": "assets/capacity_growth.png", "title_contains": "装机容量"},
    {"slide": 5, "chart": "assets/employment.png", "title_contains": "就业"},
    # ... (8 charts total)
]

Positioning Guidelines:

• Standard layout: Right column at (5.5", 2.0") from top-left corner
• Width: 4.0" (leaves 0.5" right margin on 10" slide width)
• Height: Auto (maintain aspect ratio from 10×6 inch source)
• Alternative: Full-width charts at (1.0", 2.5"), width 8.0"

---

Path A: Marp PPTX Chart Insertion

Method: Use python-pptx library to directly manipulate presentation_marp.pptx

Task Invocation:

Tool: Task
subagent_type: general-purpose
description: Insert charts into Marp PPTX
prompt: |
  Insert PNG charts into presentation_marp.pptx using python-pptx library.

  Steps:
  1. Check python-pptx availability:
     python3 -c "import pptx; print(pptx.__version__)"

     If not found: uv pip install python-pptx

  2. Create insertion script (insert_charts_marp.py):

from pptx import Presentation from pptx.util import Inches

prs = Presentation('output/presentation_marp.pptx')

chart_mapping = [ (2, 'output/assets/cost_trend.png'), # Slide 3 (0-indexed: 2) (3, 'output/assets/capacity_growth.png'), (4, 'output/assets/employment.png'),

... (all 8 charts)

]

for slide_idx, chart_path in chart_mapping: slide = prs.slides[slide_idx]

Position: right column, 5.5" from left, 2.0" from top, 4.0" wide

slide.shapes.add_picture( chart_path, Inches(5.5), Inches(2.0), width=Inches(4.0) ) print(f"✓ Inserted {chart_path} into slide {slide_idx + 1}")

prs.save('output/presentation_marp_with_charts.pptx') print("✅ Final Marp PPTX: presentation_marp_with_charts.pptx")

  3. Execute script:
     cd .
     python3 output/insert_charts_marp.py

  4. Quality checks:
     - File exists: /output/presentation_marp_with_charts.pptx
     - File size increase: +300-600KB (charts embedded)
     - All 8 charts inserted without errors

  5. Report:
     "✓ Path A charts inserted: presentation_marp_with_charts.pptx ([FINAL_SIZE]KB)"

  Fallback: If python-pptx fails, deliver presentation_marp.pptx + manual insertion instructions

Expected Output:

• File: /output/presentation_marp_with_charts.pptx (500-900KB)
• Charts: All 8 PNG images embedded at correct positions
• Styling: Marp theme preserved
• Quality: Charts readable, no overlapping text

---

Path B: document-skills:pptx Chart Insertion

Method: Use document-skills:pptx editing capabilities via Task tool

Task Invocation:

Tool: Task
subagent_type: general-purpose (with document-skills:pptx access)
description: Insert charts into document-skills PPTX
prompt: |
  Use document-skills:pptx to insert chart images into presentation_pptx.pptx.

  Chart mapping (insert in order):
  1. Slide 3: Insert /output/assets/cost_trend.png at position (5.5", 2.0"), width 4.0"
  2. Slide 4: Insert /output/assets/capacity_growth.png at position (5.5", 2.0"), width 4.0"
  3. Slide 5: Insert /output/assets/employment.png at position (5.5", 2.0"), width 4.0"
  4. Slide 6: Insert /output/assets/solar_roi.png at position (5.5", 2.0"), width 4.0"
  5. Slide 7: Insert /output/assets/health_impact.png at position (5.5", 2.0"), width 4.0"
  6. Slide 8: Insert /output/assets/emissions_reduction.png at position (5.5", 2.0"), width 4.0"
  7. Slide 9: Insert /output/assets/cost_parity.png at position (5.5", 2.0"), width 4.0"
  8. Slide 10: Insert /output/assets/future_projection.png at position (5.5", 2.0"), width 4.0"

  Actions for each chart:
  - Open: /output/presentation_pptx.pptx
  - Navigate to slide N
  - Delete placeholder text box (if exists with "[CHART:" text)
  - Insert chart image at specified position (5.5" left, 2.0" top, 4.0" width)
  - Maintain aspect ratio (auto-height)

  Save as: /output/presentation_pptx_with_charts.pptx

  Quality checks:
  - All 8 charts inserted successfully
  - No overlapping content (check visually)
  - File size increase: 300-600KB (charts embedded)

  Report:
  "✓ Path B charts inserted: presentation_pptx_with_charts.pptx ([FINAL_SIZE]KB)"

  Fallback: If document-skills:pptx unavailable, use python-pptx fallback (same as Path A method)

Expected Output:

• File: /output/presentation_pptx_with_charts.pptx (500-800KB)
• Charts: All 8 PNG images embedded
• Styling: document-skills theme preserved
• Quality: Charts readable, professional layout

---

Parallel Execution Pattern for Chart Insertion

Implementation: Launch both chart insertion tasks in parallel (if both PPTX files exist from Stage 8d).

Decision Logic:

If presentation_marp.pptx exists:
  → Launch Path A chart insertion task

If presentation_pptx.pptx exists:
  → Launch Path B chart insertion task

If both exist:
  → Launch BOTH tasks in parallel (single message with two Task calls)

If neither exist:
  → Skip Stage 8e, deliver Markdown + charts + assembly instructions

---

Quality Checks for Stage 8e

Path A (Marp) Final Checks:

• ✓ File exists: /output/presentation_marp_with_charts.pptx
• ✓ File size: 500-900KB (base PPTX + charts)
• ✓ All 8 charts visible when opening in PowerPoint/Keynote
• ✓ No overlapping text or broken layouts
• ✓ Charts maintain aspect ratio and readability

Path B (document-skills:pptx) Final Checks:

• ✓ File exists: /output/presentation_pptx_with_charts.pptx
• ✓ File size: 500-800KB
• ✓ All 8 charts visible and positioned correctly
• ✓ Theme styling preserved
• ✓ Speaker notes still present

Final Delivery Matrix:

---

User Communication After Stage 8e

Success (Both Paths):

✅ Dual-path orchestration complete!

📦 Deliverables:
  - presentation_marp_with_charts.pptx (557KB, Marp-styled)
  - presentation_pptx_with_charts.pptx (543KB, document-skills styled)

Both files contain:
  ✓ 14 slides with complete content
  ✓ 8 real data-driven charts (180 DPI)
  ✓ Speaker notes for each slide
  ✓ Professional styling and layout

Choose your preferred version or compare both!

Partial Success (One Path):

✅ Orchestration complete (partial success)

📦 Deliverables:
  - presentation_[PATH]_with_charts.pptx (557KB, complete)
  - presentation_[OTHER_PATH].pptx (210KB, charts missing)
  - assets/*.png (8 chart files for manual insertion)
  - README.md (manual insertion instructions for second path)

Reason for partial: [Brief explanation of why one path failed]

Failure (Both Paths):

⚠️ Orchestration failed at Stage 8e (chart insertion)

📦 Deliverables:
  - presentation_marp.pptx (210KB, text placeholders)
  - presentation_pptx.pptx (200KB, text placeholders)
  - assets/*.png (8 chart files)
  - README.md (manual insertion instructions)

Manual steps:
1. Open preferred PPTX in PowerPoint
2. Navigate to slides 3-10
3. Insert → Pictures → Select corresponding chart from assets/
4. Resize to 4" width, position at right column

Quality Gates

After Each Stage

8b: Data Synthesis

• ✓ All required CSV files exist in /output/data/
• ✓ CSV columns match refs.md specifications
• ✓ Data trends match source calibration (e.g., -87% for solar cost)
• ✓ No missing values or malformed rows

8c: Chart Generation

• ✓ All PNG files exist in /output/assets/
• ✓ Image dimensions: ~10×6 inches, 180 DPI
• ✓ File sizes: 40-150KB per chart (optimized)
• ✓ Visual inspection: labels readable, colors distinct, no clipping

8d: PPTX Creation

• ✓ File exists: /output/presentation.pptx
• ✓ Slide count matches slides.md (±1 slide acceptable)
• ✓ Headings converted correctly (no Markdown artifacts)
• ✓ Speaker notes embedded

8e: Chart Insertion

• ✓ File exists: /output/presentation_with_charts.pptx
• ✓ File size increase: 300-600KB (charts added)
• ✓ Visual check: Open PPTX, verify all charts visible and positioned correctly
• ✓ No overlapping text or images

Final Deliverable Checklist

Before marking orchestration complete:

• [ ] /output/presentation_with_charts.pptx exists
• [ ] File size: 500KB - 2MB (reasonable range)
• [ ] All placeholder charts replaced with real visualizations
• [ ] Speaker notes preserved
• [ ] Visual inspection: open file, scroll through all slides
• [ ] Backup files retained: slides.md, assets/*.png (for future edits)

---

Error Handling

Common Failures and Responses

1. Data Synthesis Fails (pandas unavailable)

Fallback: Skip Stage 8b, proceed with user-provided data only
Message: "⚠️ pandas unavailable - skipping synthetic data generation. Using provided data files only."

2. Chart Generation Fails (matplotlib issues)

Fallback: Deliver PPTX with text placeholders + standalone Python script
Message: "⚠️ Chart generation failed. Delivering:
  - presentation.pptx (with placeholders)
  - generate_charts.py (run manually: python generate_charts.py)
  - Installation: uv pip install pandas matplotlib"

3. document-skills:pptx Unavailable

Fallback: Deliver Markdown + manual conversion instructions
Message: "⚠️ document-skills:pptx unavailable. Delivering:
  - slides.md (complete content)
  - assets/*.png (charts ready)
  - Conversion: Use Marp/Reveal.js or pandoc to convert to PPTX
  Command: pandoc slides.md -o presentation.pptx"

4. Chart Insertion Fails (positioning issues)

Fallback: Deliver PPTX + manual insertion instructions
Message: "⚠️ Automatic chart insertion failed. Delivering:
  - presentation.pptx (content ready)
  - assets/*.png (charts ready)
  - Manual: Open PPTX → Insert → Pictures → Select chart → Resize to 4\" width"

Partial Success Strategy

Always deliver maximum value:

• If 6 out of 8 charts succeed → deliver partial PPTX + fix instructions for remaining 2
• If PPTX creation fails → deliver Markdown + charts + conversion command
• Document all failures in /output/README.md "Known Issues" section

---

Examples

Example A: Minimal User Input → Full Orchestration

User Request:

"Create a presentation about renewable energy, ready for tomorrow's board meeting."

Detection:

• Trigger: "ready for tomorrow's meeting" (implicit final deliverable request)
• Mode: Orchestration ✓

Pipeline Execution:

Stage 0-7: Content creation → slides.md (14 slides, score 87/100)
Stage 8a: Package Markdown → notes.md, refs.md
Stage 8b: Data synthesis → 8 CSV files generated (refs.md specs)
Stage 8c: Chart generation → 8 PNG charts (579KB total)
Stage 8d: PPTX creation → presentation.pptx (210KB)
Stage 8e: Chart insertion → presentation_with_charts.pptx (557KB) ✓

Delivered:

• /output/presentation_with_charts.pptx (557KB, 14 slides, 8 real charts)
• Backup: slides.md, assets/.png, data/.csv, notes.md

---

Example B: User Provides Data → Skip Synthesis

User Request:

"Generate complete PPTX from these Q3 sales data files [uploads 3 CSVs]"

Detection:

• Trigger: "complete PPTX" (explicit orchestration request)
• User data: ✓ (3 CSV files uploaded)
• Mode: Orchestration, skip Stage 8b ✓

Pipeline Execution:

Stage 0-7: Content creation → slides.md (12 slides)
Stage 8a: Package Markdown
Stage 8b: SKIPPED (user data provided)
Stage 8c: Chart generation → use user CSVs → 5 PNG charts
Stage 8d: PPTX creation → presentation.pptx
Stage 8e: Chart insertion → presentation_with_charts.pptx ✓

---

Example C: Markdown-Only Request → No Orchestration

User Request:

"Create slides.md for renewable energy topic, I'll handle the PPTX conversion myself."

Detection:

• Trigger: "slides.md" + "I'll handle conversion" (explicit manual mode)
• Mode: Manual, no orchestration

Pipeline Execution:

Stage 0-7: Content creation → slides.md
Stage 8a: Package Markdown → notes.md, refs.md
Stage 8b-e: SKIPPED

Delivered:

• /output/slides.md with placeholder charts
• /output/notes.md, /output/refs.md
• Instructions: "Convert to PPTX using Marp or pandoc"

---

Version History

• v1.0.0 (2024-01): Initial orchestration capability

PPT Quality Scoring Rubric

Purpose: Systematically evaluate presentation quality and identify areas for improvement. A score ≥ 75/100 is required before delivery. If score < 75, refine the weakest items and re-score (max 2 iterations).

---

Scoring System

• Total Score: 100 points (10 items × 10 points each)
• Passing Threshold: ≥ 75 points
• Rating Scale (per item):
• 9-10: Excellent (exceeds expectations)
• 7-8: Good (meets expectations)
• 5-6: Acceptable (minor improvements needed)
• 3-4: Weak (significant improvements required)
• 0-2: Poor (fundamental issues, must fix)

---

1. Goal Clarity (0-10 points)

What: Are the audience, objective, and call-to-action (CTA) clearly defined and documented?

Scoring Criteria:

• 10: Audience, objective, and CTA explicitly stated and tailored; assumptions documented
• 8: Audience and objective clear; CTA present but could be more specific
• 6: Audience/objective vague; CTA generic (e.g., "let's discuss")
• 4: Missing audience definition or objective; no clear CTA
• 2: Presentation lacks clear purpose or intended action

How to Check:

• Review INTAKE.md responses and archive.txt
• Check final slide for specific CTA (not "Thank you" or "Questions?")
• Verify speaker notes mention audience and goal

Example Scores:

• 10: "After this 15-minute presentation, coffee enthusiasts will try at least one new brewing technique within the next week."
• 6: "This presentation is about coffee brewing for people interested in coffee."
• 2: "Talk about coffee."

---

2. Story Structure (0-10 points)

What: Is the Pyramid Principle applied? (One conclusion → 3-5 first-level reasons → evidence)

Scoring Criteria:

• 10: Clear pyramid structure; conclusion upfront; logical flow from reasons to evidence
• 8: Pyramid structure present but hierarchy could be clearer
• 6: Some structure but not consistently pyramid-style (e.g., conclusion buried at end)
• 4: Scattered points without clear logical connection
• 2: No discernible structure; random order

How to Check:

• Review storyline in archive.txt or WORKFLOW Stage 2 output
• Verify cover slide states main conclusion
• Check that 3-5 body sections support the conclusion
• Ensure evidence supports reasons (not random facts)

Example Scores:

• 10: Cover: "Master three variables for great coffee" → Sections: Grind / Temp / Time → Each with 2-3 evidence slides
• 6: Conclusion at end; sections exist but don't clearly support a single main point
• 2: Slides jump between topics with no connective thread

---

3. Slide Assertions (0-10 points)

What: Are slide headings assertion sentences (testable claims), not topic labels?

Scoring Criteria:

• 10: All slide headings are complete, testable assertion sentences
• 8: Most headings are assertions; 1-2 topic labels remain
• 6: Mix of assertions and topic labels (50/50)
• 4: Mostly topic labels with few assertions
• 2: All headings are topic labels (e.g., "Revenue", "Background", "Methodology")

How to Check:

• Review slide titles in slides.md
• Test: Can you agree/disagree with the heading? (If yes → assertion; if no → topic label)
• ✅ Assertion: "Finer grind size extracts flavors faster"
• ❌ Topic label: "Grind Size"

Example Scores:

• 10: Every slide heading is a complete sentence making a claim
• 6: Half are assertions ("Revenue grew 35%") and half are topics ("Q3 Results")
• 2: All headings are one-word or topic-style ("Introduction", "Conclusion")

---

4. Evidence Quality (0-10 points)

What: Is evidence sufficient, credible, and properly cited?

Scoring Criteria:

• 10: All claims backed by data/examples/citations; sources cited; units/methodology clear
• 8: Most claims have evidence; minor gaps in citations or methodology
• 6: Some claims lack evidence; sources missing or vague
• 4: Many unsupported claims; no citations; unclear data provenance
• 2: Assertions without any evidence or support

How to Check:

• Verify each assertion slide has chart/table/example/case study
• Check footer for source citations (e.g., "Source: XYZ, 2024")
• Confirm data units, time ranges, and methodology are specified
• Look for placeholder charts with "Data required: [fields]" if data unavailable

Example Scores:

• 10: "68% report bad cup experiences (Source: NCA 2024 Survey, n=1,200 home brewers)"
• 6: "Most people have bad coffee sometimes" (no data, no source)
• 2: "Coffee is important" (pure opinion, no evidence)

---

5. Chart Fit (0-10 points)

What: Are charts correctly selected, labeled, and easy to read?

Scoring Criteria:

• 10: Chart type matches data/message (per VIS-GUIDE); axes, units, source, alt text all present
• 8: Chart type correct; minor labeling gaps (e.g., missing unit or source)
• 6: Chart type suboptimal (e.g., pie chart with 7 slices); some labels missing
• 4: Wrong chart type for data; poor labeling; hard to interpret
• 2: No charts, or charts are misleading/unreadable

How to Check:

• Review chart selection against VIS-GUIDE.md Chart Selection Dictionary
• Verify all charts have: axis labels, units, data source, alt text
• Check readability: Can you understand the chart in 5 seconds?

Example Scores:

• 10: Line chart for time series, properly labeled, source cited, alt text provided
• 6: Bar chart OK but Y-axis missing unit; no source citation
• 2: 3D exploded pie chart with 10 slices and no labels

---

6. Visual & Accessibility (0-10 points)

What: Does the design meet WCAG AA standards and STYLE-GUIDE specs?

Scoring Criteria:

• 10: Contrast ≥4.5:1 (text) / ≥3:1 (UI); font sizes ≥18pt body / ≥34pt heading; white space ≥40%; alt text present
• 8: Minor accessibility issues (e.g., one chart with 4.2:1 contrast)
• 6: Multiple contrast or font size issues; some alt text missing
• 4: Poor contrast (<3:1), tiny fonts (<14pt), cluttered layout
• 2: Unreadable (light gray on white, <12pt fonts, no alt text)

How to Check:

• Use WebAIM contrast checker on text/background combos
• Measure font sizes (headings ≥34pt, body ≥18pt)
• Estimate white space (aim for 40-50% empty)
• Verify alt text for all images/charts
• Check colorblind-friendliness (use simulator)

Example Scores:

• 10: Dark text (#1F2937) on white, 36pt headings, 20pt body, 45% white space, all alt text present
• 6: Some 16pt body text, one chart missing alt text, 25% white space (crowded)
• 2: Light gray text on white, 12pt font, no margins, no alt text

---

7. Coherence & Transitions (0-10 points)

What: Do slides flow logically with smooth chapter and page transitions?

Scoring Criteria:

• 10: Clear section dividers; speaker notes include transitions; logical progression
• 8: Good flow overall; minor abrupt jumps
• 6: Some disjointed transitions; missing section dividers
• 4: Slides feel disconnected; unclear how one leads to next
• 2: Random order; no transitions or connective tissue

How to Check:

• Review speaker notes for transition phrases (e.g., "Now that we've covered X, let's explore Y")
• Check for section divider slides between major chapters
• Verify table of contents matches actual slide sequence

Example Scores:

• 10: Section dividers present; every speaker note ends with "This leads us to [next topic]..."
• 6: Flow is OK but one abrupt jump from "Problem" to "Conclusion" skipping "Solution"
• 2: Slides seem shuffled; no clear reason for order

---

8. Speakability (0-10 points)

What: Are speaker notes natural, well-paced (45-60 sec/slide), and easy to deliver?

Scoring Criteria:

• 10: All notes 45-60 sec; natural spoken language; structured (opening → assertion → evidence → transition)
• 8: Most notes well-paced; minor awkward phrasing
• 6: Some notes too long (>90 sec) or too short (<30 sec); some written-style language
• 4: Many notes poorly paced; reads like an essay, not speech
• 2: No speaker notes, or notes are bullet-point lists (not full script)

How to Check:

• Read notes aloud and time them
• Listen for natural speech patterns (contractions, questions, pauses)
• Verify structure: opening hook → core assertion → evidence walkthrough → transition

Example Scores:

• 10: "Now, here's the key insight: finer grind means more surface area. Think of it like sugar—powdered sugar dissolves instantly, while sugar cubes take forever. [PAUSE] Let's see how this plays out across five grind sizes..."
• 6: "The slide shows five grind sizes ranging from espresso to cold brew. Each has different particle size." (too dry, too short)
• 2: "• Espresso grind • Pour-over grind • French press grind" (bullet list, not script)

---

9. Deliverables Complete (0-10 points)

What: Are all required output files present and correctly formatted?

Scoring Criteria:

• 10: All files present and correct: slides.md, notes.md, refs.md, assets/*.png (if applicable), README.md
• 8: All core files present; minor formatting issues or missing README
• 6: Missing one deliverable (e.g., refs.md) or major formatting issue
• 4: Missing multiple deliverables or files are incomplete
• 2: Only partial output (e.g., slides.md exists but no notes or charts)

How to Check:

• Verify /output/ directory contains:
• slides.md (Markdown slides with YAML frontmatter, speaker notes)
• notes.md (Full speaker script + assumptions section)
• refs.md (Citations and sources)
• assets/*.png (charts, if data was provided)
• README.md (explains file structure)
• presentation.pptx (optional, if python-pptx available)

Example Scores:

• 10: All 5-6 files present, properly formatted, no broken links
• 6: Missing refs.md or README.md; one broken chart image link
• 2: Only slides.md exists; everything else missing

---

10. Robustness (0-10 points)

What: Are gaps/assumptions documented, and fallback plans provided?

Scoring Criteria:

• 10: All assumptions documented in notes.md; placeholders for missing data include field lists; next steps clear
• 8: Most assumptions noted; minor gaps in fallback plans
• 6: Some assumptions undocumented; placeholder charts lack detail
• 4: Many assumptions hidden; no guidance for missing data
• 2: Assumptions concealed; no acknowledgment of limitations

How to Check:

• Review "Assumptions & Limitations" section in notes.md
• Check placeholder charts have "Data required: [field list]"
• Verify next steps or follow-up actions are mentioned (if applicable)

Example Scores:

• 10: "Assumptions: (1) Used default 15-min duration (user did not specify). (2) No data provided for extraction curves; placeholder included with required fields: temperature_f, extraction_pct, time_sec."
• 6: Assumptions partially noted but missing some; placeholders generic ("Add chart here")
• 2: No mention of assumptions; missing data silently ignored

---

Scoring Workflow

Step 1: Initial Scoring

1. Review the presentation against all 10 criteria 2. Assign 0-10 points for each item 3. Calculate total score (sum of 10 items)

Example Initial Scorecard:

1. Goal Clarity: 9/10 ✓
2. Story Structure: 8/10 ✓
3. Slide Assertions: 6/10 ⚠️
4. Evidence Quality: 7/10 ⚠️
5. Chart Fit: 8/10 ✓
6. Visual & Accessibility: 9/10 ✓
7. Coherence & Transitions: 7/10 ⚠️
8. Speakability: 8/10 ✓
9. Deliverables Complete: 9/10 ✓
10. Robustness: 8/10 ✓
────────────────────────
TOTAL: 79/100 ✓ (≥75, ready to deliver)

---

Step 2: If Score < 75, Identify Top 3 Weaknesses

1. Sort items by score (ascending) 2. Identify the 3 lowest-scoring items 3. Write specific improvement actions for each

Example (if total was 72/100):

TOP 3 WEAKNESSES:
1. Item 3 (Slide Assertions): Score 5/10
   - Problem: Slides 4, 7, 11 use topic labels ("Grind Size", "Temperature")
   - Action: Revise to assertion sentences:
     • Slide 4: "Finer grind size extracts flavors faster and more completely"
     • Slide 7: "Water between 195-205°F produces balanced, full-bodied coffee"
     • Slide 11: "Simple equipment upgrades ensure consistent results"

2. Item 4 (Evidence Quality): Score 6/10
   - Problem: Missing source citations on 3 charts; no methodology note
   - Action:
     • Add footer to charts: "Source: National Coffee Association, 2024"
     • Add methodology note in refs.md: "Survey n=1,200 home brewers, margin of error ±3%"

3. Item 7 (Coherence & Transitions): Score 6/10
   - Problem: Abrupt jump from Slide 8 (temperature) to Slide 9 (time); missing section divider
   - Action:
     • Insert transition slide: "Now that we've mastered grind and temperature, let's tackle the third variable: time"
     • Update speaker notes for Slide 8 to bridge: "...and this brings us to our final variable."

---

Step 3: Apply Improvements & Re-Score

1. Make the improvements 2. Re-score all 10 items 3. If new total ≥ 75 → deliver 4. If new total < 75 → repeat Step 2-3 (max 2 iterations total)

Example Re-Score:

1. Goal Clarity: 9/10 ✓
2. Story Structure: 8/10 ✓
3. Slide Assertions: 9/10 ✓ (improved from 5)
4. Evidence Quality: 8/10 ✓ (improved from 6)
5. Chart Fit: 8/10 ✓
6. Visual & Accessibility: 9/10 ✓
7. Coherence & Transitions: 8/10 ✓ (improved from 6)
8. Speakability: 8/10 ✓
9. Deliverables Complete: 9/10 ✓
10. Robustness: 8/10 ✓
────────────────────────
TOTAL: 84/100 ✓✓ (exceeds threshold, ready to deliver)

---

Iteration Limits

• Max Iterations: 2 rounds of improvements
• Why Limit: Avoid infinite refinement loop; deliver practical value quickly
• If Still < 75 After 2 Rounds:
• Deliver with clear disclaimer: "This presentation scores [X]/100. The following items need further work: [list weakest 3 items]."
• Provide improvement roadmap in notes.md

---

Common Score Ranges & Interpretations

---

Self-Evaluation Checklist (Quick Version)

Use this quick checklist before full scoring:

• [ ] Goal: Audience, objective, CTA documented and clear?
• [ ] Structure: Pyramid (conclusion → reasons → evidence)?
• [ ] Assertions: All headings are testable sentences?
• [ ] Evidence: All claims have data/examples/citations?
• [ ] Charts: Correct type, fully labeled, source cited?
• [ ] Accessibility: Contrast ≥4.5:1, fonts ≥18pt, alt text?
• [ ] Transitions: Smooth flow, section dividers, speaker notes?
• [ ] Speakability: Notes 45-60 sec, natural language?
• [ ] Deliverables: slides.md, notes.md, refs.md, assets/?
• [ ] Robustness: Assumptions documented, placeholders detailed?

If all checkboxes are ✓, score is likely ≥ 75.

---

Final Delivery Criteria

Before delivering to user, confirm: 1. Total score ≥ 75/100 (or 2 improvement iterations completed) 2. All deliverables in /output/ directory 3. Assumptions and limitations documented in notes.md 4. If score < 75, include improvement roadmap

Delivery Message Template:

✅ Presentation ready!

SCORE: [X]/100 (threshold: 75)
QUALITY: [Exceptional / Good / Needs improvement]

DELIVERABLES:
- /output/slides.md (Markdown deck, [N] slides)
- /output/notes.md (Speaker script + assumptions)
- /output/refs.md (Citations and sources)
- /output/assets/ ([N] charts)
- /output/presentation.pptx (if available)

NEXT STEPS:
- Review speaker notes and adjust for your personal style
- Replace placeholder charts with your data (use chartkit.py if needed)
- Customize colors/fonts per STYLE-GUIDE.md

[If score < 75: Add improvement roadmap here]

---

Next Steps: Once scoring is complete and score ≥ 75, proceed to Stage 8 (Package Deliverables) in WORKFLOW.md.

Layout & Style Guide (Neutral Theme)

Purpose: Ensure consistent, accessible, professional visual design across all slides. This neutral theme supports easy customization with your own brand colors and fonts.

---

Canvas & Grid System

Slide Dimensions

• Aspect Ratio: 16:9 (widescreen standard)
• Resolution: 1920 × 1080 pixels (Full HD) or 1280 × 720 pixels (HD)
• Safe Zone: Margins ≥ 48px on all sides (prevents content from being cut off by projectors)

Grid System

• Columns: 12-column grid (column width varies by content)
• Gutter: 24px between columns
• Baseline Grid: 8px vertical rhythm (all spacing should be multiples of 8)

Layout Examples

┌─────────────────────────────────────────────┐
│ [48px margin]                               │
│  ┌──────────────────────────────────┐      │
│  │ HEADING (top-aligned)             │      │
│  │                                   │      │
│  │ [Content area: text/chart/image]  │      │
│  │                                   │      │
│  │                                   │      │
│  └──────────────────────────────────┘      │
│       [Footer: source + page #] [48px]     │
└─────────────────────────────────────────────┘

---

Typography

Font Families

Recommended Fonts:

• Chinese: Source Han Sans (思源黑体) / PingFang SC (苹方) / Hiragino Sans (冬青黑体)
• English: Inter / Calibri / Helvetica Neue / Arial

Why These Fonts:

• High readability on screens
• Wide character support (multilingual)
• Professional appearance
• Available on most systems (or free to download)

Fallback Stack:

font-family: "Inter", "Source Han Sans", "PingFang SC", -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif;

Font Sizes

Minimum Readable Size: 14pt (anything smaller is hard to read from audience distance)

---

Line Spacing (Leading)

Example:

• Heading: 36pt font → 40pt line height (1.1×)
• Body: 20pt font → 28pt line height (1.4×)

---

Text Alignment

• Headings: Left-aligned (easier to scan)
• Exception: Cover slide title may be centered
• Body Text: Left-aligned
• Avoid full justification (creates awkward word spacing)
• Bullet Points: Left-aligned with 24-32px indent
• Footers: Right-aligned (source), left-aligned (page number/date)

---

Text Formatting

Bold:

• Use for headings, key terms, and emphasis
• Do NOT use all-caps for body text (harder to read)

Italic:

• Use sparingly for quotes, foreign terms, or subtle emphasis
• Do NOT use for long passages (reduces readability)

Underline:

• Avoid (looks like hyperlinks)
• Use bold or color for emphasis instead

ALL CAPS:

• OK for short labels (e.g., "SECTION 1", "BACKUP")
• Avoid for sentences (slows reading speed by 10-15%)

---

Color Palette (Neutral Theme, WCAG AA Compliant)

Primary Colors

Accent Colors

Note: ✓ = Passes WCAG AA (≥4.5:1 for text, ≥3:1 for UI elements); ⚠️ = Marginal (use carefully); ✗ = Fails

Color Usage Rules

1. Text on White Background:

• Primary text: Dark Ink (#1F2937) → 16.1:1 ✓
• Secondary text: Medium Gray (#6B7280) → 4.6:1 ✓
• Links/Highlights: Primary Blue (#2563EB) → 4.6:1 ✓

2. Text on Dark Background (e.g., dark slide):

• Use white (#FFFFFF) or very light gray (#F3F4F6)
• Ensure ≥4.5:1 contrast

3. Chart Colors:

• Use Primary Blue, Emphasis Red, Secondary Teal, Success Green
• Avoid relying on color alone (add patterns/labels)
• Test with colorblind simulator (see VIS-GUIDE.md)

4. Avoid These Combinations:

• Red text on green background (colorblind issue)
• Light gray text on white background (insufficient contrast)
• Pure black (#000000) on pure white (too harsh; use Dark Ink instead)

---

Spacing & Layout

Margin & Padding

Bullet Point Formatting

• Indent: 24-32px from left margin
• Bullet Style: Simple (•) or numbered (1., 2., 3.)
• Avoid fancy bullets (stars, arrows, custom icons)
• Max Bullets Per Slide: 3-5 (more gets overwhelming)
• Nested Bullets: Max 2 levels (Level 1 → Level 2)
• Level 2 indent: +24px from Level 1

Example:

• Main point one (Level 1)
  • Supporting detail (Level 2)
  • Another detail (Level 2)
• Main point two (Level 1)
• Main point three (Level 1)

---

Visual Elements

Charts & Graphs

• Padding: 8px internal padding around chart area
• Border: None (or very subtle 1px light gray if needed)
• Grid Lines: Minimal (horizontal only, light gray #E5E7EB)
• Axis Lines: 1-2px, Medium Gray (#6B7280)
• Data Labels: 16-18pt, positioned above/beside data points (not overlapping)

Images & Photos

• Border Radius: 6-8px (subtle rounded corners)
• Padding: 8px around image
• Alt Text: Always include (see Accessibility section)
• Aspect Ratio: Maintain original (don't stretch/distort)
• Max Size: Leave 48px margins on all sides

Icons

• Size: 24px × 24px (small), 48px × 48px (medium), 96px × 96px (large)
• Style: Outline or filled (be consistent across deck)
• Color: Match accent colors (Primary Blue, Emphasis Red, etc.)
• Spacing: 16px between icon and label

Dividers & Borders

• Horizontal Divider: 1-2px, Light Gray (#D1D5DB)
• Use Sparingly: Only when needed to separate sections
• Border Radius: 6-8px for boxes, cards, or containers

---

Page Density & White Space

The "70-Word Rule"

• Max Words Per Slide: ≤70 words (excluding chart labels and footer)
• Why: Audience can't read and listen simultaneously; slides should support speech, not replace it
• Exception: Backup slides or reference tables (not presented, for Q&A)

White Space Guidelines

• Don't Fill Every Pixel: Aim for 40-50% white space per slide
• Purpose: Guides eye, reduces cognitive load, looks professional
• How to Achieve:
• Use generous margins (48px+)
• Space out bullet points (16-24px apart)
• One chart or image per slide (not 3-4 crammed together)

---

Accessibility (WCAG 2.1 AA Compliance)

Contrast Requirements

Text Contrast (against background):

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

UI Components & Chart Elements:

• Graphical objects (bars, lines, icons): ≥ 3:1 against adjacent colors
• Active vs inactive states: ≥ 3:1 contrast difference

Test Your Contrast:

• WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
• Browser DevTools: Inspect element → Contrast ratio displayed

---

Color Blindness

Do NOT Rely on Color Alone:

• Add text labels, patterns, or shapes to distinguish chart series
• Example: Line chart with 3 series → use solid, dashed, dotted lines + color

Use Colorblind-Friendly Palettes:

• Avoid red + green combinations
• Use blue + orange or blue + yellow instead
• Test with simulators: Coblis, Color Oracle

---

Alt Text for Images & Charts

Every image and chart must have alt text for screen readers.

Good Alt Text:

• Describes content concisely (1-2 sentences)
• Includes key data insights (for charts)
• Example (chart): "Line chart showing monthly revenue Jan-Dec 2024, with 35% growth and a sharp Q3 spike."
• Example (photo): "Product prototype with transparent casing and LED display showing time."

Bad Alt Text:

• "Chart 1" (too vague)
• "Revenue graph" (no insight)
• [Empty alt tag] (inaccessible)

---

Screen Reader Compatibility

• Heading Hierarchy: Use proper heading levels (H1 → H2 → H3), don't skip
• Reading Order: Ensure content flows logically (top-to-bottom, left-to-right)
• Link Text: Descriptive ("Download Q4 Report" vs. "Click here")

---

Animation & Transitions (Use Sparingly)

When to Animate

• Reveal bullet points: One at a time (helps pacing)
• Highlight data: Fade in chart elements sequentially (e.g., line-by-line)
• Slide transitions: Simple fade or push (not flashy)

When NOT to Animate

• Avoid: Spinning, bouncing, dissolving, 3D effects
• Why: Distracting, unprofessional, slows down presentation
• Exception: Data storytelling where sequence matters (e.g., building a chart layer-by-layer)

---

Slide-Specific Layouts

Cover Slide

┌─────────────────────────────────────────┐
│                                         │
│         [Centered or Left-Aligned]      │
│                                         │
│   MAIN TITLE (36-40pt, Bold)           │
│   Subtitle (24-28pt, Regular)          │
│                                         │
│   Date | Presenter Name                │
│                                         │
└─────────────────────────────────────────┘

---

Content Slide (Text + Chart)

┌─────────────────────────────────────────┐
│ ASSERTION HEADING (34-36pt)             │
│                                         │
│  • Bullet point 1 (20pt)                │
│  • Bullet point 2                       │
│  • Bullet point 3                       │
│                                         │
│  [Chart with alt text]                  │
│                                         │
│         Source: XYZ, 2024 | Page 5     │
└─────────────────────────────────────────┘

---

Section Divider Slide

┌─────────────────────────────────────────┐
│                                         │
│                                         │
│        SECTION TITLE (40pt)            │
│        Brief Description (24pt)         │
│                                         │
│                                         │
│                                         │
└─────────────────────────────────────────┘

---

Customization Guide (Replace with Your Brand)

Step 1: Update Colors

Find and replace these hex codes in your slides:

Test Contrast: Use WebAIM checker to ensure ≥4.5:1 for text, ≥3:1 for UI.

---

Step 2: Update Fonts

Find and replace font families:

• Headings: Inter → [Your Brand Font]
• Body: Source Han Sans → [Your Brand Font]

Web Font Loading (if using Google Fonts or Adobe Fonts):

<link href="https://fonts.googleapis.com/css2?family=YourFont:wght@400;600;700&display=swap" rel="stylesheet">

---

Step 3: Add Logo

• Place logo file in /output/assets/logo.png
• Add to cover slide (top-left or top-right)
• Add to footer of content slides (small, 32-48px height)

---

Step 4: Customize Templates

• Open references/TEMPLATES.md
• Adjust spacing, margins, or layout to match your brand guidelines
• Update STYLE-GUIDE.md to document your changes

---

Step 5: Export & Test

• Export to PPTX or PDF
• Test on projector (check margins, readability)
• Verify accessibility (screen reader, contrast, colorblind mode)

---

Quick Reference Checklist

Before finalizing each slide, check:

• [ ] Contrast: Text ≥ 4.5:1, UI elements ≥ 3:1
• [ ] Margins: ≥ 48px safe zone on all sides
• [ ] Font Size: Headings ≥ 34pt, body ≥ 18pt
• [ ] Line Spacing: Headings 1.1×, body 1.3-1.5×
• [ ] Word Count: ≤ 70 words per slide
• [ ] Alt Text: All charts and images have descriptive alt text
• [ ] Bullet Points: Max 3-5 per slide
• [ ] White Space: 40-50% of slide is empty
• [ ] Source Citation: Every chart has source in footer
• [ ] Color Independence: Not relying on color alone (patterns/labels added)

---

Tools & Resources

1. Contrast Checkers:

• WebAIM: https://webaim.org/resources/contrastchecker/
• Chrome DevTools: Inspect → Contrast ratio

2. Colorblind Simulators:

• Coblis: https://www.color-blindness.com/coblis-color-blindness-simulator/
• Color Oracle (desktop app)

3. Fonts:

• Google Fonts: https://fonts.google.com/
• Adobe Fonts: https://fonts.adobe.com/
• Source Han Sans (free): https://github.com/adobe-fonts/source-han-sans

4. WCAG 2.1 Guidelines:

• Contrast (Minimum): https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html

---

Next Steps: Once style is finalized, proceed to Stage 6 (Speaker Notes) in WORKFLOW.md.