Visual Deck

visual-deck · 图文混合演示稿

把一个选题/大纲，做成一套全屏播放的图文演示稿（可翻页；默认横版 16:9，比例可换）。

为什么是「图 + HTML 混合」，不是纯图也不是纯 HTML

这是这个 skill 的核心判断，先理解它，后面每一步都顺：

imgen 擅长整张渲染的质感（人物、3D 元素、场景光影浑然一体）；HTML 擅长准确文字、排版、交互。所以：让 imgen 出视觉底图、HTML 叠准确文字，差距就没了。

但反过来也成立：imgen 画不准结构化信息（波形、表格、代码、时间线会糊）。所以这类页反而纯 HTML 更好，而且这类页本来也没有 3D 质感差距。

→ 结论：逐页判类型，视觉页走「图+叠字」，信息页走「纯 HTML」。

流程总览

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

核心顺序：先出拼接图定下每页版式，再照着排 HTML。跳过这步直接凭空写页，每页会套成同一个骨架（版式雷同，一眼就嫌「结构都差不多」）。

比例不写死：默认横版（导出视频也常是横屏），全套统一。要换比例只改 style-claymation.css 的 --slide-w/--slide-h 一处，骨架的 fit 读 slide 实际尺寸自适应、imgen 出图尺寸跟着换。

imgen 是一个文生图 CLI（输出 PNG，-s 尺寸 / -q 质量 / -o 输出，-i 图生图），不是本 skill 自带、也非通用公开工具。 换环境：把你自己的文生图 CLI 别名成 imgen 并对齐参数，或先用任意工具按 prompt 模板的构图把底图出好直接丢进页面。只用信息页/组件库的话不需要它。详见 README 的「关于 imgen」。

第 1 步 · 选题 → 大纲

和用户敲定选题后，列一个逐页大纲，每页标三件事：① 这页讲什么 ② 屏上放什么 ③ 页类型（视觉页 / 信息页）。

真实底线（最重要）：经历、数字、踩坑细节，AI 不编。用户没给的留 > [!待补] 占位问用户，绝不推测补全。

判类型的依据：

• 视觉页：封面、章节卡、有人物/吉祥物/3D 物件、靠「氛围和质感」的页
• 信息页：波形、时间线、对比、表格、字幕列表、终端/代码、流程步骤、清单——靠「结构和准确」的页

第 1.5 步 · 出拼接结构总览图（动手画任何一页之前先做）

这一步同时定两件事：① 全套统一的风格 ② 每页各自的版式。 一张「把所有页缩略拼在一起」的总览图，既能一眼看全套风格，又顺带把版式也定了，正好治「每页长一个样」。

做法：把逐页大纲交给 imgen，让它出一张「把所有页缩略拼在一张」的结构总览图（contact-sheet / montage）——每格一页、每页点名一个不同版式（封面式 / 横向流程 / 大数字 / 侧栏清单 / 左右对照 / 结尾…）、整套风格统一、吉祥物贯穿。图里文字用灰条占位即可（NO readable letters，准确字之后 HTML 叠，别指望 imgen 写对，坑#7）。

• 想给用户选择感，就 -n 2/-n 3 出版式编排不同的变体让用户挑一张。
• 锁既定风格和吉祥物：用 imgen -i 参考图.png 图生图出。
• 选定后，这张拼接图就是排版蓝本：第 2、3 步逐页做 HTML 时，照它每一格的布局排。
• prompt 模板见 → references/imgen-prompts.md（A0 节）。

⚠ 别跳过这步、套一个统一模板凭空写每页 HTML——那样每页骨架会长一个样（顶部标题条 + 中间一块居中卡），一眼就嫌「结构都差不多」（坑#13）。风格统一 ≠ 版式统一：配色 / 字体 / 质感 / 吉祥物全程一致（这是品牌），但每页 layout 要换（这是节奏）。版式从拼接图来，逐页照对应格排，每页天然不同。

只有 2-3 页的极简稿、且不需要版式多样时，才退回轻量办法「抽卡定风格」（同一构图换 4-6 个风格词各出一张只挑风格，见 imgen-prompts.md D 节）。

第 2 步 · 视觉页（图当底 + HTML 叠字）

这是本 skill 的招牌做法，分两半：

2a. imgen 出「留白底图」

关键是 prompt 要让 imgen 把主体放一侧、另一侧留白、不放主标题文字——给 HTML 叠字腾地方。出图是不透明整图（当背景用，不抠图）。详细 prompt 模板见 → references/imgen-prompts.md。

bashCopy code
# 尺寸跟 slide 比例走：默认横版 1536x864（16:9）；换比例就换尺寸（如竖版 864x1536）
imgen "<构图: 主体在右/中, 另一侧留白, NO text>, <风格词>" -s 1536x864 -q high -o bg.png

2b. HTML 把底图当 slide 背景 cover + px 叠字

用 assets/skeleton/visual-page.html 当模板。视觉页和信息页同为「定尺 .slide」（视觉页多挂一个 bgcover class），整块复制进 deck 零返工。要点：

• 底图设到 .slide 的 --bg-img，bgcover 让它 center/cover 铺满这一页
• 文字块用 px（slide 是定尺、靠 fit 整体缩放）——别用 vw，vw 是视口相对的，进 deck 缩放后会变形
• 居中交给 flex（bgcover 已是 row + align-items:center），别用 transform 居中（会被入场动效盖掉，坑#8）

第 3 步 · 信息页（纯 HTML/CSS）

逐页照拼接图对应格的布局排——别所有信息页都套同一个「顶部标题条 + 中间一块居中卡」骨架（版式雷同，坑#13）。同一套组件、换不同布局：有的页大数字压底、有的左右分栏、有的侧栏竖排、有的倾斜抽卡。

