slidewright

交互式演示文稿构建器

构建以网站形式运行、可投影到会议室的幻灯片。演示文稿是演讲的视觉部分；由演讲者负责讲解。两种构建方式，共用一套设计语言。

首先，了解基本思路（编写任何代码前请先阅读）

只有一位操作者（演讲者）在一台设备上操作。幻灯片显示在大屏幕上； 观众只会观看，不会点击、输入或进行交互。以下所有要求都由此而来。需要避免以下四种问题：

• 文字太小。 幻灯片要让会议室另一端的人也能看清，而不是只适合在笔记本电脑上阅读。切勿使用适合网页阅读的字号（text-sm、16px）或固定的 Tailwind 文本类（text-4xl）。始终使用流式 clamp()，让文字随屏幕大小缩放。遵守字体大小下限（正文约为 30–36px，在 1080p 画布上不得低于 28px）。参见 references/design-system.md。
• 内容紧贴边缘。 内边距是一个双层约定。幻灯片内容必须位于视口安全区域内；卡片、面板、提示框、边框框体或其他可见容器中的内容，也必须与容器自身边缘保持间距。父级幻灯片的内边距无法保护嵌套容器；gap 和子元素外边距不能替代容器自身的内边距。两种脚手架都提供安全区域内边距和 .slide-surface 内缩辅助类。即使是 fullBleed 幻灯片，文字内容也必须保持内缩。
• 把它做成应用。 不要有输入框、不要有“提交”按钮、不要登录、不要收集数据——这里没有后端，也没有数据接收处。交互仅限演讲者点击以显示或切换内容。如果某个组件会问“这些数据要发到哪里？”，那它就是不对的。
• 面向观众的表达方式不当。 董事会报告不是课程，推介也不是状态更新。演示文稿类型决定结构和表达方式。请先确定类型——参见 references/deck-types.md。

演讲者可以拿着手机遥控器（从终端扫描二维码，然后点按“下一页”/“上一页”）。这是同一位操作者使用的第二台设备，并非观众交互。

references/design-system.md 是这项技能的核心，涵盖字体大小下限、双层内边距约定、内容溢出、布局方案、动效和配色。设计或调整幻灯片内容时，请阅读该文档。

工作流

1. 理解并明确演讲内容。
   • 内容： 如果演示内容含糊不清，请在开始制作前询问问题，明确主题、受众、演讲者（姓名／角色）和关键信息。对于越南语内容，默认语气应朴实、诚恳、直接，不要夸大宣传。
   • 演示文稿类型： 写作前先判断演示文稿的用途：向上汇报、请求决策、推介、培训、演讲或内部更新。根据请求推断类型，并用一句话告诉用户你的选择；只有当两种类型同样合适时才提问。然后阅读 references/deck-types.md，遵循该类型的叙事结构、语气和禁忌。
   • 风格： 询问用户偏好的视觉风格，并推荐以下 5 种现代风格：
     1. 极简主义包豪斯：高对比度、几何字体、大量留白。
     2. 暗色电影感：深石板色／黑色背景、强烈对比、发光点缀。
     3. 编辑／杂志风：精致的字体搭配（衬线字体 + 无衬线字体）、结构化网格布局。
     4. 玻璃拟态：柔和的背景渐变、带模糊效果的半透明内容面板。
     5. 新粗野主义：粗体字、裸露边框、硬阴影、强烈动感。
2. 选择制作路线（见下文）。如果不确定，询问一次；否则，小型／快速演示文稿默认使用纯 HTML，内容较多且需要维护的演讲默认使用 React。
3. 使用匹配的脚本搭建框架，不要手动拼装样板代码。
4. 制作幻灯片时，遵循演示文稿类型的叙事结构和语气，并遵照 references/design-system.md：每张幻灯片只讲一个观点、文字精简、使用真实视觉素材、字体大小适合投影、交互仅供演讲者使用，并确保视口容器和内容容器都遵守双层内边距约定。遵守内容密度限制——每张幻灯片不得超过 5 个项目符号、约 60 个单词或 5×4 个表格单元格。如果内容在最低字号下仍无法放下，就拆分成更多幻灯片；绝不能缩小到最低字号以下，也不能制作会垂直滚动的幻灯片。
5. 保留必需的界面元素： 显示在底部的导航滑块（圆点条）和幻灯片编号。两种搭建框架都包含这些元素，不要移除。
6. 在搭建框架创建的 <deck-name>-notes.md 文件中撰写演讲者备注（不要写在幻灯片上）。
7. 运行验证脚本，检查字体过小和内容过密的问题：

   bash /mnt/skills/user/slidewright/scripts/verify-slides.sh <path-to-deck>
   

   继续之前，修复报告中的所有问题。
