visual-deck — Visual PPT Generation

When to Trigger

Applicable Scenarios:

Evangelism decks, client-facing proposals, internal sharing PPTs where layout takes priority and content follows the imagery
Unified "image + text" style requiring background images with foreground text
High information density per slide while maintaining a clean visual appearance

Inapplicable Scenarios:

Pure data reports or text-heavy documents → Use docx/xlsx instead
Temporary one-off PPTs where building a pipeline isn't worth it → Use the pptx skill directly
Clients who don't accept cinematic style → The visual language of this skill doesn't match

Three Non-Negotiable Hard Constraints

These are lessons learned from past mistakes; any violation will result in immediate rejection:

1. Text Only in Safe Zones, Overflow Goes to Notes

Each slide has a natural image safe zone (darkened/blank area); foreground text must be placed only within this zone
When content doesn't fit: Never reduce font size, never revert to "full-screen mask over text". Pour overflow content into
```
slide.addNotes()
```
See
```
references/safe-zone-spec.md
```
for specific safe zone percentages

2. Image Prompts Must Follow V2 Four-Segment Format

All four segments

Description / Composition / Style / Do not include

must be complete

Safe zone percentages are hardcoded in the Composition segment (e.g., "top 15% / bottom 15% fade to void")
Colors are specified using both token and hex code (e.g., "warm coral, hex #FF6B47")
See
```
references/image-prompts-v2.md
```
for templates and examples

3. Nano Banana Has Aspect Ratio Limitations

Supported ratios: 16:9 / 4:3 / 1:1 / 3:4 / 9:16
21:9 is NOT supported — Use workarounds for ultra-wide needs (stitching / cropping / HF background + dark mask)
See
```
references/nano-banana-ratios.md
```
for details

Complete Pipeline

