web-deck

Web Deck — CoinFund 网页演示文稿构建器

构建简约、采用 CoinFund 品牌风格的幻灯片演示文稿，并将其制作为独立 HTML 文件。每个演示文稿都是一个 .html 文件——无需构建步骤、无需依赖，可轻松在 Git 中进行版本管理。

适用场景

用户需要基于网页的幻灯片演示文稿（HTML/CSS/JS）时，使用此工具。若要输出 .pptx，请改用 jake-deck 技能。此技能用于可在浏览器中原生呈现、也可导出为 PDF 的演示文稿。

用户需指定：

1. 模式：static（针对打印优化，不使用 JS）或 dynamic（键盘导航、幻灯片切换效果）。默认：dynamic。
2. 内容：幻灯片标题和内容，以大纲或项目符号的形式提供。

设计系统

配色方案（CSS 自定义属性）

:root {
  --bg:      #F7F3EE;  /* Warm cream — all slide backgrounds        */
  --text:    #1A1A1A;  /* Near-black — headings, primary body text   */
  --gray:    #7A7A7A;  /* Secondary text, labels                     */
  --ltgray:  #C8C2BA;  /* Divider rules, subtle borders              */
  --white:   #FFFFFF;  /* Title slide background, table headers      */
  --red:     #C0392B;  /* Warnings, risks, negative indicators       */
  --green:   #27AE60;  /* Positive indicators, "ready" status        */
  --blue:    #2C3E50;  /* Section headers, callout boxes             */
}

字体排版

所有文本均使用 Nunito（从 Google Fonts 加载，离线时回退到系统字体）。

元素	大小	字重	颜色
幻灯片标题	28px	700	--blue
章节标题	16px	700	--text
正文	13px	400	--text
标签/次要文本	11px	400	--gray
脚注	10-11px	400	--red 或 --gray

布局

幻灯片的纵横比为 16:9（基准尺寸为 960px x 540px，并缩放至填满视口）。

