revealjs

Reveal.js 演示文稿

使用 reveal.js 创建 HTML 演示文稿。无需构建步骤，只需在浏览器中打开 HTML 即可。

创建内容

reveal.js 演示文稿由以下部分组成：

1. HTML 文件 - 包含幻灯片，并从 CDN 加载 reveal.js
2. CSS 文件 - 用于布局、颜色、字体排版和组件的自定义样式

设计原则

重要：创建任何演示文稿之前，都要先分析内容并选择合适的设计元素：

1. 考虑主题内容：这份演示文稿的主题是什么？它暗示了怎样的语气、行业或氛围？
2. 检查品牌元素：如果用户提到了公司或组织，请考虑其品牌颜色和形象
3. 使配色与内容相符：选择能体现主题内容的颜色
4. 说明设计思路：编写代码之前，先解释你的设计选择

要求：

• ✅ 编写代码之前，先说明基于内容制定的设计思路
• ✅ 使用适用于 Web 的字体（Arial、Helvetica、Georgia、Verdana 等），或通过 CSS 中的 @import 使用 Google Fonts
• ✅ 通过字号、字重和颜色构建清晰的视觉层次
• ✅ 确保易读性：对比度明显、字号合适、对齐整洁
• ✅ 保持一致：在各张幻灯片中重复使用相同的模式、间距和视觉语言
• ✅ 字体大小始终使用 pt（磅）——幻灯片尺寸固定，因此 pt 可预测且常见（类似 PowerPoint/Keynote）。字体大小不得使用 em、rem 或 px。

配色方案选择

创意地选择颜色：

• 不要局限于默认配色：哪些颜色真正适合这个特定主题？避免不假思索地套用默认配色。
• 从多个角度考虑：主题、行业、氛围、活力程度、目标受众、品牌形象（如有提及）
• 大胆尝试：尝试出人意料的组合——医疗保健演示文稿不一定要用绿色，金融演示文稿也不一定要用海军蓝
• 构建配色方案：选择 3-5 种相互协调的颜色（主色 + 辅助色调 + 点缀色）
• 确保对比度：文字必须在背景上清晰易读

配色方案示例（可从中汲取灵感——选择一种、调整后使用，或创建自己的方案）：

1. 经典蓝：深海军蓝（#1C2833）、板岩灰（#2E4053）、银色（#AAB7B8）、米白色（#F4F6F6）
2. 青绿色与珊瑚色：青绿色（#5EA8A7）、深青绿色（#277884）、珊瑚色（#FE4447）、白色（#FFFFFF）
3. 醒目红色：红色（#C0392B）、亮红色（#E74C3C）、橙色（#F39C12）、黄色（#F1C40F）、绿色（#2ECC71）
4. 暖腮红色调：灰紫色（#A49393）、腮红色（#EED6D3）、玫瑰色（#E8B4B8）、奶油色（#FAF7F2）
5. 酒红奢华风：酒红色（#5D1D2E）、深红色（#951233）、铁锈色（#C15937）、金色（#997929）
6. 深紫与翡翠绿：紫色（#B165FB）、深蓝色（#181B24）、翡翠绿（#40695B）、白色（#FFFFFF）
7. 奶油色与森林绿：奶油色（#FFE1C7）、森林绿（#40695B）、白色（#FCFCFC）
8. 粉色与紫色：粉色（#F8275B）、珊瑚色（#FF574A）、玫瑰色（#FF737D）、紫色（#3D2F68）
9. 青柠绿与李子色：青柠绿（#C5DE82）、李子色（#7C3A5F）、珊瑚色（#FD8C6E）、蓝灰色（#98ACB5）
10. 黑色与金色：金色（#BF9A4A）、黑色（#000000）、奶油色（#F4F6F6）
11. 鼠尾草绿与陶土色：鼠尾草绿（#87A96B）、陶土色（#E07A5F）、奶油色（#F4F1DE）、炭灰色（#2C2C2C）
12. 炭灰色与红色：炭灰色（#292929）、红色（#E33737）、浅灰色（#CCCBCB）
13. 活力橙色：橙色（#F96D00）、浅灰色（#F2F2F2）、炭灰色（#222831）
14. 森林绿：黑色（#191A19）、绿色（#4E9F3D）、深绿色（#1E5128）、白色（#FFFFFF）
15. 复古彩虹色：紫色（#722880）、粉色（#D72D51）、橙色（#EB5C18）、琥珀色（#F08800）、金色（#DEB600）
16. 复古大地色调：芥末黄（#E3B448）、鼠尾草绿（#CBD18F）、森林绿（#3A6B35）、奶油色（#F4F1DE）
17. 海岸玫瑰色调：旧玫瑰色（#AD7670）、河狸棕（#B49886）、蛋壳色（#F3ECDC）、灰绿色（#BFD5BE）
18. 橙色与绿松石色：浅橙色（#FC993E）、灰调绿松石色（#667C6F）、白色（#FCFCFC）

