slides-to-pptx

幻灯片转 PPTX

创建零依赖、动画丰富的 HTML 演示文稿，完全在浏览器中运行，并可选择通过 PptxGenJS 导出 PPTX。

核心原则

1. 零依赖 — 使用内联 CSS/JS 的单个 HTML 文件。无需 npm，也无需构建工具。
2. 展示，而非空谈 — 生成可视化预览，而不是抽象选项。人们通过亲眼所见来发现自己想要什么。
3. 独特设计 — 不要千篇一律的“AI 垃圾”。每份演示文稿都必须有量身打造的感觉。
4. 适配视口（不可妥协） — 每张幻灯片都必须恰好适配 100vh。幻灯片内绝不允许滚动。内容放不下？拆分成多张幻灯片。
5. 逐步执行 — 必须严格按步骤执行此工作流。绝不跳到下一阶段。每次提问后都必须停下来等待用户输入。

设计美学

你往往会趋向千篇一律、“符合分布”的输出。在前端设计中，这会形成用户所说的“AI 垃圾”风格。请避免这种情况，打造富有创意、独具特色、令人惊喜的前端设计。

请重点关注：

• 排版：选择美观、独特且有趣的字体。避免使用 Arial 和 Inter 等通用字体；应选择能提升前端美感的特色字体。
• 色彩与主题：保持统一的美学风格。使用 CSS 变量确保一致性。鲜明的主色搭配醒目的强调色，胜过谨慎且平均分配的配色方案。可从 IDE 主题和文化美学中汲取灵感。
• 动效：使用动画实现效果和微交互。对于 HTML，优先使用纯 CSS 方案。对于 React，在可用时使用 Motion 库。聚焦于高影响力的时刻：一次精心编排、带有交错呈现效果（animation-delay）的页面加载，比零散的微交互更能带来惊喜。
• 背景：营造氛围与层次感，不要默认使用纯色。叠加 CSS 渐变、使用几何图案，或添加与整体美学相符的情境效果。

避免常见的 AI 生成审美：

• 过度使用的字体系列（Inter、Roboto、Arial、系统字体）
• 老套的配色方案（尤其是白色背景上的紫色渐变）
• 可预测的布局和组件模式
• 缺少情境特色、千篇一律的设计

发挥创意，做出意想不到、真正契合情境的设计。在浅色与深色主题、不同字体和不同美学风格之间灵活切换。不过，你仍然容易在不同生成结果中趋向常见选择（例如 Space Grotesk）。请避免这种情况：跳出固有思维至关重要！

视口适配规则

以下不变量适用于每份演示文稿中的每张幻灯片：

• 每个 .slide 都必须设置 height: 100vh; height: 100dvh; overflow: hidden;
• 所有字号和间距都必须使用 clamp(min, preferred, max)，绝不能使用固定的 px/rem
• 内容容器需要设置 max-height 限制
• 图片：max-height: min(50vh, 400px)
• 必须针对 700px、600px、500px 高度设置断点
• 必须支持 prefers-reduced-motion
• 绝不要直接对 CSS 函数取反（-clamp()、-min()、-max() 会被静默忽略）——应改用 calc(-1 * clamp(...))

生成时，读取 viewport-base.css，并在每份演示文稿中包含其完整内容。

每张幻灯片的内容密度限制

幻灯片类型	内容上限
标题页	1 个标题 + 1 个副标题 + 可选的标语
内容页	1 个标题 + 4-6 个项目符号，或 1 个标题 + 2 个段落
功能网格	1 个标题 + 最多 6 张卡片（2x3 或 3x2）
代码页	1 个标题 + 8-10 行代码
引用页	1 条引用（最多 3 行）+ 署名
图片页	1 个标题 + 1 张图片（高度最多为 60vh）

内容超出限制？拆分成多张幻灯片。绝不硬塞，也绝不滚动。

阶段 0：检测模式

确定用户的需求：

• 模式 A：新建演示文稿 — 从头开始创建。转到阶段 1。
• 模式 B：PPT 转换 — 转换 .pptx 文件。转到阶段 4。
• 模式 C：优化 — 改进现有 HTML 演示文稿。读取并理解内容，然后进行优化。遵循下方的模式 C 修改规则。

