visual-deck

visual-deck

A Claude Code skill that turns a topic or outline into a multi-page, full-screen HTML presentation deck — mixing AI-generated visual backgrounds (imgen) with HTML-overlaid, pixel-accurate text. Optional one-command export to MP4 via hyperframes.

把一个选题 / 大纲做成「图文混合的全屏 HTML 演示稿」——科普图、讲解 PPT、知识卡、口播配图、流程图解。可一键导出 MP4。

看一份做出来的成品 → examples/codex-ppt/（7 页，含拼接蓝本和成品截图）。

核心思路：图 + HTML 混合，不是纯图也不是纯 HTML

这是这个 skill 的判断基础——逐页判类型，各干各擅长的：

• imgen 擅长整张渲染的质感（人物、3D 元素、场景光影浑然一体）→ 出视觉页底图
• HTML 擅长准确文字、排版、交互 → 叠准确中文字、画信息页（波形 / 时间线 / 表格 / 代码 / 流程，imgen 画这些会糊）

→ 结论：视觉页走「imgen 留白底图 + HTML 叠字」，信息页走「纯 HTML/CSS」。

工作流

选题 → 大纲(逐页规划 + 定每页类型)
     → 拼接结构总览图(全部页拼一张, 定版式+风格, 排版蓝本)
     → 照拼接图逐页做 → 合成翻页 → deckcheck 体检 →〔可选〕hyperframes 出 MP4
              ├─ 视觉页 → imgen 留白底图 + HTML 叠字(定尺 slide + cover 铺满)
              └─ 信息页 → 纯 HTML/CSS(用组件库)

1. 选题 → 大纲：逐页列「讲什么 / 屏上放什么 / 页类型（视觉页 or 信息页）」
2. 拼接结构总览图（关键）：让 imgen 出一张「把所有页缩略拼在一张」的总览图，每格一个不同版式、整套风格统一 → 当排版蓝本。先定版式再排 HTML，否则每页容易套成同一个骨架、看着「结构都差不多」
3. 视觉页：imgen 出主体在一侧、另一侧留白、无文字的底图 → HTML 用 background:cover 铺满 + px 叠字（定尺 slide）
4. 信息页：用 assets/style-claymation.css 组件库（卡片 / 波形 / 时间线 / 字幕表 / 终端 / 标签云 / 步骤条）纯 HTML 拼，逐页照拼接图对应格的布局排
5. 合成：所有页装进一个 index.html，← → / 空格 / 点击翻页，全屏自适应
6. 体检：scripts/deckcheck.py 一次截全每页 + 自动查内容溢出、四缘色差缝
7. （可选）出视频：scripts/deck-to-video.sh 把 deck 转成 hyperframes 工程 → 渲成 MP4

仓库结构

visual-deck/
├─ SKILL.md                      # 技能定义（agent 读这个执行）
├─ assets/
│  ├─ skeleton/
│  │  ├─ visual-page.html        # 视觉页模板（底图 + flex 居中叠字）
│  │  ├─ info-page.html          # 信息页模板（组件库拼装）
│  │  ├─ deck.html               # 合成翻页骨架（翻页 JS + 入场动效 + 全屏 fit）
│  │  └─ hf-composition.html     # deck → 视频的 hyperframes composition 模板
│  ├─ style-claymation.css       # 现成组件库（黏土风为默认，改 :root 变量即换风格）
│  └─ fit.js                     # 单页全屏等比缩放
├─ references/
│  ├─ imgen-prompts.md           # imgen 出拼接图 / 底图 / 素材的 prompt 模板
│  ├─ pitfalls.md                # 踩坑清单（动手前必读，13 条）
│  └─ hyperframes.md             # deck → MP4 的改造清单 + 踩坑
├─ scripts/
│  ├─ deckcheck.py               # 截全每页 + 查溢出 + 扫色差缝（playwright）
│  ├─ preview.sh                 # 单页 headless 截图（跨平台找 chromium）
│  ├─ chroma_cut.py              # 白底素材抠透明（连通域色键 + 自动阈值）
│  └─ deck-to-video.sh           # deck → hyperframes 视频工程脚手架
└─ examples/
   └─ codex-ppt/                 # 一份完整成品 deck（拼接蓝本 + 7 页 + 截图）

依赖

信息页那一半是纯 HTML/CSS，不需要任何 AI 工具——只有「视觉页底图」「抠透明素材」「出视频」用到外部工具。

关于 imgen

skill 里出底图调的是 imgen——一个文生图 / 图生图 CLI（imgen "<prompt>" -s 1536x864 -q high -o bg.png，-i 图生图），不是 npm install 就有的通用公开工具。换到你的环境，两条路任选其一：