用 assets/style-claymation.css——这是一套现成的黏土/卡通风组件库（卡片、徽章、立体标题、波形、时间线、删除前后帧、字幕表、终端窗、文件图标、标签云、步骤条…），照着 assets/skeleton/info-page.html 拼。

风格不锁死黏土：换风格就改 :root 里的 CSS 变量（配色/字体/圆角）+ 改标题样式。黏土只是默认示例。

需要的立体小图标/人物素材（CSS 画不出的），用 imgen 出白底图再抠透明：见 scripts/chroma_cut.py 和踩坑清单。

第 3.5 步 · 质感：多用 imgen 实体素材，别堆纯 CSS

信息页全靠 CSS 扁平卡，会和封面的 imgen 质感拉开落差、显得「豆腐块」。两个高 ROI 手法补上：

• 吉祥物贯穿全场：出一个统一吉祥物（机器人 / 小人…），imgen 白底图 → chroma_cut 抠透明 → 当 <img> 在每页复用（封面放大、信息页放角落做「指向 / 反应」）。给全套角色感 + 一致性。必须是同一只：复用同一张 cutout，或用 imgen -i 本体图 图生图出「指 / 点赞 / 举牌」等姊妹姿势——别每页重新文生图，会变脸。prompt 见 references/imgen-prompts.md C2 节。
• 焦点换 imgen 物件：信息页每页 1-2 个 imgen 3D/等距物件（话筒 / 文档 / 网格…）当焦点，替代纯色块，把信息页质感拉到和封面齐平；文字仍走 HTML（保准确，别让 imgen 写字）。

别用 emoji 当图标（🎭👍✅ 这类）：系统/平台渲染不一、一眼掉质感。图标一律 imgen 小图标抠透明当 <img>，或干净 CSS（✓ ✕ → 这类纯符号可以，彩色 emoji 不行）。

第 4 步 · 合成可翻页全屏

把所有页装进一个 index.html，← → / 点击 / 空格翻页，全屏自适应。用 assets/skeleton/deck.html 骨架（含翻页 JS + 入场动效 + 全屏缩放）。视觉页和信息页同为定尺 .slide，整块复制进来即可、不用改定位。想要一份完整范本照着改：见 examples/。

第 5 步 · 体检 + 截图预览

先跑 scripts/deckcheck.py 自动体检（python playwright），一次拿到：① 每页干净截图 ② 哪页内容溢出 slide 高被截（坑#5）③ 四缘有没有色差缝（坑#4——这是最坑的一层，别再靠肉眼采样）：

bashCopy code
python3 scripts/deckcheck.py index.html _check     # 截图落 _check/，有问题退出码=1 并列出

要单独截某页（本机常没装 Chrome，用封装好的 headless，跨 macOS/Linux）：

bashCopy code
bash scripts/preview.sh 03-页.html out.png         # 单页
bash scripts/preview.sh index.html#3 out3.png      # deck 第 3 页（靠 location.hash）

第 6 步 · 出动态视频（可选 · hyperframes）

deck 默认是静态翻页页面；要让它动起来出成 MP4，用 hyperframes（HeyGen 的 HTML→视频框架，npx hyperframes）。不用 Remotion——那个要把 deck 重写成 React，纯重做。

铁律：绝不改原 deck 的 index.html——它是要直接拿去用的成品。出视频用的 composition 一律是独立工程里的新文件（deck-to-video.sh 把 deck 当只读、产出落独立目录，且加锁拒绝覆盖原 deck）。

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

核心改造：每页改成 clip（data-start/duration/track-index，框架按时间窗自动翻页）→ 去掉 fit()/交互翻页 → 入场动效交给 GSAP 时间轴（挂 window.__timelines["main"]）→ 图片进 assets/、复用图加 ?N 唯一化。完整清单 + 踩坑（中文字体 fallback、确定性逻辑限制等）见 → references/hyperframes.md，模板 assets/skeleton/hf-composition.html。

渲完务必抽帧自检：ffmpeg -ss 1.6 -i renders/*.mp4 -frames:v 1 /tmp/chk.png —— 看中文有没有掉、动效/图在不在。

踩过的坑（动手前必读）

这套流程踩过不少坑，开工前先读 → references/pitfalls.md。最高频的几个：

• imgen 不支持透明背景（-b transparent 报 400）→ 出白底再抠
• 竖图素材塞进扁横条脸只剩一半 → 用横向构图 prompt 出「视频帧」素材
• 全屏 letterbox 色差缝 → body 底色 = slide 边缘色；底图当 slide 背景 cover 铺满；全屏遮罩用 90deg 水平别用斜向（坑#4，deckcheck.py 能自动扫出来）
• 封面标题跑到右上 / 往下掉 → 用 flex 居中别用 transform 居中（会被入场动效盖掉），重新 flex 化 .slide 要写 flex-direction:row（坑#8/#9）
• 单页内容溢出 slide 高 → 压元素高度/间距，别硬塞（deckcheck.py 自动检测）
• 信息页版式雷同（套一个模板凭空写每页）→ 先出拼接结构总览图、逐页照对应格排版（坑#13、第 1.5 步）

产出去哪

产出（HTML/CSS/JS/素材/预览图）落到一个工作目录，别动项目里无关的文件。要不要分「草稿/定稿」目录、成片（mp4/mov）要不要进 git，按你所在项目的约定来。

默认风格取向（可按项目改）

并入 references/pitfalls.md 第 12 条（扁平描边别用 3D 挤出字 / 信息页留白 / 文案直白 / 经历数字不编），单一出处，改一处即可。