模式 C：修改规则

优化现有演示文稿时，视口适配是最大的风险：

1. 添加内容之前： 统计现有元素，并检查是否符合密度限制
2. 添加图片： 必须设置 max-height: min(50vh, 400px)。如果幻灯片已有最多的内容，就拆分成两张幻灯片
3. 添加文本： 每张幻灯片最多 4-6 个项目符号。超出限制？拆分成续页
4. 任何修改之后，都要验证： .slide 具有 overflow: hidden，新元素使用 clamp()，图片设置了相对于视口的最大高度，且内容在 1280x720 下完整显示
5. 主动重新组织： 如果修改会导致内容溢出，就自动拆分内容并告知用户。不要等用户提出要求

向现有幻灯片添加图片时： 先将图片移至新幻灯片，或减少其他内容。添加图片前，务必检查现有内容是否已占满视口。

---

阶段 1：内容收集（新建演示文稿）

根据用户的消息和内容检测语言，并在整个工作流程中使用同一种语言回复。

在一次交互中提出所有问题，让用户一次性填写完毕：

问题 1 — 用途（标题：“用途”）： 这份演示文稿的用途是什么？选项：推介演示文稿 / 教学教程 / 会议演讲 / 内部演示

问题 2 — 时长（标题：“时长”）： 大约需要多少张幻灯片？选项：短篇 5-10 张 / 中篇 10-20 张 / 长篇 20 张以上

问题 3 — 内容（标题：“内容”）： 你准备好内容了吗？选项：所有内容都已准备好 / 粗略笔记 / 只有主题

问题 4 — 内联编辑（标题：“编辑”）： 生成后，你需要直接在浏览器中编辑文本吗？选项：

• “是（推荐）” — 可在浏览器中编辑文本，自动保存到 localStorage，并导出文件
• “否” — 仅生成演示文稿，文件更小

记住用户选择的编辑选项——这决定了阶段 3 是否包含编辑相关代码。

如果用户已有内容，请让他们分享。

🛑 关键：在此处停止并等待。必须等待用户回答上述问题。用户回复之前，不要继续阶段 2 或阶段 3。

步骤 1.2：图片评估（如果提供了图片）

如果用户选择“无图片” → 跳到阶段 2。

如果用户提供了图片文件夹：

1. 扫描 — 列出所有图片文件（.png、.jpg、.svg、.webp 等）
2. 查看每张图片 — 使用 Read 工具（Claude 支持多模态）
3. 评估 — 对每张图片说明：展示内容、是否可用及原因、代表的概念、主色调
4. 共同设计大纲 — 精选图片应与文本一同决定幻灯片结构。这不是“先规划幻灯片，再添加图片”，而是从一开始就围绕两者共同设计（例如：3 张截图 → 3 张功能介绍幻灯片，1 个徽标 → 标题页/结束页）
5. 确认（标题：“大纲”）：“这份幻灯片大纲和图片选择合适吗？”选项：看起来不错 / 调整图片 / 调整大纲

🛑 关键：在生成演示文稿之前，停止并等待用户确认大纲。

预览中的徽标： 如果确认有可用的徽标，请在阶段 2 的每种样式预览中嵌入它（base64），让用户看到品牌以三种不同风格呈现。

---

阶段 2：样式探索

这是“展示，而非描述”的阶段。 大多数人无法用语言清楚表达自己的设计偏好。

第 2.0 步：选择风格路径

询问用户想如何选择（标题：“风格”）：

• “向我展示选项”（推荐）——根据氛围生成 3 个预览
• “我知道自己想要什么”——直接从预设列表中选择

如果直接选择： 显示预设选择器，然后跳到第 3 阶段。可用预设定义在 STYLE_PRESETS.md 中。

🛑 重要：在此暂停并等待用户选择风格路径。不要模拟用户的选择。

第 2.1 步：选择氛围（引导探索）

询问（标题：“氛围”，可多选，最多 2 项）： 希望观众有什么感受？选项：

• 印象深刻／充满信心——专业、可信赖
• 兴奋／精力充沛——创新、大胆
• 平静／专注——清晰、周到
• 深受启发／感动——富有情感、令人难忘

🛑 重要：在此暂停并等待用户选择氛围。在用户回复前，不要继续生成预览。

