html-ppt

html-ppt — HTML PPT Studio

以静态文件的形式制作专业的 HTML 演示文稿。一个主题文件 = 一种外观。一个布局文件 = 一种页面类型。一个动画类 = 一种入场效果。 所有页面都共享 assets/base.css 中基于令牌的设计系统。

安装

npx skills add https://github.com/lewislulu/html-ppt-skill

一条命令，无需构建。纯静态 HTML/CSS/JS，仅使用 CDN 网络字体。

目标机器无法联网？让 CLI 指向本地副本 （npx skills add ./html-ppt-skill），或者直接将此文件夹复制到 Agent 的 技能目录中——Claude Code 的目录为 ~/.claude/skills/html-ppt/。演示文稿可离线渲染；只有网络字体会回退到系统字体栈。请参阅 README.md。

此技能提供的内容

• 36 个主题（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
• 15 个完整演示文稿模板（templates/full-decks/<name>/）——带有作用域限定 .tpl-<name> CSS 的完整多页演示文稿。其中 8 个提取自真实演示文稿（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 个为场景脚手架（pitch-deck、product-launch、tech-sharing、weekly-report、xhs-post 3:4、course-module、presenter-mode-reveal——专用于演讲者模式）
• 36 种布局（templates/single-page/*.html），包含逼真的演示数据，其中包括 5 种真实图片布局（单图 / 满幅 / 图片+文字 / 图库 / 前后对比）
• 27 种 CSS 动画（assets/animations/animations.css），通过 data-anim 调用
• 20 种 Canvas FX 动画（assets/animations/fx/*.js），通过 data-fx 调用——particle-burst、confetti-cannon、firework、starfield、matrix-rain、knowledge-graph（力导向）、neural-net（脉冲）、constellation、orbit-ring、galaxy-swirl、word-cascade、letter-explode、chain-react、magnetic-field、data-stream、gradient-blob、sparkle-trail、shockwave、typewriter-multi、counter-explosion
• 键盘运行时（assets/runtime.js）——方向键、T（主题）、A（动画）、F/O、S（演讲者模式：磁吸卡片弹窗，含 CURRENT / NEXT / SCRIPT / TIMER 卡片）、N（备注抽屉）、R（重置演讲者模式中的计时器）
• 触控导航——在手机和平板上向左 / 向右滑动以切换幻灯片
• FX 运行时（assets/animations/fx-runtime.js）——进入幻灯片时自动初始化 [data-fx]，离开时清理
• 主题 / 布局 / 动画 / 完整演示文稿图库的展示演示文稿
• 无头 Chrome 渲染脚本，用于导出 PNG

适用场景

当用户需要任何类型的幻灯片输出，或想将文本 / 笔记转换成可用于展示的演示文稿时使用。与其从头构建，不如优先使用此技能。

🎤 演讲者模式（演讲者模式 + 逐字稿）

如果用户提到以下任一内容：演讲 / 分享 / 讲稿 / 逐字稿 / speaker notes / presenter view / 演讲者视图 / 提词器，或说出类似“我要去给团队讲 xxx”“要做一场技术分享”“怕讲不流畅”“想要一份带逐字稿的 PPT”的话，使用 presenter-mode-reveal 全套幻灯片模板，并在每张幻灯片的 <aside class="notes"> 中撰写 150–300 字的逐字稿。

完整的编写指南（包括撰写讲稿的 3 条规则）请参阅 references/presenter-mode.md：

1. 不是讲稿，是提示信号——加粗核心词 + 将过渡句独立成段
2. 每页 150–300 字——按每页 2–3 分钟的节奏
3. 用口语，不用书面语——将“因此”改为“所以”，将“该方案”改为“这个方案”

所有全套幻灯片模板都支持 S 键演讲者模式（此功能内置于 runtime.js）。按 S 键会打开一个新的弹出窗口，里面有 4 张磁吸卡片：

• 🔵 CURRENT（当前页）——当前幻灯片的像素级精确 iframe 预览
• 🟣 NEXT（下一页）——下一张幻灯片的像素级精确 iframe 预览
• 🟠 SPEAKER SCRIPT（演讲稿）——大字号逐字稿（可滚动）
• 🟢 TIMER（计时器）——已用时间 + 幻灯片计数器 + 上一页 / 下一页 / 重置按钮

每张卡片都可以拖动标题栏，并通过右下角的拖动手柄调整大小。卡片位置和大小会按每套幻灯片保存到 localStorage。点击“Reset layout（重置布局）”按钮可恢复默认排列。

预览为何像素级精确：每个预览都是一个 <iframe>，会通过 ?preview=N 查询参数加载实际的幻灯片 HTML；runtime.js 会检测该参数，并仅渲染第 N 张幻灯片，不显示浏览器界面。因此，预览与观众视图使用相同的 CSS、主题、字体和视口，颜色和布局保证完全一致。

流畅导航：切换幻灯片时，演讲者窗口会向每个 iframe 发送 postMessage({type:'preview-goto', idx:N})。iframe 只会在幻灯片之间切换 .is-active，无需重新加载，也不会闪烁。两个窗口还会通过 BroadcastChannel 保持同步。

只有 presenter-mode-reveal 是从设计之初就围绕此功能打造的，并且每张幻灯片都提供了合适的逐字稿示例。

演讲者窗口中的键盘操作：← → 导航（与观众视图同步） · R 重置计时器 · Esc 关闭弹出窗口。 观众窗口中的键盘操作：S 打开演讲者窗口 · T 切换主题 · ← → 导航（与演讲者窗口同步） · F 全屏 · O 概览。

开始撰写前——务必先询问或提出建议

**了解三件事之前，不要开始撰写幻灯片。**可以直接询问用户；如果用户已经提供了丰富的内容，则提出一个得体的默认方案并确认。

1. **内容与观众。**这套幻灯片的主题是什么、需要多少页、观众是谁（工程师 / 高管 / 小红书读者 / 学生 / VC）？
2. **风格 / 主题。**36 种主题中，哪种最合适？如果不确定，可以根据内容基调推荐 2–3 个候选项：
   • 商业 / 投资者推介 → pitch-deck-vc、corporate-clean、swiss-grid
   • 技术分享 / 工程 → tokyo-night、dracula、catppuccin-mocha、terminal-green、blueprint
   • 小红书图文 → xiaohongshu-white、soft-pastel、rainbow-gradient、magazine-bold
   • 学术 / 报告 → academic-paper、editorial-serif、minimal-white
   • 前卫 / 赛博 / 发布会 → cyberpunk-neon、vaporwave、y2k-chrome、neo-brutalism
3. **起点。**从 15 种全套幻灯片模板中选择一种，还是从头开始？指出最接近的 templates/full-decks/<name>/，并询问是否合适。如果用户的内容明显对应某个模板（例如“我要做产品发布会”→ product-launch），就自信地提出，而不是盲目询问。

一个合适的开场消息示例如下：

我可以给你做这份 PPT！先确认三件事：

1. 大致内容 / 页数 / 观众是谁？
2. 偏好什么风格？我建议从这 3 个主题里选一个：tokyo-night（技术分享的默认主题，效果不错）、xiaohongshu-white（小红书风）、corporate-clean（正式汇报）。
3. 要不要用我现成的 tech-sharing 全套幻灯片模板打底？

确认这些事项后，再搭建幻灯片并开始撰写。

快速开始

1. 搭建一个新演示文稿。 在仓库根目录中执行：

   ./scripts/new-deck.sh my-talk
   open examples/my-talk/index.html
   

2. 选择主题。 打开演示文稿并按 T 循环切换。也可以直接指定主题 （这里的 ../assets/ 是占位符——请使用文件中其他部分已采用的前缀；new-deck.sh 已将其设置为正确的路径深度）：

   <link rel="stylesheet" id="theme-link" href="../assets/themes/aurora.css">
   

   主题目录见 references/themes.md。
3. 选择布局。 将 templates/single-page/ 中的文件里的 <section class="slide">...</section> 区块复制到你的演示文稿中。替换示例数据。 布局目录见 references/layouts.md。
4. 添加动画。 在任意元素上添加 data-anim="fade-up"（或 class="anim-fade-up"）。对于 <ul>/网格，请使用 anim-stagger-list 实现依次显示。 对于画布特效，请使用 <div data-fx="knowledge-graph">...</div> 并引入 <script src="../assets/animations/fx-runtime.js"></script>。 动画目录见 references/animations.md。
5. 使用完整演示文稿模板。 从模板搭建，不要手动复制——模板中的 ../../../assets/ 是相对于模板自身位置的路径，因此手动复制会导致路径深度错误：

   ./scripts/new-deck.sh my-talk -t pitch-deck
   

   每个文件夹都自包含，并带有作用域限定的 CSS。模板目录见 references/full-decks.md，示例库见 templates/full-decks-index.html。
6. 渲染为 PNG。

   ./scripts/render.sh templates/theme-showcase.html       # one shot
   ./scripts/render.sh examples/my-talk/index.html 12      # 12 slides
   

编写规则（重要）

• 始终从模板开始。 不要从头编写幻灯片——先从 templates/single-page/ 复制最接近的布局，再替换内容。
• 使用设计令牌，不要使用字面颜色值。 所有颜色、圆角和阴影都应来自 assets/base.css 中定义、并由主题覆盖的 CSS 变量。 正确：color: var(--text-1)。错误：color: #111。 在 --accent 填充色上方的文字最容易出错：必须使用 color: var(--accent-ink)，因为这里的强调色范围从 #ffffff 到 #000000，没有任何一种固定的文字颜色能在所有强调色上都清晰可读。
• 不要自行创建新的布局文件。 优先组合现有布局。只有 36 种布局都不适用时，才添加新的 templates/single-page/*.html。
• 要在幻灯片上放置图片？ 请从五种 image-* 布局之一开始，并使用 .img-frame——参见下文的图片部分。绝不要将裸 <img> 直接放入幻灯片：没有边框的图片不会遵循幻灯片高度，会把其余内容挤出页面。
• 遵守预留区域约定。 .deck-header、.deck-footer、.slide-number 和进度条由 assets/base.css + runtime.js 提供。
• 以声明方式添加 Logo，只需一次。 在 <body> 上设置 data-logo——不要在每张幻灯片中粘贴 <img>。参见下文的自定义 Logo部分。
• 优先支持键盘操作。 始终引入运行时脚本，例如 <script src="../assets/runtime.js"></script>，这样演示文稿才能支持 ← → / T / A / F / S / O / 哈希深层链接。
• 绝不要手动修改资源路径中的 ../ 深度。 每个 assets/ 引用都相对于包含该引用的文件：templates/deck.html 使用 ../assets/，templates/single-page/*.html 使用 ../../assets/，而 templates/full-decks/*/index.html 使用 ../../../assets/。将文件复制到不同深度会导致所有路径悄然失效。请使用 ./scripts/new-deck.sh <name> [parent] [-t <template>] 搭建，它会根据演示文稿的位置计算前缀，并验证每个引用都能正确解析。
• 每个逻辑页面只使用一个 .slide。 runtime.js 会显示 .slide.is-active，并隐藏其他幻灯片。
• 提供备注。 在每张幻灯片中使用 <div class="notes">…</div> 包裹演讲者备注。按 S 打开叠加层。
• 绝不要在幻灯片本身放置仅供演讲者查看的文字。 “这一页展示了……”或“Speaker: 这里可以补充……”之类的描述性文字，或面向演讲者的简短说明，必须放入 <div class="notes">，不能作为可见的 <p> / <span> 元素放在幻灯片上。.notes 类默认设置为 display:none——只有在 S 叠加层中才会显示。幻灯片只能包含面向观众的内容（标题、项目符号、数据、图表、图片）。