幻灯片内容原则

多样化呈现至关重要。 即使幻灯片的内容类型相似，也要变化视觉呈现方式：

• 在不同幻灯片中使用不同布局：一页使用分栏，另一页使用堆叠容器，第三页使用样式化卡片
• 混合使用容器样式：纯文本、自定义样式容器、引用块
• 运用视觉层次：使用 <strong> 突出关键术语，使用不同颜色区分类别
• 使用其他元素（引用、样式化容器、分栏）打散列表
• 不要在连续的幻灯片中重复相同的布局模式

确保内容易于浏览：

• 使用简短的项目符号，而非段落
• 尽可能让每张幻灯片只表达一个主要观点
• 使用图标（Font Awesome）增添视觉趣味

幻灯片内容较少时，应放大内容——不要留出空白，却只放很小的文字。

工作流

第 1 步：规划结构

根据用户的内容，确定：

• 需要多少张幻灯片
• 哪些幻灯片应作为章节分隔页（居中显示较大文字）
• 在哪里使用垂直幻灯片堆叠来呈现逐层深入的内容

第 2 步：生成脚手架

使用 create-presentation.js 脚本（位于与此 SKILL.md 文件同一目录下的 scripts/ 目录中）生成 HTML 脚手架。

node <path-to-skill>/scripts/create-presentation.js --structure 1,1,d,3,1,d,1 --title "My Presentation" --output presentation.html

查找脚本路径： 脚本位于相对于此 SKILL.md 文件的 scripts/create-presentation.js。常见位置：

• 项目技能：.claude/skills/revealjs/scripts/create-presentation.js
• 用户技能：~/.claude/skills/revealjs/scripts/create-presentation.js

选项：

• --slides N - 创建 N 张水平幻灯片（简单模式）
• --structure <list> - 混合布局，使用逗号分隔的值：
  • 1 = 单张水平幻灯片
  • N（N > 1）= N 张幻灯片组成的垂直堆叠
  • d = 章节分隔幻灯片（居中显示，无内容包装器）
• --output <file> - 输出文件名（默认：presentation.html）
• --title <text> - 演示文稿标题
• --styles <file> - 自定义 CSS 文件名（默认：styles.css）

示例：

# 10 horizontal slides
node <path-to-skill>/scripts/create-presentation.js --slides 10 --output presentation.html

# Mixed structure: intro, 2 content slides, divider, 3-slide vertical stack, divider, closing
node <path-to-skill>/scripts/create-presentation.js --structure 1,1,1,d,3,d,1 --title "Q4 Review" --output presentation.html

第 3 步：自定义 CSS

脚手架脚本会自动将 base-styles.css 复制到演示文稿目录，并命名为 styles.css。现在自定义 CSS 变量（尤其是颜色），以适配演示文稿主题。

使用 Google Fonts： 在 CSS 文件顶部添加 @import：