第 2.2 步：生成 3 个风格预览

根据氛围生成 3 个不同的单页 HTML 预览，展示字体排版、颜色、动画和整体美感。阅读 STYLE_PRESETS.md，了解可用预设及其规格。

氛围	推荐预设
印象深刻／充满信心	Bold Signal、Electric Studio、Dark Botanical
兴奋／精力充沛	Creative Voltage、Neon Cyber、Split Pastel
平静／专注	Notebook Tabs、Paper & Ink、Swiss Modern
深受启发／感动	Dark Botanical、Vintage Editorial、Pastel Geometry

将预览保存到 .claude-design/slide-previews/（style-a.html、style-b.html、style-c.html）。每个文件应自包含，约 50-100 行，并展示一张带动画的标题幻灯片。

自动为用户打开每个预览。

第 2.3 步：用户选择

询问（标题：“风格”）： 你更喜欢哪个风格预览？选项：风格 A：[名称]／风格 B：[名称]／风格 C：[名称]／混合元素

如果用户选择“混合元素”，询问具体要求。

🛑 重要：在此暂停并等待用户选择偏好的风格。在用户明确作出选择前，不要继续进入第 3 阶段。

---

第 3 阶段：生成演示文稿

使用第 1 阶段的内容（文本，或文本 + 精选图片）和第 2 阶段的风格生成完整演示文稿。

如果用户提供了图片，幻灯片大纲已在第 1.2 步中纳入这些图片。如果没有图片，CSS 生成的视觉效果（渐变、形状、图案）也能营造视觉吸引力——这是完全支持的首选方案。

生成前，请阅读以下支持文件：

• html-template.md——HTML 架构和 JS 功能
• viewport-base.css——必需的 CSS（完整包含）
• animation-patterns.md——所选氛围的动画参考

关键要求：

• 使用单个自包含 HTML 文件，所有 CSS/JS 均内联
• 在 <style> 块中包含 viewport-base.css 的全部内容
• 使用来自 Fontshare 或 Google Fonts 的字体，绝不使用系统字体
• 添加详细注释，说明各个部分
• 每个部分都需要清晰的 /* === SECTION NAME === */ 注释块
• 根据内容语言设置 <html lang="...">（例如，中文用 zh-CN，英语用 en，日语用 ja）

---

第 4 阶段：转换 PPT

转换 PowerPoint 文件时：

1. 提取内容——运行 python scripts/extract-pptx.py <input.pptx> <output_dir>（如有需要，安装 python-pptx：pip install python-pptx）
2. 与用户确认——展示提取出的幻灯片标题、内容摘要和图片数量
3. 选择风格——进入第 2 阶段进行风格探索
4. 生成 HTML——转换为所选风格，并保留所有文本、图片（来自 assets/）、幻灯片顺序和演讲者备注（作为 HTML 注释）

🛑 重要：生成 HTML 后，暂停并等待用户反馈，然后再自动继续导出 PPTX。

阶段 5：导出 PPTX

生成 HTML 演示文稿后，询问用户是否要导出为 PPTX。如果要，请询问：

问题：导出格式 您想要可编辑的原生 PPTX，还是高保真截图 PPTX？选项：

• “原生文本/形状”（文件较小，文本可编辑，但字体/布局可能与 HTML 略有不同）
• “截图”（文件较大，文本不可编辑，但能 100% 保留原始 HTML 设计和字体）

根据用户的选择，遵循下方相应章节。

选项 A：原生 PPTX（通过 PptxGenJS）

依赖项

npm install pptxgenjs

PPTX 生成规则

生成前，请阅读以下辅助文件：

• html2pptx.md — HTML 转 PPTX 的详细指南
• ooxml.md — OOXML 技术参考
• generate-pptx.js — 参考实现

基本结构

const PptxGenJS = require('pptxgenjs');

// Create presentation
const pptx = new PptxGenJS();


// Metadata
pptx.author = 'Author Name';
pptx.title = 'Presentation Title';

// Layout (16:9)
pptx.defineLayout({ name: 'CUSTOM', width: 13.33, height: 7.5 });
pptx.layout = 'CUSTOM';

重要说明

1. 颜色代码 — 在 PptxGenJS 中不要加 # 前缀：

