presentation-builder

演示文稿构建器

创建零依赖、动画丰富的 HTML 演示文稿，完全在浏览器中运行。

基于 zarazhangrui/frontend-slides，并针对 OrchestKit 重新组织。

核心理念

1. 零依赖 —— 使用包含内联 CSS/JS 的单个 HTML 文件。无需 npm 或构建工具。
2. 展示，而非讲述 —— 生成视觉预览，而非抽象选项。人们通过观看来发现自己的偏好。
3. 独特设计 —— 避免泛泛的“AI 垃圾风格”。每份演示文稿都应具有精心定制的质感。
4. 生产级质量 —— 代码注释完善、易于访问且性能出色。
5. 适配视口 —— 每张幻灯片都必须恰好适配视口。任何情况下都不得在幻灯片内滚动。

阶段 0：检测模式

确定用户的需求：

模式	触发条件	下一阶段
A：新建演示文稿	从头创建幻灯片	阶段 1
B：PPT 转换	有 .ppt/.pptx 文件	加载 Read("${CLAUDE_SKILL_DIR}/references/pptx-conversion.md")，然后进入阶段 2
C：增强	有现成的 HTML 演示文稿	读取文件、了解结构并进行增强

---

阶段 1：内容探索

设计之前，先了解内容。使用 AskUserQuestion：

问题 1：目的

• 标题：“目的”
• 选项：“演示提案”、“教学/教程”、“会议演讲”、“内部演示”

问题 2：幻灯片数量

• 标题：“篇幅”
• 选项：“短（5-10 张）”、“中（10-20 张）”、“长（20 张以上）”

问题 3：内容准备情况

• 标题：“内容”
• 选项：“我已准备好所有内容”、“我有一些粗略笔记”、“我只有一个主题”

如果用户已有内容，请他们分享。如果只有主题，请帮助他们拟定大纲。

---

阶段 2：风格探索

这是“展示，而非讲述”的阶段。

步骤 2.0：选择风格路径

询问用户想如何选择风格：

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

可用预设（加载 Read("${CLAUDE_SKILL_DIR}/references/style-presets.md") 查看完整详情）：

预设	氛围	最适合
Bold Signal	自信、有冲击力	演示提案、主题演讲
Electric Studio	简洁、专业	代理机构演示
Creative Voltage	活力十足、复古现代	创意提案
Dark Botanical	优雅、精致	高端品牌
Notebook Tabs	编辑风、有条理	报告、评审
Pastel Geometry	友好、亲切	产品概览
Split Pastel	活泼、现代	创意代理机构
Vintage Editorial	风趣、个性鲜明	个人品牌
Neon Cyber	未来感、科技感	科技初创公司
Terminal Green	面向开发者	开发工具、API
Swiss Modern	极简、精准	企业演示、数据展示
Paper & Ink	文学气息、深思熟虑	叙事演示

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

如果选择“向我展示选项”，通过 AskUserQuestion 提问：

问题：氛围

• “你希望观众感受到什么？”
• 选项（可多选，最多选 2 项）：
  • “印象深刻/充满信心” —— 专业、可信
  • “兴奋/充满活力” —— 创新、大胆
  • “平静/专注” —— 清晰、易于跟进
  • “受到启发/感动” —— 富有情感、令人难忘

氛围与风格映射：

氛围	建议风格
印象深刻/充满信心	Bold Signal、Electric Studio、Dark Botanical
兴奋/充满活力	Creative Voltage、Neon Cyber、Split Pastel
平静/专注	Notebook Tabs、Paper & Ink、Swiss Modern
受到启发/感动	Dark Botanical、Vintage Editorial、Pastel Geometry

步骤 2.2：生成风格预览

在 .claude-design/slide-previews/ 中生成 3 个不同的迷你 HTML 文件：

.claude-design/slide-previews/
├── style-a.html   # ~50-100 lines, single title slide
├── style-b.html
└── style-c.html

每个预览都应独立完整，包含内联 CSS/JS，并以动画标题幻灯片展示排版、色彩和动效风格。

步骤 2.3：展示预览

向用户展示 3 个选项，并通过 AskUserQuestion 询问：

• “你更喜欢哪种风格的预览？”
• 选项：Style A、Style B、Style C、“Mix elements”

---

阶段 3：生成演示文稿

根据内容（阶段 1）和风格（阶段 2）生成完整的演示文稿。

文件输出

presentation.html    # Self-contained presentation
assets/              # Images if any (PPT conversion)

HTML 架构

每份演示文稿都遵循以下结构：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Presentation Title</title>
    
    <style>
        /* Theme variables in :root */
        /* Base styles + viewport fitting (see rules/viewport-fitting.md) */
        /* Slide container styles */
        /* Animations */
        /* Responsive breakpoints */
    </style>