8. 交付前运行间距审查。 在 1920×1080 和一种更小的视口下检查每张幻灯片。任何文字或主要内容都不得越出视口安全区域。对于每个带有可见边界的元素（background、border、outline、shadow、圆角表面或文字叠加面板），请确认其内容四周都留有内边距。媒体和纯装饰性的通栏图层是仅有的例外；其上的文字应放在带内边距的嵌套表面中。
9. 告知用户如何使用手机遥控器进行演示。 两种搭建框架都包含该功能。HTML 路线运行 node <deck>/slidewright-remote.mjs。React 路线运行 npm run dev。终端会打印供手机使用的 QR 码。请参阅 references/remote-control.md。 编辑导航代码时，请保留演示文稿的 window.slidewright API 和 slidewright:change 事件。
10. 如果用户要求，导出为 PDF——请参阅 references/export-pdf.md。

每份演示文稿都应放在单独的文件夹中。任何现场演示应用都应作为独立项目保存，不要放在演示文稿文件夹内。

选择制作路线

选择	适用情况	参考文档
纯 HTML	希望零配置；打开文件即可运行；快速制作演示文稿；可在任何地方分享；无需工具链。超过约 15–20 张内容丰富的幻灯片后会变得难以管理。	references/html-track.md
Vite + React	幻灯片较多、需要可复用组件、由状态驱动的交互、TypeScript、Framer Motion，或需要维护／重复使用的演讲。	references/react-track.md

两种路线都能呈现相同的投影效果，并遵循相同的设计系统；区别仅在于实现方式。

脚手架

纯 HTML — 单个自包含的 index.html，通过 CDN 使用 Tailwind，无需构建：

bash scripts/new-html-deck.sh <deck-name> [target-dir] [--title "Deck title"]

Vite + React — 使用官方 Vite 工具搭建，并安装最新版本的 React、Tailwind、Framer Motion 和 Lucide（版本有意不固定，因此每个演示文稿都从当前工具开始），然后构建 App → Deck → Slide 架构：

bash scripts/new-react-deck.sh <deck-name> [target-dir] [--no-install]
cd <deck-name> && npm run dev

两种脚手架都包含手机遥控器（slidewright-remote.mjs，零依赖）。 对于在遥控器推出前搭建的演示文稿：

bash scripts/add-remote.sh <path-to-deck>

完成脚手架搭建后，阅读对应轨道的参考文档，了解幻灯片的组织方式以及如何添加／重新排序，然后开始构建内容。

此技能中的文件

• references/design-system.md — 投影规则、字体排版下限、布局配方、动效、调色板。核心文档；进行任何内容／设计工作时都应查阅。
• references/deck-types.md — 六种演示文稿类型，以及各自的叙事脉络、语气和禁忌。撰写幻灯片内容前请先阅读。
• references/html-track.md — 纯 HTML 演示文稿结构、模板内部实现、添加幻灯片。
• references/react-track.md — Vite+React 架构、幻灯片排序、Tailwind 接入。
• references/export-pdf.md — PDF 导出选项和演讲者备注规范。
• references/remote-control.md — 手机遥控器：运行方法、演示文稿 API 契约、安全性、故障排查（IP 错误、防火墙、场地 Wi-Fi）。
• scripts/new-html-deck.sh — 搭建纯 HTML 演示文稿。
• scripts/new-react-deck.sh — 搭建 Vite + React 演示文稿。
• scripts/add-remote.sh — 为现有演示文稿添加手机遥控器。
• assets/remote/slidewright-remote.mjs — 手机遥控器：WebSocket 中继、遥控页面、终端二维码、静态服务（HTML 轨道）和 Vite 插件（React 轨道）。 脚手架会将其复制到每个演示文稿中；请修改此源文件，而非副本。
• scripts/export-deck-pdf.py — 将演示文稿导出为内容完整的 PDF（等待渲染并显示隐藏内容；基于图像）。
• scripts/verify-slides.sh — 对演示文稿文件进行静态分析：标记低于字体排版下限的文本、固定像素的字号、过多的项目符号，以及每张幻灯片的高词语密度。构建幻灯片后、交付前运行。