# HTML 页面生成统一规范（Step 5c 全体 PageAgent 必读）

> 本文件是 26 页 HTML 生成的**唯一统一规范**。所有子代理必须先读本文件，再读自己负责页面的 planning JSON 与 `ppt-output/style.json`。

---

## 0. 输入文件位置

| 项目 | 路径 |
|------|------|
| 全局风格 | `D:\workspace\cfc\ppt-output\style.json` |
| 每页策划稿 | `D:\workspace\cfc\ppt-output\planning\planning{N}.json`（N = 页码）|
| 配图目录 | `D:\workspace\cfc\ppt-output\images\` |
| 输出目录 | `D:\workspace\cfc\ppt-output\slides\slide-{N}.html` |

**图片路径映射规则**（必须严格遵守）：
- planning 中某 card 的 `image.needed == true` 时，该 card 配图文件 = `../images/slide_{页码:02d}_{card在cards数组中的索引}.png`
- 例：slide 6 的 cards[2].image.needed=true → `../images/slide_06_2.png`
- HTML 位于 `slides/` 目录，所以 `<img src="../images/slide_06_2.png">`

---

## 1. 画布物理红线（不可违反）

```css
body {
  width: 1280px; height: 720px; overflow: hidden;
  background: var(--bg-primary);
  font-family: var(--font-family);
  position: relative;
}
```

- 画布固定 1280×720，**禁止**写 `100%` 或 `transform: scale()` 缩放 hack
- 所有 CSS 内联在 `<style>` 标签中，禁止外部 CSS 文件
- 所有颜色必须通过 `var(--xxx)` 引用 CSS 变量（从 style.json 的 css_variables 展开到 `:root`），**禁止硬编码色值**
- **禁止动画**：`@keyframes` / `animation` / `transition` 一律禁用（PPTX 导出不支持）
- 字体：中文 `'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif`；数字可用 `'Inter', 'PingFang SC', ...`

## 2. 统一导航骨架（跨页一致性合同）

### 标题区（content / toc 页强制）

```html
<header class="slide-header">
  <span class="overline">PART 0X &mdash; 章节名</span>
  <h1 class="page-title">页面标题</h1>
</header>
```

```css
.slide-header { position: absolute; top: 20px; left: 40px; right: 40px; height: 50px;
  display: flex; align-items: baseline; gap: 16px; z-index: 10; }
.overline { font-size: 10px; font-weight: 700; letter-spacing: 2px;
  color: var(--accent-1); opacity: 0.8; text-transform: uppercase; white-space: nowrap; }
.page-title { font-size: 26px; font-weight: 700; color: var(--text-primary); line-height: 1.2; margin: 0; }
```

### 页脚区（content / toc / section 页强制）

```html
<footer class="slide-footer">
  <span class="footer-section">章节标签</span>
  <span class="footer-page">NN / 26</span>
</footer>
```

```css
.slide-footer { position: absolute; bottom: 12px; left: 40px; right: 40px; height: 20px;
  display: flex; justify-content: space-between; align-items: center; z-index: 10; }
.footer-section { font-size: 10px; color: var(--text-secondary); opacity: 0.5; letter-spacing: 1px; }
.footer-page { font-size: 10px; color: var(--text-secondary); opacity: 0.5; }
```

- `cover` 页：标题自由发挥（巨大冲击力），页脚可选
- `section` 页：标题自由发挥，**页脚强制**
- `end` 页：标题自由发挥，页脚可选

## 3. 管线兼容防偏移规则（html2svg → svg2pptx 转换保证）

| 禁止 | 正确替代 |
|------|---------|
| `::before` / `::after` 用于视觉装饰 | 真实 `<div>` / `<span>` |
| `background-clip: text` 渐变文字 | `color: var(--accent-1)` |
| `mask-image` / `-webkit-mask-image` | div 遮罩（linear-gradient 背景）|
| `conic-gradient` | 内联 SVG `<circle>` + stroke-dasharray |
| CSS border 三角形 | 内联 SVG `<polygon>` |
| `mix-blend-mode` | `opacity` 叠加 |
| `filter: blur()` | `opacity` 或 `box-shadow` |
| `content: '文字'` | 真实 `<span>` |
| CSS `background-image: url(...)` 放图 | `<img>` 标签 |
| SVG 内 `<text>` 元素 | HTML `<div>` 绝对定位叠加 |
| 大小字号内嵌 span（`3.08<s>s</s>`） | flex + 独立 span |
| `stroke-dashoffset` | `stroke-dasharray="弧长 间隔"` 两值格式 |

**配图融入技法**（管线安全）：渐隐融合（div 遮罩 linear-gradient）/ 色调蒙版（半透明 div）/ 氛围底图（低 opacity `<img>` 0.05-0.40）/ 裁切视窗（overflow:hidden）/ 圆形裁切（border-radius）。全部用 `<img>` 标签实现。

## 4. 卡片系统

### card_style 6 种存在感（每页至少混用 2 种）

| 变体 | 存在感 | 实现 |
|------|--------|------|
| `filled` | 沉稳大地 | 实体背景 `linear-gradient(var(--card-bg-from), var(--card-bg-to))` + border |
| `transparent` | 无界之灵 | 无背景无边框，内容裸露 |
| `outline` | 虚境描边 | 极淡边框 `border: 1px solid rgba(255,255,255,0.08)` |
| `accent` | 灼焰核心 | accent 渐变填充 + 反色文字，**每页最多 1 个** |
| `glass` | 雾中幻影 | 半透明背景 `rgba(255,255,255,0.06)` + backdrop-blur |
| `elevated` | 悬崖浮岩 | 实体背景 + 3-4 层 box-shadow + translateY(-4px)，**每页最多 1 个** |