</head>
<body>
    <div class="progress-bar"></div>
    <nav class="nav-dots"></nav>
    <section class="slide title-slide">...</section>
    <section class="slide">...</section>
    
    <script>
        /* SlidePresentation class with navigation */
    </script>
</body>
</html>

重要：视口适配

每张幻灯片都必须恰好适配视口。 加载：Read("${CLAUDE_SKILL_DIR}/rules/viewport-fitting.md")

快速检查清单：

• 每个 .slide 都包含 height: 100vh; height: 100dvh; overflow: hidden;
• 所有字体大小都使用 clamp(min, preferred, max)
• 所有间距都使用 clamp() 或视口单位
• 内容符合密度限制（加载 ${CLAUDE_SKILL_DIR}/rules/content-density.md）
• 针对以下高度设置断点：700px、600px、500px
• 内容无法适配时：拆分为多张幻灯片，绝不滚动

高级 clamp()/容器查询模式另请参阅 responsive-patterns 技能。

必需的 JavaScript 功能

1. SlidePresentation 类——键盘操作（方向键、空格键）、触摸/滑动、鼠标滚轮、进度条、导航圆点
2. Intersection Observer——滚动时添加 .visible 类以触发 CSS 动画
3. 可选增强功能（取决于风格）：自定义光标、粒子背景、视差效果、3D 倾斜、磁吸按钮

代码质量

• 每个 CSS/JS 区块都要有清晰注释，说明作用、原因以及修改方法
• 使用语义化 HTML（<section>、<nav>、<main>）
• 键盘导航正常工作
• 在需要的位置添加 ARIA 标签
• 支持减少动态效果：@media (prefers-reduced-motion: reduce)

反模式（禁止使用）

• 字体： Inter、Roboto、Arial、系统字体作为展示字体
• 颜色： #6366f1（通用靛蓝色）、白底紫色渐变
• 布局： 所有内容居中、通用型主视觉区、千篇一律的卡片网格
• 装饰： 写实插画、滥用玻璃拟态效果

---

阶段 4：交付

1. 如果 .claude-design/slide-previews/ 存在，则将其清理
2. 打开演示文稿：open [filename].html
3. 提供摘要：

Your presentation is ready!

File: [filename].html
Style: [Style Name]
Slides: [count]

Navigation:
- Arrow keys or Space to navigate
- Scroll/swipe also works
- Click dots on the right to jump

To customize:
- Colors: :root CSS variables at top
- Fonts: Change the font link
- Animations: Modify .reveal class timings

---

风格参考：效果与感受的对应关系

感受	动画风格	视觉处理
戏剧性/电影感	慢速淡入（1-1.5s）、大幅度缩放过渡	深色背景、聚光灯效果、视差
科技感/未来感	霓虹发光、故障/乱码文字	粒子系统、网格图案、等宽字体点缀
活泼/友好	弹性缓动、浮动动画	柔和/明亮配色、圆角
专业/商务	细微快速动画（200-300ms）	简洁的无衬线字体、海军蓝/石板灰、侧重数据可视化
平静/极简	非常缓慢而细微的动态效果	大量留白、柔和配色、衬线字体
编辑/杂志风	鲜明的字体层级	引文、打破网格的布局、黑白搭配强调色

---

故障排查

问题	解决方案
字体未加载	检查 Fontshare/Google Fonts URL，确认字体名称与 CSS 中的一致
动画未触发	确认 Intersection Observer 正在运行，检查 .visible 类
滚动吸附无效	确保在 html 上设置 scroll-snap-type，并在幻灯片上设置 scroll-snap-align
移动端问题	在 768px 处禁用复杂效果，测试触摸事件，减少粒子数量
性能问题	谨慎使用 will-change，优先使用 transform/opacity 动画

---

相关技能

• ork:responsive-patterns -- 高级 clamp()、容器查询、响应式断点
• ork:accessibility -- WCAG 2.2 合规性、键盘导航、ARIA 模式
• ork:ui-components -- shadcn/ui 和 Radix 组件模式
• ork:demo-producer -- 终端录制和视频演示

规则

按需使用 Read("${CLAUDE_SKILL_DIR}/rules/<file>") 加载：

文件	内容
viewport-fitting.md	视口锁定幻灯片的必需 CSS
content-density.md	各类幻灯片的内容上限

参考资料

需要时使用 Read("${CLAUDE_SKILL_DIR}/references/<file>") 加载：

文件	内容
style-presets.md	12 种精选视觉主题及其 CSS 变量
pptx-conversion.md	PowerPoint 提取与转换工作流