图片

templates/single-page/ 中有 5 种布局会使用真实图片。请根据页面需要承载的图片数量选择：

我有……	使用	原因
一张截图 / 示意图 / 图表	image-single.html	.img-frame.contain — 添加黑边，不会裁剪
一张需要作为页面主视觉的照片	image-full-bleed.html	填满幻灯片，渐变遮罩让标题清晰易读
一张图片和一段论述	image-text-split.html	各占 50%；给 .split 添加 flip 可将图片移到右侧
3–6 张图片	image-gallery.html	统一网格；框架会规范化不同的图片比例
一张前后对比图	image-compare.html	两侧尺寸相同，下方各有结论

image-grid.html 和 image-hero.html 不在此列表中：它们是渐变占位布局，完全不含 <img>。如果想要 Bento 墙的布局样式，但不提供图片，请使用它们。

这 5 种布局都基于 assets/base.css 中的一个基本组件：

<figure class="img-frame"><img src="shot.png" alt=""></figure>
<figure class="img-frame contain" style="--img-ratio:4/3"><img src="diagram.svg" alt=""></figure>

• .img-frame 负责纵横比和裁剪；<img> 会通过 object-fit: cover 填满它。这样用户可以替换为任意形状的照片，布局也不会错乱。
• .img-frame.contain 会添加黑边，而不是裁剪图片 — 截图、示意图和徽标务必使用它。
• --img-ratio（默认为 16/10）和 --img-pos（object-position）可用于调整。
• .img-scrim / .img-cap / .img-tag 分别是遮罩、说明文字和角标。
• 幻灯片中引用的图片路径相对于该幻灯片自己的 index.html 解析 — 请将图片放在幻灯片文件夹内，例如 examples/my-talk/shot.png。
• assets/demo-images/ 存放这些布局使用的占位插图：手写 SVG，每张约 1 KB，无需联网。