### 排版阶梯

| 层级 | 字号 | 字重 | 用途 |
|------|------|------|------|
| H0 | 48-160px | 900 | 封面主标题（尽量 ≥80px）|
| H1 | 26-32px | 700 | 页面主标题 |
| H2 | 16-20px | 700 | 卡片标题 |
| Body | 13-14px | 400 | 正文（line-height 1.8）|
| Caption | 9-12px | 400 | 辅助标注 |
| Data-Hero | 64-120px | 900 | 核心 KPI 超级数字（数据页至少 1 个 ≥64px）|
| Data-Sub | 28-40px | 800 | 辅助指标 |

- 每页最大/最小字号倍数比尽量 ≥ 5 倍
- **所有数字** `font-variant-numeric: tabular-nums proportional-nums`
- 字距：大字 -0.02em~-0.045em，小标 +0.15em~+0.3em

### 布局（layout_hint 决定重力场）

| layout_hint | 重力场 |
|-------------|--------|
| `single-focus` | 全重力汇聚中心/黄金分割点 |
| `symmetric` | 左右等量对峙 |
| `asymmetric` | 重力偏向一侧（6:4）|
| `three-column` | 三个均衡重力池 |
| `primary-secondary` | 贯穿式主区 + 轻量卫星 |
| `hero-top` | 顶部横贯大坝 + 底部溪流 |
| `mixed-grid` | 多个异构重力点交错 |
| `l-shape` | L 形轨迹：主体→侧面→底部 |

内容区：x=40, y=80, w=1200, h=580；卡片间距 16-20px；圆角 12-14px。
**禁止所有卡片等宽等高排一行**（那是 Word 文档）。用主副节奏 / 递减 / 交错 / 孤岛+群落制造韵律。

## 5. 图表规范（planning 中 chart.chart_type 必须实现）

- 纯 HTML/CSS/SVG 实现，**无 JS 运行时**
- 所有颜色用 CSS 变量
- SVG 内**禁止 `<text>`**，所有标签/数字/图例用 HTML div 叠加
- 环形图：SVG circle + `stroke-dasharray="弧长 间隔"` + `transform="rotate(-90 cx cy)"`，中心文字 HTML 叠加
- 进度条：div 填充 `width:%`
- 时间线：HTML flex 结构 + 真实 div 连线
- 数字必须 tabular-nums

## 6. 数据卡片铁律

- 每个 `data` 卡片：核心数字 ≥64px + 单位/标签 + 补充解读 + 至少一个 CSS 可视化（进度条/环形/对比柱/sparkline）
- `data_points` 数组逐项渲染，`interpretation` 作为解读文字

## 7. 对账与打标（visual_qa 检查项）

- **每个 planning card 必须有对应 HTML 渲染根节点**，根节点加 `data-card-id="<card_id>"`（如 c1, c2...）
- 每个 chart 渲染节点加 `data-chart-type="<chart_type>"`
- **所有纯装饰节点**显式打标 `data-decoration-layer="background|floating|page-accent"` + `aria-hidden="true"`，并按 `density_contract.decoration_budget` 控制数量
- 五层景深：背景层 z=0 / 装饰底纹 z=1 / 内容卡 z=2 / 强调浮层 z=3 / 焦点 z=4，每页至少激活 3 层

## 8. 跨页一致性

- 全部 26 页共享同一风格基因（CSS 变量 + 字体系统）
- 数据页/内容页视觉风格统一骨架，但每页构图不同
- 章节色彩递进：Part 01 用 accent-1（暖橙 #FF8C42）、Part 02 用 accent-2（亮蓝 #5AB0FF）、Part 03 accent-1/2 交替、五维页用五维色（身#FF8C42 心#FF6B9D 智#6366F1 行#10B981 富#F59E0B）点缀
- 密度交替：章节封面（低密度留白）与内容页（中高密度）形成节奏

## 9. 输出要求

- 每个 HTML 文件写入 `D:\workspace\cfc\ppt-output\slides\slide-{N}.html`（N 为页码，如 slide-1.html）
- 文件开头必须有 `<!DOCTYPE html><html lang="zh-CN"><head><meta charset="UTF-8">`
- 文件必须是**纯净 HTML**，禁止写入任何 Prompt 指令/思考过程/注释说明

## 10. 生成后自检清单

- [ ] body 1280×720 overflow:hidden，无 scale hack
- [ ] 全部颜色走 CSS 变量
- [ ] 无动画、无伪元素装饰、无 background-image 放图
- [ ] SVG 内无 `<text>`
- [ ] 每个 planning card 有 `data-card-id` 根节点
- [ ] 装饰节点有 `data-decoration-layer` + aria-hidden
- [ ] 每页 ≥2 种 card_style，accent/elevated 各 ≤1
- [ ] 数字全部 tabular-nums
- [ ] data 卡片有 ≥64px 超级数字 + 可视化
- [ ] 图片用 `<img src="../images/slide_XX_Y.png">` 且文件存在
- [ ] 无文字溢出画布（overflow:hidden + 合理字号）