make-revealjs-presentation

制作 RevealJS 演示文稿

当用户想要基于 RevealJS 制作幻灯片，或想从仓库的标准模板开始准备新演讲时，请使用此技能。

默认做法

从随附的模板资源开始，而不是从头重建 RevealJS 外壳：

• 模板资源：./assets/index.html
• 将该文件复制到用户指定的输出路径，然后编辑复制的文件。
• 除非用户明确要求更改，否则保留 RevealJS CDN 引用和 Reveal.initialize(...) 代码块。

优先自定义的内容

复制模板后，先替换以下占位内容，再扩充幻灯片：

• Talk Title
• Conference Name · Month Year
• Your Name
• Role · Company · website.example
• filename.html 和 example.com/... 等示例链接

然后重写或删除示例幻灯片，使演示文稿符合用户的主题。

模板约定

• 模板刻意保持简洁，整体接近标准 RevealJS。
• 分隔幻灯片使用 class="heading-only"。
• 代码幻灯片只是包含 <pre><code> 块的普通区段。
• 如果使用代码徽标或复制按钮插件，且需要在某张幻灯片上禁用它，请为该区段添加 class="no-code-badge"。

自定义提示

正文字体

在模板顶部附近的 .reveal 规则中更改正文字体：

.reveal {
  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}

示例：

• 极简／系统默认：保留现有字体栈
• 无衬线网络字体：font-family: 'Work Sans', sans-serif;
• 衬线字体演示文稿：font-family: 'Source Serif 4', serif;

如果使用网络字体，还要在 <head> 中添加对应的 <link rel="stylesheet">。

标题字体

在以下位置单独更改标题字体：

.reveal h1,
.reveal h2,
.reveal h3 {
  font-family: inherit;
}

示例：

• 与正文一致：保留 inherit
• 标题风格鲜明：font-family: 'Roboto', sans-serif;
• 编辑风格：font-family: 'Fraunces', serif;

文字大小

在此处调整默认正文字号：

.reveal p,
.reveal li,
.reveal td,
.reveal th {
  font-size: 1em;
}

如果用户希望整体放大或缩小演示文稿，请增大或减小该 font-size。

代码块样式

全局代码块样式位于：

.reveal pre { ... }
.reveal pre code { ... }

调整这些规则，以使用更大的代码字体、不同的内边距，或更浅／更深的边框。

分隔幻灯片

分隔幻灯片的外观由 section.heading-only 和下划线规则控制：

.reveal section.heading-only h1::after,
.reveal section.heading-only h2::after,
.reveal section.heading-only h3::after { ... }

如果用户希望分隔幻灯片更接近普通的 RevealJS 标题，可移除该代码块。

颜色对比度

如果用户自定义颜色，请确保文字与背景的组合具有良好的可访问性对比度。

• 优先使用浅色背景搭配深色文字，或深色背景搭配浅色文字。
• 尤其注意正文、幻灯片编号、链接和代码块。
• 更改主题颜色、背景填充或标题样式后，重新检查对比度。

可访问性

创建或自定义演示文稿时，请保留可访问性基础要求。

• 确保文字与背景的对比度符合可访问性要求，尤其是在更改主题后。
• 确保链接文字清晰易懂。
• 确保有意义的图片包含替代文本。
• 检查问题时，应将插件生成的界面与幻灯片内容分开处理。RevealMenu 目前存在已知的可访问性问题：其生成的菜单触发器可能缺少可识别的无障碍名称。如果用户保留该插件，即使幻灯片内容本身没有问题，这仍可能被 axe 标记为违规。

axe-core 可访问性审查示例

如果用户在 VS Code 中要求进行可访问性审查，请在集成浏览器中打开演示文稿，并对渲染后的页面运行 axe-core。

Playwright 代码片段示例：

await page.addScriptTag({
  url: 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js'
});

const results = await page.evaluate(async () => {
  return await window.axe.run(document, {
    runOnly: {
      type: 'tag',
      values: ['wcag2a', 'wcag2aa']
    }
  });
});

报告结果时：

• 将实际的 violations 与 incomplete 检查分开。
• 指出每个实际问题对应的确切 HTML 或选择器。
• 区分演示文稿作者导致的问题与插件生成的问题。
• 如果 Reveal 的叠加层或变换导致 axe 无法确定对比度检查结果，请明确说明，而不要将其报告为已确认的失败。

编辑指南

• 优先使用普通章节、标题、列表、表格、图片和代码块，而非自定义布局系统。
• 除非用户要求更鲜明的视觉风格，否则不要添加额外的装饰性 CSS。
• 默认保持演示文稿为黑底白字，除非用户希望使用主题样式。

验证

创建或编辑演示文稿后：

1. 检查 HTML 文件是否存在诊断问题。
2. 在集成浏览器中打开。
3. 如果用户要求进行无障碍审查，请对渲染后的页面运行 axe 审计，并将实际违规项与无法确定的检查结果分开报告。