wizz-method 1.0.2 → 1.1.0

package/src/skills-lib/huashu-design/references/editable-pptx.md

@@ -0,0 +1,334 @@
+# 可编辑 PPTX 导出：HTML 硬约束 + 尺寸决策 + 常见错误
+
+本文档讲的是**用 `scripts/html2pptx.js` + `pptxgenjs` 把 HTML 逐元素翻译成真·可编辑 PowerPoint 文本框**的路径，也是 `export_deck_pptx.mjs` 唯一支持的路径。
+
+> **核心前提**：要走这条路，HTML 必须从第一行就按下面 4 条约束写。**不是写完再转**——事后补救会触发 2-3 小时返工（2026-04-20 期权私董会项目实测踩坑）。
+>
+> 视觉自由度优先的场景（动画 / web component / CSS 渐变 / 复杂 SVG）请改走 PDF 路径（`export_deck_pdf.mjs` / `export_deck_stage_pdf.mjs`），**不要**指望 pptx 导出能兼得视觉保真和可编辑——这是 PPTX 文件格式本身的物理约束（见文末「为什么 4 条约束不是 Bug 而是物理约束」）。
+
+---
+
+## 画布尺寸：用 960×540pt（LAYOUT_WIDE）
+
+PPTX 单位是 **inch**（物理尺寸），不是 px。决策原则：body 的 computedStyle 尺寸要**匹配 presentation layout 的 inch 尺寸**（±0.1"，由 `html2pptx.js` 的 `validateDimensions` 强制检查）。
+
+### 3 个候选尺寸对比
+
+| HTML body | 物理尺寸 | 对应 PPT layout | 何时选 |
+|---|---|---|---|
+| **`960pt × 540pt`** | **13.333″ × 7.5″** | **pptxgenjs `LAYOUT_WIDE`** | ✅ **默认推荐**（现代 PowerPoint 16:9 标配） |
+| `720pt × 405pt` | 10″ × 5.625″ | 自定义 | 仅当用户指定「老版 PowerPoint Widescreen」模板时 |
+| `1920px × 1080px` | 20″ × 11.25″ | 自定义 | ❌ 非标尺寸，投影后字体显得异常小 |
+
+**别把 HTML 尺寸当分辨率想。** PPTX 是矢量文档，body 尺寸决定的是**物理尺寸**不是清晰度。超大 body（20″×11.25″）不会让文字更清晰——只会让字号 pt 相对画布变小，投影/打印时反而更难看。
+
+### body 写法三选一（等价）
+
+```css
+body { width: 960pt;  height: 540pt; }    /* 最清晰，推荐 */
+body { width: 1280px; height: 720px; }    /* 等价，px 习惯 */
+body { width: 13.333in; height: 7.5in; }  /* 等价，英寸直觉 */
+```
+
+配套的 pptxgenjs 代码：
+
+```js
+const pptx = new pptxgen();
+pptx.layout = 'LAYOUT_WIDE';  // 13.333 × 7.5 inch, 无需自定义
+```
+
+---
+
+## 4 条硬约束（违反会直接报错）
+
+`html2pptx.js` 把 HTML 的 DOM 逐元素翻译成 PowerPoint 对象。PowerPoint 的格式约束投射到 HTML 上 = 下面 4 条规则。
+
+### 规则 1：DIV 里不能直接写文字 — 必须用 `<p>` 或 `<h1>`-`<h6>` 包裹
+
+```html
+<!-- ❌ 错误：文字直接在 div 里 -->
+<div class="title">Q3营收增长23%</div>
+
+<!-- ✅ 正确：文字在 <p> 或 <h1>-<h6> 里 -->
+<div class="title"><h1>Q3营收增长23%</h1></div>
+<div class="body"><p>新用户是主要驱动力</p></div>
+```
+
+**为什么**：PowerPoint 文本必须存在 text frame 里，text frame 对应 HTML 的段落级元素（p/h*/li）。裸 `<div>` 在 PPTX 里没有对应的文本容器。
+
+**也不能用 `<span>` 承载主文字**——span 是行内元素，没法独立对齐成文本框。span 只能**夹在 p/h\* 里**做局部样式（加粗、换色）。
+
+### 规则 2：不支持 CSS 渐变 — 只能用纯色
+
+```css
+/* ❌ 错误 */
+background: linear-gradient(to right, #FF6B6B, #4ECDC4);
+
+/* ✅ 正确：纯色 */
+background: #FF6B6B;
+
+/* ✅ 如果必须多色条纹，用 flex 子元素各自纯色 */
+.stripe-bar { display: flex; }
+.stripe-bar div { flex: 1; }
+.red   { background: #FF6B6B; }
+.teal  { background: #4ECDC4; }
+```
+
+**为什么**：PowerPoint 的 shape fill 只支持 solid/gradient-fill 两种，但 pptxgenjs 的 `fill: { color: ... }` 只映射 solid。渐变走 PowerPoint 原生 gradient 需要另写结构，目前工具链不支持。
+
+### 规则 3：背景/边框/阴影只能在 DIV 上，不能在文字标签上
+
+```html
+<!-- ❌ 错误：<p> 有背景色 -->
+<p style="background: #FFD700; border-radius: 4px;">重点内容</p>
+
+<!-- ✅ 正确：外层 div 承载背景/边框，<p> 只负责文字 -->
+<div style="background: #FFD700; border-radius: 4px; padding: 8pt 12pt;">
+  <p>重点内容</p>
+</div>
+```
+
+**为什么**：PowerPoint 里 shape（方块/圆角矩形）和 text frame 是两个对象。HTML 的 `<p>` 只翻译成 text frame，背景/边框/阴影属于 shape——必须在**包裹 text 的 div** 上写。
+
+### 规则 4：DIV 不能用 `background-image` — 用 `<img>` 标签
+
+```html
+<!-- ❌ 错误 -->
+<div style="background-image: url('chart.png')"></div>
+
+<!-- ✅ 正确 -->
+<img src="chart.png" style="position: absolute; left: 50%; top: 20%; width: 300pt; height: 200pt;" />
+```
+
+**为什么**：`html2pptx.js` 只从 `<img>` 元素提取图片路径，不解析 CSS 的 `background-image` URL。
+
+---
+
+## 合并文本框（`data-pptx-merge`）
+
+**默认行为**：HTML 里每个 `<p>`/`<h1>`-`<h6>` 在 PPTX 里都是**独立文本框**。卡片里写 3 个 `<p>` → PPT 里 3 个文本框摞着，编辑时不能整段回车换行加段，得逐个改字号/对齐。
+
+**解决方法**：给外层 div 加 `data-pptx-merge="true"`，容器内的所有 `<p>/<h*>` 会合并为**一个可编辑文本框**，每段之间用段落分隔符隔开，PPT 里就是一段一段连续编辑。
+
+```html
+<!-- ✅ 合并写法：4 段全部在一个文本框里 -->
+<div class="card" data-pptx-merge="true"
+     style="position: absolute; top: 60pt; left: 60pt; width: 420pt;
+            background: #1A4A8A; border-radius: 8pt; padding: 20pt 24pt;">
+  <h2 style="font-size: 24pt; color: #FFFFFF;">标题</h2>
+  <p  style="font-size: 14pt; color: #DDEEFF;">第一段正文。</p>
+  <p  style="font-size: 14pt; color: #FFD166;">第二段：换颜色作为强调。</p>
+  <p  style="font-size: 14pt; color: #DDEEFF;">第三段：同一个文本框里继续写。</p>
+</div>
+```
+
+**保留的样式**（per-paragraph 作为 run options 写入）：`font-size`、`color`、`font-family`、`font-weight`（bold）、`font-style`（italic）、`text-decoration: underline`、`<b>/<i>/<u>/<strong>/<em>/<span>` 内联样式。
+
+**取自第一段、整框统一**：`text-align`、`line-height`。因为 PowerPoint 的对齐和行距是 paragraph/textbox 级别——一框里只能有一种对齐。如果几段对齐不同，请别用 merge，让它们各自独立。
+
+**容器自身的 `background`/`border`/`box-shadow`/`border-radius`** 照常作为 shape 渲染，行为和普通 div 完全一样——也就是说蓝色卡片底 + 文本仍然是「shape + text frame」两层，只是文本层从 3-4 个文本框塌缩成 1 个。
+
+**限制**：
+- 不能嵌套 `data-pptx-merge`（会报错）。
+- 容器不能用 `background-image`（同 4 条硬约束规则 4）。
+- 容器内不要再放有 `background`/`border` 的子 div——它们仍会被当作独立 shape 渲染，但里面的文字已被合并走了，可能产生视觉错位。
+
+**什么时候用**：内容会反复改、要在 PPT 里继续编辑的场景。一次性导出归档的不用加，行为一致。
+
+---
+
+## Path A HTML 模板骨架
+
+每张 slide 一个独立 HTML 文件，彼此作用域隔离（避开单文件 deck 的 CSS 污染）。
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    width: 960pt; height: 540pt;           /* ⚠️ 匹配 LAYOUT_WIDE */
+    font-family: system-ui, -apple-system, "PingFang SC", sans-serif;
+    background: #FEFEF9;                    /* 纯色，不能渐变 */
+    overflow: hidden;
+  }
+  /* DIV 负责布局/背景/边框 */
+  .card {
+    position: absolute;
+    background: #1A4A8A;                    /* 背景在 DIV 上 */
+    border-radius: 4pt;
+    padding: 12pt 16pt;
+  }
+  /* 文字标签只负责字体样式，不加背景/边框 */
+  .card h2 { font-size: 24pt; color: #FFFFFF; font-weight: 700; }
+  .card p  { font-size: 14pt; color: rgba(255,255,255,0.85); }
+</style>
+</head>
+<body>
+
+  <!-- 标题区：外层 div 定位，内层文字标签 -->
+  <div style="position: absolute; top: 40pt; left: 60pt; right: 60pt;">
+    <h1 style="font-size: 36pt; color: #1A1A1A; font-weight: 700;">标题用断言句，不是主题词</h1>
+    <p style="font-size: 16pt; color: #555555; margin-top: 10pt;">副标题补充说明</p>
+  </div>
+
+  <!-- 内容卡片：div 负责背景，h2/p 负责文字 -->
+  <div class="card" style="top: 130pt; left: 60pt; width: 240pt; height: 160pt;">
+    <h2>要点一</h2>
+    <p>简短说明文字</p>
+  </div>
+
+  <!-- 列表：使用 ul/li，不用手动 • 符号 -->
+  <div style="position: absolute; top: 320pt; left: 60pt; width: 540pt;">
+    <ul style="font-size: 16pt; color: #1A1A1A; padding-left: 24pt; list-style: disc;">
+      <li>第一条要点</li>
+      <li>第二条要点</li>
+      <li>第三条要点</li>
+    </ul>
+  </div>
+
+  <!-- 插图：用 <img> 标签，不用 background-image -->
+  <img src="illustration.png" style="position: absolute; right: 60pt; top: 110pt; width: 320pt; height: 240pt;" />
+
+</body>
+</html>
+```
+
+---
+
+## 常见错误速查
+
+| 错误信息 | 原因 | 修复方法 |
+|---------|------|---------|
+| `DIV element contains unwrapped text "XXX"` | div 里有裸文字 | 把文字包进 `<p>` 或 `<h1>`-`<h6>` |
+| `CSS gradients are not supported` | 用了 linear/radial-gradient | 改为纯色，或用 flex 子元素分段 |
+| `Text element <p> has background` | `<p>` 标签加了背景色 | 外套 `<div>` 承载背景，`<p>` 只写文字 |
+| `Background images on DIV elements are not supported` | div 用了 background-image | 改为 `<img>` 标签 |
+| `HTML content overflows body by Xpt vertically` | 内容超出 540pt | 减少内容或缩小字号，或 `overflow: hidden` 截断 |
+| `HTML dimensions don't match presentation layout` | body 尺寸和 pres layout 对不上 | body 用 `960pt × 540pt` 配 `LAYOUT_WIDE`；或 defineLayout 自定义尺寸 |
+| `Text box "XXX" ends too close to bottom edge` | 大字号 `<p>` 距离 body 底边 < 0.5 inch | 往上挪，留足下边距；PPT 底部本身就会被遮住一部分 |
+
+---
+
+## 基本工作流（3 步出 PPTX）
+
+### Step 1：按约束写每页独立 HTML
+
+```
+我的Deck/
+├── slides/
+│   ├── 01-cover.html    # 每个文件都是完整 960×540pt HTML
+│   ├── 02-agenda.html
+│   └── ...
+└── illustration/        # 所有 <img> 引用的图片
+    ├── chart1.png
+    └── ...
+```
+
+### Step 2：写 build.js 调用 `html2pptx.js`
+
+```js
+const pptxgen = require('pptxgenjs');
+const html2pptx = require('../scripts/html2pptx.js');  // 本 skill 脚本
+
+(async () => {
+  const pres = new pptxgen();
+  pres.layout = 'LAYOUT_WIDE';  // 13.333 × 7.5 inch，匹配 HTML 的 960×540pt
+
+  const slides = ['01-cover.html', '02-agenda.html', '03-content.html'];
+  for (const file of slides) {
+    await html2pptx(`./slides/${file}`, pres);
+  }
+
+  await pres.writeFile({ fileName: 'deck.pptx' });
+})();
+```
+
+### Step 3：打开检查
+
+- PowerPoint/Keynote 打开导出 PPTX
+- 双击任意文字应能直接编辑（如果是图片说明第 1 条违反了）
+- 验证 overflow：每页应该在 body 范围内，没有被截
+
+---
+
+## 这条路径 vs 其他选项（什么时候选什么）
+
+| 需求 | 选什么 |
+|------|------|
+| 同事会改 PPTX 里的文字 / 发给非技术人员继续编辑 | **本文路径**（editable，需从头按 4 条约束写 HTML） |
+| 只是演讲用 / 发存档，不再改 | `export_deck_pdf.mjs`（多文件）或 `export_deck_stage_pdf.mjs`（单文件 deck-stage），出矢量 PDF |
+| 视觉自由度优先（动画、web component、CSS 渐变、复杂 SVG），接受不可编辑 | **PDF**（同上）——PDF 既保真又跨平台，比「图片 PPTX」更合适 |
+
+**绝不要在视觉自由写好的 HTML 上硬跑 html2pptx**——实测视觉驱动的 HTML pass 率 < 30%，剩下的逐页改造比重写还慢。这种场景应该出 PDF，不是硬挤 PPTX。
+
+---
+
+## Fallback：已有视觉稿但用户坚持要 editable PPTX
+
+偶尔会遇到这个场景：你/用户已经写好一份视觉驱动的 HTML（渐变、web component、复杂 SVG 都用上了），本来出 PDF 最合适，但用户明确说「不行，必须是可编辑的 PPTX」。
+
+**不要硬跑 `html2pptx` 期待它 pass**——实测视觉驱动 HTML 在 html2pptx 上 pass 率 <30%，剩下 70% 会报错或走样。正确的 fallback 是：
+
+### Step 1 · 先告知局限性（透明沟通）
+
+一句话跟用户说清三件事：
+
+> 「你现在的 HTML 用了 [具体列出：渐变 / web component / 复杂 SVG / ...]，直接转 editable PPTX 会 fail。我有两个方案：
+> - A. **出 PDF**（推荐）——视觉 100% 保留，接收方能看能印但不能改文字
+> - B. **以视觉稿为蓝本，重写一版 editable HTML**（保留色彩/布局/文案的设计决策，但按 4 条硬约束重新组织 HTML 结构，**牺牲**渐变、web component、复杂 SVG 等视觉能力）→ 再导出 editable PPTX
+>
+> 你选哪个？」
+
+不要把 B 方案说得云淡风轻——明确告知**会丢失什么**。让用户做取舍。
+
+### Step 2 · 如果用户选 B：AI 主动改写，不要求用户自己写
+
+这里的 doctrine 是：**用户给的是设计意图，你负责翻译成合规实现**。不是让用户去学 4 条硬约束然后自己重写。
+
+改写时的遵循原则：
+- **保留**：色彩系统（主色/辅色/中性色）、信息层级（标题/副标题/正文/注解）、核心文案、layout 骨架（上中下 / 左右分栏 / 网格）、页面节奏
+- **降级**：CSS 渐变 → 纯色或 flex 分段、web component → 段落级 HTML、复杂 SVG → 简化的 `<img>` 或纯色几何、阴影 → 删除或降为极弱、自定义字体 → 向系统字体靠齐
+- **重写**：裸文字 → 包进 `<p>` / `<h*>`、`background-image` → `<img>` 标签、`<p>` 上的背景边框 → 外层 div 承载
+
+### Step 3 · 产出对照清单（透明交付）
+
+改写完成后给用户一份 before/after 对照，让他知道哪些视觉细节被简化了：
+
+```
+原设计 → editable 版调整
+- 标题区紫色渐变 → 主色 #5B3DE8 纯色背景
+- 数据卡片阴影 → 删除（改为 2pt 描边区分）
+- 复杂 SVG 折线图 → 简化为 <img> PNG（从 HTML 截图生成）
+- Hero 区 web component 动效 → 静态首帧（web component 无法翻译）
+```
+
+### Step 4 · 导出 & 双格式交付
+
+- `editable` 版 HTML → 跑 `scripts/export_deck_pptx.mjs` 出可编辑 PPTX
+- **建议同时保留**原视觉稿 → 跑 `scripts/export_deck_pdf.mjs` 出高保真 PDF
+- 双格式交付给用户：视觉稿的 PDF + 可编辑的 PPTX，各司其职
+
+### 什么情况下直接拒绝 B 方案
+
+个别场景下改写代价过高，应该劝用户放弃 editable PPTX：
+- HTML 核心价值是动画或交互（改写后只剩静态首帧，信息量损失 50%+）
+- 页数 > 30，改写成本超过 2 小时
+- 视觉设计深度依赖精确 SVG / 自定义 filter（改写后和原图几乎无关）
+
+此时告诉用户：「这个 deck 改写代价过高，建议出 PDF 而不是 PPTX。如果接收方确实要 pptx 格式，就接受视觉会大幅朴素化——要不要换成 PDF？」
+
+---
+
+## 为什么 4 条约束不是 Bug 而是物理约束
+
+这 4 条不是 `html2pptx.js` 作者偷懒——它们是 **PowerPoint 文件格式（OOXML）本身的约束**投射到 HTML 上的结果：
+
+- PPTX 里文字必须在 text frame（`<a:txBody>`），对应段落级 HTML 元素
+- PPTX 的 shape 和 text frame 是两个对象，无法在同一 element 上同时画背景和写文字
+- PPTX 的 shape fill 对 gradient 支持有限（仅某些 preset gradients，不支持 CSS 任意角度渐变）
+- PPTX 的 picture 对象必须引用真实图片文件，不是 CSS 属性
+
+理解这点后，**不要期待工具变聪明** —— 是 HTML 写法要适配 PPTX 格式，不是反过来。

package/src/skills-lib/huashu-design/references/hero-animation-case-study.md

@@ -0,0 +1,250 @@
+# Gallery Ripple + Multi-Focus · 场景编排哲学
+
+> 从 huashu-design hero 动画 v9（25 秒，8 场景）里提炼出的**一种可复用的视觉编排结构**。
+> 不是动画制作流水线，是**什么场景下这种编排是"对的"**。
+> 实战参考：[demos/hero-animation-v9.mp4](../demos/hero-animation-v9.mp4) · [https://www.huasheng.ai/huashu-design-hero/](https://www.huasheng.ai/huashu-design-hero/)
+
+## 一句话先行
+
+> **当你有 20+ 同质视觉素材、场景需要"表达规模感和深度"时，优先考虑 Gallery Ripple + Multi-Focus 这套编排，而不是堆砌排版。**
+
+通用 SaaS feature 动画、产品发布会、skill 推广、系列作品集展示——只要素材数量够、风格一致，这套结构几乎都能出效果。
+
+---
+
+## 这个手法究竟在表达什么
+
+不是"秀素材"——是通过**两个节奏变化**讲一个叙事：
+
+**第一拍 · Ripple 展开（~1.5s）**：从中心向四周扩散出 48 张卡片，观众被"量"震住——「哦，这东西有这么多产出」。
+
+**第二拍 · Multi-Focus（~8s，4 次循环）**：镜头在慢速 pan 的同时，4 次把背景 dim + desaturate，把某一张卡单独放大到屏幕中央——观众从"量的冲击"切换到"质的凝视"，每次 1.7s 节奏稳定。
+
+**核心叙事结构**：**规模（Ripple） → 凝视（Focus × 4） → 淡出（Walloff）**。这三拍组合起来表达的是「Breadth × Depth」——不只是能做很多，每一个还都值得停下来看。
+
+对比一下反例：
+
+| 做法 | 观众感知 |
+|------|---------|
+| 48 张卡静态排列（没有 Ripple）| 好看但无叙事，像一张 grid screenshot |
+| 一张一张快切（没有 Gallery context）| 像 slideshow，失去"规模感" |
+| 只有 Ripple 没有 Focus | 震住了但没让人记住任何具体一张 |
+| **Ripple + Focus × 4（本配方）** | **先震撼于量，再凝视于质，最后平静淡出——完整情绪弧线** |
+
+---
+
+## 前置条件（必须全部满足）
+
+这套编排**不是万能的**，下面 4 条缺一不可：
+
+1. **素材规模 ≥ 20 张，最好 30+**
+   少于 20 张 Ripple 会显得"空"——48 格里每格都在动才有密度感。v9 用了 48 格 × 32 张图（循环填充）。
+
+2. **素材视觉风格一致**
+   全是 16:9 slide 预览 / 全是 app 截图 / 全是封面设计——长宽比、色调、版式得像是"一套"。混搭会让 Gallery 看起来像剪贴板。
+
+3. **素材单独放大后仍有可读信息**
+   Focus 是把某张卡放大到 960px 宽，如果原图放大后糊了或信息稀薄，Focus 这一拍就废了。反向验证：能不能从 48 张里挑出 4 张作为"最有代表性"的？挑不出来就说明素材质量不齐。
+
+4. **场景本身是 landscape 或 square，不是竖屏**
+   Gallery 的 3D 倾斜（`rotateX(14deg) rotateY(-10deg)`）需要横向延伸感，竖屏会让倾斜效果看起来窄且别扭。
+
+**缺条件的后备路径**：
+
+| 缺什么 | 退化为什么 |
+|-------|-----------|
+| 素材 < 20 张 | 改用「3-5 张并排静态展示 + 逐个 focus」 |
+| 风格不一致 | 改用「封面 + 3 章节大图」的 keynote-style |
+| 信息稀薄 | 改用「data-driven dashboard」或「金句 + 大字」 |
+| 竖屏场景 | 改用「vertical scroll + sticky cards」 |
+
+---
+
+## 技术配方（v9 实战参数）
+
+### 4-Layer 结构
+
+```
+viewport (1920×1080, perspective: 2400px)
+  └─ canvas (4320×2520, 超大 overflow) → 3D tilt + pan
+      └─ 8×6 grid = 48 cards (gap 40px, padding 60px)
+          └─ img (16:9, border-radius 9px)
+      └─ focus-overlay (absolute center, z-index 40)
+          └─ img (matches selected slide)
+```
+
+**关键**：canvas 比 viewport 大 2.25 倍，这样 pan 才有"窥视更大世界"的感觉。
+
+### Ripple 展开（距离延迟算法）
+
+```js
+// 每张卡的入场时间 = 距中心的距离 × 0.8s 延迟
+const col = i % 8, row = Math.floor(i / 8);
+const dc = col - 3.5, dr = row - 2.5;       // 到中心的 offset
+const dist = Math.hypot(dc, dr);
+const maxDist = Math.hypot(3.5, 2.5);
+const delay = (dist / maxDist) * 0.8;       // 0 → 0.8s
+const localT = Math.max(0, (t - rippleStart - delay) / 0.7);
+const opacity = expoOut(Math.min(1, localT));
+```
+
+**核心参数**：
+- 总时长 1.7s（`T.s3_ripple: [8.3, 10.0]`）
+- 最大延迟 0.8s（中心最早出，角落最晚）
+- 每张卡入场时长 0.7s
+- Easing: `expoOut`（爆发感，不是平滑）
+
+**同时做的事**：canvas scale 从 1.25 → 0.94（zoom out to reveal）—— 配合出现的同步推远感。
+
+### Multi-Focus（4 次节奏）
+
+```js
+T.focuses = [
+  { start: 11.0, end: 12.7, idx: 2  },  // 1.7s
+  { start: 13.3, end: 15.0, idx: 3  },  // 1.7s
+  { start: 15.6, end: 17.3, idx: 10 },  // 1.7s
+  { start: 17.9, end: 19.6, idx: 16 },  // 1.7s
+];
+```
+
+**节奏规律**：每个 focus 1.7s，间隔 0.6s 喘息。总计 8s（11.0–19.6s）。
+
+**每次 focus 内部**：
+- In ramp: 0.4s（`expoOut`）
+- Hold: 中间 0.9s（`focusIntensity = 1`）
+- Out ramp: 0.4s（`easeOut`）
+
+**背景变化（这是关键）**：
+
+```js
+if (focusIntensity > 0) {
+  const dimOp = entryOp * (1 - 0.6 * focusIntensity);  // dim to 40%
+  const brt = 1 - 0.32 * focusIntensity;                // brightness 68%
+  const sat = 1 - 0.35 * focusIntensity;                // saturate 65%
+  card.style.filter = `brightness(${brt}) saturate(${sat})`;
+}
+```
+
+**不只是 opacity——同时 desaturate + darken**。这让前景 overlay 的色彩"跳出来"，而不是只是"变亮一点"。
+
+**Focus overlay 尺寸动画**：
+- 从 400×225（入场）→ 960×540（hold 态）
+- 外围有 3 层 shadow + 3px accent 色 outline ring，呈现"被框住的感觉"
+
+### Pan（持续感让静止不无聊）
+
+```js
+const panT = Math.max(0, t - 8.6);
+const panX = Math.sin(panT * 0.12) * 220 - panT * 8;
+const panY = Math.cos(panT * 0.09) * 120 - panT * 5;
+```
+
+- 正弦波 + 线性 drift 双层运动——不是纯循环，每个时刻位置都不同
+- X/Y 频率不同（0.12 vs 0.09）避免视觉上看出"规律循环"
+- clamp 在 ±900/500px 防止漂出
+
+**为什么不用纯线性 pan**：纯线性观众会"预测"下一秒在哪；正弦+drift 让每一秒都是新的，3D 倾斜下产生"微晕船感"（好的那种），注意力被拉住。
+
+---
+
+## 5 个可复用模式（从 v6→v9 迭代中蒸馏）
+
+### 1. **expoOut 作为主 easing，不是 cubicOut**
+
+`easeOut = 1 - (1-t)³`（平滑）vs `expoOut = 1 - 2^(-10t)`（爆发后迅速收敛）。
+
+**选择理由**：expoOut 的前 30% 很快达到 90%，更像物理阻尼，符合"重的东西落地"的直觉。特别适合：
+- 卡片入场（重量感）
+- Ripple 扩散（冲击波）
+- Brand 浮起（落定感）
+
+**什么时候仍用 cubicOut**：focus out ramp、对称的微动效。
+
+### 2. **纸感底色 + 赤陶橙 accent（Anthropic 血统）**
+
+```css
+--bg: #F7F4EE;        /* 暖纸 */
+--ink: #1D1D1F;       /* 几乎黑 */
+--accent: #D97757;    /* 赤陶橙 */
+--hairline: #E4DED2;  /* 暖线条 */
+```
+
+**为什么**：温暖底色在 GIF 压缩后依然有"呼吸感"，不像纯白会显得"屏幕感"。赤陶橙作为唯一 accent 贯穿 terminal prompt、dir-card 选中、cursor、brand hyphen、focus ring——所有视觉锚点都被这一个色串起来。
+
+**v5 教训**：加了 noise overlay 以模拟"纸纹"，结果 GIF 帧压缩全废（每帧都不同）。v6 改为"只用底色 + 暖 shadow"，纸感保留 90%，GIF 体积缩小 60%。
+
+### 3. **两档 Shadow 模拟深度，不用真 3D**
+
+```css
+.gallery-card.depth-near { box-shadow: 0 32px 80px -22px rgba(60,40,20,0.22), ... }
+.gallery-card.depth-far  { box-shadow: 0 14px 40px -16px rgba(60,40,20,0.10), ... }
+```
+
+用 `sin(i × 1.7) + cos(i × 0.73)` 确定性算法给每张卡分配 near/mid/far 三档 shadow——**视觉上有"三维堆叠"感，但每帧 transform 完全不变，GPU 消耗 0**。
+
+**真 3D 的代价**：每个 card 单独 `translateZ`，GPU 每帧都在算 48 个 transform + shadow blur。v4 试过，Playwright 录制 25fps 都吃力。v6 的两档 shadow 肉眼效果差距 <5%，但成本差 10 倍。
+
+### 4. **字重变化（font-variation-settings）比字号变化更电影感**
+
+```js
+const wght = 100 + (700 - 100) * morphP;  // 100 → 700 over 0.9s
+wordmark.style.fontVariationSettings = `"wght" ${wght.toFixed(0)}`;
+```
+
+Brand wordmark 从 Thin → Bold 用 0.9s 渐变，配合 letter-spacing 微调（-0.045 → -0.048em）。
+
+**为什么比放大缩小好**：
+- 放大缩小观众看过太多，预期固化
+- 字重变化是"内在的充实感"，像气球被吹满，而不是"被推近"
+- variable fonts 是 2020+ 才普及的特性，观众下意识感觉"现代"
+
+**限制**：必须用支持 variable font 的字体（Inter/Roboto Flex/Recursive 等）。普通静态字体只能拟态（切换几个固定 weight 有跳变）。
+
+### 5. **Corner Brand 低强度持续签名**
+
+Gallery 阶段左上角有个 `HUASHU · DESIGN` 小标识，16% opacity 色值，12px 字号，宽字距。
+
+**为什么加这个**：
+- Ripple 爆发后观众容易"失焦"不记得在看什么，左上角轻标示帮助 anchor
+- 比全屏大 logo 更高级——做品牌的人知道，品牌签名不需要喊
+- 在 GIF 被截屏分享时仍留下归属信号
+
+**规则**：只在中段（画面 busy）出现，开场关闭（不遮 terminal），结尾关闭（brand reveal 是主角）。
+
+---
+
+## 反例：什么时候不要用这套编排
+
+**❌ 产品演示（要展示功能的）**：Gallery 让每一张都一闪而过，观众记不住任何一个功能。改用「单屏 focus + tooltip 标注」。
+
+**❌ 数据驱动内容**：观众要读数字，Gallery 的快速节奏不给时间读。改用「数据图表 + 逐项 reveal」。
+
+**❌ 故事叙事**：Gallery 是"并列"结构，故事需要"因果"。改用 keynote 章节切换。
+
+**❌ 素材只有 3-5 张**：Ripple 密度不够，看起来像"补丁"。改用「静态排列 + 逐张高亮」。
+
+**❌ 竖屏（9:16）**：3D tilt 需要横向延伸，竖屏会让倾斜感觉"歪"而不是"展开"。
+
+---
+
+## 如何判断自己的任务适用这套编排
+
+三步快速检查：
+
+**Step 1 · 素材数量**：数一下你有多少同类视觉素材。< 15 → 停；15-25 → 凑；25+ → 直接用。
+
+**Step 2 · 一致性测试**：把 4 张随机素材并排放，是否像「一套」？不像 → 先统一风格再做，或改方案。
+
+**Step 3 · 叙事匹配**：你要表达的是「Breadth × Depth」（量 × 质）吗？还是「流程」「功能」「故事」？不是前者就别硬套。
+
+三步都 yes，直接 fork v6 HTML，改 `SLIDE_FILES` 数组和时间轴就能复用。调色板改 `--bg / --accent / --ink`，整体换皮不换骨。
+
+---
+
+## 相关 Reference
+
+- 完整技术流程：[references/animations.md](animations.md) · [references/animation-best-practices.md](animation-best-practices.md)
+- 动画导出流水线：[references/video-export.md](video-export.md)
+- 音频配置（BGM + SFX 双轨）：[references/audio-design-rules.md](audio-design-rules.md)
+- Apple 画廊风格的横向参考：[references/apple-gallery-showcase.md](apple-gallery-showcase.md)
+- 源 HTML（v6 + 音频集成版）：`www.huasheng.ai/huashu-design-hero/index.html`