---
name: ppt-design
description: Design presentation slides, infographic pages, and PPT-style visuals as 1600x900 HTML slides with optional PPT export. Use when the agent needs to pick or explain a slide style, recommend styles based on content, generate one or more static HTML slides, support `background_mode` paper or white for compatible light styles, or render finished slides into a high-fidelity image-based PPTX.
version: 0.3.0
---
# PPT Design
Design each slide as a standalone 1600x900 HTML file, then export to PPT only when the user asks for it.
In this repo, the executable slide contract lives in `./scripts/slide_engine/`.
The shared JS manifest and shared renderers are the runtime source of truth.
Files in `./styles/style_[a-j].md` remain human-facing design references and must stay manually aligned with that executable manifest.
## Workflow
1. Identify the topic, audience, and deliverable.
2. If the user provides a Markdown document, treat each `Page X` section as one slide unless the document clearly indicates a different page structure.
3. Read [style-selector.md](./references/style-selector.md) before choosing a style.
4. If the deck is in Chinese or mixed Chinese and English, read [bilingual-typography.md](./references/bilingual-typography.md).
5. Recommend 2-3 styles when the user has not already chosen one.
6. Explain each recommended style in plain language:
- style name
- one-line visual description
- what kind of content it fits best
- use English by default for these style explanations and recommendations
7. Confirm or infer `background_mode`:
- default to `paper`
- allow `white` only for compatible light styles
- if the chosen style does not support `white`, say so and keep `paper` or recommend a compatible style
8. Read [background-modes.md](./references/background-modes.md).
9. Read [presentation-layout-rules.md](./references/presentation-layout-rules.md).
10. Read [html-review-checklist.md](./references/html-review-checklist.md).
11. When the deck is `client-facing` or `public-stage`, read [presentation-quality-rubric.md](./references/presentation-quality-rubric.md).
12. Read [layout-prototypes.md](./references/layout-prototypes.md). Classify each slide's content role and select a layout prototype before writing HTML. Do not repeat the same layout on consecutive slides.
13. Read [safe-zone.md](./references/safe-zone.md). Enforce content boundaries on every slide: all primary content must live inside the main frame area (`y = 108px` to `y = 804px`). Include chrome labels only on cover and closing slides when `chrome=bookend`.
14. If a slide contains strict tables, org charts, framework diagrams, or other geometry-sensitive structures, read [geometry-preserve.md](./references/geometry-preserve.md) before writing that slide.
15. Read the chosen style file in `./styles/style_[a-j].md` before writing HTML. Treat it as the design reference for mood, typography, and ornament logic; runtime behavior is enforced by the shared slide engine.
16. Preserve the chosen style's native whitespace, ornament density, contrast, and pacing. Do not normalize all styles toward the same layout density.
17. When the slide copy is Chinese or bilingual, follow the style's Chinese and English pairing guidance rather than reusing the English display font everywhere.
18. Recompose page content into slide hierarchy instead of preserving raw Markdown formatting literally, except when geometry-sensitive structure should be preserved.
19. Generate one HTML file per slide in `./outputs/html/`.
20. Review every generated HTML slide before delivery. Treat this as mandatory, not optional.
21. Fix layout, spacing, typography, hierarchy, and geometry issues found in review using the smallest change that keeps the slide true to the chosen style.
22. When `speaker_notes_mode` is enabled, generate a sidecar notes file for presenter use.
23. If the user wants PPT, render the HTML slides to PNG and package them into a PPTX.
For `public-stage` work, treat the flow as a task pipeline:
1. draft generation
2. polish pass
3. audit gate
4. render / export
Do not skip the polish pass and do not export before the audit gate passes.
## Inputs
Use these fields when the user provides them or when you need to make them explicit in your own reasoning:
- `input_markdown`: the source Markdown for the deck, ideally grouped by `Page 1`, `Page 2`, and so on
- `style`: `A-J` or a named style
- `background_mode`: `paper` or `white`
- `chrome`: `all`, `bookend`, or `none`
- `geometry_mode`: `auto`, `preserve`, or `recompose`
- `presentation_scenario`: `brand-launch`, `investor-board`, `client-pitch`, or `research-brief`
- `quality_tier`: `internal`, `client-facing`, or `public-stage`
- `speaker_notes_mode`: `none`, `outline`, or `full`
- `brand_profile`: brand lock settings for logo, footer, palette, and font policy
- `deliverable`: `html`, `ppt`, or `both`
Default behavior:
- `input_markdown`: infer page structure from headings when possible
- `style`: recommend candidates first when unspecified
- `background_mode`: `paper`
- `chrome`: `bookend`
- `geometry_mode`: `auto`
- `presentation_scenario`: `brand-launch`
- `quality_tier`: `public-stage`
- `speaker_notes_mode`: `outline`
- `deliverable`: `html`
Repo note:
- The bundled demo builders in `./scripts/build_template_style_cases.mjs` and `./scripts/build_twitter_style_cases.mjs` are fixed internal benchmark pipelines.
- They currently render with `chrome=bookend` and validate HTML before PNG/PPT export.
- They do not expose every skill input as a CLI flag.
## Style Selection
Read [style-selector.md](./references/style-selector.md) first.
When the user has not chosen a style:
- Recommend only 2-3 styles, not all 10.
- Match the recommendation to the content rather than to arbitrary taste words like "nice" or "cool".
- Explain what the style looks like and what kind of material it suits.
- Default the style recommendation language to English, even when the working conversation is in another language.
- Keep generated slide copy in the user's source language unless the user explicitly asks for translation.
Examples:
- Business report, finance, policy, research summary: bias toward `A`, `D`, or `I`.
- Brand story, culture, exhibition, philosophy, editorial: bias toward `B`, `E`, or `F`.
- Creative proposal, event, youth brand, campaign, entertainment: bias toward `C`, `G`, `H`, or `J`.
## Background Modes
Read [background-modes.md](./references/background-modes.md).
Apply these rules:
- `paper` keeps paper grain, print texture, and warm off-white stock when the style supports it.
- `white` switches the slide canvas to clean white and removes paper-specific texture, fold marks, and stock simulation.
- `white` does not remove style identity. Keep the typography, grid, ornament, contrast system, and non-paper decorative devices.
- `white` is supported only by styles `A`, `B`, `C`, `D`, `E`, `G`, and `J`.
- Styles `F`, `H`, and `I` are dark-native. Do not whitewash them.
## HTML Rules
- Create one file per slide: `slide_01.html`, `slide_02.html`, and so on.
- Keep the canvas fixed at `1600x900`.
- Use static HTML, CSS, and inline SVG only.
- Do not use JavaScript in the slide files.
- Do not use external images other than Google Fonts.
- Save outputs in `./outputs/html/`.
- Design for projection and presentation first, not for dense document reading.
Use this base structure unless the style file overrides a specific detail:
```html
Slide Title
STYLE A / Swiss International
Cover
cover-swiss-rail
01 / 05
```
## Chrome Labels
Read [safe-zone.md](./references/safe-zone.md).
Apply these rules:
- `chrome=bookend`: show `.chrome-top` and `.chrome-bottom` on cover and closing slides only.
- `chrome=all`: show `.chrome-top` and `.chrome-bottom` on every slide.
- `chrome=none`: omit chrome labels entirely.
- The main content frame does not move when chrome visibility changes.
## Style Fidelity
Apply these rules on every slide:
- The shared engine manifest is the executable source of truth; the chosen style file is the human design reference.
- Preserve the style's native whitespace strategy. Minimal and editorial styles should stay restrained.
- Preserve ornament logic. Decorative rules, frames, and accents should support the composition, not dominate it.
- When fixing density or collisions, prefer content edits, card count changes, or local spacing adjustments over turning every style into the same template.
- A successful revision should still look unmistakably like the chosen style family.
## Presentation Typography
Read [presentation-layout-rules.md](./references/presentation-layout-rules.md).
Apply these rules on every slide:
- Prioritize legibility at presentation distance.
- Do not allow text blocks, labels, or numbers to collide with each other.
- Prefer fewer, larger text groups over many small annotations.
- Keep headline and body contrast obvious in size, weight, and spacing.
- If a slide is text-heavy, redesign the hierarchy instead of shrinking everything.
- If a slide contains table-like information, convert it into presentation-friendly structure unless the user explicitly requires a literal dense table.
For presentation use, apply the full typography scale from [presentation-layout-rules.md](./references/presentation-layout-rules.md). The eight roles and their hard minimums are:
| Role | EN Min | CN Min |
|---|---|---|
| Display Title | `44px` | `40px` |
| Section Heading | `28px` | `28px` |
| Body | `22px` | `24px` |
| Table Header | `20px` | `22px` |
| Table Cell | `18px` | `20px` |
| Support Copy | `18px` | `20px` |
| Label / Caption | `16px` | `18px` |
| Page Number (chrome only) | `14px` | `14px` |
Do not shrink any role below its minimum. If content does not fit, reduce content, split the slide, or rebuild the hierarchy. When the chosen style is intentionally fancy or experimental, preserve the style but still protect legibility.
## Tables And Text-Heavy Content
Read [presentation-layout-rules.md](./references/presentation-layout-rules.md).
When the user asks for tables, comparisons, or many words:
- Default to redesigned comparison blocks, metric cards, timeline rows, or labeled columns instead of raw spreadsheet tables.
- Use a true table only when row-column comparison is the main point and simplifying it would lose meaning.
- Break large tables into multiple slides when needed.
- Highlight only the few values or row groups that matter.
- Maintain generous padding inside cells or cards so text never feels cramped.
- For dense content, prefer 3-6 major points per slide rather than squeezing everything into one page.
## Geometry-Sensitive Content
Read [geometry-preserve.md](./references/geometry-preserve.md) when a slide contains diagrams, framework maps, org charts, box-and-arrow structures, or strict tables.
Apply these rules:
- `geometry_mode=auto`: preserve geometry when box size, connector position, or table structure carries meaning.
- `geometry_mode=preserve`: keep the structural skeleton intact even if that means reducing copy or splitting the figure across slides.
- `geometry_mode=recompose`: reinterpret the content into slide-friendly cards or bands only when the user explicitly wants that.
- For geometry-sensitive slides, style changes surface treatment only. Do not distort the diagram's core proportions just to match a preferred layout prototype.
- Use explicit tracks, coordinates, or bounded box sizes for the diagram skeleton instead of leaving box proportions fully driven by text length.
- If content does not fit inside the diagram cleanly, shorten labels, split the figure, or move detail into notes. Do not compress the geometry until the structure becomes misleading.
## Mandatory HTML Review
Read [html-review-checklist.md](./references/html-review-checklist.md).
After generating each slide, perform a second-pass review before delivery:
1. Check for overlap, collision, clipping, and crowding.
2. Check that typography is large enough for presentation.
3. Check that text-heavy or table-heavy content has been reformatted for slides.
4. Check that geometry-sensitive diagrams or tables still preserve their intended proportions.
5. Check that the chosen style is still intact after readability adjustments.
6. When tools allow it, render the HTML and inspect the actual visual result instead of relying only on source review.
7. If exporting to PPT, confirm the rendered PNG aspect ratio matches the final PPT slide.
8. Revise the HTML if any item fails.
Never hand off first-draft HTML without this review pass.
## PPT Export
When the user wants `ppt` or `both`, use the bundled scripts:
1. Ensure dependencies are installed with `npm install`.
2. Render HTML slides to PNG:
```powershell
node .\scripts\render_slides.mjs --input .\outputs\html --output .\outputs\rendered
```
3. Build the PPTX:
```powershell
node .\scripts\export_ppt.mjs --input .\outputs\rendered --output .\outputs\ppt\deck.pptx
```
The PPT export is intentionally image-based for fidelity. Each slide becomes one full-bleed PNG inside a 16:9 deck.
## Quality Checks
- The chosen style matches the content type and tone.
- The user can understand why that style was chosen.
- `background_mode` is honored correctly.
- Compatible light styles can switch between `paper` and `white`.
- Incompatible dark styles reject `white` explicitly.
- Every slide remains visually coherent within one style family.
- Text does not overlap, collide, clip, or crowd nearby elements.
- Typography is large enough for projection and presentation use.
- Text-heavy and table-like content has been reformatted into stronger slide hierarchy where appropriate.
- A second-pass HTML review happened after generation, not only before.
- PPT pages preserve the HTML composition without cropping or scaling errors.
- Decorative blocks, especially dark or saturated ones, do not invade the primary reading zones unless that overlap is deliberate, padded, and presentation-safe.
- All primary content stays within the main frame area (`108px` to `804px` vertically).
- No text content appears in the top reserved zone (`0-96px`) or bottom reserved zone (`804-900px`) except chrome labels allowed by the current `chrome` mode.
- Consecutive slides use different layout prototypes.
- A 10-slide deck uses at least 5 distinct layout prototypes.
- Refinements preserve the original style instead of flattening all decks toward the same density or ornament pattern.