@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;600;700&family=Lato:wght@300;400;600&display=swap');

:root {
  --heading-font: "Playfair Display", Georgia, serif;
  --body-font: "Lato", Helvetica, sans-serif;
  /* ... */
}

基础文件包含：

1. CSS 变量，便于自定义：

:root {
  /* ===========================================
     BACKGROUND COLOR - Set this first!
     =========================================== */
  --background-color: #ffffff;  /* Change for dark themes (e.g., #1a1a2e) */

  /* Typography - ALWAYS use pt for font sizes */
  --heading-font: "Source Sans Pro", Helvetica, sans-serif;
  --body-font: "Source Sans Pro", Helvetica, sans-serif;
  --base-font-size: 32px;  /* Only px value - sets reveal.js base */
  --text-size: 16pt;       /* Base body text - intentionally small */
  --h1-size: 48pt;
  --h2-size: 36pt;
  --h3-size: 24pt;

  /* Colors - customize these for each presentation */
  --primary-color: #2196F3;
  --secondary-color: #ff9800;
  --text-color: #222;       /* Use light color (e.g., #FAF7F2) for dark backgrounds */
  --muted-color: #666;      /* Adjust for dark backgrounds too */
}

2. 使用 .reveal 前缀覆盖 reveal.js 样式：

.reveal {
  font-family: var(--body-font);
}

.reveal h1, .reveal h2, .reveal h3 {
  font-family: var(--heading-font);
  text-transform: none;
  color: var(--text-color);
}

.reveal p, .reveal li {
  font-size: var(--text-size);
  color: var(--text-color);
}

3. 幻灯片布局样式——控制内边距和定位：

.reveal .slides section {
  padding: 40px 60px;
  text-align: left;
}

4. 文字大小工具类（幻灯片内容较少时，用它们放大文字）：

/* Base text is 16pt - use these classes to increase size when needed */
.text-lg { font-size: 18pt; }    /* Slightly larger */
.text-xl { font-size: 20pt; }    /* Medium emphasis */
.text-2xl { font-size: 24pt; }   /* Strong emphasis */
.text-3xl { font-size: 28pt; }   /* Very large */
.text-4xl { font-size: 32pt; }   /* Maximum body text */
.text-muted { color: var(--muted-color); }
.text-center { text-align: center; }

排版指导：

• 基础文字大小（--text-size: 16pt）经过刻意设置，以便容纳更多内容
• 幻灯片内容较少时，使用 .text-lg、.text-xl 等类适当填充空间
• 这种方法既能避免内容较多的幻灯片溢出，又能让内容较少的幻灯片保持灵活

用于重复模式的自定义 CSS 类：

布局（网格、弹性容器）因幻灯片而异，因此使用内联样式。但如果某种视觉模式会出现在多张幻灯片中，应在 styles.css 中创建专用 CSS 类，而不是重复编写内联样式。这样可以让 HTML 更简洁，并确保样式一致。常见示例：统计框（数字 + 标签）、功能卡片（图标 + 标题 + 描述）、时间线／流程步骤、个人资料／简介卡片。如果某个元素重复出现 3 次或以上，就应该定义为类。

步骤 4：填写 HTML 内容

重要：请使用 Edit 工具逐步填写幻灯片——每次处理一张或几张幻灯片。不要使用 Write 工具重写整个 HTML 文件。脚手架会为每张幻灯片生成唯一的占位文本（例如，Slide 2 Title Here），因此可以使用 Edit 针对各个部分进行修改。与一次性生成整个文件相比，这种方式更节省 Token，也更不容易出错。

请遵循以下模式：

标准幻灯片结构：

<section id="unique-slide-id">
  <h2>Slide Title</h2>
  <div class="content">
    
  </div>
</section>

多列布局——始终使用内联 CSS 网格（不要创建 .grid-2 之类的实用类）：