image-prompts.md                notes-map.js
       │                              │
       ▼  (Nano Banana)               ▼
  images/*.png                 溢出文案映射
       │                              │
       ▼  (tools/scrim-bake.js)       │
 images/*-scrimmed.png                │
       │                              │
       ▼  (CSS background)            │
   slides/*.html ──────────────► html2pptx.js ──► pptx
       │
       ▼ preview
   player.html  +  tools/check-overflow.js

File Roles:

File	Purpose	Editable?
`pipeline/html2pptx.js`	HTML→PPTX renderer, handles positioning/text/images/shapes/overflow detection	No
`templates/build.js`	Build entry point. Supports `--lint` (validation only, no pptx output) / `--strict` (stop on first error)	Yes (modify metadata: title/author/file name)
`templates/player.html`	Dependency-free HTML player with keyboard navigation, fullscreen, and thumbnails	Optional (fill TITLES for thumbnail display)
`templates/tools/scrim-bake.js`	Uses Sharp to bake scrim masks into background PNGs (HTML2PPTX doesn't recognize CSS gradients)	Yes (fill PAIRS array per project)
`templates/tools/check-overflow.js`	Uses Playwright to verify each slide ≤ 540px (preview level)	No
`templates/tools/fix-html-for-pptx.js`	Scans for `<p class="...">` with background/border and automatically wraps them in `<div><p>...</p></div>`	No
`templates/themes/*.css`	Theme tokens — `dark-coral.css` (default) / `dark-teal.css`	Yes (modify only this file to change themes)
`templates/layouts/*.html`	Layout skeleton library (see decision tree below)	Yes (copy and fill in content)
`templates/notes-map.js`	Overflow content mapping `{ slideNum: "notes..." }`	Yes (fill as needed)
`templates/package.json`	Dependencies (playwright / pptxgenjs / sharp)	No
`references/html2pptx-contract.md`	Required Reading · Valid HTML/CSS subset + common error fixes	No

Layout Decision Tree (Follow This When Choosing a Layout)

问 1：这页是章节边界 / 封面 / 封底吗？
  是 → slide-cover.html (HF)
  否 → 继续

问 2：这页只有一句金句（≤40 字），别的都稀释它？
  是 → slide-quote.html
  否 → 继续

问 3：这页是"数字说话"（KPI / 成绩单 / 市场数据）？
  是 → 只有一个核心数字？
        是 → slide-quote.html（把数字放大成金句）
        否（3~4 个并列数字）→ slide-stats.html
  否 → 继续

问 4：这页是"按时间/阶段讲流程"？
  是 → slide-timeline.html（3~5 个节点）
  否 → 继续

问 5：这页是"对比/并列"？
  是 → 几项？
        2 项 → slide-2col.html（before/after, A/B）
        3 项 → slide-3col.html（三段论）
        4+ → 拆页或 stats
  否 → 继续（下面是默认主力）

问 6：有一个核心视觉隐喻 + 2~4 条要点？
  是 → 前后页已连续 r34 两次？
        是 → slide-l34.html（换方向打破节奏）
        否 → slide-r34.html（默认）
  否 → 停下来想想这页要讲什么，版式够不够（不够再扩）

每次选完问自己：
  - 前后三页是否都是同一个版式？→ 考虑切镜像或换 layout
  - quote 页是否超过 3 页？→ 金句稀释了，降级成 r34

Layout Directory (8 Types):

Layout	Use Case	Key Signals
`slide-cover.html`	Full-screen HF, for covers/section dividers/back covers	Has background image + large title
`slide-quote.html`	Centered key quote	Single sentence, ≤40 characters
`slide-stats.html`	2×2 grid of numbers	3~4 parallel KPIs
`slide-timeline.html`	Horizontal timeline	3~5 stages/nodes
`slide-2col.html`	Two-column comparison	Binary comparison (A/B)
`slide-3col.html`	Three-column parallel	Three-part argument / three types of X
`slide-r34.html`	Right image + left text (main layout)	One argument + 2~4 bullet points
`slide-l34.html`	Left image + right text (mirror)	Same as r34, just reversed direction

Each layout file has

USE WHEN

DO NOT USE WHEN

comments at the top; open the file if you're unsure.

Extension Constraints (For Future Reference)

Must Answer These Before Adding New Layouts/Themes:

Why are existing layouts insufficient? Provide a specific slide scenario where they don't work.
What are the USE WHEN / DO NOT USE WHEN conditions for the new layout?
Will modifying the decision tree make layout selection "easier" rather than "more confusing"?

If you can't answer any of these three questions clearly, this layout shouldn't be added. Piling up layouts flatly will make it difficult for Claude to choose when using this skill; information structure ≫ number of options.

Same applies to new themes: Only add after explaining "why existing dark-coral / dark-teal are insufficient".

Standard Execution Process

Clarify Theme and Slide Count — First ask the user: theme color scheme (default dark CORAL), number of slides, whether covers/table of contents/back covers are needed
Read the Contract First —
```
references/html2pptx-contract.md
```
to understand the valid HTML/CSS subset and avoid pitfalls
Generate HTML Slides — Write HTML for each slide based on the
```
templates/layouts/
```
skeletons
Preview Validation — Use
```
templates/player.html
```
for navigation + run
```
node tools/check-overflow.js
```
to verify the 540px hard boundary
Generate Image Prompts — Follow the V2 four-segment format and output to
```
image-prompts.md
```
; users will run these in batches via Nano Banana
Collect Images + Bake Scrims — Place images in
```
images/
```
, configure the PAIRS array in
```
tools/scrim-bake.js
```
, then run
```
node tools/scrim-bake.js
```
to generate
```
*-scrimmed.png
```
Run Lint First —
```
node build.js --lint
```
to check all slides for contract violations in one go (no pptx output)
Fix Violations — Run
```
node tools/fix-html-for-pptx.js
```
for automated fixes (wrap
```
<p>
```
with bg in
```
<div><p>
```
); manually fix remaining issues
Fill notes-map.js — Put overflow content and supplementary speaking notes here
Generate PPTX — Run
```
node build.js
```

Key Pitfalls (Most Common for Claude)

HTML/CSS Contract Violations (See

references/html2pptx-contract.md

for details):

❌ Using CSS gradients on elements — Must bake into PNG via
```
tools/scrim-bake.js
```

❌ Writing

margin-*

on inline

<span>

— Use

padding-*

display: block

+ parent

<p>

❌

<p>

<h1-6>

<ul>

with

background

border*

box-shadow

— Wrap in

<div class="X"><p>...</p></div>

or run

tools/fix-html-for-pptx.js

for automated fix

❌ Directly placing text in
```
<div>
```
(mixed content) — Text must be wrapped in
```
<p>
```
or similar tags
❌
```
<p>
```
starting with
```
*
```
/
```
-
```
/
```
•
```
— Will be rejected as manual bullets
❌ Content placed within < 0.5" (36pt) of the slide bottom edge — Preview may pass, but build will fail. Use
```
--lint
```
for pre-check

Other Common Pitfalls:

❌ "Reduce font size to 10pt when content doesn't fit" — Violates Constraint 1; must use notes instead
❌ "This image needs to be 21:9 ultra-wide" — Not supported by Nano Banana; either crop to 16:9 HF or stitch images
❌ Missing "Do not include" segment in image prompts — Will result in text/logo/watermark contamination
❌ Incorrect HTML body size (not
```
720pt × 405pt
```
for 16:9) —
```
html2pptx.js
```
will throw a dimension mismatch error
❌ Hardcoding slide count in
```
build.js
```
— Use
```
fs.readdirSync('slides/')
```
for dynamic enumeration

Theme System

All colors/fonts/font sizes/padding are defined as CSS variables in

templates/themes/*.css

. Each slide HTML references the theme via

<link rel="stylesheet" href="../themes/<theme>.css">

at the top; internal

<style>

tags must only use

var(--xxx)

— never hardcode hex values.

Available Themes:

```
dark-coral.css
```
(default) — Warm color scheme, suitable for emotional/insight/humanistic tones
```
dark-teal.css
```
— Cool color scheme, suitable for technical/architectural/rational tones

Switch Themes: Modify the

<link>

path in all slide HTML files (or use project-level sed/find for one-click replacement if the entire deck uses the same theme).

Customize Themes: Only modify the

theme.css

file; all slides will update accordingly. The end of theme.css includes commented example variables for dark TEAL and light NAVY schemes.

Core Tokens:

```
--bg / --fg / --muted / --dim / --faint
```
— Background/body text/secondary text/weakest text/footer
```
--accent / --accent-2
```
— Primary/secondary accent colors

--font-sans

--fs-hero/title/subtitle/lede/body/label/source

— Font family and sizes

```
--pad-slide / --pad-r34 / --pad-l34
```
— Padding for three layout types

--scrim-base / --scrim-left / --scrim-heavy

— Scrim opacity levels

Quick Start

Check

examples/minimal/

— A 2-slide minimal working example. Copy the entire directory to a new project, run

npm install

, then

node build.js

to generate the pptx.

Recommended Modify One Slide, Validate Once Feedback Loop:

bash

node tools/check-overflow.js   # 1. 540px preview 硬边界
node build.js --lint           # 2. 契约完整校验（所有违规一次列齐）
node build.js                  # 3. 真正出 pptx

visual-deck

NPX Install

Tags

SKILL.md Content (Chinese)