┌──────────────────────────────────────────────┐
│  padding-left: 76px (~0.8" equivalent)       │
│  ┌─ Title zone: top 50px ──────────────────┐ │
│  │                                          │ │
│  ├─ Content zone: top 110px ───────────────┤ │
│  │  width: 808px (~8.4" equivalent)        │ │
│  │                                          │ │
│  ├─ Footnote zone: bottom 30px ────────────┤ │
│  └──────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

必备幻灯片

标题页（始终为第一页）

• 背景：--white（#FFFFFF），而非奶油色
• CoinFund 标志：文字标识“CoinFund”，使用 52px Arial 粗体，颜色为 --text，居中
• 文字标识下方的细分隔线：宽 240px，颜色为 --text，居中
• 演示文稿标题：28px Nunito 粗体，颜色为 --blue，在分隔线下方居中
• 副标题/日期：14px Nunito，颜色为 --gray，居中

<section class="slide slide--title">
  <div class="slide__wordmark">CoinFund</div>
  <hr class="slide__divider slide__divider--title">
  <h1 class="slide__deck-title">Deck Title Here</h1>
  <p class="slide__subtitle">March 2026</p>
</section>

结束页（始终为最后一页）

• 背景：--bg（奶油色）
• “CoinFund”：36px Nunito 粗体，颜色为 --blue，居中
• 灰色分隔线，居中
• “coinfund.io”：13px Nunito，颜色为 --gray，居中

<section class="slide slide--end">
  <div class="slide__end-wordmark">CoinFund</div>
  <hr class="slide__divider slide__divider--end">
  <p class="slide__end-url">coinfund.io</p>
</section>

内容页样式

每张内容页均采用以下 HTML 结构：

<section class="slide">
  <h2 class="slide__title">Slide Title</h2>
  <hr class="slide__accent">
  <div class="slide__body">
    
  </div>
  
  <footer class="slide__footnote">Footnote text</footer>
</section>

样式 1：标题 + 正文区块（默认且最常见）

适用于包含 3-5 个主题的幻灯片，每个主题均有粗体标题和描述。

<div class="block">
  <div class="block__header">Bold header text</div>
  <div class="block__body">Gray body description text.</div>
</div>

样式 2：标签-值网格

双栏布局：左侧为灰色标签，右侧为文本值。

<div class="kv-grid">
  <div class="kv-grid__row">
    <span class="kv-grid__label">Label</span>
    <span class="kv-grid__value">Value text here</span>
  </div>
  
</div>

样式 3：表格

蓝色标题行搭配白色文本，正文行交替使用奶油色和白色背景。

<table class="deck-table">
  <thead>
    <tr><th>Column A</th><th>Column B</th><th>Column C</th></tr>
  </thead>
  <tbody>
    <tr><td>Data</td><td>Data</td><td>Data</td></tr>
    <tr><td>Data</td><td>Data</td><td>Data</td></tr>
  </tbody>
</table>

样式 4：编号列表

蓝色编号 + 粗体标签 + 行内正文。

<ol class="numbered-list">
  <li>
    <span class="numbered-list__label">Item name</span>
    <span class="numbered-list__desc">Description text explaining the item.</span>
  </li>
</ol>

样式 5：说明框

浅蓝灰色填充，左侧带强调边框。

<div class="callout">
  <p>Key insight or important note goes here.</p>
</div>

入场动画

在动态模式下，为需要在幻灯片激活时播放动画的元素添加 class="reveal"。元素会淡入并向上移动，动画延迟时间根据其在同级元素中的位置依次递增。

<section class="slide">
  <h2 class="slide__title reveal">Title animates first</h2>
  <hr class="slide__accent reveal">
  <div class="slide__body">
    <div class="block reveal">This block animates third</div>
    <div class="block reveal">This one fourth (0.08s delay)</div>
  </div>
</section>

在静态模式下，reveal 不会产生任何效果——元素将正常呈现。

静态模式与动态模式

静态模式（data-mode="static"）

• 完全不使用 JavaScript
• 所有幻灯片依次显示，并以 CSS 分页符分隔
• 针对浏览器打印（Cmd+P / Ctrl+P）或使用 Puppeteer 导出 PDF 进行了优化
• 每个 <section class="slide"> 均会设置 page-break-after: always

动态模式（data-mode="dynamic"）

• 键盘导航：方向键、空格键、Page Up/Down
• 支持在手机和平板上触控/滑动导航
• 在右下角显示当前幻灯片指示器（例如“3 / 12”）
• 视口顶部显示蓝色进度条
• 幻灯片之间带有细微的淡入淡出效果（CSS opacity + transition）
• .reveal 元素依次播放入场动画
• 每张幻灯片都会更新 URL 哈希（#slide-3），便于深层链接
• 按 F 进入全屏，按 Esc 退出
• 按 P 切换到总览模式（显示所有幻灯片，点击即可跳转）
• prefers-reduced-motion 会自动禁用动画

HTML 模板

文件 template.html（与此 SKILL.md 位于同一目录）是每个幻灯片的完整可用样板。它包含所有 CSS（设计令牌、模式 1-5、动画、静态／动态模式、打印样式）和所有 JS（键盘／触控导航、概览模式、全屏、进度条、哈希深层链接）。

创建新幻灯片

每次创建新幻灯片时，都复制此模板：

cp <skill-dir>/template.html deck.html

然后：

1. 将 <html> 上的 data-mode 设为 "dynamic" 或 "static"
2. 替换 <title> 和 .slide__deck-title 中的 DECK_TITLE_HERE
3. 替换 .slide__subtitle 中的 MONTH YEAR
4. 在标题幻灯片和结尾幻灯片之间添加内容幻灯片，并使用上文记录的内容模式

不要凭记忆重新生成样板。 务必复制模板文件。

实时开发服务器（必须）

务必通过开发服务器提供幻灯片。 切勿通过 file:// 直接打开幻灯片文件——服务器提供实时重新加载、汉堡菜单覆盖层和 PDF 导出功能。否则，用户看到的将是没有交互工具的静态文件。

开发服务器位于 serve-deck.mjs（与此 SKILL.md 位于同一目录）。无需 npm 依赖（首次导出 PDF 时会自动安装 Puppeteer）。

启动服务器

node /path/to/skills/web-deck/serve-deck.mjs 3333 /path/to/deck/directory

然后打开浏览器：

open http://localhost:3333/deck.html

先启动服务器，再打开浏览器。 使用 run_in_background: true，使服务器在编辑期间持续运行。

服务器提供的功能

1. 实时重新加载 — 基于 SSE，每次保存文件时都会自动重新加载浏览器。编辑幻灯片后，用户可以立即看到更改。
2. 汉堡菜单覆盖层 — 右上角始终显示汉堡图标（☰），其中包含：
   • 下载为 PDF — Puppeteer 在服务器端以每张幻灯片 960×540px 的尺寸渲染幻灯片，生成字体和样式完整保留的 PDF。首次使用时会自动安装 Puppeteer。
   • ⌘P 提示 — 提醒用户也可以使用浏览器打印
3. 静态文件服务 — 提供幻灯片和所有本地资源（图片、字体）

覆盖层菜单和重新加载客户端会在提供服务时注入——它们并不存在于 deck.html 文件本身。幻灯片保持整洁且自包含。这就是服务器不可或缺的原因：没有服务器，就没有汉堡菜单、PDF 导出或实时重新加载。

工作流

1. 用户提供大纲（幻灯片标题和内容要点）以及模式偏好（静态／动态）
2. 复制模板：cp <skill-dir>/template.html deck.html
3. 在复制的文件中设置模式、标题和副标题
4. 为每张幻灯片选择合适的内容模式，并添加内容幻灯片
5. 启动服务器（在后台启动一次）：node <skill-dir>/serve-deck.mjs 3333 .，并设置 run_in_background: true
6. 在浏览器中打开（打开一次）：open http://localhost:3333/deck.html
7. 迭代 — 使用 Edit 工具修改幻灯片。每次保存后，浏览器都会自动重新加载。
8. 准备就绪后，用户点击汉堡菜单 → 下载为 PDF。

重要：保持服务器运行

• 使用 run_in_background: true 启动服务器，使其在编辑期间持续运行
• 第二个参数是要提供服务的目录（默认为 .）
• 服务器会在整个会话期间保持运行——不会自动关闭
• 会话结束或用户完成后，终止服务器：pkill -f serve-deck，或让它自然退出

风格原则

CoinFund 演示文稿的风格以克制为核心：

1. 不使用渐变、投影或装饰元素。 幻灯片上的 CSS box-shadow 仅用于浏览器视口的边框效果，并非幻灯片内容的一部分。
2. 颜色具有语义。 蓝色用于结构，红色用于风险／警告，绿色用于就绪／积极信息。绝不用于装饰。
3. 留白承担主要作用。 留足内边距，清晰分隔各个内容块。如果感觉拥挤，就拆分成两张幻灯片。
4. 每张幻灯片最多放 4-5 个内容块。 这样可以避免内容溢出，也方便快速浏览。
5. 脚注放在主要内容下方， 中间留出清晰间距。使用定位在底部的 slide__footnote。
6. 每张幻灯片只用一条强调线。 短横线 slide__accent <hr> 用于分隔标题和内容，这是唯一的装饰。
7. 简洁胜于冗长。 项目符号内容最多写 1-2 句话。演示文稿旨在引发讨论，而不是充当白皮书。
8. 统一风格变更。 用户对一张幻灯片提出视觉或风格修改时，应在整套演示文稿的所有幻灯片中一致应用。

增量编辑

实时服务让编辑过程像使用 REPL 一样——修改文件后立即查看结果。

由于演示文稿是一个 HTML 文件：

• 便于使用 Git： 每张幻灯片都是一个 <section> 块，因此差异清晰且有意义
• 添加幻灯片： 在现有幻灯片之间插入新的 <section class="slide"> 块
• 重新排序： 剪切／粘贴 <section> 块
• 编辑内容： 修改现有区块中的文本
• 微调样式： 调整 :root 中的 CSS 自定义属性，以进行全局更改

当用户要求编辑特定幻灯片时，使用 Edit 工具仅修改相关的 <section> 块。小幅修改时，不要重新生成整个文件。实时服务会在每次保存时自动重新加载。

防止内容溢出

• 每张幻灯片最多 5 个内容块（模式 1）
• 标签－值网格最多 6 行（模式 2）
• 表格最多 7 行（含表头）
• 脚注通过绝对定位固定在 bottom: 20px
• 如果内容放不下，拆分成两张幻灯片——字号绝不能缩小到 10px 以下