minimal-agent 0.9.0 → 0.10.0

package/skills/ui-design/references/layout-composition.md

@@ -0,0 +1,654 @@
+# 图文混排方法论（deck / PPT 专用）
+
+> 解决一件事：**文字排好之后，AI 插图该放哪、配什么比例、怎么不遮挡文案、怎么生成贴切的图。**
+> 配合 `ai-image` 技能（`generate.mjs` 文生图 / 图生图）+ `export-pptx.md` 的 hybrid 导出使用。
+> 适用 1920×1080（16:9）deck；其它尺寸按比例换算。
+
+---
+
+## ★ 编辑式最高标准（苹果/大疆产品详情页范式 —— 所有 deck 内容页的默认，先读这条）
+
+**deck 的最高样式标准 = 苹果手机 / 大疆无人机产品详情页那种「图文融合」**：图片作背景、文字作前景、需要数据时插图表、需要特写时插插图，**不靠卡片墙 / 网格 / 表格划分区域**。每页动笔前先认这条——下面 §0.6 archetype、§0.7 grid、§2 构图模式、以及任何 VI 模板的一切，都**在这条之下**；凡与它冲突的旧措辞，以本条为准。
+
+**最佳质量默认值**：不把 AI 生图当成本项克制使用。只要页面需要真实画面、产品感、场景、操作、安装、环境、特写、氛围背景，而用户没有提供合适图片，就**积极文生图**；客户图默认先图生图增强后使用。唯一例外是流程图、数据图表、架构图、关系图、参数轴、时间线这类精确信息，必须用 HTML/SVG 可编辑元素表达，不能交给 AI 生图。
+
+1. **背景层（每个内容页都要有）**：客户图 / AI 图 / 或 VI 同色系渐变·纹理 + scrim 铺底，`position:absolute; inset:0` **出血到画布边**（被 `.slide overflow:hidden` 钳死、物理不溢出）。**没有任何内容页是"白底 + 一堆卡片"**。
+2. **前景层**：标题 / 要点 / 参数 / 行动**直接浮在背景上**（守安全内边距 + scrim 保对比，深底白字 / 浅底深墨字），**不靠白底悬浮卡片分区**。如果需要小容器，只能是贴着文字的可读性背板、参数胶囊或图上短标签，不能承载正文。
+3. **数据 → 图表**：柱 / 饼 / 折线 / 进度环 / 参数胶囊 / 对比列等可视化承载数据；**不堆表格、不堆 div 对比表**（old/new 对比做成「双列对照浮背景」或图表）。
+4. **特写 → 插图**：材质 / 接口 / 产品 / 场景特写用插图（含**透明背景前景切图**浮在编辑式背景之上），不用小图标卡。
+5. **一屏一件事 + 有质感的负空间**（承载实质、非空洞）。**卡片墙 / 网格 / 表格 = 罕见例外**——仅真·并列指标矩阵且做成**图表 / 指标面板浮背景**时才用，绝不是默认的"白底分区卡海"。
+
+> 落地骨架见 §0.7 的「编辑式三层默认骨架」（`.edit-bg` / `.edit-scrim` / `.edit-content`）；模板优先级见 §2.2「产品详情页式图文融合模板库」。
+
+---
+
+## 先决策：优先 HTML；HTML 表达不好、或 AI 明显更美观更贴设计时才调 AI 生图
+
+**不是每页都要 AI 图，但需要画面的页必须积极用 AI 图。** 每个视觉先问一句：这是精确信息，还是摄影/场景/产品画面？
+精确信息用 HTML/CSS/SVG——矢量清晰、可编辑、零等待、更可控。摄影感场景、真实物体、产品、设备、操作、安装、环境、特写、氛围背景，只要没有合适客户图，就积极文生图；不要退回“纯渐变 + 白卡片”。
+
+**用 HTML/CSS/SVG（这些不调 AI）：**
+- 流程图、架构图、框架图、时间线、关系图、箭头 / 连线
+- 图标、徽标位、色块、分隔、几何 / 抽象装饰、网格背景
+- 数据可视化：柱 / 饼 / 折线 / 进度环 / 指标卡（SVG 或 CSS 画）
+- **观点分块 / 分类对比 / 要点并列**——**默认走编辑式前景浮层**（要点直接浮在背景上 + 参数胶囊 / 对比列 / 图表），**不默认堆卡片墙 / 网格 / 表格**；真·并列指标矩阵才用图表化面板（见 §0「编辑式最高标准」+ §2.2）
+- 玻璃面板、渐变光、图表、指标面板——视觉系统本身的零件（卡片仅作图表/指标容器浮背景，**非白底分区卡海**）
+
+**必须积极调 AI 生图 / 图生图（进入 `img_plan.json`；质量优先，不以成本为约束）：**
+- 摄影感场景 / 真实物体 / 人物 / 环境 / 产品 / 车辆（载具）/ 设备
+- 动物 / 植物 / 电路板 / 电子元件等**实物细节**（HTML 画不出真实质感）
+- 素描线条图 / 设计图 / 工程图 / 平面图 / 地图
+- 应用场景图 / 使用方法演示 / 设备关系图 / 组装安装图
+- 富插画 / 概念艺术 / 纹理材质 / 有机形态
+- 封面 / 章节 / 总结 / 观点页需要的**氛围大图或底部锚点场景图**（**仅光影 / 质感 / 隐喻意象，不得承载可命名结构**）
+- **文字与 HTML 都画不清的非结构化画面 / 意象**（一图胜千言；指真实物像、隐喻场景，**不是**层/流程/树/对比这类信息结构）
+- **HTML 能凑但明显不够美观 / 不够契合设计语言**的配图——此时也用 AI（仍按预算克制张数）
+- **客户图增强（route=source-enhanced）**：ppt 工作流现已把**所有客户图**默认走 Seedream 图生图重绘（低清/原背景/比例都不契合编辑式版面），
+  从 `src_K.png` 派生 `enhanced_src_K.png` 重绘到槽位比例/高清/贴 PPT 风格、`object-fit:cover` 填满；它不是丢弃客户图，必须保留 `source_file`
+  映射，后续 `source_usage_check.py` 把增强图计入原始客户图使用。**逐图规划与 cover/contain 落地详见 ppt 独占的 `source-image-layout.md`**（唯无 vision 盲态例外，直接用原图 contain）。
+
+> 一句话：**「画面」「需要美感的配图」积极生图，「图形 / 示意 / 结构」用 HTML。**
+> 不是先做 HTML 再看要不要图；而是先判断页面第一眼要看到的画面是什么。**ppt 客户图默认全部 source-enhanced 图生图重绘**（仅无 vision 盲态直接用原图，详见 `source-image-layout.md`）。
+
+> 🚫 **绝不可把结构图伪装成"抽象背景"用 AI 生（高频偷懒，已被确定性闸门拦截）。**
+> 真机事故：把"五层架构 / 双轨演进 / 选型决策树"写成 `route=ai-A` 的"抽象概念背景"丢给 AI——
+> 结果**糊、错、无文字、不可编辑**（AI 画不出准确的层数 / 步骤 / 分支 / 标签）。**理据**：结构 = 精确信息，
+> 只有 HTML/SVG 能精确、可编辑、带文字、零成本；AI 擅长的是**质感与画面**，不是信息结构。
+> **判别**：山峰隐喻 / 渐变光氛围 / 真实产品照 = ✅ AI；五层架构 / 并轨对比 / 决策树 / 流程 / 时间线 = ❌ 必 HTML/SVG
+> （即便在 section/cover 页：底图可走纯氛围 AI，**结构作为 HTML/SVG 浮层叠上去**）。
+> 因此 `route=ai-*` 的 prompt / `visual.note` **不得出现**结构名词（architecture / flowchart / decision tree /
+> parallel tracks / 架构 / 分层 / 流程图 / 决策树 / 双轨 / 对比图…）——`scripts/image_plan_lint.py` 会确定性拦截违规并回退 HTML。
+
+这些 HTML 图形**同样参与三层分离（背景 / 前景 / 文本）**：要当独立可编辑对象的 `<svg>`/`<canvas>`/图表/卡片/色块
+标 `data-pptx-layer="foreground"`（导出逐元素切图成独立可编辑图片）；其中的文字标 `data-pptx-kind="text"`（顶层原生文本框还原）；
+纯装饰底纹/渐变留背景层（不标）。下面的 A/B 路线、负空间、不遮挡规则**对 AI 图和 HTML 图一视同仁**。
+
+---
+
+## 0. 一条必须先懂的「比例真相」
+
+PPT 里图片的**最终位置和尺寸，完全由 HTML 槽位的几何决定**（导出器读元素的 `getBoundingClientRect`
+线性映射到幻灯片坐标，`object-fit:cover` 的裁切烘进截图）。**生成图的原生宽高比不决定 PPT 几何。**
+
+那为什么还要管「生成什么比例」？因为 **aspect 越贴合槽位，`object-fit:cover` 裁掉的越少、构图意图
+（主体位置、给文字留的负空间）越能保住**。比例不对 → 主体被裁飞 / 负空间被裁没 → 文字压到主体上。
+
+**所以：先按版面定槽位 → 由槽位算 aspect → 把 aspect 写进 `img_plan.json` 让 generate.mjs 按比例生成。**
+
+OpenRouter 支持的 aspect：`1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9`（其它端点忽略时靠提示词 + CSS 兜底）。
+
+---
+
+## 0.6 每页内容预算（archetype × 1920×1080）—— 先定「装多少」再排版
+
+**最常见的失败不是没规则，是对「一页 1920×1080 该装多少内容」没概念**：装太多→挤压重叠，装太少→空半。
+**两害相权，"乱"比"空"更糟**——现在的目标不是把每个角落填满，而是让观众一眼看见主视觉和一句重点。合理留白、强主视觉、短文案，优先于信息密度。每页**先认领一个 archetype（版式原型）+ 图像叙事角色 + 文字预算**，再开始排：
+
+| archetype | 用途 | 标题 | 正文 / 要点 | 视觉（填充手段） | 构图要点 |
+|------|------|------|------|------|------|
+| **cover 封面** | 首页 | 主标 **≤12 字且保持一行** + 副标 ≤20 字 | 0 | **必须**全幅氛围图(B) 或大幅主视觉(A) | 图铺满整页，标题压黄金分割线；主标与副标**分属不同 grid 行、留足行距**——导出原生文本框后 Office 会按本机字体**重折行**，长标题在 Office 折两行下溢压住副标（封面头号事故），故宁短一行、行距留够 |
+| **section 章节分隔** | 过渡 | ≤10 字 | 0–1 行 | 大序号 + 氛围图(B) 或大色块 | 图/色块铺满，文字浮一侧 |
+| **split 左图右文 / 右图左文** | 概念+画面 | ≤14 字 | 3–5 条 ×≤22 字 | A 路线半幅图（~45%） | 图占一半、文字占另一半，**两半都不空** |
+| **cards 多卡片（罕见例外·非默认）** | **仅真·并列指标矩阵**（先用编辑式/图表替代） | ≤14 字 | 4–6 项 | **图表/指标面板浮背景**(HTML) | 用前先问「能不能图打底 + 前景要点 或 图表」——能就**别用卡**；真要用，每'卡'是图表/指标面板浮在背景上、**禁白底分区卡海** |
+| **metric 大数字/指标** | 数据 | ≤14 字 | 2–4 指标 | 进度环/柱图(HTML/SVG)**浮背景** | 指标 + 图表浮在背景上、分布黄金/三分点 |
+| **fullbleed 全幅图+浮层（★内容页编辑式默认）** | 强视觉 | ≤16 字 | ≤3 条 | B 路线全幅图 | 图铺满，文字浮一侧，scrim 兜可读 |
+| **list 正文/列表** | 详述 | ≤14 字 | 5–7 条 ×≤28 字 | **背景层 + 前景要点浮层**（或侧栏配图） | 要点浮在背景/侧栏视觉上、互补填满，**不堆白卡** |
+
+> **★ 默认 archetype = 编辑式**（cover / section / split / fullbleed = 「图铺满或半幅 + 文字浮前景 + scrim」；list = 「前景短要点浮背景 + 侧栏视觉」；metric = 「图表/指标浮背景」）。**`cards` 已降为罕见例外、内容页默认不选**——遇「并列要点」先改成图像叙事、参数条、对比轴或 HTML/SVG 图表；仅真·并列指标矩阵且无法编辑式表达时才退用「图表化面板浮背景」。**每个内容页都要有背景层**（客户图 / AI 图 / VI 渐变纹理 + scrim），不留"白底 + 卡海"。
+
+**默认目标（不是可选经验值）**：1920×1080 一页承载 **1 句 takeaway + 1 个主视觉 + 1–3 个参数/证据点**。
+🚨 **上表的「5–7 条 / 4–6 项」是防溢出的【硬顶】，不是配额**——弱模型最常见的退化就是把上限当目标、
+每页塞满 7 条实质长句：条条有料、页页合规，**整页却是一篇文章不是一张幻灯片**。演示页的判据是
+**朗读测试：观众 3–5 秒能读完这页上屏文字**；points 默认是**短语/数字标签**，多条长句 = 文本阅读型排布（检查器会抓）。
+- 内容**多于**默认目标 → 先把数据/流程/层级改成 HTML/SVG 图表或轴线；论证/机制/出处**移入讲稿**（ppt 工作流的
+  `speaker_notes` 字段，导出进 PPT 备注栏——深度不丢、只是不上屏）；仍多就拆成两页。不要把 5–7 条长文塞进白卡。
+- 内容**偏少**时 → 首先强化主视觉：客户图图生图、AI 场景、底部锚点插图、产品特写或数据图表，而不是再补白卡。薄文字配强画面，可以是优质 PPT；薄文字配空渐变和白卡，是失败。
+> 内容从 `draft.md`（知乎深度长文）→ `outline.json` 每页的 **key_point（核心论点）+ evidence（支撑事实/数据）** 提炼——
+> 上屏每条要点都要**承载一个具体主张/事实**（禁止"重要/高效/赋能"空话填充）；**"简短概括"≠"电报体碎片"——别为凑字硬切成残缺短语，个别条目需要时可用一句完整短句把主张说清**（cards 说明 / list 正文可 1–2 句），但**整页仍须过 3–5 秒朗读测试**。
+> 稿件够厚，**版面靠主视觉/图表/参数胶囊填满**、文字只留一眼看懂的重点——「填满」的责任在视觉层，**不在堆文字**；不灌水也不空壳。
+>
+> 🚨 **铁律：上屏文案要「精炼 + 说人话」，不堆砌、不硬塞。** 把概念**用类比/具体例子讲透**，宁可近似也要好懂：
+> 「全景相机」说成「多镜头拼成谷歌街景那种可转视角的画面」、「π」说「约 3.14～3.15」——比堆精确细节更易懂。
+> **文案精炼到位了，内容自然装得下**（不顶出画布、不必缩小字号）；**别把一堆长定义硬塞进一页**——塞不下就精炼/拆点/拆页，绝不靠缩字。
+>
+> ⚠️ **纯文字页覆盖率天然偏低**（构图门量的是"内容框占格"，文本框是细行）——实测同样 4 条要点，**裸文字读 ~11%、包进前景面板/卡片读 ~66%**。所以 list / 正文页要么**把要点包进前景面板或卡片**（装实质、别空心）、要么**配侧栏图**（这正是 list archetype 默认带侧栏配图的原因），别让裸文字飘在大画布上被判过空。封面用全幅底图（B 路线）时覆盖率自动按 WARNING 放宽，不必硬凑。
+
+## 0.7 grid 结构化构图（**先搭骨架再填内容 —— 构图好坏 90% 在这一步**）
+
+**为什么必须用 grid（而不是绝对定位）**：1920×1080 是固定画布，但**不要用 `position:absolute` 给每个元素手写 left/top**——那等于逐像素算坐标，极易挤上半 / 挤角 / 留空半（弱模型尤甚，这正是之前 PPT 构图崩坏的根因）。正确做法和网页一样：**每张 slide 是一个 CSS grid 容器**，靠 `grid-template` + 统一 `padding` + `align/justify` 让**布局引擎自动把内容铺满画布、留出均匀边距**。于是「均衡 / 不空半 / 黄金比例」成为 grid 的**结构性结果**，而非要你手动照做的散文规则。
+
+**骨架（每张 slide 都从这里起步）—— 纵向流式、人可滚动审阅（像 PPT 导出的 PDF）：**
+```css
+html, body { margin:0; }
+body { background:#0e0e14; }                          /* 深色衬底分隔每页，像 PDF 页间留白 */
+.slide{
+  position:relative;                                  /* 只承载 3 个 z 层（edit-bg/scrim/content）；顺序纵向排开、可滚动审阅，不再 absolute 叠放 */
+  width:1920px; height:1080px; margin:0 auto 40px;    /* 每页固定尺寸 + 居中 + 页间距；margin-top=0 保证导出钉顶不偏 */
+  padding:56px 112px 48px;                            /* 内容内边距：左右 112 不贴边、上 56 下 48 少吃竖向 */
+  overflow:hidden;                                    /* 🚫 .slide【本身不是 grid】——栅格落在 .edit-content（见下编辑式三层骨架），写在 .slide 上两栏会塌进左半 */
+}
+[hidden]{ display:none !important; }
+```
+> **为什么纵向流式而不是 `position:absolute` 叠在一起**：叠放（每页钉 inset:0）能让导出截图/构图门几何零偏移，
+> 但直接打开 deck.html 会「所有页糊成一团」、没法人工审阅中间结果。改纵向流式后**人能像 PDF 一样滚动看每一页**；
+> 而**导出不受影响**——导出器 `renderSlides::prepare()` 本就逐页隐藏其余页，再由 export CSS **把「当前页」钉回视口 (0,0)**
+> 截图，所以构图门/截图仍按真实 1920×1080、**零偏移**（`getBoundingClientRect` 相对视口落在 0..1920/0..1080），几何代码一行不改。
+
+**★★ 编辑式三层·【锁定骨架·逐字复用】——内容页一律先套这套，build 只填内容、不改类名、不自创每页布局类。** 这套是「图打底+文字前景」correct-by-construction 的唯一正确写法（治真机头号事故：兜底渐变盖死 AI 图、客户图裱进白卡缩成缩略图、自创类塌成空白页）：
+```css
+/* —— 背景层：图 cover 填满、纯色兜底在底；AI/客户图永远可见，🚫绝不被渐变盖死 —— */
+.edit-bg{ position:absolute; inset:0; z-index:0; overflow:hidden;
+          background:var(--vi-fallback) center/cover no-repeat; }       /* 纯色兜底：仅当图缺失才露 */
+.edit-bg>img.bg-img{ width:100%; height:100%; object-fit:cover; object-position:center; display:block; }  /* 推荐：<img class="bg-img"> 填满，可精准 object-position 对 key_region */
+/* 或纯 CSS：.edit-bg{ background-image:url("assets/<img_K|enhanced_src_K>"); background-size:cover; background-position:center; } */
+/* 🚫🚫 绝对禁止 `background:<不透明渐变>,url()` —— CSS 里逗号前者画在上面，不透明渐变会把 AI 图整张盖死（真机头号事故，封面/综述全成空蓝）。渐变只许进下面的半透明 .edit-scrim */
+/* —— scrim：半透明遮罩，只压文字侧、保对比，永不盖死图（这才是渐变的唯一去处）—— */
+.edit-scrim{ position:absolute; inset:0; z-index:1;
+             background:linear-gradient(90deg, rgba(8,12,20,.64) 0%, rgba(8,12,20,.28) 44%, rgba(8,12,20,0) 72%); } /* 深底白字方案；浅底深字改 rgba(255,255,255,.55) 浅磨砂（见 §0.9 对比铁律）*/
+/* 🚫🚫 真凶 6（2026-07-04 真机 p3/p7 同一根因两次事故）：上面这行渐变是「左侧不透明 → 右侧透明」，
+   隐含假设文字浮在左侧、图的裸露区在右侧——这只对 fullbleed（文字贴一侧、图铺满全页）成立。
+   split/two-col archetype 默认「左图右文」（图在 grid-column:1、文字在 grid-column:2，见下方 archetype 表）：
+   此时文字恰好落在渐变**透明**的那一侧，AI 全幅底图在文字区完全裸露、正文压图不可读
+   （两页事故的 `.edit-scrim` 渐变都是原样照抄这行方向，没有跟着文字实际所在栏镜像）。
+   规则：scrim 不透明端必须对齐【文字实际所在的那一栏】，与图在哪栏无关，照抄前先看这页文字落在左栏还是右栏——
+   左图右文（文字在右）→ 镜像成 linear-gradient(90deg, rgba(8,12,20,0) 0%, rgba(8,12,20,.28) 56%, rgba(8,12,20,.64) 100%)；
+   右图左文（文字在左）→ 维持上面这行不变。 */
+.edit-content{ position:relative; z-index:2; height:100%; box-sizing:border-box; display:grid; gap:32px; }
+.edit-content > *{ min-width:0; min-height:0; }   /* 🚫🔒【铁律·逐字复用】栅格子项恒 min-width:0/min-height:0 —— 见下「真凶 5」 */
+  /* ★★ 前景【就是栅格容器】—— archetype 的 grid-template-columns/rows【落在 .edit-content 上，不是 .slide】。
+     真机头号事故：栅格写在 .slide 上时，edit-bg/scrim 是 absolute（脱流）、edit-content 成 .slide 唯一在流子项 →
+     独占第 1 列、第 2 列永远空 + 内部 grid-column 失效 → 两栏（split/metric/list）全塌进左半、溢出被裁。
+     正解：.slide 只承载 3 个 z 层、不开 grid-template-columns；栅格一律在这层。前景：标题+要点+参数胶囊/图表，守安全内边距、落 vision 净区 */
+  /* 🚫🚫🚫 真凶 5（p5/9/10 事故·内容整页不可见）：split/metric 分栏子项里放 `.fig-contain`（object-fit:contain 的 <img>，
+     width:auto）时，**grid item 默认 min-width:auto = 不小于其 min-content**；图的**原始像素宽**（如 3072px）成为该子项
+     min-content → 把 `.85fr` 轨道撑到 ~2000px 出画布、第 2 列被顶到 x≈2124（观众只见空白/背景，标题正文全飞出）。
+     **治本＝上面这条 `.edit-content > *{ min-width:0; min-height:0 }`**（让 fr 轨道能压回容器宽、图再 max-width:100% 装进去）。
+     导出端 layout_balance.py `--strict-offcanvas/--catastrophic-only` 会把「可见<20% 的越界」判 ERROR 兜底，但**别依赖兜底、务必写 min-width:0**。*/
+
+/* —— 图填满槽·铁律（半幅 hero / 配图 / 证据图都用 .fig-fill）：cover 填满、object-position 对重点；🚫禁 max-height 帽、🚫禁 `background:白/surface;padding` 白裱框（真凶 2：低清图缩成 340px 小裱照浮空框）—— */
+.fig-fill{ position:relative; width:100%; height:100%; overflow:hidden; border-radius:14px; }
+.fig-fill>img{ width:100%; height:100%; object-fit:cover; object-position:center; display:block; }  /* object-position 换成该图 vision.key_region 中心% */
+/* —— .fig-contain（唯 dense-info 数据图/截图/无 vision 盲态原图才用 contain 不裁切；见 source-image-layout §0）：
+   ⚠️ contain 图 width:auto → 必须给容器 min-width:0（上面 .edit-content>* 已保底），且 img 加 max-width:100% 兜住，
+   否则重演真凶 5 撑爆轨道。cover 优先用 .fig-fill；只有"不能裁切保全数据"才用 contain。
+   🚫🚫🚫 真凶 6（2026-07-05 第6/8页事故·内容 catastrophic 不可见导致 -p 在导出阶段硬 halt）：
+   `.fig-contain`/`.fig-fill` 本身已经是安全的 `width:100%;height:100%`（尺寸交给父级 flex/grid 决定），
+   但如果在内联 style 里额外加了 `aspect-ratio:<W>/<H>`（如 `style="aspect-ratio:1432/792;width:min(1320px,80%)"`），
+   这个内联 `aspect-ratio` 会覆盖类里的 `height:100%`——图按自身宽高比独立撑出一个固定像素高度，与父级
+   `1fr` 轨道实际可用高度无关，一旦这个固定高度大于轨道实际分到的高度就会撑爆/顶出画布，导出端
+   `layout_balance.py --catastrophic-only` 判定可见部分<20%、直接硬 halt（无重试预算，比一般溢出更严重）。
+   **`.fig-contain`/`.fig-fill` 的内联 style 上绝不加 `aspect-ratio`**——两个类自身已经是安全写法，
+   需要控制图片显示比例交给内部 `<img>` 的 `object-fit:contain/cover` 处理，不要在外层容器上二次定死宽高比。 */
+.fig-contain{ position:relative; width:100%; height:100%; min-width:0; overflow:hidden; border-radius:14px; display:flex; align-items:center; justify-content:center; }
+.fig-contain>img{ max-width:100%; max-height:100%; width:auto; height:auto; object-fit:contain; display:block; }
+```
+> **`--vi-fallback`** = 所选 VI 的纯色底（build 在 `:root` 定义，如 `--vi-fallback:#0e1b2e`）。AI 生图失败时 `url()` 指向的是 generate 写的**渐变占位 PNG**（资产级兜底，见 ai-image），所以**永远不用 CSS 渐变去盖图**。
+> **AI 底图引用约定（route=ai-A/ai-B）**：底图用**约定名 `assets/ai_p<page>.png`**（page=该页页号，由工作流 `--ensure-ai-img-plan` 确定性注入 img_plan + 生成，build 只按名引用、不自己起名）。放成 `<img class="bg-img" src="assets/ai_p<page>.png" onerror="this.onerror=null;this.remove();this.parentNode.classList.add('ai-fallback')">`。
+> 想让「连渐变占位 PNG 都没有」时露更好看的氛围底（非纯色），给 `.edit-bg.ai-fallback{background:<VI 同色系径向/线性渐变>}` 定义同色系深/浅两版即可——**这渐变只在没有任何图时露、绝不盖在图上**（区别于真凶 1 的「渐变压图」）。**🚫 内容页绝不只上 CSS 渐变 class、不放 `<img>`** —— 那等于放弃 AI 底图、整页平涂（真机 p2/3/9 事故）。
+> 🚫 **每页 `<section class="slide X">` 的 X 必须是下面已定义 grid 的标准 archetype 类（cover/section/split/fullbleed/list/metric）**——**禁止自创 `.cockpit/.paradigm/.five-shift` 这类没在 `<style>` 里定义 `grid-template` 的 bespoke 类**（真凶 4：grid 未定义→内容塌成空白页）。需要语义命名就在标准类后追加修饰类（`class="slide split paradigm"`）但布局仍走标准类。
+**按 archetype 选前景布局（grid 一律落在 `.edit-content` 上、【绝不写在 `.slide` 上】，数值可微调）：**
+```css
+/* ★ 通用：header 跨满整宽（无论几列），左右栏内容用 grid-column:1 / grid-column:2 落位 */
+.deck-header{ grid-column:1 / -1; }
+/* cover 封面：标题区 + 视觉区左右分栏，底部对齐 */
+.slide.cover    .edit-content{ grid-template-columns:1.2fr .8fr; align-items:end; }
+/* split / two-col 左图右文 / 右图左文：图栏 + 文栏，垂直居中（右图左文则 1.15fr .85fr） */
+.slide.split    .edit-content,
+.slide.two-col  .edit-content{ grid-template-columns:.85fr 1.15fr; align-items:center; }
+/* metric 大数字：指标区 + 图表区分布两侧 */
+.slide.metric   .edit-content{ grid-template-columns:1fr 1fr; align-items:center; }
+/* list 列表 / 目录：文字主栏 + 配图（或第二栏要点）侧栏——**两栏都铺满，绝不留右半空** */
+.slide.list     .edit-content{ grid-template-columns:1.4fr .6fr; align-items:start; }
+/* section 章节分隔：全幅背景 + 大序号/标题浮一侧（单列、内容垂直居中沿 scrim 侧） */
+.slide.section   .edit-content{ grid-template-columns:1fr; align-content:center; }
+/* fullbleed 全幅图+浮层：.edit-bg 满铺，.edit-content 单列浮一侧、scrim 兜可读 */
+.slide.fullbleed .edit-content{ grid-template-columns:1fr; align-items:end; }
+/* cards（罕见例外·仅真并列指标矩阵）：每'卡'是图表/指标面板浮在 .edit-bg 背景上、禁白底分区卡海；优先用编辑式前景要点/图表替代整页 */
+.slide.cards    .edit-content{ grid-template-rows:auto 1fr; }
+.slide.cards .edit-content .grid{ display:grid; grid-template-columns:repeat(2,1fr); gap:28px; align-content:stretch; }
+```
+> 🚫🚫 **绝不把 `grid-template-columns` 写在 `.slide.X` 上**（如 `.slide.split{grid-template-columns:1fr 1fr}`）——`.slide` 里只有 `.edit-content` 一个在流子项（背景/scrim 是 absolute 脱流），栅格写在 `.slide` 上会让 edit-content 独占第 1 列、第 2 列空，且内部 `grid-column` 失效 → **两栏页全塌进左半、溢出被裁（真机头号事故，p4/5/7/8/10/12 全中）**。栅格只许在 `.edit-content`；左右栏内容用 `grid-column:1` / `grid-column:2` 落位。
+
+> 🚨 **list / 目录页必须占满整宽（治「目录右半大片空白」真机事故）**：**绝不**把要点塞进一个 `max-width` 受限的窄单列、
+> 任右半空着。少要点就用 `.slide.list` 的「文字主栏 + 侧栏视觉（图标列 / SVG / 章节缩略）」两栏互补；
+> 目录这类**多条等价项**直接用**双列**铺满（`grid-template-columns:1fr 1fr; gap:48px`，6 条 → 左 3 右 3）。
+> 当前 PPT 工作流默认关闭占空比族迭代；这里是**人工设计原则**，不是让脚本为了"填满"反复逼改。
+> 治本方式仍然是结构上占满画布，而不是牺牲留白或堆卡片。
+
+要点：**用 `1fr / auto / 分数比` 让内容撑满，用 `align-items / align-content:stretch|center` 控制垂直分布**，几乎不写死像素坐标。卡片网格用 `1fr` 行让它自动占满下半区（这就是「卡片别只挤上半」的结构性修复）。
+> **slide 容器本身现在是 `position:relative`（纵向流式）；`position:absolute` 在 slide *内部* 的唯一合法场景 = B 路线全幅底图 + 浮在其上的文字**（背景 `background-image` + 一个绝对定位的文字浮层按 scrim 侧摆放）。除此之外 slide 内部不要再出现 absolute。
+
+## 0.8 每页 ≥1 视觉元素 + 元素渲染决策（区别于 Word，且让构图门自然过）
+
+**铁律：每页至少一个视觉元素。** 纯文字 + 背景板的页 = Word，不是 deck——既无活力，又会被构图门判过空。
+没 AI 配图的页也要有：SVG 图表（柱/饼/折线/进度环）、图标组、装饰几何（连线/节点/分隔光带）、结构色块。
+这同时是过构图门的**正道**：有前景视觉块的页，"空"类缺陷自动降为 WARNING（见第 4 节），不必逼字填满。
+🚨 **纯装饰几何（连线/圆环/十字准线这类不代表任何图表/流程关系的点缀 SVG）统一命名
+`<svg class="vi-deco">`，不要自造别的名字（如 `crosshair-svg`）**：`deck_visual_style_check` 的
+孤立连线检测认这个约定名来豁免"缺 diagram-node 节点归属"误报（2026-07-06 真机复盘：自造名字
+导致 3 页纯装饰 SVG 被误判成"图表连线缺节点"）；只有真正的图表/流程图（连线应该配 node/step/
+chip 等标签的场景）才需要 diagram-node 归属，纯装饰几何本就不需要，用统一类名让检测器认得出来。
+
+**每个内容块先定 render（怎么呈现），再写 HTML**（webppt 的 design.json 每块带 `render` 字段）：
+
+| render | 用于 | 怎么做 |
+|------|------|------|
+| `text` | 纯标题/短说明/引言 | h*/p/span，标 `data-pptx-kind="text"`（导出提顶层可编辑框） |
+| `html+text` | **绝大多数内容**：结构/对比/并列/数据/流程/要点 | 卡片/分栏/表格/SVG 图表/图标 + 文字（HTML 精确、可编辑、零成本） |
+| `text+image` | 真实画面/物体/场景/产品（HTML 画不出） | A 路线 `<img>` 半幅图 + 文字在另一侧（见第 1、2 节） |
+| `html+text+image` | 画面 + 结构标注并存 | 图当底/侧，结构用 HTML/SVG 叠（结构永远 HTML，不烧进图） |
+
+**判据**：能用 HTML/CSS/SVG 清晰表达的（图形/示意/数据/结构化文字）→ `html+text`；只有"真实画面/质感/物体"才 `text+image`。
+**结构（层级/流程/对比/树）永远 HTML/SVG，绝不当 AI 图生**（见第 4 节配图分流闸门）。
+
+> 🚨 **铁律：所有可读文字必须是「真实 DOM 文本节点」（h*/p/span/SVG `<text>`）。** 导出器靠它把文字隐藏出截图、再提成
+> **顶层可编辑文本框**——这是「截图绝不带 HTML 字、文字永远可编辑」的前提。**绝不**把可读文字写成：
+> - CSS `::before/::after` 的 `content:"…"`（无法标注/隐藏/提取 → **必烧进底图/切图、永不可编辑**）；
+> - 烧进背景图 / HTML 图元 / SVG `<path>` 轮廓字（同样无法提取）。
+>
+> **唯一例外 = AI 插图（route=ai-*）画面里天然带的字**（栅格像素无法隐藏，故不提取、不会双层；其 prompt 仍要 `no text` 尾巴尽量无字）。
+> 违反此律的后果就是真机事故「切图上有字、上面又落一层文本 = 双层」。导出端 `layout_balance.py` 有
+> **【截图夹带文本】ERROR** 确定性兜底（背景截图态仍可见的 DOM/伪元素文字一律拦下）。
+
+> 🚨 **铁律：要在 PPT 里可单独拖拽的结构，必须用「离散 HTML 元素」搭，不要画成整块 `<svg>`。**
+> 架构分层 / 流程节点 / 决策树 / 一排圆/徽标 / 卡片矩阵——**每个层/节点/圆/卡是一个独立的 HTML 块**
+> （`<div>` + 自带底色边框，用 grid/flex 排），导出会**递归把每块切成各自可拖的图片对象**（见第 4 节）。
+> **整块 `<svg>` 画的结构图导出只能整张切、节点不可拆**（矢量是一张图）——SVG 只用来画**连线/箭头/真矢量插画**
+> （连线作一层 underlay 切图，节点用 HTML 叠在上面）。真机事故：六个圆/四层架构/决策树各被切成一整张、不能单独调。
+
+> 🚨 **铁律：卡片/选项卡/悬浮卡内部要填实，别留大片空白；整页内容别高过画布。**
+> - **填充度**：一张大白卡/底板里只放一句话、或一小撮图元挤一角旁边大片留白 = 失败。按内容定卡尺寸、减小 `padding`、
+>   放大内部图元铺满、或补实质内容。导出端有 **【卡片/分组填充不足】WARNING**（卡内「文字+子块」面积 ÷ 卡面积 过低即提示）。
+> - **不溢出画布**：一列层块/节点别堆到高过 1080（或宽过 1920），否则被裁出可视区——内容多就拆两栏/拆页。
+>   导出端有 **【超出画布】WARNING**。
+
+## 0.85 放映级字号阶梯（1920×1080 deck 专用——正文要放映级可读，不是网页 16px）
+
+**为什么单列**：VI 模板出厂 CSS 是**网页尺度**（正文常 16px）；deck 满屏 1920×1080、导出按 `pxToPt`（px×0.375）
+换算，16px → 6pt，投影上正文形同蚂蚁。**deck 一律按下面这套放映级字号写，覆盖 VI 文档里的网页字号**
+（VI 文档的 16px 只适用网页、不改它，deck 这里覆盖）。**2026-06-19 用户裁决：整体再放大 ≈1.5×**——
+只有「每页最大的标题」（封面主标 / 章节大序号）维持现状，**其余各级等比放大约 1.5×**（治「投影上正文还是偏小」）。
+
+| 层级 | 1920×1080 字号 | 说明 |
+|------|------|------|
+| 封面主标 / 章节大序号 | 维持现状（cover ~88–120px、章节序号 ~150–180px） | **全 deck 最大、不参与放大**；其余一切都 < 它 |
+| 内容页主标题 | ~72–88px（放大自 ~48–64） | 每页最大、< 封面主标 |
+| 区块小标题 / 卡标 | ~44–52px（按 archetype/构图比例取） | 介于正文与主标之间，**恒 < 该页主标** |
+| 副标题 / 引言 | ~40–46px | < 小标题 |
+| **正文 / 要点 / 卡片正文** | **≥ 38px（放映级硬下限，≈1.5×）** | 页面正文与悬浮卡片正文同标准；治「16px→6pt 蚂蚁字」 |
+| 注释 / 来源 / 角标 | ~28–32px | |
+| 药丸 / 图例 / 图内标签 | ~26–28px | 最小，**仍 ≥ 24px 导出下限** |
+
+**排序不变量（每页）**：`主标 > 小标题 ≥ 副标 > 正文 > 注释`；**任何非主标元素不得 ≥ 该页主标题**。
+
+> **导出端确定性字号检查**：导出器量每段文本的**屏上视觉 px**（SVG 已含 viewBox→视口缩放），低于 `FONT_FLOOR_PX = 24`
+> 的段会被 `layout_balance.py` 报 **WARNING【字号过小】**（不硬拦、提示放大）。所以**别让任何可读文字落到 24px 以下**——
+> 上表最小档（药丸/图例/图内标签 26–28px）已留余量。治本是**设计阶段就按本阶梯定档**（webppt 的 design.json 每块规划字号），导出只忠实搬运。
+
+**图内文字同标准 + 图形配套放大**：图表 / 框图 / 流程图 / 节点图 / 图标内部的文字（坐标轴 / 图例 / 数据标签 /
+节点名 / 说明）**同样要 ≥ 放映级下限**——按**屏上视觉像素**算（SVG 把 `viewBox→视口` 缩放算进去，使实际显示字号达标）。
+**图形要画得够大以容纳达标文字**：图太小、字塞不下 / 被裁 / 挤成一团时，**放大图形 / 减少标签**，**绝不把图内字缩到下限以下**
+（与「重叠先移动、空先补内容」同向：调结构不缩字）。
+
+## 0.9 配色解耦（VI 管底，图表/插图/辅助图形以内容为准——别一片单色）
+
+VI 模板（如 violet-meridian 紫系）定的是**品牌色 + 整体气质**，但**不该把一页里所有东西都染成同一个色相**——
+否则图表数据系列分不清、整页死板。划清职责：
+
+- **VI 管**：页面背景 / 底板 / chrome（导航条、分隔、边框）/ 整体氛围 + **主强调色**（accent，用于焦点 / 主按钮 / 标题点缀）。
+- **以内容为准（与 VI 协调、不被单一色相吞没）**：
+  - **图表数据系列（柱/饼/折线/进度环）**：**必须用一组可区分的分类色**——按系列数取 N 个有别的色相，让数据一眼分得开。
+    取色法：以 VI accent 为锚 + VI 已有功能色（如 signal 青 / amber 琥珀 / danger 红）+ 邻近/互补色凑足序列
+    （**同属一个冷暖基调、彼此分得开**）；单系列图（单进度环/单柱）才可用 VI accent 一色。各 VI 现成分类色见 `vi-<name>.md`「数据可视化分类色」。
+  - **非背景 AI 插图（A 路线）**：**以画面内容真实/恰当色为准**（电路板=铜绿、山=蓝绿、产品=本色），只需与 VI 协调（共享冷暖、或留 VI 作点缀），不强行染成 VI 单色。
+  - **HTML 辅助解释图形 / 图标**：用内容恰当的语义色（成功=绿、警告=琥珀、风险=红、不同类别不同色），与 VI 协调即可。
+- **唯一反例（=失败）**：整页一个紫、柱/饼各系列同色分不清数据、插图也被染紫——死板、不可读。
+- **底线**：上述内容色**必须与 VI 背景协调、不冲突**（同冷暖、留呼吸、对比足够可读），不是各画各的。
+
+> 🚨 **铁律：文字与其背景必须高对比（WCAG ≥ 4.5，放映大字 ≥ 3.0）。**
+> - **浅底（VI 浅紫/白，内容页默认）→ 深墨字（`--ink`）**；**深底（封面/章节，或深色卡）→ 白/浅字**。
+> - **绝不**深底深字、浅底浅字（真机事故：深紫底 `#1B1A31` + 近黑字 `#11121A` → 对比 ~1.1 全糊）。
+> - VI 的深色只用于 **cover/section**；一旦某页/某卡用深底，**该处文字必须随之转白/浅**。
+> - 导出端 `layout_balance.py` 有 **【文字对比度不足】WARNING**（提示、不硬拦——治本在这条铁律：写 deck 时就深底白字/浅底深字）。
+
+## 1. 两种图，两条导出路线（**关键二分，先判这个**）
+
+AI 插图在 deck 里只有两种角色，导出方式不同，**先判属于哪种再排版**：
+
+### A. 可编辑插图（不压文字）—— 标 `foreground`
+图放在自己的槽位里、**不和文字重叠**（左右半幅、上下横幅、内嵌卡片）。
+导出后是 PPT 里**独立可编辑图片对象**（可移动/缩放/替换）。这是三层里的「前景层」。
+
+```html
+<div class="img-slot" data-pptx-layer="foreground">
+  <img src="assets/img_1.png" alt="<中文描述>">
+</div>
+```
+
+> 前景**只标最外层**：槽位 `div` 标了 `foreground`，里面的 `<img>` 就别再标（会重叠重影）；整个槽位烘成**一张**切图。
+> `data-pptx-kind="image"` 现在可省（标了 `foreground` 即逐元素切图）；卡片/色块/图标同理标 `foreground` 即可。
+```css
+/* 图槽 = 某个 grid 单元，靠 grid 占位铺满该单元（**不要** position:absolute；绝对定位只留给 B 路线全幅图） */
+.img-slot{ width:100%; height:100%; overflow:hidden; }
+.img-slot img{ width:100%; height:100%; object-fit:cover; object-position:center; display:block; }
+```
+
+### B. 全幅氛围背景图（文字浮在图上）—— 用 CSS `background-image`，**不标 foreground**
+封面 / 章节页常见：一张大图打底，标题浮在上面。
+**不要用 `<img>`**（会触发「未标 foreground 将被烘进背景」的警告，且和浮层文字有 z 序纠缠）。
+直接做成 section 的 `background-image`，再叠一层**可读性遮罩 scrim / 文字底板**，文字单独标 `foreground/text`。
+导出后：图 + scrim 烘进背景截图（不可编辑），文字是可编辑文本框浮在上面。这是「文字 / 背景分离」。
+
+> 🚨 **封面/章节文字对比度铁律（治「浅底图 + 白字看不清」真机事故）**：氛围底图**亮暗不可控**（尤其浅色模板的 AI 底图常偏亮），
+> **不能默认白字靠一层弱 scrim**——浅底上白字必糊。两条达标做法任选（**浅色模板首选 ① 深字**）：
+> - **① 深字 + 浅色磨砂板（推荐，配浅色模板）**：文字用深墨色（`var(--ink)`），文字区垫一块**半透明浅色磨砂板**
+>   （`background:rgba(255,255,255,.55); backdrop-filter:blur(6px)`）——任意亮/暗底图上深字都清晰，且与浅色正文页气质统一。
+> - **② 白字 + 足够暗 scrim/板**：坚持白色大标题时，文字侧 scrim 必须**压到足够暗**（起手不透明度 ≥ .72，或文字区垫深色半透明板），保证白字在任意底图上可读。
+
+```html
+<section class="slide cover" data-screen-label="01 封面">
+  <div class="scrim"></div>
+  <div class="cover-plate">
+    <h1>标题文案</h1>            <!-- 真实 DOM 文本，导出自动提为可编辑框；无需手标 kind/foreground -->
+    <p class="subtitle">副标</p>
+  </div>
+</section>
+```
+```css
+.cover{ background:url("assets/img_1.png") center/cover no-repeat; }
+/* ① 推荐（浅色模板）：浅色磨砂文字板 + 深字 —— 任意底图都对比达标 */
+.cover .scrim{ position:absolute; inset:0;
+  background:linear-gradient(90deg, rgba(255,255,255,.35) 0%, rgba(255,255,255,0) 60%); }
+.cover .cover-plate{ position:absolute; left:120px; bottom:160px; max-width:52%;
+  padding:32px 40px; border-radius:20px;
+  background:rgba(255,255,255,.55); backdrop-filter:blur(6px); }
+.cover h1{ color:var(--ink); }          /* 深墨字，不是 #fff */
+.cover .subtitle{ color:var(--ink-soft); }
+/* ② 备选（要白字）：把上面三块换成——scrim 暗到 ≥.72、plate 深色半透明、h1 color:#fff */
+```
+
+> 判别口诀：**图要可单独编辑/替换 → A（foreground image）；图只是氛围底、文字压在上面 → B（background-image + scrim）。**
+
+---
+
+## 2. 六种构图模式（含槽位几何 + 该选的 aspect）
+
+| 模式 | 路线 | 槽位（1920×1080 内）| 槽位比 | **选 aspect** | 负空间 / 文字位置 |
+|------|------|------|------|------|------|
+| ① 全幅背景 + 浮层文字 | B | 1920×1080 | 16:9 | **16:9** | 提示词在文字侧留低对比净空；scrim 兜底 |
+| ② 左图右文 | A | ~864×1080（左45%）| 0.8 | **4:5** | 文字在右半，图内主体可居中/偏左 |
+| ③ 右图左文 | A | ~864×1080（右45%）| 0.8 | **4:5** | 文字在左半，图内主体可居中/偏右 |
+| ④ 上图下文 | A | 1920×~560（上）| ~3.4 | **21:9** | 文字在下方区块 |
+| ⑤ 下图上文 | A | 1920×~520（下）| ~3.7 | **21:9** | 文字在上方区块 |
+| ⑥ 内嵌卡片图 / 点缀 | A | ~520×390 或 480×480 | 4:3 / 1:1 | **4:3** 或 **1:1** | 图在卡片/栏内，文字环绕，留 ≥40px padding |
+
+- 一页**最多一个主图槽位**（象限/多图卡片例外，但别堆）；图片距舞台边缘留白 ≥80px（全幅背景除外）。
+- 标题/正文/logo 与图槽位**不重叠**（A 路线）；重叠只允许 B 路线且必须有 scrim。
+
+---
+
+## 2.1 空间构图法（先选「内容怎么摆」——webppt 的 composition 字段）
+
+第 2 节六种是「图槽 + 文字」的图文模式；这里是更通用的**整页空间布局**：每页先选一种 composition、再填内容，
+**同类页换不同构图，避免页页一个样**。都用 CSS grid 实现、不绝对定位：
+
+| composition | grid 骨架 | 适用 |
+|------|------|------|
+| **左右** | `grid-template-columns:1fr 1fr`（或 .85/1.15 黄金比） | 图文对照、概念+画面、对比两栏 |
+| **左中右** | `grid-template-columns:repeat(3,1fr)` | 三要素并列、流程三段、输入→处理→输出 |
+| **上下** | `grid-template-rows:auto 1fr`（标题带 + 内容区） | 标题统领 + 下方铺主体；横幅图+文 |
+| **上中下** | `grid-template-rows:auto 1fr auto` | 引子→主体→结论；时间线三段 |
+| **四宫格** | `grid-template-columns:1fr 1fr;grid-template-rows:1fr 1fr` | 4 个并列要点/象限/对比矩阵 |
+| **中心辐射** | 中心元素 + 环绕单元（grid 居中 + 四周，或 `<svg>` 放射连线） | 核心概念 + 多分支/能力；架构总览 |
+| **全幅浮层** | `position:absolute` 底图 + scrim + 文字浮层（**唯一允许 absolute**） | 封面/章节氛围页（B 路线） |
+
+要点：**用 `1fr/auto/分数比` 让内容撑满 + `align/justify` 控分布**，几乎不写死像素。卡片/象限网格用 `1fr` 行自动占满，
+杜绝「只挤上半」。中心辐射的连线/节点用 `<svg>` 画（自动切前景层），本身就是 0.8 要求的"每页视觉元素"。
+
+## 2.2 产品详情页式图文融合模板库（苹果式整体感，不等于卡片堆叠 —— 编辑式融合是内容页首选默认）
+
+PPT 不是每页都要浮动卡片。先根据内容和素材选择**整页视觉策略**，再决定客户图、AI 图、HTML 图表分别承担什么。
+**优先级总则**：**「图打底 / 半幅大图 + 文字浮前景 + scrim」的编辑式融合模板（下表标★首选）是内容页的默认选择**（像苹果手机/大疆产品详情页，不靠表格/网格/悬浮卡片划分区域）；
+卡墙/证据/画廊类（标◇次选）只在「真·并列小图 / 低清证据图」时用；**有可做背景或 hero 的图（AI 或合格客户图）的页，一律走★首选融合、不再叠表格或悬浮卡墙**。
+
+### 2.2.1 `composition_style` 机器枚举（design.json 必填）
+
+`ppt.yaml` 的 `design.json` 每页必须写 `composition_style`，构建时按它落地，不再只靠 `archetype/composition` 猜：
+
+| composition_style | 首选用途 | 视觉重量 | 禁用项 |
+|---|---|---:|---|
+| `product-hero` | 产品、设备、主体、方案封面 | 图/主体占 65–85% | 禁大卡、禁表格、禁小图裱框 |
+| `feature-theater` | 一屏只讲一个核心能力 | 场景/插图占 60–75% | 禁 4–6 卡列表 |
+| `detail-closeup` | 镜头、部件、材质、接口、局部证据 | 特写占 60–80% | 禁把特写缩成角落 |
+| `scenario-fullbleed` | 真实场景、使用情境、安装/操作画面 | 全幅背景 + 前景文字 | 禁文字压主体，禁图内文字 |
+| `data-visual` | 数据、成本、效率、时间、对比 | HTML/SVG 图表占 50–70% | 禁大表格矩阵，除非确为多维表 |
+| `gallery-strip` | 多张证据图、样张带、低清图集合 | 图带/画廊占 50–70% | 禁每张图加大白卡 |
+| `chapter-cinematic` | 章节分隔、情绪转场 | 背景/大字占 80%+ | 禁补卡片填满 |
+| `quote-focus` | 总结、金句、决策页 | 大字 + 背景占 80%+ | 禁堆要点 |
+
+配套字段也必须写：`visual_focus`（第一眼看到什么）、`text_zone`（文字净区）、`visual_role`（背景/前景/图表/画廊）、`copy_budget`（标题和要点字数上限）。这些字段是防止弱模型退回“卡片墙”的护栏。
+
+最佳质量页还必须写清以下设计决策，供工作流和检查器验证：
+
+- `main_visual_layer`：主视觉层。必须是具体画面或图表，例如 `AI 场景底图`、`客户图增强背景`、`透明前景特写`、`HTML/SVG 数据图`，不能写“渐变背景”或“文字内容”。
+- `supporting_visual_layer`：辅助视觉层。可为空，但总结页、实施页、观点页若没有客户图，应优先写 `底部锚点 AI 场景`、`前景特写插图`、`参数条/图表`。
+- `text_overlay_zone`：文字实际落区，必须和 `safe_text_zone` 一致或更具体，例如 `left-center`、`bottom-left`、`right-top`。
+- `visual_story`：这一页第一眼画面如何帮助理解 takeaway，1 句即可。
+- `semantic_image_prompt`：页面级最终生图提示词，融合 takeaway、VI、构图、文字净区、图片角色、目标比例和 `no text` 禁令；非 AI 页写 `html-svg` 并说明图表类型。
+- `forbidden_layout`：本页明确禁止项，通常包含 `no card wall`、`no table wall`、`no white floating panels`、`no image frame`。
+
+### 2.2.2 Apple / DJI 式页面语法（`page_grammar` 必填）
+
+`composition_style` 解决“这一页大类是什么”，`page_grammar` 解决“这一页像产品详情页那样怎么讲”。设计文档每页必须写
+`page_grammar / image_weight / text_overlay_mode / primary_visual_type / safe_text_zone / max_visible_words`：
+
+| page_grammar | 用法 | 图文关系 | 禁用项 |
+|---|---|---|---|
+| `hero-scene` | 首屏、章节、总结、强观点 | 全幅场景/产品做背景，文字浮在净区 | 禁白卡，禁解释长段 |
+| `cinematic-feature` | 一个能力、一种体验 | 场景或产品渲染占 60–80%，文字只做标题+短证据 | 禁 4–6 个文字卡 |
+| `product-closeup` | 设备、部件、接口、材质、镜头 | 大特写 + 1–3 个标注/参数胶囊 | 禁把特写缩成角落 |
+| `image-mosaic` | 多场景、多样张、多使用案例 | 多个 rounded image tile，每块图为主体、短标签浮图上 | 禁文字卡片网格 |
+| `spec-overlay` | 参数、性能、卖点点睛 | 产品/场景大图 + 少量参数条/焦段条/性能数字 | 禁大表格 |
+| `data-visual` | 数据、成本、效率、趋势 | HTML/SVG 图表、轴线、条形、曲线承载信息 | 禁截图表格充数 |
+| `before-after-scene` | 改造前后、对比演示 | 左右/上下两个大场景或同一视角对比 | 禁小图 + 长解释 |
+
+字段语义：
+
+- `image_weight`：0–1 数字。产品/场景/特写页通常 0.60–0.90；`image-mosaic` ≥0.65；`data-visual` 的图表重量 ≥0.50。
+- `text_overlay_mode`：`scrim` / `floating-text` / `frosted-caption` / `side-copy` / `none`。它描述文字如何浮在图上或旁边，不是卡片分区。
+- `primary_visual_type`：`ai-background` / `source-enhanced-background` / `source-enhanced-hero` / `transparent-closeup` / `scene-photo` / `product-render` / `html-svg-chart` / `image-mosaic`。
+- `safe_text_zone`：文字净区，必须避让主体/人物/产品/图表关键区。
+- `max_visible_words`：本页可见中文字数上限。产品/场景页建议 30–55 字；影像拼贴 55 字以内；数据页可到 80 字但信息应由图表承载。
+
+**DJI 式网格不是卡片墙**：它可以有多个圆角块，但每块首先是照片、产品渲染、镜头剖面或场景图，文字只是短标签。若一个网格块里主要是标题+正文+小图标，它就是文字卡片墙，必须改为 `data-visual` 图表或拆成 `cinematic-feature`。
+
+| 优先级 | 模板 | 适合内容 | 图像策略 | 文字策略 |
+|---|---|---|---|---|
+| ★首选 | **背景主导** | 封面、章节、总结、强观点页 | 高分辨率 AI 背景、合格客户图背景，或 `source-enhanced` 背景 | 少量大字 + scrim/磨砂板，文字落净区 |
+| ★首选 | **左右产品剧场** | 产品/设备/场景 + 解释 | 左/右一侧大图，另一侧文字和参数 | 标题 + 3–5 条要点 + 指标条 |
+| ★首选 | **上图下文** | 横向宽图、场景图、全景图 | 上方 21:9/16:9 横幅，保留主体 | 下方做论点、证据和数据 |
+| ★首选 | **半包围文字** | 主图不适合背景但想要融合感 | 图在一侧或中部，文字沿边缘/上下包围 | 使用短句、参数胶囊、引导线 |
+| ★首选 | **参数条 + 大图** | 产品页、方案页、性能页 | 大图占 55–70%，底部/侧边参数条 | 参数用 HTML 原生文本与图标 |
+| ○图表 | **图表主导** | 数据、对比、成本、效率、时间变化 | HTML/SVG **优先 柱/曲线/进阶时间线/指标胶囊/对比列**承载数据；**表格仅作最后手段（确为多维矩阵时）** | 标题说明结论，图表承载证据 |
+| ◇次选 | **图像证据卡** | 低清但有价值的客户图、截图、事故图 | 小图或角落证据图，周围用边框/标注解释 | 文案承担解释，图只做证据 |
+| ◇次选 | **四宫格画廊** | 多张同类小图、设备矩阵、场景组合 | 每格 contain，不裁切；统一题注 | 每格一句判断，或一条总标题统领 |
+| ◇次选 | **中心产品 + 周围论点** | 产品能力、平台生态、硬件参数 | 中心大图/产品图，四周卡片/指标/连线 | 论点环绕，避免压主体 |
+
+决策原则：
+
+- **有可做背景/hero 的图（AI 或合格客户图）的页 → 走★首选编辑式融合（背景主导/左右剧场/上图下文/半包围/参数条+大图），不再叠表格或悬浮卡墙**；客户图证据卡/画廊仅用于低清证据图，**且同页不堆叠多张大图**（多张→拆页或缩为证据画廊）。
+- **客户图不是只有“背景/不用”两种选择**：低清图做证据卡/小图画廊，高质图做主视觉，不合比例但重要的图走 `source-enhanced`。
+- **结构性表达优先 HTML/SVG，且数据优先图表化**：柱状图、折线图、时间线、流程图、架构图、对比矩阵、指标卡都由 HTML/CSS/SVG 画，文字可编辑、比例可控；**数据/对比优先做成图表/对比列，表格是最后手段（仅多维矩阵）**。
+- **非结构化画面积极生图**：用户没给但文案需要的安装图、产品使用场景、车间现场、设备特写、氛围背景，用文生图；用户给了低质参考则图生图。
+- **一页可以多层协作**：例如 AI 氛围背景 + HTML 参数条 + 客户图证据卡 + 可编辑标题，不要机械限制成一页一图。
+
+---
+
+## 2.5 整体构图均衡（铁律——每页排完先过这关）
+
+> **先立心态：大胆按设计原则把画布填满。** 构图闸门（见文末）是**事后抓"真重叠"**的——重叠便宜、可改；
+> 别为了躲重叠而畏首畏尾地摊空、缩字、留大片白。**"空"是比"挤"更糟的失败**：宁可先按设计原则填满、
+> 再让闸门指出真碰撞去微调，也不要一上来就设计得稀疏求稳。填满靠的是**实质内容 + 图文互补**，不是放大字 / 塞空图。
+
+构图模式选好后，还要让**整页视觉重量均衡**，不能半边满半边空、也不能挤在角上：
+
+- **黄金比例 / 三分法**：主标题、主图、关键数据这些视觉焦点，落在**黄金分割线（≈0.618）或三分法的四个交点**
+  附近，比硬居中或贴边更稳、更高级。横版 16:9 善用左右分栏（约 38:62 / 62:38）或上下分带的**互补**关系。
+- **禁止空半**：内容只占上 / 下 / 左 / 右一半，而**另一半空着、既无图也无文**——版面失衡、像没做完。
+  要么用图填、要么用文字/图形填、要么调分栏让两侧都有内容。
+- **禁止挤角**：所有内容只堆在某个角或四个角、中间大片空——同样失衡。
+- **留白是有意的负空间**：留白用来给主体/文字呼吸、对齐图槽、引导视线，不是"半张纸没排满"。
+- **图文互补填满版面**：A 路线图与文字零重叠，但**图块 + 文字块合起来要把版面填得均衡**；
+  B 路线全幅图天然铺满、文字按 scrim 侧布局。整体追求稳定的视觉平衡（对称，或有重量感的非对称平衡）。
+- **空半先补实质内容，别急着塞图**：某页显得空，**先回 `draft.md` 精炼更多要点 / 改用更密的版式**把它填实（见 0.6 的补救顺序）。
+  AI 插图只在两类真需求时上：封面 / 章节分隔的**氛围大图**，以及「文字与 HTML 都画不清的画面 / 概念」（见第 1 节 A/B 二分）。
+  **不要把"配一张图"当薄内容的创可贴**——薄文字旁再放一张 airy 空图，是把单重空变成双重空，看着更没做完。
+- **重叠的修法优先级：① 移动/重排 → ② 精炼文案 → ③ 缩字（≤20%）**（2026-06-18 裁决，配合放大字号要保大字号）：
+  内容相互叠加（封面小标签压大标题、两段文字框相交、图内标签挤）时，**首选移动/重排躲开**（拉开间距 / 换槽位 / 调 grid 模板 / 放大图形给标签让位），
+  其次**精炼/精简该段描述使其更短**；实在不行才**缩小字体，但单次最多缩 20%、且仍 < 该页主标题**——别靠狂缩字把原文硬塞下。
+- **空先补内容 + 加辅助解释 HTML 元素，不是放大字号/拉大卡片**：某页显空时，**先回 `draft.md` 补实质要点**，
+  再加**辅助解释的 HTML 元素**（图示 / 图标 / 要点卡 / SVG 小图表 / 分隔光带）把版面做实；放大字号、把卡片拉大撑满都是治标末选，单靠它们=「空心更大」。
+  （注：当前 PPT 工作流默认用 `--no-occupancy` 关闭占空比族迭代；空半、挤角、页面过空只作为人工审美判断和手动调试线索，不作为默认改稿驱动。）
+- **图片防挤压（等比 + 热区，绝不变形）**：A 路线图被槽位 `object-fit:cover` 裁切时，**绝不**用非等比的
+  `width/height` 拉伸；用 `object-position` 把图片**内容热区（主体）**对到槽位可见区（如 `object-position:center 30%`
+  做垂直平移），让裁掉的是**边缘负空间**而非主体。要换构图比例就**改槽位尺寸 + 按新 aspect 重新生成**
+  （见第 2 节映射表），不要直接改 `<img>` 的宽高比把图压扁/拉长。
+
+---
+
+## 3. 构图型提示词配方（写进 `img_plan.json` 的 prompt）
+
+把「**本页文案要表达的核心**」翻译成贴切的**英文**提示词，按这个结构拼（顺序即权重）：
+
+```
+<主体/场景：紧扣本页要表达的概念>,
+<风格：与 VI/设计系统一致，如 modern flat vector / clean 3D isometric / cinematic photo>,
+<构图：主体位置 + 负空间位置，对齐槽位与文字侧>,
+<光线/色调：与配色协调，如 cool blue-and-white palette, soft diffused light>,
+<aspect：显式写出，如 4:5 portrait composition>,
+no text, no words, no letters, no captions, no logos
+```
+
+**铁律：**
+- **必须英文**（中文 prompt 模型也认，但效果差；用户给中文别主动翻，由调用方/设计步翻成英文）。
+- **必须显式禁止图内文字**（结尾 `no text, no words, no letters…`）——AI 生图爱在图里加字，中文尤其会糊；
+  PPT 的字由 PPT 文本框负责，图里绝不能有字。
+- **构图按路线对齐版面（A 路线图要填满、别 airy）**：
+  - **B 路线（模式①全幅背景，文字压在图上）**：只在**文字所在侧留一条低对比净空带**（够放标题即可，如
+    `a low-contrast calm zone on the left for headline overlay`），**其余照常画满**，别整张图都空。
+  - **A 路线（模式②③半幅图，图在自己槽位、文字在另一半）**：图**不需要**为文字让空——让
+    **主体填满画面、占满槽位**（`subject fills the frame, edge-to-edge composition`），构图饱满才不显空。
+- **色调与 VI 协调，但内容插图以画面真实色为准（见 0.9 配色解耦）**：
+  - **B 路线全幅底图 / 氛围图 → 跟 VI 走**（它就是背景）：`vi-aqua-glass` 写 `cool blue and white, soft gradients`、
+    `vi-nebula-console` 写 `deep navy, electric blue accents, dark tech mood`。
+  - **A 路线内容插图 → 以画面内容真实/恰当色为准**（电路板=铜绿、山=蓝绿、产品=本色），只需与 VI **协调不冲突**
+    （共享冷暖或留 VI 作点缀），**别把所有插图都染成 VI 单色**（否则页面死板、配图失真）。
+
+示例（模式② 左图右文，主题「云计算服务模型」，aqua-glass 风）：
+```
+A clean modern flat vector illustration of cloud computing service layers (IaaS, PaaS, SaaS)
+as stacked translucent panels connected to a central cloud icon, subject fills the frame
+edge to edge, cool blue and white palette, soft diffused light,
+4:5 portrait composition, no text, no words, no letters, no captions, no logos
+```
+
+---
+
+## 4. 与 hybrid 三层导出 / 校验的衔接
+
+- **分层现在自动**（`tagLayers` 截图前按结构判定），下面的标注**可选**、仅作 override：
+  - A 路线的图槽（含 `<img>`/`<svg>`/卡片/色块/带底色或边框的块）**自动**切成中层独立图片，无需标 `foreground`。
+  - **中层「递归切图」（每个 HTML 图元各自可拖）**：一个带底色/边框的容器若含 **≥2 个独立块子**（一排圆、多层架构、树节点、卡片网格），
+    导出会把它当**底板 plate** 切一张、再把**每个子块各切一张**（可多层嵌套），切 plate 时自动隐藏子块、零重复。
+    于是 PPT 里**每个圆/每层/每个节点/每张卡都是独立可拖对象**。**前提：这些结构必须用离散 HTML 元素搭**（见下「可拆结构」铁律）。
+    只含 0–1 个块子的卡仍整切（不过碎）。显式 `data-pptx-layer="foreground"` = 强制整切（去嵌套），用于「这块就要当一张图」。
+  - B 路线用 `background-image`+scrim 仍**自动**留背景层（全幅基底不切）。
+  - 文字（含卡内、SVG `<text>`、散字）**自动**提到顶层可编辑框、永不烧进图；带底色的药丸/标签其**底色留切图、文字提顶层**。
+  - 要让某元素**保留烧进底图**（不单独编辑，如嵌进图形的艺术字）用 `data-pptx-export="ignore"`。
+- 导出必备 CSS 只剩一条（三层可见性切换由导出脚本注入的 CSS 自动完成，无需手写 `data-export-mode` 规则）：
+  ```css
+  [hidden]{ display:none !important; }
+  ```
+- 生成图任意原生尺寸都行——槽位 + `object-fit:cover` 会裁到位；aspect 只是让裁切更友好。
+
+### 构图均衡确定性闸门（前置到 HTML 层，**任何固定画布产物通用**）
+
+第 2.5 节的「禁止空半 / 挤角 / 叠加」不是散文劝诫，而是一道**绕不过的确定性门**——但**先在 HTML 层判、别等导出 pptx**：
+
+```
+node scripts/export_pptx_from_html.mjs <deck.html> --measure-only --mode hybrid --width 1920 --height 1080 --workdir <dir>
+python scripts/layout_balance.py <dir>/layout-report.json --no-occupancy -v
+```
+
+- `--measure-only` 只渲染量三层几何、写 `layout-report.json`（**不截图、不切图、不打包 pptx**），秒级；
+  `layout_balance.py` 读它逐页判，FAILED 会**指出哪页、哪种缺陷、在哪（归一化坐标）、量化到多少**。
+- **闸门像 zod 一样只报问题、不替你定方案**：每条消息格式 `【问题类型】页 · 位置 · 量化范围`，后缀「｜可参考修法」仅提示。
+  ★ **2026-06-24 工作流裁决：默认关闭占空比族迭代，保留重叠 / 截图夹带文本等硬门。** 判定如下：
+  - **ERROR（硬门，必清零）**：
+    ① **内容相互叠加**（主门，唯一不可妥协）：报 元素@归一化坐标 ×「另一元素」@归一化坐标 · 重叠区@归一化坐标（0–1，原点左上）。
+       同一前景块内文本互叠（如 SVG 图密排标签）自动豁免。
+    ② **截图夹带文本**（用户硬要求）：背景截图态下仍可见的 HTML/SVG/伪元素文字——会烧进底图/切图且不可编辑。
+       修法 = 改成真实 DOM 文本节点（别放 `::before/::after`、别烧进图）；唯一例外是 AI 插图自带画面字（不在此列）。
+    ③ **整页啥也没有**：无文本/前景框且无底图（最小 sanity，仍 downgradeable）。
+  - **WARNING（提示不拦）**：① 文本溢出/裁切；② **字号过小**（屏上 < `FONT_FLOOR_PX=24`，按 §0.85 阶梯放大）；
+    ③ 超出画布、对比度不足等会影响放映的工程风险。
+  - **手动调试项**：页面过空 / 过半页面过空 / 空半·挤角 / 空心卡片等占空比族检查仍在脚本里，但默认工作流用 `--no-occupancy` 关闭；
+    只有人工明确要排查"页面是否太空/太碎"时才打开，避免把合理留白误判成失败。
+- 所以构图门**默认不管"够不够满"**：靠 **0.8「每页 ≥1 视觉元素」+ 实质内容**自然填满；硬门是「重叠 / 截图夹带文本」。
+  闸门只量**像素几何 + 字号**抓真碰撞/夹带/偏小；内容深度/密度由上游 draft / design 的 key_point 保证。
+- **修法方向（闸门提示也照此给）**：修「重叠 / 溢出」→ **先移动/重排躲开 → 再精炼描述文案使其更短 → 最后才缩小字体
+  （单次最多 20%、仍 < 主标题）**；保住放大后的字号，别一味缩字。
+- **每页修改配额（防无限改烧配额）**：对每个被判 ERROR 的页**最多修 3 次**（Edit + 重跑 measure-only），
+  **第 3 次后无条件放行**（`touch layout_ok` 继续导出），report 诚实列出仍有残留的页——不再无限纠缠。
+- **这是 TAOR 式「工具校验 → 报错 → 重设计」闭环**：把 FAILED 的具体违规喂回去改 HTML（复用同批图、重排不重新生图）→ 再 measure → 直到 PASS。
+  **PASS 前不要导出 pptx**——measure 是秒级的，反复全量导出 pptx 才是浪费。
+- **通用性**：这套度量适用于**任何固定画布产物**——deck 每页、app/移动端固定框、canvas 选项格（传对 `--slides` 选择器与画布尺寸即可）。
+  **响应式网页不适用**（其滚动/英雄区留白是合理的），网页走 `browser_check_ui_artifact.mjs`（溢出/触达/控制台/视觉）。
+
+### 配图分流确定性闸门（结构图必须 HTML，**生图前拦截**）
+
+与构图闸门同哲学的**第二道确定性门**，治"AI 偷懒把结构图当配图生"：
+
+```
+python scripts/image_plan_lint.py <dir>/img_plan.json --outline <dir>/outline.json -v
+```
+
+- 扫 `img_plan.json` 的 prompt（英）+ `outline.json` 里 `route=ai-A/ai-B/source-enhanced` 页的 `visual.note`（中），命中**图表型名词**
+  （architecture / flowchart / decision tree / parallel tracks / 架构 / 流程图 / 决策树 / 双轨 / 对比图…）即 FAILED——那张应改 HTML/SVG。
+- **刻意不封堵**装饰/设计词（nodes / lines / geometric / gradient / visual hierarchy / 对比色 / 裸 layers·分层）→ 不误伤氛围/隐喻图。
+- **诚实边界**：只抓**自报式**结构 prompt；改写措辞规避（"five stacked bands" 不写 "layers"）抓不到，那一层靠本节「🚫 绝不可把结构图伪装成抽象背景」的 guidance。
+- 闭环同上：FAILED → 把该页 route 改 html、用 div+CSS Grid / SVG 画结构、从 img_plan.json 删该条 → 重跑直到 PASSED。**置于生图前**，省下无效生图。
+
+---
+
+## 5. `img_plan.json` 契约（设计步产出，生图步消费）
+
+设计步在 `./build/img_plan.json` 写一个数组，**条数 = 实际需要 AI 生成或客户图增强的图**
+（HTML/CSS/SVG 能画的图形**不进**此文件；route=source 原图直接用也不进；条数可少于预算上限、甚至为 0=不写此文件），每条：
+
+```json
+[
+  { "file": "img_1.png", "mode": "text-to-image", "aspect": "16:9", "prompt": "<构图型英文提示词，见第3节>" },
+  { "file": "enhanced_src_1.png", "mode": "image-to-image", "source_file": "src_1.png", "aspect": "16:9", "prompt": "<基于原图扩图/换背景/提高清晰度的英文提示词>" }
+]
+```
+
+- `file`：落到 `./build/assets/<file>`；HTML 里用 `assets/<file>` 引用（相对 deck.html）。
+- `mode`：`text-to-image` 表示纯文生图；`image-to-image` 表示基于 `source_file` 的客户图增强。老计划未写 `mode` 时按 `text-to-image` 兼容。
+- `source_file`：仅 `image-to-image` 必填，必须是 `material.json images[].file` 里的原始客户图文件名，如 `src_1.png`。
+- `aspect`：**按第 2 节表格由槽位定**，不是随手填。
+- `prompt`：英文、含禁字尾巴、构图对齐版面与文字侧。
+- 不需要插图就**不写这个文件**（生图步据此跳过）。
+
+---
+
+## 6. 自检清单（交付前过一遍）
+
+- [ ] 每张图判过「HTML 还是 AI」：示意图形用了 HTML，画面 / 需美感的配图才进 img_plan.json？
+- [ ] 每页整体构图均衡：焦点在黄金分割/三分线附近，无空半、无挤角，图文互补填满版面？
+- [ ] 每张图判过 A/B 路线，标注 / `background-image` 用对了？
+- [ ] 每张图的 aspect 由槽位推出、写进 img_plan.json？
+- [ ] A 路线图与文字零重叠；B 路线有 scrim 且文字侧够暗/够亮可读？
+- [ ] prompt 全英文、含 `no text…` 尾巴、色调跟 VI、构图对齐文字侧？
+- [ ] 前景块只标最外层（去嵌套）、卡内文字标 `kind="text"`、导出必备 CSS（`[hidden]`）在？
+- [ ] 图距边 ≥80px（全幅背景除外）、一页不堆多图？