自定义徽标

要为幻灯片添加公司 / 产品徽标，请在 <body> 上声明一次：

<body data-logo="logo.svg"
      data-logo-position="bottom-right"
      data-logo-size="40px">

属性	默认值	说明
data-logo	—	图片 URL，相对于幻灯片自己的 HTML 文件。必填。
data-logo-position	top-right	top-left / top-right / bottom-left / bottom-right
data-logo-size	44px	任意 CSS 长度；设置徽标的高度，宽度会按纵横比调整
data-logo-opacity	.9	完全显示时设为 1
data-logo-alt	""	替代文本

• 在单张幻灯片上隐藏徽标，使用 <section class="slide" data-no-logo> — 通常用于封面，以及带有自身品牌标识的全幅图片幻灯片。
• 微调内边距，在 .deck-logo 上设置 --logo-inset-x / --logo-inset-y。
• 如果想将徽标放在界面装饰区域内，或放在 4 种预设位置之外，也可以手动放置：

  <div class="deck">
    <img class="deck-logo" data-pos="bottom-left" src="logo.svg" alt="">
  

  此方式完全不需要 JS — base.css 会以相同方式为两者设置样式。
• 徽标会显示在演讲者预览中，也会显示在打印 / PDF 导出的每一页上（与打印时会隐藏的页眉 / 页脚 / 进度条装饰不同）。带有 data-no-logo 的幻灯片也会在此处跳过。逐页打印由 runtime.js + @media print 实现；不包含运行时脚本的幻灯片仍会在屏幕上显示徽标，但 PDF 中只会显示在一页上。

