html-ppt

html-ppt — HTML 演示文稿工作室

将专业的 HTML 演示文稿编写为静态文件。一个主题文件 = 一种外观。一个布局文件 = 一种页面类型。一个动画类 = 一种进入效果。 所有页面共用 assets/base.css 中基于设计令牌的设计系统。

安装

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

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

此技能提供的内容

• 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——专用于演讲者模式）
• 31 种布局（templates/single-page/*.html），附带逼真的演示数据
• 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]，离开时清理
• 主题 / 布局 / 动画 / 完整演示文稿模板库展示
• 用于导出 PNG 的托管 Chromium 渲染脚本

适用场景

当用户需要任何类型的幻灯片内容，或想将文本 / 笔记转换成适合展示的演示文稿时使用。优先使用它，而不是从头构建。

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

如果用户提到以下任一内容：演讲 / 分享 / 讲稿 / 逐字稿 / 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>，会加载实际的演示文稿 HTML，并附带 ?preview=N 查询参数；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. 起点。 选择 14 种全套演示文稿模板之一，或从零开始？选择最接近的 templates/full-decks/<name>/。如果用户的内容明显适合某种模板（例如“我要做产品发布会”→ product-launch），就直接使用，不要贸然提问。

如果确实需要澄清，请遵循当前启用的 discovery-question-form 协议，并且只询问尚未明确的事项。例如，内容和受众已知，但用户要求的语气与不同主题不兼容时，只需询问主题，并推荐 2–3 个选项。不要把表单重复写成 Markdown 检查清单。

如果现有上下文已足以确定这些事项，就立即搭建演示文稿并开始撰写。

快速开始

1. 创建新演示文稿。 在仓库根目录中运行：

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

2. 选择主题。 打开演示文稿并按 T 循环切换主题。也可以硬编码：

   <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. 使用完整演示文稿模板。 将 templates/full-decks/<name>/ 复制到 examples/my-talk/，作为起点。每个文件夹都包含独立作用域的 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。
• 不要创建新的布局文件。 优先组合现有布局。只有在 30 种布局都不适用时，才添加新的 templates/single-page/*.html。
• 遵循页面框架槽位。 .deck-header、.deck-footer、.slide-number 和进度条由 assets/base.css + runtime.js 提供。
• 优先支持键盘操作。 始终包含 <script src="../assets/runtime.js"></script> ，以支持演示文稿使用 ← → / T / A / F / S / O / 哈希深链接。
• 每个逻辑页面对应一个 .slide。 runtime.js 会显示 .slide.is-active；其他页面均会隐藏。
• 提供备注。 在每张幻灯片中，将演讲者备注放在 <div class="notes">…</div> 内。按 S 打开浮层。
• 绝不要在幻灯片上放置仅供演讲者查看的文字。 诸如“这一页展示了……”或“Speaker: 这里可以补充……”这样的描述文字，或面向演讲者的小型说明文字，必须放在 <div class="notes"> 内，而不是作为幻灯片上可见的 <p> / <span> 元素。.notes 类默认设置为 display:none——只会在 S 浮层中显示。幻灯片应仅包含面向观众的内容（标题、项目符号、数据、图表、图片）。

写作指南

请参阅 references/authoring-guide.md，其中提供了分步说明：文件结构、命名、如何将大纲转换为演示文稿、如何根据受众选择布局和主题、如何制作中英双语演示文稿，以及如何导出。

目录（按需加载）

• references/themes.md — 全部 36 种主题及其适用场景。
• references/layouts.md — 全部 31 种布局类型。
• references/animations.md — 27 种 CSS 动画 + 20 种画布特效动画。
• 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)
│   ├── 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 31 layouts)
│   ├── animation-showcase.html    (20 FX + 27 CSS animation slides)
│   ├── full-decks-index.html      (gallery of all 14 full-deck templates)
│   ├── full-decks/<name>/         (14 scoped multi-slide deck templates)
│   └── single-page/*.html         (31 layout files with demo data)
├── scripts/
│   ├── new-deck.sh                (scaffold a deck from deck.html)
│   └── render.sh                  (managed Chromium → PNG)
└── examples/demo-deck/            (complete working deck)

渲染为 PNG

scripts/render.sh 使用 Playwright 管理的 Chromium 渲染器。不要直接调用用户安装的 Google Chrome 来导出 PNG，尤其是在 macOS 桌面构建环境中，Crashpad/配置文件权限可能会导致 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

Keyboard cheat sheet

←  →  Space  PgUp  PgDn  Home  End    navigate
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

License & author

MIT. Copyright (c) 2026 lewis <[email protected]>.