slidewright

Interactive presentation builder

构建可当作网站运行、并投影到房间大屏的幻灯片。幻灯片是演讲的视觉部分，讲解由演讲者完成。两种构建方式，共用同一套设计语言。

一、心智模型（写代码前先读）

只有一个操作者（演讲者）在一台机器上。幻灯片放在大屏幕上，观众只看，从不点击、输入或交互。以下所有内容都由此推导。需要避免四种失败模式：

1. 文字过小。幻灯片是从房间另一头阅读的，不是在笔记本电脑上。不要使用网页阅读尺寸（text-sm、16px）或固定 Tailwind 文字类（text-4xl）。始终使用流式 clamp()，让文字随屏幕缩放。遵守排版下限（正文约 30–36px，在 1080p 画布上从不低于 28px）。见 references/design-system.md。

2. 内容贴边。内边距是两层契约。幻灯片内容必须保持在视口安全区内，卡片、面板、标注、带边框盒子或其他可见容器中的内容必须与该容器自身边缘保持内缩。父级幻灯片的内边距不能保护嵌套容器；gap 和子元素外边距不能替代容器自身的内边距。两个脚手架都提供安全区内边距和 .slide-surface 内缩辅助工具。即使 fullBleed 幻灯片也保持文本内容内缩。

3. 把它当作应用来构建。没有输入框，没有“提交”，没有登录，没有数据收集——没有后端，数据也无处可去。交互仅为演讲者点击以显示/推进内容。如果某个组件问“这些数据去哪里？”，那就是错的。

4. 面向观众的语气不对。董事会报告不同于教学，路演不同于状态更新。演示类型决定结构和语气。先确定类型——见 references/deck-types.md。

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

references/design-system.md 是本技能的核心——排版下限、两层内边距契约、内容溢出、布局配方、动效和配色。只要设计或重新设计幻灯片内容，就阅读它。

二、工作流程

理解并澄清演讲。

内容：如果演示内容模糊或不清晰，先提问以澄清主题、观众、演讲者（姓名/角色）和关键信息，然后再构建。对于越南语内容，默认语气是朴素、诚实、直接——不做营销炒作。

演示类型：写之前先确定演示的用途：向上汇报、请求决策、路演、培训、演讲或内部更新。从请求中推断，并用一句话告诉用户你的选择；仅当两种类型同等契合时才询问。然后阅读 references/deck-types.md，遵循该类型的叙事弧线、语气和禁止事项。

风格：询问用户偏好的视觉风格，并建议以下 5 种现代选项：

• Minimalist Bauhaus：高对比度、几何排版、充足留白。
• Dark Mode Cinematic：深石板/黑色背景、戏剧性对比、发光强调。
• Editorial / Magazine：精致的字体搭配（衬线 + 无衬线）、结构化网格布局。
• Glassmorphism：柔和背景渐变，搭配模糊半透明内容面板。
• Neo-Brutalism：粗犷排版、原始边框、硬阴影、高能量。

选择一条技术路线（见下）。如果不确定，先询问一次；否则默认：小型/快速幻灯片用纯 HTML，规模较大且需维护的演讲用 React。

用匹配的脚本搭建脚手架——不要手工拼装样板代码。

按照演示类型的叙事弧线和语气构建幻灯片，遵循 references/design-system.md：每张幻灯片一个想法、少字、真实视觉、投影可读的字体、仅演讲者交互，以及视口和内容容器的两层内边距契约。遵守密度限制——每张幻灯片绝不超过 5 个要点、约 60 词或 5×4 表格单元格。如果内容在排版下限下放不下，就拆成更多幻灯片——绝不缩小到低于下限，也绝不产生需要垂直滚动的幻灯片。

保留必需的界面元素：可见的底部导航滑块（圆点条）和幻灯片编号。两个脚手架都包含它们——不要移除。

在脚手架创建的 <deck-name>-notes.md 文件中写演讲者备注（绝不要写在幻灯片本身上）。

运行验证脚本以捕获文字过小和内容过密问题：

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

在继续之前修复所有报告的问题。

交付前运行间距审计。在 1920×1080 和至少一个更小视口下检查每张幻灯片。任何文字或主要内容都不得越过视口安全区。对于每个绘制可见边界的元素（背景、边框、轮廓、阴影、圆角表面或文字覆盖面板），验证其内容在四边都有内边距。仅媒体和纯装饰性的通栏层例外；其上的文字应放在嵌套的带内边距表面中。

告诉用户如何用手机遥控器演讲。两个脚手架都包含它。HTML 路线运行 node <deck>/slidewright-remote.mjs。React 路线运行 npm run dev。终端会打印手机可扫的二维码。见 references/remote-control.md。编辑导航代码时，保留 deck 的 window.slidewright API 和 slidewright:change 事件。

如被要求，导出为 PDF——见 references/export-pdf.md。

每套幻灯片放在自己的文件夹中。任何现场演示应用都作为独立项目，不要放在幻灯片内。

三、选择技术路线

选择	何时	参考
Plain HTML	零配置；打开文件即可运行；快速幻灯片；可在任何地方分享；无工具链。超过约 15–20 张富内容幻灯片会变得难以管理。	references/html-track.md
Vite + React	幻灯片多、可复用组件、状态驱动交互、TypeScript、Framer Motion、需要维护/重复演讲。	references/react-track.md

两者产出相同的投影体验并遵守相同的设计系统；仅实现方式不同。

四、脚手架

Plain 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——手机遥控器：运行方式、deck 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——对幻灯片文件做静态分析：标记低于排版下限的文字、固定 px 字号、过多要点数以及每张幻灯片过高的词密度。构建幻灯片后、交付前运行。