编写指南

请参阅 references/authoring-guide.md，了解分步指南：文件结构、命名方式、如何将大纲转化为幻灯片、如何根据受众选择布局和主题、如何制作中英双语幻灯片，以及如何导出。

目录（按需加载）

• references/themes.md — 全部 36 种主题及其适用场景。
• references/layouts.md — 全部 36 种布局类型。
• references/animations.md — 27 种 CSS + 20 种 canvas FX 动画。
• references/full-decks.md — 全部 15 种完整幻灯片模板。
• references/presenter-mode.md — 演讲者模式 + 逐字稿编写指南（技术分享/演讲必看）。
• references/authoring-guide.md — 完整工作流。

文件结构

html-ppt/
├── SKILL.md                 (this file)
├── references/              (detailed catalogs, load as needed)
├── assets/
│   ├── base.css             (tokens + primitives — do not edit per deck)
│   ├── demo-images/*.svg    (tiny offline placeholders for the image-* layouts)
│   ├── fonts.css            (webfont imports)
│   ├── runtime.js           (keyboard + presenter + overview + theme cycle)
│   ├── themes/*.css         (36 token overrides, one per theme)
│   └── animations/
│       ├── animations.css   (27 named CSS entry animations)
│       ├── fx-runtime.js    (auto-init [data-fx] on slide enter)
│       └── fx/*.js          (20 canvas FX modules: particles/graph/fireworks…)
├── templates/
│   ├── deck.html                  (minimal 6-slide starter)
│   ├── theme-showcase.html        (36 slides, iframe-isolated per theme)
│   ├── layout-showcase.html       (iframe tour of all 36 layouts)
│   ├── animation-showcase.html    (20 FX + 27 CSS animation slides)
│   ├── full-decks-index.html      (gallery of all 15 full-deck templates)
│   ├── full-decks/<name>/         (15 scoped multi-slide deck templates)
│   └── single-page/*.html         (36 layout files with demo data)
├── scripts/
│   ├── new-deck.sh                (scaffold a deck from deck.html)
│   └── render.sh                  (headless Chrome → PNG)
└── examples/demo-deck/            (complete working deck)

渲染为 PNG

scripts/render.sh 封装了位于 /Applications/Google Chrome.app/Contents/MacOS/Google Chrome 的无头 Chrome。对于多页幻灯片截图， runtime.js 提供 #/N 深层链接，render.sh 会遍历 1..N。

./scripts/render.sh templates/single-page/kpi-grid.html        # single page
./scripts/render.sh examples/demo-deck/index.html 8 out-dir    # 8 slides, custom dir

键盘快捷键速查表

←  →  Space  PgUp  PgDn  Home  End    navigate
swipe left / right (touch)              navigate — phones and tablets, no keyboard needed
F                                       fullscreen
S                                       open presenter window (magnetic cards: current/next/script/timer)
N                                       quick notes drawer (bottom overlay)
R                                       reset timer (in presenter window)
?preview=N                              URL param — force preview-only mode (single slide, no chrome)
O                                       slide overview grid
T                                       cycle themes (reads data-themes attr)
A                                       cycle demo animation on current slide
#/N in URL                              deep-link to slide N
Esc                                     close all overlays

许可证与作者

MIT。版权所有 (c) 2026 lewis <[email protected]>。