<div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 30px;">
  <div>Column 1</div>
  <div>Column 2</div>
</div>


<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 25px;">
  <div>Column 1</div>
  <div>Column 2</div>
  <div>Column 3</div>
</div>


<div style="display: grid; grid-template-columns: 1fr 2fr; gap: 30px;">
  <div>Narrow sidebar</div>
  <div>Wide main content</div>
</div>

为什么网格要使用内联样式？每张幻灯片的布局需求都不同，例如列宽比例、间距等。内联样式让你可以灵活控制每张幻灯片，而无需创建大量实用类。

重要的 HTML 模式：

• 每个 <section> 都应有唯一的 id 属性，以便稳定识别
• 居中的章节标题幻灯片请使用 class="section-divider"
• 将主要内容放在 <div class="content"> 中，以保持间距一致。这是一个 flexbox 容器，会填充标题下方剩余的垂直空间，确保内容正确排列。
• 使用 <div class="footnote"> 在底部标注署名或来源
• 所有可见文本都必须放在文本元素中（<p>、<li> 或 <h1>–<h6>）。这些元素会继承 CSS 中的基础字号、颜色和行高。切勿将文本直接放在 <span> 或 <div> 中——它们不会应用基础样式，显示的字号也会不正确。仅将 <div> 用作布局容器（例如网格、flexbox 等），并在其中使用 <p> 元素放置实际文本。

步骤 5：检查内容溢出

运行溢出检查器，确保没有幻灯片内容超出边界：

node scripts/check-overflow.js presentation.html

脚本会检查每张幻灯片是否存在：

• 垂直溢出：内容高度超过幻灯片高度
• 水平溢出：内容宽度超过幻灯片宽度

如果检测到溢出，请缩减内容或调整受影响幻灯片的字号。

步骤 6：使用屏幕截图进行视觉检查

至关重要：必须检查每一张幻灯片的屏幕截图。 不要跳过任何幻灯片，也不要只检查部分样例。视觉问题很常见，只有逐张检查幻灯片才能发现。

截取所有幻灯片的屏幕截图：

cd <presentation-directory>
npx decktape reveal "presentation.html?export" output.pdf \
  --screenshots \
  --screenshots-directory "screenshots/$(date +%Y%m%d_%H%M%S)"

注意： ?export 查询参数会禁用图表动画，让 PDF 渲染效果更简洁。直接在浏览器中查看 HTML 时，图表仍会播放动画。

这会创建一个带时间戳的文件夹（例如，screenshots/20241210_143052/），方便你跟踪不同版本并比较修复前后的效果。

然后使用 Read 工具查看每张屏幕截图文件。

检查要点

溢出脚本可以捕获大多数布局问题，但以下问题需要通过视觉检查来发现：

1. 容器中的颜色继承：样式化容器中的文本可能会错误地继承父元素的颜色。如果页面背景较暗且文本颜色较浅，那么浅色容器中的文本将无法阅读，除非明确为该容器设置深色文本。

2. 自定义项目符号／列表样式：如果覆盖了默认列表样式，项目符号在某些容器背景上可能对比度不足。

3. 图标未渲染：如果 Font Awesome 加载失败，图标的位置会显示空白方块或什么都不显示。

4. 溢出的边缘情况：脚本可以捕获大多数溢出，但复杂的嵌套布局偶尔会漏检。

5. 意外的文本换行：原本预期能在一行内显示的文本实际换成了两行。这在分栏布局中尤其常见：某一列的标题可能会换行，而其他列不会，导致布局不均匀。

修复后重新截取特定幻灯片：

npx decktape reveal "presentation.html?export" output.pdf \
  --screenshots \
  --screenshots-directory "screenshots/$(date +%Y%m%d_%H%M%S)" \
  --slides 2,5,7-9

然后重新检查更新后的屏幕截图，确认问题已修复。新的带时间戳文件夹便于与之前的版本进行比较。

步骤 7：建议在浏览器中编辑