• 把你自己的「文生图 CLI（输出 PNG）」装成 / 别名成 imgen，参数对齐 -s(尺寸) -q(质量) -o(输出) -i(输入图)，调用样例见 references/imgen-prompts.md；
• 或用任意工具先按 prompt 模板的构图（主体一侧、另一侧留白、图里不放文字）把底图生成好，直接丢进页面当 background。

只用信息页 / 组件库 / 翻页骨架的话，连文生图都不用，纯 HTML 即可。

安装（作为 Claude Code 技能）

clone 到项目级或全局的 skills 目录：

# 全局（所有项目可用）
git clone https://github.com/xiaomoBoy/visual-deck.git ~/.claude/skills/visual-deck

# 或项目级
git clone https://github.com/xiaomoBoy/visual-deck.git <你的项目>/.claude/skills/visual-deck

装依赖（按需）：

pip install playwright && playwright install chromium   # 体检 / 截图预览（建议装）
pip install pillow numpy scipy                          # 仅在要抠透明素材时

之后在 Claude Code（或其他读取 SKILL.md 执行的 AI agent）里说「做个演示稿 / 把这个选题做成图 / 给大纲配图 / 做知识卡 / 把流程画出来」即可触发，agent 会读 SKILL.md 按流程执行。SKILL.md 只用 shell 命令（imgen / deckcheck.py / chroma_cut.py 等），不绑定任何特定 agent 的工具。

Quick start（手动跑一遍，不经 Claude）

想先不依赖 Claude 直接看效果，照 examples/codex-ppt/ 那份成品改最快。从零搭：

1. 信息页：复制 assets/skeleton/info-page.html + assets/style-claymation.css + assets/fit.js，照组件库的 class（卡片 / 波形 / 时间线 / 字幕表 / 终端 / 标签云 / 步骤条）把内容拼进 .sbody；
2. 视觉页：复制 assets/skeleton/visual-page.html，把 BG.png 换成你的留白底图，文字用 px 叠在留白侧（定尺 .slide，靠 fit 整体缩放——别用 vw）；
3. 合成翻页：把每页塞进 assets/skeleton/deck.html 的 .slide 里，浏览器打开，← → / 空格 / 点击翻页，全屏自动缩放；
4. 体检：python3 scripts/deckcheck.py index.html（截全每页 + 查溢出 + 扫色差缝）。

换风格：改 style-claymation.css 里 :root 的 CSS 变量（配色 / 字体 / 圆角）+ 标题样式即可，黏土只是默认示例。

deck → 视频（可选）

deck 默认是静态翻页页面，可一键转成动态 MP4（hyperframes，HeyGen 的 HTML→视频框架）：

bash scripts/deck-to-video.sh <deck目录> <输出工程目录>   # 脚手架：建工程 + 拷素材 + 落 composition 模板
# 按 references/hyperframes.md 把 deck 填进 index.html，再：
cd <输出工程目录> && npm run check && npm run render        # 出片在 renders/*.mp4

原 deck 的 index.html 始终只读不改，composition 是独立工程里的新文件。完整改造清单 + 踩坑见 references/hyperframes.md。

踩坑速查

完整清单见 references/pitfalls.md（13 条）。最高频的几个：

• imgen 不支持透明背景 → 出白底再用 chroma_cut.py 抠（自动阈值，白主体也保得住）
• 竖图素材塞进扁横条脸只剩一半 → 用横向构图 prompt 出「视频帧」素材
• 全屏 letterbox 色差缝 → body 底色 = slide 边缘色；deckcheck.py 自动扫四缘
• 封面标题跑右上 / 往下掉 → 用 flex 居中，别用 transform 居中（会被入场动效盖掉）；重新 flex 化 .slide 要写 flex-direction:row
• 单页内容溢出 1080 → 压元素高度 / 间距（deckcheck.py 自动检测）
• 信息页版式雷同 → 先出拼接结构图、逐页照对应格排版（别套一个模板凭空写每页）

来源说明

本 skill 从一个个人短视频项目里抽出来，已脱去项目专属设定（沙盒规则 / 目录约定 / 特定受众 / 对其他私有 skill 的引用），方法论与踩坑清单是通用的。底图视觉默认是黏土风，改 style-claymation.css 的 :root 变量（配色 / 字体 / 圆角）+ 标题样式即可换成任意风格（玻璃科技 / 等距 2.5D / 杂志极简…）——examples/codex-ppt/ 就是换成「粉蓝玻璃风」的一例。

Platform

Tested on macOS. deckcheck.py / preview.sh 跨平台找 chromium（macOS / Linux / Windows git-bash），其余是纯 HTML/CSS/Python，理论跨平台但仅在 macOS 验证过。deck-to-video.sh 依赖 npx（Node）。

License

MIT — see LICENSE.