| 1 | --- |
| 2 | name: html-ppt |
| 3 | description: HTML PPT Studio — author professional static HTML presentations in many styles, layouts, and animations, all driven by templates. Use when the user asks for a presentation, PPT, slides, keynote, deck, slideshow, "幻灯片", "演讲稿", "做一份 PPT", "做一份 slides", a reveal-style HTML deck, a 小红书 图文, or any kind of multi-slide pitch/report/sharing document that should look tasteful and be usable with keyboard navigation. Triggers include keywords like "presentation", "ppt", "slides", "deck", "keynote", "reveal", "slideshow", "幻灯片", "演讲稿", "分享稿", "小红书图文", "talk slides", "pitch deck", "tech sharing", "technical presentation". |
| 4 | --- |
| 5 | |
| 6 | # html-ppt — HTML PPT Studio |
| 7 | |
| 8 | Author professional HTML presentations as static files. One theme file = one |
| 9 | look. One layout file = one page type. One animation class = one entry effect. |
| 10 | All pages share a token-based design system in `assets/base.css`. |
| 11 | |
| 12 | ## Install |
| 13 | |
| 14 | ```bash |
| 15 | npx skills add https://github.com/lewislulu/html-ppt-skill |
| 16 | ``` |
| 17 | |
| 18 | One command, no build. Pure static HTML/CSS/JS with only CDN webfonts. |
| 19 | |
| 20 | No network on the target machine? Point the CLI at a local copy |
| 21 | (`npx skills add ./html-ppt-skill`), or just copy this folder into your agent's |
| 22 | skills directory — `~/.claude/skills/html-ppt/` for Claude Code. Decks render |
| 23 | offline; only the webfonts fall back to the system stack. See |
| 24 | [README.md](README.md#offline--manual-install). |
| 25 | |
| 26 | ## What the skill gives you |
| 27 | |
| 28 | - **36 themes** (`assets/themes/*.css`) — minimal-white, editorial-serif, soft-pastel, sharp-mono, arctic-cool, sunset-warm, catppuccin-latte/mocha, dracula, tokyo-night, nord, solarized-light, gruvbox-dark, rose-pine, neo-brutalism, glassmorphism, bauhaus, swiss-grid, terminal-green, xiaohongshu-white, rainbow-gradient, aurora, blueprint, memphis-pop, cyberpunk-neon, y2k-chrome, retro-tv, japanese-minimal, vaporwave, midcentury, corporate-clean, academic-paper, news-broadcast, pitch-deck-vc, magazine-bold, engineering-whiteprint |
| 29 | - **15 full-deck templates** (`templates/full-decks/<name>/`) — complete multi-slide decks with scoped `.tpl-<name>` CSS. 8 extracted from real-world decks (xhs-white-editorial, graphify-dark-graph, knowledge-arch-blueprint, hermes-cyber-terminal, obsidian-claude-gradient, testing-safety-alert, xhs-pastel-card, dir-key-nav-minimal), 7 scenario scaffolds (pitch-deck, product-launch, tech-sharing, weekly-report, xhs-post 3:4, course-module, **presenter-mode-reveal** — 演讲者模式专用) |
| 30 | - **36 layouts** (`templates/single-page/*.html`) with realistic demo data, including **5 real-image layouts** (single / full-bleed / image+text / gallery / before-after) |
| 31 | - **27 CSS animations** (`assets/animations/animations.css`) via `data-anim` |
| 32 | - **20 canvas FX animations** (`assets/animations/fx/*.js`) via `data-fx` — particle-burst, confetti-cannon, firework, starfield, matrix-rain, knowledge-graph (force-directed), neural-net (pulses), constellation, orbit-ring, galaxy-swirl, word-cascade, letter-explode, chain-react, magnetic-field, data-stream, gradient-blob, sparkle-trail, shockwave, typewriter-multi, counter-explosion |
| 33 | - **Keyboard runtime** (`assets/runtime.js`) — arrows, T (theme), A (anim), F/O, **S (presenter mode: magnetic-card popup with CURRENT / NEXT / SCRIPT / TIMER cards)**, N (notes drawer), R (reset timer in presenter) |
| 34 | - **Touch navigation** — swipe left/right to change slides on phones and tablets |
| 35 | - **FX runtime** (`assets/animations/fx-runtime.js`) — auto-inits `[data-fx]` on slide enter, cleans up on leave |
| 36 | - **Showcase decks** for themes / layouts / animations / full-decks gallery |
| 37 | - **Headless Chrome render script** for PNG export |
| 38 | |
| 39 | ## When to use |
| 40 | |
| 41 | Use when the user asks for any kind of slide-based output or wants to turn |
| 42 | text/notes into a presentable deck. Prefer this over building from scratch. |
| 43 | |
| 44 | ### 🎤 Presenter Mode (演讲者模式 + 逐字稿) |
| 45 | |
| 46 | If the user mentions any of: **演讲 / 分享 / 讲稿 / 逐字稿 / speaker notes / presenter view / 演讲者视图 / 提词器**, or says things like "我要去给团队讲 xxx", "要做一场技术分享", "怕讲不流畅", "想要一份带逐字稿的 PPT" — **use the `presenter-mode-reveal` full-deck template** and write 150–300 words of 逐字稿 in each slide's `<aside class="notes">`. |
| 47 | |
| 48 | See [references/presenter-mode.md](references/presenter-mode.md) for the full authoring guide including the 3 rules of speaker script writing: |
| 49 | 1. **不是讲稿，是提示信号** — 加粗核心词 + 过渡句独立成段 |
| 50 | 2. **每页 150–300 字** — 2–3 分钟/页的节奏 |
| 51 | 3. **用口语，不用书面语** — "因此"→"所以"，"该方案"→"这个方案" |
| 52 | |
| 53 | All full-deck templates support the S key presenter mode (it's built into `runtime.js`). **S opens a new popup window with 4 magnetic cards**: |
| 54 | - 🔵 **CURRENT** — pixel-perfect iframe preview of the current slide |
| 55 | - 🟣 **NEXT** — pixel-perfect iframe preview of the next slide |
| 56 | - 🟠 **SPEAKER SCRIPT** — large-font 逐字稿 (scrollable) |
| 57 | - 🟢 **TIMER** — elapsed time + slide counter + prev/next/reset buttons |
| 58 | |
| 59 | Each card is **draggable by its header** and **resizable by the bottom-right corner handle**. Card positions/sizes persist to `localStorage` per deck. A "Reset layout" button restores the default arrangement. |
| 60 | |
| 61 | **Why the previews are pixel-perfect**: each preview is an `<iframe>` that loads the actual deck HTML with a `?preview=N` query param; `runtime.js` detects this and renders only slide N with no chrome. So the preview uses the **same CSS, theme, fonts, and viewport as the audience view** — colors and layout are guaranteed identical. |
| 62 | |
| 63 | **Smooth navigation**: on slide change, the presenter window sends `postMessage({type:'preview-goto', idx:N})` to each iframe. The iframe just toggles `.is-active` between slides — **no reload, no flicker**. The two windows also stay in sync via `BroadcastChannel`. |
| 64 | |
| 65 | Only `presenter-mode-reveal` is designed from the ground up around the feature with proper example 逐字稿 on every slide. |
| 66 | |
| 67 | Keyboard in presenter window: `← →` navigate (syncs audience) · `R` reset timer · `Esc` close popup. |
| 68 | Keyboard in audience window: `S` open presenter · `T` cycle theme · `← →` navigate (syncs presenter) · `F` fullscreen · `O` overview. |
| 69 | |
| 70 | ## Before you author anything — ALWAYS ask or recommend |
| 71 | |
| 72 | **Do not start writing slides until you understand three things.** Either ask |
| 73 | the user directly, or — if they already handed you rich content — propose a |
| 74 | tasteful default and confirm. |
| 75 | |
| 76 | 1. **Content & audience.** What's the deck about, how many slides, who's |
| 77 | watching (engineers / execs / 小红书读者 / 学生 / VC)? |
| 78 | 2. **Style / theme.** Which of the 36 themes fits? If unsure, recommend 2-3 |
| 79 | candidates based on tone: |
| 80 | - Business / investor pitch → `pitch-deck-vc`, `corporate-clean`, `swiss-grid` |
| 81 | - Tech sharing / engineering → `tokyo-night`, `dracula`, `catppuccin-mocha`, |
| 82 | `terminal-green`, `blueprint` |
| 83 | - 小红书图文 → `xiaohongshu-white`, `soft-pastel`, `rainbow-gradient`, |
| 84 | `magazine-bold` |
| 85 | - Academic / report → `academic-paper`, `editorial-serif`, `minimal-white` |
| 86 | - Edgy / cyber / launch → `cyberpunk-neon`, `vaporwave`, `y2k-chrome`, |
| 87 | `neo-brutalism` |
| 88 | 3. **Starting point.** One of the 15 full-deck templates, or scratch? Point |
| 89 | to the closest `templates/full-decks/<name>/` and ask if it fits. If the |
| 90 | user's content suggests something obvious (e.g. "我要做产品发布会" → |
| 91 | `product-launch`), propose it confidently instead of asking blindly. |
| 92 | |
| 93 | A good opening message looks like: |
| 94 | |
| 95 | > 我可以给你做这份 PPT！先确认三件事： |
| 96 | > 1. 大致内容 / 页数 / 观众是谁？ |
| 97 | > 2. 风格偏好？我建议从这 3 个主题里选一个：`tokyo-night`（技术分享默认好看）、`xiaohongshu-white`（小红书风）、`corporate-clean`（正式汇报）。 |
| 98 | > 3. 要不要用我现成的 `tech-sharing` 全 deck 模板打底？ |
| 99 | |
| 100 | Only after those are clear, scaffold the deck and start writing. |
| 101 | |
| 102 | ## Quick start |
| 103 | |
| 104 | 1. **Scaffold a new deck.** From the repo root: |
| 105 | ```bash |
| 106 | ./scripts/new-deck.sh my-talk |
| 107 | open examples/my-talk/index.html |
| 108 | ``` |
| 109 | 2. **Pick a theme.** Open the deck and press `T` to cycle. Or hard-code it |
| 110 | (`../assets/` here is a placeholder — use whatever prefix the rest of the |
| 111 | file already uses; `new-deck.sh` has set it to the right depth): |
| 112 | ```html |
| 113 | <link rel="stylesheet" id="theme-link" href="../assets/themes/aurora.css"> |
| 114 | ``` |
| 115 | Catalog in [references/themes.md](references/themes.md). |
| 116 | 3. **Pick layouts.** Copy `<section class="slide">...</section>` blocks out of |
| 117 | files in `templates/single-page/` into your deck. Replace the demo data. |
| 118 | Catalog in [references/layouts.md](references/layouts.md). |
| 119 | 4. **Add animations.** Put `data-anim="fade-up"` (or `class="anim-fade-up"`) on |
| 120 | any element. On `<ul>`/grids, use `anim-stagger-list` for sequenced reveals. |
| 121 | For canvas FX, use `<div data-fx="knowledge-graph">...</div>` and include |
| 122 | `<script src="../assets/animations/fx-runtime.js"></script>`. |
| 123 | Catalog in [references/animations.md](references/animations.md). |
| 124 | 5. **Use a full-deck template.** Scaffold from it, don't copy it by hand — |
| 125 | the template's `../../../assets/` is relative to *its own* location, so a |
| 126 | manual copy lands the paths at the wrong depth: |
| 127 | ```bash |
| 128 | ./scripts/new-deck.sh my-talk -t pitch-deck |
| 129 | ``` |
| 130 | Each folder is self-contained with scoped CSS. Catalog in |
| 131 | [references/full-decks.md](references/full-decks.md) and gallery at |
| 132 | `templates/full-decks-index.html`. |
| 133 | 6. **Render to PNG.** |
| 134 | ```bash |
| 135 | ./scripts/render.sh templates/theme-showcase.html # one shot |
| 136 | ./scripts/render.sh examples/my-talk/index.html 12 # 12 slides |
| 137 | ``` |
| 138 | |
| 139 | ## Authoring rules (important) |
| 140 | |
| 141 | - **Always start from a template.** Don't author slides from scratch — copy the |
| 142 | closest layout from `templates/single-page/` first, then replace content. |
| 143 | - **Use tokens, not literal colors.** Every color, radius, shadow should come |
| 144 | from CSS variables defined in `assets/base.css` and overridden by a theme. |
| 145 | Good: `color: var(--text-1)`. Bad: `color: #111`. |
| 146 | Text on top of an `--accent` fill is the one people get wrong: it needs |
| 147 | `color: var(--accent-ink)`, because accents here run from `#ffffff` to |
| 148 | `#000000` and no literal ink is readable on all of them. |
| 149 | - **Don't invent new layout files.** Prefer composing existing ones. Only add |
| 150 | a new `templates/single-page/*.html` if none of the 36 fit. |
| 151 | - **Putting images on a slide?** Start from one of the five `image-*` layouts and |
| 152 | use `.img-frame` — see *Images* below. Never drop a bare `<img>` into a slide: |
| 153 | an unframed image ignores the slide's height and pushes the rest off the page. |
| 154 | - **Respect chrome slots.** `.deck-header`, `.deck-footer`, `.slide-number` |
| 155 | and the progress bar are provided by `assets/base.css` + `runtime.js`. |
| 156 | - **Add a logo declaratively, once.** Put `data-logo` on `<body>` — don't paste |
| 157 | an `<img>` into every slide. See *Custom logo* below. |
| 158 | - **Keyboard-first.** Always include the runtime, e.g. |
| 159 | `<script src="../assets/runtime.js"></script>`, so the deck supports |
| 160 | ← → / T / A / F / S / O / hash deep-links. |
| 161 | - **Never hand-edit the `../` depth in asset paths.** Every `assets/` reference |
| 162 | is relative to the file that holds it: `templates/deck.html` uses |
| 163 | `../assets/`, `templates/single-page/*.html` use `../../assets/`, and |
| 164 | `templates/full-decks/*/index.html` use `../../../assets/`. Copying a file to |
| 165 | a new depth silently breaks all of them. Scaffold with |
| 166 | `./scripts/new-deck.sh <name> [parent] [-t <template>]`, which computes the |
| 167 | prefix for wherever the deck lands and verifies every reference resolves. |
| 168 | - **One `.slide` per logical page.** `runtime.js` makes `.slide.is-active` |
| 169 | visible; all others are hidden. |
| 170 | - **Supply notes.** Wrap speaker notes in `<div class="notes">…</div>` inside |
| 171 | each slide. Press S to open the overlay. |
| 172 | - **NEVER put presenter-only text on the slide itself.** Descriptive text like |
| 173 | "这一页展示了……" or "Speaker: 这里可以补充……" or small explanatory captions |
| 174 | aimed at the presenter MUST go inside `<div class="notes">`, NOT as visible |
| 175 | `<p>` / `<span>` elements on the slide. The `.notes` class is `display:none` |
| 176 | by default — it only appears in the S overlay. Slides should contain ONLY |
| 177 | audience-facing content (titles, bullet points, data, charts, images). |
| 178 | |
| 179 | ## Images |
| 180 | |
| 181 | Five layouts in `templates/single-page/` take real images. Pick by how many |
| 182 | images the page has to carry: |
| 183 | |
| 184 | | I have… | Use | Why | |
| 185 | |---|---|---| |
| 186 | | one screenshot / diagram / chart | `image-single.html` | `.img-frame.contain` — letterboxed, **never cropped** | |
| 187 | | one photo that should carry the page | `image-full-bleed.html` | fills the slide, gradient scrim keeps the title readable | |
| 188 | | one image plus an argument | `image-text-split.html` | 50/50; add `flip` to `.split` to move the image right | |
| 189 | | 3–6 images | `image-gallery.html` | uniform grid; mixed source ratios are normalised by the frame | |
| 190 | | a before and an after | `image-compare.html` | both sides identical size, conclusion under each | |
| 191 | |
| 192 | `image-grid.html` and `image-hero.html` are **not** in this list: they are |
| 193 | gradient-placeholder layouts with no `<img>` at all. Reach for them when you |
| 194 | want the shape of a bento wall without supplying pictures. |
| 195 | |
| 196 | All five are built on one primitive from `assets/base.css`: |
| 197 | |
| 198 | ```html |
| 199 | <figure class="img-frame"><img src="shot.png" alt=""></figure> |
| 200 | <figure class="img-frame contain" style="--img-ratio:4/3"><img src="diagram.svg" alt=""></figure> |
| 201 | ``` |
| 202 | |
| 203 | - `.img-frame` owns the **aspect ratio and the crop**; the `<img>` fills it with |
| 204 | `object-fit: cover`. That's what lets a user swap in a photo of any shape |
| 205 | without the layout breaking. |
| 206 | - `.img-frame.contain` letterboxes instead of cropping — **always use it for |
| 207 | screenshots, diagrams and logos.** |
| 208 | - `--img-ratio` (default `16/10`) and `--img-pos` (`object-position`) tune it. |
| 209 | - `.img-scrim` / `.img-cap` / `.img-tag` are the scrim, caption and corner pill. |
| 210 | - Images referenced from a deck are resolved relative to the deck's own |
| 211 | `index.html` — keep them in the deck folder, e.g. `examples/my-talk/shot.png`. |
| 212 | - `assets/demo-images/` holds the placeholder artwork used by these layouts: |
| 213 | hand-written SVG, ~1 KB each, **no network needed**. |
| 214 | |
| 215 | ## Custom logo |
| 216 | |
| 217 | To brand a deck with a company / product logo, declare it once on `<body>`: |
| 218 | |
| 219 | ```html |
| 220 | <body data-logo="logo.svg" |
| 221 | data-logo-position="bottom-right" |
| 222 | data-logo-size="40px"> |
| 223 | ``` |
| 224 | |
| 225 | | Attribute | Default | Notes | |
| 226 | |---|---|---| |
| 227 | | `data-logo` | — | Image URL, relative to the deck's own HTML file. Required. | |
| 228 | | `data-logo-position` | `top-right` | `top-left` / `top-right` / `bottom-left` / `bottom-right` | |
| 229 | | `data-logo-size` | `44px` | Any CSS length; sets the logo's **height**, width follows the aspect ratio | |
| 230 | | `data-logo-opacity` | `.9` | `1` for full strength | |
| 231 | | `data-logo-alt` | `""` | Alt text | |
| 232 | |
| 233 | - **Skip it on one slide** with `<section class="slide" data-no-logo>` — usually |
| 234 | the cover and any full-bleed image slide that carries its own branding. |
| 235 | - **Fine-tune the inset** with `--logo-inset-x` / `--logo-inset-y` on `.deck-logo`. |
| 236 | - **Place it by hand** instead, if you want it inside the chrome slots or in a |
| 237 | spot the four presets don't cover: |
| 238 | ```html |
| 239 | <div class="deck"> |
| 240 | <img class="deck-logo" data-pos="bottom-left" src="logo.svg" alt=""> |
| 241 | ``` |
| 242 | This path needs no JS at all — `base.css` styles both the same way. |
| 243 | - The logo shows in the **presenter preview**, and on **every page of a |
| 244 | print/PDF export** (unlike the header/footer/progress chrome, which print |
| 245 | hides). `data-no-logo` slides are skipped there too. Per-page printing is |
| 246 | painted by `runtime.js` + `@media print`; a deck that omits the runtime still |
| 247 | gets the logo on screen, but only on one page of a PDF. |
| 248 | |
| 249 | ## Writing guide |
| 250 | |
| 251 | See [references/authoring-guide.md](references/authoring-guide.md) for a |
| 252 | step-by-step walkthrough: file structure, naming, how to transform an outline |
| 253 | into a deck, how to choose layouts and themes per audience, how to do a |
| 254 | Chinese + English deck, and how to export. |
| 255 | |
| 256 | ## Catalogs (load when needed) |
| 257 | |
| 258 | - [references/themes.md](references/themes.md) — all 36 themes with when-to-use. |
| 259 | - [references/layouts.md](references/layouts.md) — all 36 layout types. |
| 260 | - [references/animations.md](references/animations.md) — 27 CSS + 20 canvas FX animations. |
| 261 | - [references/full-decks.md](references/full-decks.md) — all 15 full-deck templates. |
| 262 | - [references/presenter-mode.md](references/presenter-mode.md) — **演讲者模式 + 逐字稿编写指南（技术分享/演讲必看）**. |
| 263 | - [references/authoring-guide.md](references/authoring-guide.md) — full workflow. |
| 264 | |
| 265 | ## File structure |
| 266 | |
| 267 | ``` |
| 268 | html-ppt/ |
| 269 | ├── SKILL.md (this file) |
| 270 | ├── references/ (detailed catalogs, load as needed) |
| 271 | ├── assets/ |
| 272 | │ ├── base.css (tokens + primitives — do not edit per deck) |
| 273 | │ ├── demo-images/*.svg (tiny offline placeholders for the image-* layouts) |
| 274 | │ ├── fonts.css (webfont imports) |
| 275 | │ ├── runtime.js (keyboard + presenter + overview + theme cycle) |
| 276 | │ ├── themes/*.css (36 token overrides, one per theme) |
| 277 | │ └── animations/ |
| 278 | │ ├── animations.css (27 named CSS entry animations) |
| 279 | │ ├── fx-runtime.js (auto-init [data-fx] on slide enter) |
| 280 | │ └── fx/*.js (20 canvas FX modules: particles/graph/fireworks…) |
| 281 | ├── templates/ |
| 282 | │ ├── deck.html (minimal 6-slide starter) |
| 283 | │ ├── theme-showcase.html (36 slides, iframe-isolated per theme) |
| 284 | │ ├── layout-showcase.html (iframe tour of all 36 layouts) |
| 285 | │ ├── animation-showcase.html (20 FX + 27 CSS animation slides) |
| 286 | │ ├── full-decks-index.html (gallery of all 15 full-deck templates) |
| 287 | │ ├── full-decks/<name>/ (15 scoped multi-slide deck templates) |
| 288 | │ └── single-page/*.html (36 layout files with demo data) |
| 289 | ├── scripts/ |
| 290 | │ ├── new-deck.sh (scaffold a deck from deck.html) |
| 291 | │ └── render.sh (headless Chrome → PNG) |
| 292 | └── examples/demo-deck/ (complete working deck) |
| 293 | ``` |
| 294 | |
| 295 | ## Rendering to PNG |
| 296 | |
| 297 | `scripts/render.sh` wraps headless Chrome at |
| 298 | `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`. For multi-slide |
| 299 | capture, runtime.js exposes `#/N` deep-links, and render.sh iterates 1..N. |
| 300 | |
| 301 | ```bash |
| 302 | ./scripts/render.sh templates/single-page/kpi-grid.html # single page |
| 303 | ./scripts/render.sh examples/demo-deck/index.html 8 out-dir # 8 slides, custom dir |
| 304 | ``` |
| 305 | |
| 306 | ## Keyboard cheat sheet |
| 307 | |
| 308 | ``` |
| 309 | ← → Space PgUp PgDn Home End navigate |
| 310 | swipe left / right (touch) navigate — phones and tablets, no keyboard needed |
| 311 | F fullscreen |
| 312 | S open presenter window (magnetic cards: current/next/script/timer) |
| 313 | N quick notes drawer (bottom overlay) |
| 314 | R reset timer (in presenter window) |
| 315 | ?preview=N URL param — force preview-only mode (single slide, no chrome) |
| 316 | O slide overview grid |
| 317 | T cycle themes (reads data-themes attr) |
| 318 | A cycle demo animation on current slide |
| 319 | #/N in URL deep-link to slide N |
| 320 | Esc close all overlays |
| 321 | ``` |
| 322 | |
| 323 | ## License & author |
| 324 | |
| 325 | MIT. Copyright (c) 2026 lewis <sudolewis@gmail.com>. |
| 326 |