Visual Deck

visual-deck — 视觉版 deck 设计系统

绿皮火车频道的 deck 设计语言。基于 open-slide React 框架,提供:两套频道主题 + 四个核心版式词汇 + Nano Banana 背景图规范 + 安全区/溢出/V2 prompt 编辑纪律。

v1.0 是大版本切换:旧版的 HTML→PPTX 渲染管线(pptxgenjs / scrim-bake / 8 layouts / check-overflow)已全部移除。如果你要找 PPTX 输出能力,见 SKILL.md 末尾的 [PPTX Roadmap](#pptx-roadmap)。

何时触发

适用:

• 布道版 / 对外方案 / 内部分享 / YouTube 视频用 deck,最终交付物可以是 URL 或 PDF
• 单页信息密度高,版式需要干净一致
• 需要重复复用绿皮火车的视觉身份(dark-teal 技术系 / dark-coral 人文系)
• agent 主导的迭代式 deck(pnpm dev HMR + 浏览器 inspector + /apply-comments)

不适用:

• 必须交付 .pptx 文件让客户在 PowerPoint 里编辑 → 暂时回退到 pptx skill,或等 PPTX 上游 export
• 纯数据报表 / 纯文字文档 → 用 docx/xlsx skill
• 一次性临时 deck(不值得 setup open-slide 项目) → 直接用 pptx skill

三条硬约束(从 visual-deck 0.x 继承)

这三条是踩过坑换来的,违反任何一条直接退回。

1. 文字只进安全区,溢出走 speaker notes

• 每张 slide 都有天然的安全区(暗色区 / 留白区),前景文字只能排在里面
• 正文装不下时:不许缩字号,不许退回"全屏蒙版压字"。把溢出内容塞进 speaker notes(写在 `` 里),或拆页
• 详见 references/safe-zone-spec.md(已按 1920×1080 像素校准)

2. Image prompt 必须 V2 四段式

• 描述 / Composition / Style / Do not include 四段齐全
• 安全区百分比写死在 Composition 段
• 色彩用 token + hex 双写
• 详见 references/image-prompts-v2.md

3. Nano Banana 比例有限

• 支持 16:9 / 4:3 / 1:1 / 3:4 / 9:16
• 不支持 21:9 — 见 references/nano-banana-ratios.md 的三种变通

完整 Pipeline(v1.0)

立论文档(/ppt-classify + /ppt-research-setup)
       │
       ▼
image-prompts.md(V2 四段式)
       │
       ▼ (Nano Banana / agent 跑)
slides//assets/*.png
       │
       ▼ (CSS scrim,不再烘焙 PNG)
slides//index.tsx
       │     │
       │     └── 顶部 design: DesignSystem(从 themes/dark-teal.md 复制)
       │     └── layout helper(从 layouts/*.md 复制)
       │     └── 每个 Page 组件实现一页
       │
       ▼
open-slide pnpm dev → HMR .md` 复制 helper components,从 `layouts/*.md` 复制版式模板,改成你的内容
6. **dev server 预览** — `pnpm dev`,改 JSX 实时刷新
7. **inspector 协作** — 浏览器点元素加 `@slide-comment` 批注,跑 `/apply-comments` 让 agent 改
8. **交付** — `pnpm build` 出静态站点,或 export PDF

## 关键陷阱(agent 最容易犯的)

**版式相关**:
- ❌ 用 4 个核心 layout 装不下的内容时去 hack layout(改 padding / 缩字号) → **写 inline 组件**,参考 ep10 实战
- ❌ TOC / KPI 卡片用 `array.map` 渲染 → 违反 slide-authoring 硬规则。**显式 `` × N 实例化**,inspector 才能编辑单个
- ❌ Chapter cover 双栏长度悬殊 → 改成单栏或拆页

**主题相关**:
- ❌ 一份 deck 里混用 dark-teal 和 dark-coral 章节 → 频道身份混乱。如果章节调性不同,拆成不同 deck
- ❌ 把 `Accent` 当装饰用(每页 5+ 处) → accent 是强调点,过度使用失去强调意义。一页 1-2 处,thesis 页最多 2 处

**Nano Banana / 图片相关**:
- ❌ 需要 21:9 时强行让 Nano Banana 出 → 不支持,见 ratios.md 的变通
- ❌ 用 base64 data URL 嵌图 → open-slide 用 ES module import,从 `./assets/` 引用
- ❌ scrim 调到 0.85+ 盖住整张图 → 图就白生成了

**open-slide 框架相关**:
- ❌ 加 npm 依赖 → framework 禁止,只能用 react + 标准 web API
- ❌ 在 `slides//` 里建 sibling `.tsx` 文件 → 禁止,helper 组件必须 inline 在同一个 index.tsx
- ❌ 改 package.json / open-slide.config.ts → 禁止
- ❌ 用 `overflow: hidden/scroll` 隐藏溢出 → canvas 不滚动,溢出 = 内容消失。**改文案或拆页**

## 与 open-slide 框架自带 skill 的关系

open-slide 框架本身自带 5 个 agent skill:`/create-slide` / `/slide-authoring` / `/apply-comments` / `/create-theme` / `/current-slide`。

**visual-deck 与它们不冲突,而是分层**:

| 层 | 谁负责 |
|---|---|
| **通用规则**(1920×1080 canvas、type scale 范围、anti-patterns) | open-slide 的 `/slide-authoring` |
| **绿皮火车特化**(dark-teal/coral 主题、4 个 layout、V2 prompt、Nano Banana 比例) | visual-deck(本 skill) |
| **流程编排**(scaffold / dev server / inspector 工作流) | open-slide 的 `/create-slide` + `/apply-comments` |
| **PPT 立论**(分类、研究框架、storyline 评审) | `/ppt-classify` / `/ppt-research-setup` / `/ppt-narrative-review` |

**做新 deck 时的建议路径**:
1. 先 `/ppt-classify` 定 PPT 类型
2. 启动 open-slide 项目(`/create-slide` 或手动 scaffold)
3. 写 JSX 时,**读 visual-deck 的 layouts/.md + themes/.md**,从模板复制粘贴
4. inspector 反馈用 `/apply-comments`

## v0.x → v1.0 迁移指南

如果你有用 v0.x 做过的旧 deck:

1. **HTML 文件**:逐页转 JSX,参考 `layouts/` 里的对应版式
2. **CSS 变量**:从 `var(--accent)` 换成 `palette.accent`(hex 直写或用 `var(--osd-accent)`)
3. **背景图**:`background: url(../images/...)` → ES module import + CSS gradient(scrim 不再烘焙)
4. **notes-map.js**:废弃,改成每页 `` 内联
5. **build.js**:废弃,改用 `pnpm dev` / `pnpm build`
6. **单位**:pt × 2.667 = px(safe-zone-spec.md 末尾有完整对照表)

参考实战:ep10 NVIDIA 护城河 deck 已完成 16 页迁移,源码可对照(`~/Github/greentrain-studio/main/episodes/ep10-ai-ppt/open-slide-deck/`)。

## PPTX Roadmap

v1.0 **不输出 .pptx 文件**。这是有意识的取舍——绿皮火车实际工作流(YouTube + 现场演讲)不需要 .pptx,只需要 deck 在浏览器里看得清。

**未来计划**:把 v0.x 时代的 HTML→pptxgenjs 管线封装成 **open-slide 的 export-pptx 命令**,贡献到 open-slide 上游。届时任何用 open-slide 的 deck(包括非绿皮火车用户)都能受益,而 visual-deck 自己不需要维护这套管线。

时间表未定,需要时再开工。

## 扩展约束(给未来的自己)

**新增 layout 之前必须回答**:
1. 现有 4 个版式为什么不够?举一个具体 slide 说不通的场景
2. 新版式的 USE WHEN / DO NOT USE WHEN 分别是什么?
3. 它真的可复用,还是只在一个 deck 出现过?(只用一次就别抽象,直接 inline 在 deck 里写)

**新增 theme 之前必须回答**:
1. dark-teal / dark-coral 为什么不够?
2. 新 theme 与现有两个的镜像关系是什么(palette 哪些不变,哪些变)
3. 这套主题的 "适用调性" 在频道里有几集会用?(一集就别加)

扁平堆叠 layout / theme 会让 agent 选不到对的——**信息结构 ≫ 选项数量**。

## 快速开始

```bash
# 1. scaffold
npx @open-slide/cli@latest init my-deck --use-pnpm --locale zh-CN --no-git
cd my-deck

# 2. 复制主题(从 visual-deck 仓库)
cp ~/Github/skills/visual-deck/themes/dark-teal.* themes/

# 3. 跑 dev
pnpm dev   # → http://localhost:5173

# 4. 写第一张 slide(参考 references/open-slide-bootstrap.md)
mkdir slides/
# ... 见 bootstrap 文档第 4 步

完整步骤见 references/open-slide-bootstrap.md。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: crazynomad
• Source: crazynomad/skills
• License: MIT

Install and usage instructions live in the source repository linked above.