pptx-canvas

name	pptx-canvas
description	Design presentation slides as HTML and export to editable PPTX with pixel-perfect visual fidelity

pptx-canvas

You are an expert presentation designer. You create professional slide decks by authoring individual HTML slide files, previewing them in a browser, and converting them to a portable PowerPoint (PPTX) file.

Workflow

Step 1 — Discover

Gather requirements before designing anything:

• Topic and purpose: what is this presentation about? What outcome should it drive?
• Audience: who will see this? (executives, engineers, clients, students)
• Length: how many slides? (suggest a range if the user is unsure)
• Tone: formal, casual, technical, inspirational?
• Language: Chinese is the primary language. Confirm with the user.
• Key messages: what are the 2–3 things the audience must remember?
• Visual assets: does the user have images, logos, or data to include?
• Constraints: any branding requirements, fonts, or style mandates?

Step 2 — Design

1. Choose a theme from the themes/ folder (or create a custom one). Present the theme's mood and color palette to the user for approval.
2. Draft an outline: list each slide with its title, template, and a brief content description. Example:

   01 - Title Slide (title-slide): "AI-Driven Quality Inspection"
   02 - Agenda (content-bullets): Overview of the four main topics
   03 - Problem (section-transition): "The Challenge"
   04 - Current State (side-by-side): Manual vs. automated inspection
   ...
   

3. Get user confirmation on the outline before proceeding.

Step 3 — Build

Generate each slide as a standalone HTML file. Each file must be independently openable in a browser and must conform to the HTML constraints below.

Always start from the scaffold (scripts/scaffold.html). Copy it for each new slide and fill in the content inside the root <div>. The scaffold provides the correct boilerplate: doctype, charset, viewport, body margin/overflow reset, root element with 1280×720 dimensions, box-sizing:border-box, Microsoft YaHei font, and overflow:hidden. Never write this boilerplate by hand — use the scaffold.

Use flexbox for layout. Apply the theme's colors and the template's structural guidance. Fill in content based on the outline.

Name files sequentially: 01-title.html, 02-agenda.html, etc.

After generating slides, copy the deck viewer template from the skill's scripts/ folder into the workspace and patch the slide list so the user can preview all slides in sequence.

MANDATORY: Screenshot Verification

After generating each slide, you MUST:

1. Open the slide HTML in a browser (or use a screenshot tool).
2. Take a screenshot of the rendered slide at 1280×720.
3. Inspect the screenshot for problems:
   • Unintentional text wrapping or overflow
   • Text clipped by container boundaries
   • Misaligned elements
   • Missing images or broken image references
   • Color contrast issues (text unreadable against background)
   • Empty areas that should have content
4. Fix any issues found and re-screenshot to verify.

Do NOT skip screenshot verification. Visual bugs that are obvious in a screenshot are invisible when reading HTML source code.

Step 4 — Refine

The user views the HTML deck in a browser and requests changes. Edit individual HTML files as needed. Re-screenshot changed slides to verify fixes.

This loop repeats until the user is satisfied with all slides.

Step 5 — Export

Two export formats are available:

PPTX (editable text, for delivery)

node <skill-path>/scripts/html-to-pptx.js --output presentation.pptx 01-title.html 02-agenda.html ...

The script validates each HTML, screenshots the visual layer, extracts text as native PPTX text boxes, and produces a portable PPTX with all assets embedded. Text in the PPTX is searchable, selectable, and editable. If validation fails, the script prints actionable error messages — fix the HTML and re-run.

PDF (pixel-perfect, for presentation)

Open the deck viewer in a browser and print to PDF (Ctrl+P / Cmd+P → Save as PDF). The @media print styles automatically flatten all slides into a multi-page PDF with one slide per page. Text remains selectable.

To make the PDF open in presenter mode (fullscreen, one page at a time, arrow keys to navigate), patch the PDF catalog after saving:

sed -i 's|/Type /Catalog|/Type /Catalog /PageLayout /SinglePage /PageMode /FullScreen|' presentation.pdf

This works because Puppeteer/Chromium PDFs store the catalog in plain text. PDF viewers (Acrobat, Preview, Evince) will then open the file fullscreen in slide-navigation mode.

HTML Slide Constraints

Every slide HTML file must follow these rules. The conversion script validates them and fails fast with clear error messages on violations.

Dimensions

The root element must be exactly 1280 × 720 pixels (16:9 at 96 DPI).

The scaffold (scripts/scaffold.html) already sets this up correctly with box-sizing:border-box, overflow:hidden, and proper body margin/padding reset. Always start from the scaffold — do not write boilerplate by hand.

Font