完成演示文稿后，告知用户可以使用随附的编辑器脚本直接在浏览器中编辑文本：

node <path-to-skill>/scripts/edit-html.js <presentation-directory>/presentation.html

这会在本地服务器中打开演示文稿，用户可以点击任意文本进行行内编辑，然后将更改保存回文件。此功能适用于润色措辞、修正拼写错误，或调整文案，无需编辑原始 HTML。

请务必在每份演示文稿的末尾提及此建议，例如：

如需进一步润色措辞，可以直接在浏览器中编辑文本：

node <resolved-path>/scripts/edit-html.js <presentation-directory>/presentation.html

点击任意文本进行编辑，按 Escape 取消选择，然后点击 Save。完成后按 Ctrl+C 停止服务器。

CSS 组件参考

引用块

.reveal blockquote {
  border-left: 4px solid var(--primary-color);
  padding-left: 20px;
  margin: 20px 0;
  font-style: italic;
  background: none;
  box-shadow: none;
  width: 100%;
}

.reveal blockquote cite {
  display: block;
  margin-top: 10px;
  font-style: normal;
  color: var(--muted-color);
}

图标（Font Awesome）

脚手架中已包含 Font Awesome。用法：

<i class="fa-solid fa-lightbulb"></i>
<i class="fa-solid fa-check"></i>
<i class="fa-solid fa-gears"></i>

高级功能

关于片段（渐进式显示）、演讲者备注、自定义背景、自动动画和过渡效果，请参阅 references/advanced-features.md。

Reveal.js 配置

Reveal.initialize({
  controls: true,          // Show navigation arrows
  progress: true,          // Show progress bar
  slideNumber: true,       // Show slide numbers
  hash: true,              // Update URL hash for each slide
  transition: 'slide',     // none/fade/slide/convex/concave/zoom
  center: false,           // Vertical centering of slide content
  autoSlide: 0,            // Auto-advance (ms), 0 to disable
  loop: false,             // Loop presentation
});

**关于 center 的说明：**默认值为 false（内容顶部对齐），最适合内容较多的幻灯片。对于希望内容垂直居中的简约或创意型演示文稿，可设为 true。

内置 Reveal.js 类

无需自定义 CSS，直接使用以下类：

• r-fit-text - 自动调整文本大小以填满幻灯片
• r-stretch - 拉伸元素以填满剩余的垂直空间
• r-stack - 将元素彼此叠放

<h1 class="r-fit-text">BIG TEXT</h1>
<img class="r-stretch" src="image.jpg">

添加图表

**重要：添加任何图表之前，必须先阅读 references/charts.md。**图表需要采用特定的 flexbox/grid 布局模式，才能正确调整大小并避免溢出。未完整阅读文档前，请勿尝试添加图表。

脚手架中包含 Chart.js 插件，可用于在幻灯片中添加条形图、折线图、饼图、圆环图和散点图。

必需模式——图表需要使用 flexbox 容器和 maintainAspectRatio: false：

<section style="display: flex; flex-direction: column; height: 100%;">
  <h2>Chart Title</h2>
  <div style="flex: 1; position: relative; min-height: 0;">
    <canvas data-chart="bar">
    
    </canvas>
  </div>
</section>

references/charts.md 涵盖以下内容（必读）：

• 布局模式：整张幻灯片、半幅（水平/垂直）、四分之一幅、不等比例拆分（1fr 2fr、1fr 3fr）
• 为什么必须采用 flexbox 模式（Chart.js 的宽高比行为）
• 所有图表类型（条形图、折线图、饼图、圆环图、散点图等）
• 样式和颜色选项
• CSV 数据格式（比 JSON 更简单的替代方案）

依赖项

脚本运行所需，应该已经安装：

• Node.js（用于运行脚本）
• Puppeteer（用于检查溢出）：npm install puppeteer
• Decktape（用于截图）：npx decktape（可直接运行）