// ✅ Correct
{ color: '10B981' }
{ fill: 'F9FAFB' }

// ❌ Wrong (may corrupt file)
{ color: '#10B981' }
{ fill: '#F9FAFB' }

2. 字体 — 应与内容语言匹配：

// Chinese
{ fontFace: 'Noto Sans SC' }
// English
{ fontFace: 'Arial' }
// Japanese
{ fontFace: 'Noto Sans JP' }

3. 换行 — 使用 \n：

slide.addText('第一行\n第二行', { ... });

4. Emoji — 在某些环境中可能无法显示。重要信息请使用文本作为备用。

文件保存

pptx.writeFile({ fileName: 'output/presentation.pptx' })
  .then(fileName => console.log(`Created: ${fileName}`));

调色板

使用阶段 2 中所选样式的颜色。 下表仅供备用参考：

用途	颜色代码	描述
主要	2563EB	主强调色
成功	10B981	正面/完成
警告	F59E0B	注意/偏好
危险	EF4444	负面/未满足
中性	6B7280	次要文本
背景	F9FAFB	背景
主要文本	111827	主文本
次要文本	6B7280	次要文本
边框	E5E7EB	边框/分隔线

重要： 始终根据 HTML 演示文稿的样式确定 PPTX 颜色。如果已选择特定样式，不要默认使用上述调色板。

选项 B：截图 PPTX（通过 Playwright）

如果用户想要像素级精确的截图演示文稿：

依赖项

npm install playwright pptxgenjs

截图生成规则

1. 编写 Node.js 脚本，使用 playwright 启动无头浏览器。
2. 脚本应打开生成的 HTML 文件。
3. 必须等待初始动画结束（例如，await page.waitForTimeout(2000)）。
4. 遍历所有幻灯片（可调用演示文稿的导航 JS，例如 await page.evaluate(() => app.goToSlide(i))，或模拟键盘事件，例如 await page.keyboard.press('ArrowDown')）。
5. 导航到每张幻灯片后，等待过渡/显示动画完成再进行截取（await page.waitForTimeout(1500)）。
6. 截取视口截图（const buffer = await page.screenshot()）。
7. 使用 pptxgenjs 创建新的演示文稿，每张截图添加一张幻灯片，并将截图设为幻灯片背景或全尺寸图像。
8. 保存 .pptx 文件。

---

阶段 6：交付

1. 清理 — 如果 .claude-design/slide-previews/ 存在，则将其删除
2. 打开 — 使用 open [filename].html 在浏览器中打开
3. 总结 — 告知用户：
   • 文件位置、样式名称、幻灯片数量
   • 导航方式：方向键、空格键、滚动/滑动、点击导航圆点
   • 自定义方法：用于颜色的 :root CSS 变量、用于排版的字体链接、用于动画的 .reveal 类
   • 如果启用了内联编辑：将鼠标悬停在左上角，或按 E 进入编辑模式；点击任意文本即可编辑，按 Ctrl+S 保存
   • 如果已导出 PPTX：
     • PPTX 文件位置和文件大小
     • 使用 PowerPoint / WPS / Keynote 打开并检查
     • 建议安装适用的字体（例如，中文使用 Noto Sans SC），以获得最佳显示效果
     • 提醒用户 Emoji 图标可能无法在所有 PowerPoint 版本中显示
4. 询问 — 用户是否需要进行任何调整？

---

支持文件

文件	用途	阅读时机
STYLE_PRESETS.md	12 种精选视觉预设，包含颜色、字体和标志性元素	阶段 2（样式选择）
viewport-base.css	必需的响应式 CSS——复制到每份演示文稿中	阶段 3（生成）
html-template.md	HTML 结构、JS 功能和代码质量标准	阶段 3（生成）
animation-patterns.md	CSS/JS 动画片段及效果与感受指南	阶段 3（生成）
scripts/extract-pptx.py	用于提取 PPT 内容的 Python 脚本	阶段 4（转换）
html2pptx.md	HTML 转 PPTX 的详细指南	阶段 5（导出 PPTX）
ooxml.md	OOXML 技术参考	阶段 5（导出 PPTX）
generate-pptx.js	PptxGenJS 的参考实现	阶段 5（导出 PPTX）