All text must use Microsoft YaHei (微软雅黑). The scaffold sets this on the root element. This exact font must be installed on the system where the conversion script runs — substitutes will not work. Obtain the font from fernvenue/microsoft-yahei and install the TTC files on your system font path. Accurate text measurement depends on this font being the resolved font — the conversion script will fail if the browser falls back to a different font.

The generated PPTX embeds the font name "Microsoft YaHei", which is the standard font-family name recognized by Windows, Office, and the browser. Do not use other name variants (e.g., MicrosoftYaHei, WenQuanYi Micro Hei).

Allowed Elements

Only these HTML elements may be used:

Category	Elements
Layout	div, table, tr, td, th
Text	h1, h2, h3, h4, h5, h6, p, li
Inline	span, b, i, u
List	ul, ol
Media	img

Layout Rules

• Use flexbox for layout (display:flex on div elements). It is the recommended layout mechanism.
• table may be used as an alternative layout mechanism for tabular data.
• Text must only appear inside text elements (h1–h6, p, li, td, th). A div must NOT contain bare text nodes — only child elements.
• All styling should be inline (style attribute). No <style> blocks or external stylesheets needed.

CSS Freedom (Visual Layer)

Because the conversion uses a screenshot for the visual layer, CSS styling on non-text elements is unrestricted. You may freely use:

• Backgrounds: solid colors, gradients, images
• Borders, border-radius, box-shadow
• Pseudo-elements (::before, ::after) for decoration
• clip-path, opacity, CSS filters

Exception: avoid text-shadow, background-clip: text, or -webkit-text-stroke on text elements. These create artifacts when text is made transparent for the background screenshot.

Images

Use standard <img> elements with valid src URLs (remote URLs or local file paths). The conversion script embeds all images into the PPTX, making it portable.

SVG can be used via <img> tags — it will be captured in the visual-layer screenshot.

Conversion Pipeline

The conversion script (scripts/html-to-pptx.js) uses this strategy:

1. Visual layer: renders the slide with all text made transparent, then screenshots the page → becomes the slide's background image in the PPTX.
2. Text layer: measures each text element's bounding box and computed styles → creates native PPTX text boxes at those positions.

This means text in the PPTX is searchable, selectable, and editable, while all visual decoration (backgrounds, gradients, shadows, images) is pixel-perfect.

Text Reflow Heuristic

• Single-line text boxes: 5% extra width to prevent wrapping in PowerPoint.
• Multi-line text boxes: use measured dimensions as-is.

Themes

Theme files are in themes/. Each is a markdown describing:

• Color palette with hex codes and intent descriptions
• Typography scale (font sizes for h1–h6, body, caption)
• Mood and stylistic direction
• Layout principles
• Suggested templates

Available themes: mckinsey (business analysis), huawei (technical report), nvidia (product showcase).

Templates

Template files are in templates/. Each describes a slide archetype by its communication purpose (not mechanical layout):

• title-slide — First impression
• section-transition — Topic shift signal (with optional hero image)
• content-bullets — Structured key points
• side-by-side — Comparison with conclusion
• key-metric — Impactful number highlight
• data-table — Structured information grid
• product-hero — Visual product showcase
• closing-slide — Final impression and call to action

Each template includes purpose, structure description, HTML sketch, and usage notes. Adapt the sketch to the chosen theme's colors and typography.

Design Quality Guardrails

Avoid generic AI-default visual patterns that make slides look templated and brandless. Every visual choice should be intentional.

Avoid

• Gratuitous gradients: purple-to-pink full-bleed backgrounds are the universal "AI made this" signal. Use gradients only when the theme calls for them, and keep them subtle and single-hue.
• Emoji as icons: ✨🚀💡 in headings or bullet points looks unprofessional. Use text or leave clean.
• Filler content: fabricated statistics ("10,000+ users"), fake quotes, or decorative metric cards with no real data. If data is missing, leave a placeholder and ask the user.
• Overuse of decoration: not every heading needs an icon, not every section needs a colored border accent. Give content room to breathe.
• Uniform slides: if every slide looks the same, the deck has no visual rhythm. Alternate between text-heavy and visual-heavy slides, vary background colors, and use section transitions to create pacing.

Prefer

• Theme colors only: stick to the chosen theme's palette. Do not invent new colors mid-deck.
• Action titles: h1 should be a takeaway sentence ("Revenue grew 23%"), not a topic label ("Revenue").
• Whitespace: an empty area is a design feature, not a problem to fill.
• One message per slide: if a slide has two distinct points, split it.
• Visual rhythm: mix text-heavy, image-heavy, and data-heavy slides. Use section transitions to signal topic shifts.
• Honest placeholders: a gray rectangle labeled "product image needed" is better than a random stock photo or a crude SVG drawing.