---
name: html-product-showcase
description: 根据产品特点、目标用户与真实功能证据设计 HTML/CSS/SVG 产品展示动画，选择合适的动效与分镜，交付可 seek 的网页、MP4 和可复用项目；支持横竖屏重新编排与配音字幕。
version: 0.1.0
author: Shenrui Ma（四倍体果蝇）
license: "See LICENSES.md for component terms"
platforms: [linux, macos]
---

# HTML 产品展示动画

交付目标：围绕产品实际价值的一支展示动画，以及可编辑 HTML、时间线、资产清单和视频。先理解产品，再选择动画手法；示例只演示技术，不作为固定片头、布局或分镜。

## 1. 理解产品与任务

从用户描述、提供的产品文档、可访问页面或代码中确认：面向谁、解决什么问题、最值得展示的 1–3 个特点、可以展示的证据。只查与当前产品有关的资料。缺少产品本身或核心信息时补问；其他可选参数用合理默认并记录。

默认中文、1920×1080、30fps、约 20–30 秒、无声，无固定角色贴纸。用户指定平台时按其比例与观看场景重排；3:4、9:16 和16:9分别设计。新建版本目录，保存需求、素材来源与哈希，保留已接受版本。

区分真实界面录制、演示状态和概念解释。演示数值不能冒充性能测试；未确认功能不编成卖点。实体产品没有可用照片/模型时，提供清晰标注的示意结构，不能把 CSS 假3D说成精确产品建模。

## 2. 把特点变成分镜

读[产品叙事方法](references/product-design.md)，为每个候选镜头写：

`观众的问题 → 产品主张 → 可见证据 → 状态怎样变化 → 最终应读懂什么`。

选择能证明当前卖点的手法，见[动画技巧库](references/motion-patterns.md)。可以直接展示成果、用前后对比、跟随一次任务或拆解结构；无需固定“痛点→功能→安装→远程”顺序，也不为凑页数加无关镜头。

用 [storyboard.json](examples/storyboard.json) 记录镜头与节拍。每镜留出稳定阅读时间，主体转移才移动视线。先按最终最大信息量布置标题、演示区和可选字幕安全区，再添加动效。空间不够就拆段或分时，不先缩小所有字。

## 3. 编写确定性 HTML 动画

读[制作契约](references/production.md)，参考 [技术骨架](examples/film.html) 与 [纯时间函数](scripts/motion.js)。根据本次分镜重新编写 `film.html`，不只替换示例标题。

- CSS 负责排版，SVG 负责路径、矢量部件和标注，JavaScript 只按叙事时间设置状态。UI 文本用真实 DOM，复杂照片保比例作为资产。
- 暴露 `window.setShotTime(seconds)`；每次完整重算文本、变换、颜色、进度、可见性。先跳后再退必须恢复相同状态，不依赖调用顺序。
- 一份 HTML 可以容纳整支影片；场景起点来自编译时间线。局部时间为 `t-global_start`，重叠期明确绘制相邻场景并设置各自透明度。
- 禁止让 CSS transition、timer、Web Animations、视频、粒子或随机数各自跑时钟。随机样式固定 seed；如使用 WAAPI，暂停并显式设置 currentTime；视频素材需显式 seek 并等待解码。
- `#stage` 填满导出画布；重要元素标 `data-protected`，可选角色标 `data-mascot`。横竖屏重排组件、路径和节奏，截图不拉伸。
- 本地保存实际需要的资源；不依赖 CDN、在线字体或登录状态。链接和箭头从同一坐标系求锚点，先布局再测量，不猜目标坐标。

## 4. 时间线、声音与视频

从仓库根目录运行，`PROJECT` 为新项目目录，`RECIPE` 为本模板目录：

```bash
python3 "$RECIPE/scripts/plan.py" "$PROJECT/storyboard.json" --output "$PROJECT/timeline.json"
# 根据时间线完成 film.html，并把 motion.js 放到项目的 scripts/ 中。
node "$RECIPE/scripts/render-film.cjs" "$PROJECT/film.html" "$PROJECT/output.mp4" 1920 1080 30 30
```

最后四个参数是宽、高、秒数、fps；按 `timeline.json` 实值填写，示例的30秒不是固定模板长度。渲染器输出无声视频及 `.qc.json`，不会自动从网页录取音频。缺依赖先复用现有安装；新装须遵循当前环境与用户授权，不改用户浏览器配置。

需要配音时按真实录音时长安排镜头，不截句尾；字幕跟随最终时间线，变速后同步重算。已接受配音可以复用，新配音按当前请求选择服务。添加 BGM 或组合已渲染片段可复用[合集剪辑 Skill](../../../skills/character-showcase-editing/SKILL.md)的 D 模式，设置 `layout.mode=plain`、相同画布，转场和尾淡出显式填写，避免把已完成的 HTML 动效重复处理。详细音频/多镜头规则见制作契约。

## 5. 检查、修正、交付

先检查字体和图像加载、JS 错误、时间回跳、实际 DOM 边界、入场过冲、长文本、字幕占位和场景交接。渲染器的机械检查不代表视觉审美通过；按当前任务允许的检查范围验收。只整理 Skill 或检查文件时不调用推理、不生成媒体，不把计划说成成片。

HTML 或依赖资产改变后使对应渲染失效；只改音轨时复用已锁定视频。失败只重做受影响部分，输出始终选新版本。视频完成以编码、规格和完整解码结果为据，之后交付 HTML、素材、时间线、MP4、检查记录与未验项。发布或发送到外部账号依照用户实际授权处理。

整理：**Shenrui Ma（四倍体果蝇）**。