ppt-build

name	ppt-build
description	PPT 编码生成子技能。生成、编写、修改、调试幻灯片的 HTML/CSS/JS 代码。 当用户说"生成PPT的HTML"、"写CSS"、"PPT代码有问题"、"CSS样式出问题"、 "JS报错"、"slide切换不正常"、"文件结构怎么组织"、"字体大小不对"、"PPT bug"时触发。 触发词: 生成HTML, 写CSS, 写JS, 编码, 代码有问题, 样式出问题, 报错, bug, slide切换, 文件结构, 多文件项目, build slides, code slides, HTML, CSS, JS.

ppt-build — 编码阶段

子技能 of web-ppt。负责 HTML/CSS/JS 编码规范、命名契约、字体下限、录制面板。

---

决策树

编码任务
  │
  ├─ 新建 PPT 项目
  │    ├─ 确定文件结构 → §文件结构与生成顺序
  │    ├─ 确定所有类名 → §命名契约核心
  │    ├─ 写 HTML → 按命名规则
  │    ├─ 写 CSS → 按命名规则 + ../references/css-gotchas.md
  │    ├─ 写 JS → 按全局 UI 名称
  │    └─ 验证 → §事后对齐验证
  │
  ├─ 字体大小相关 → font-size-rules.md
  ├─ 录制面板相关 → recording-system.md
  └─ CSS 技术问题 → ../references/css-gotchas.md

---

文件结构与生成顺序（内联）

my-presentation/
├── slides.html            # HTML 入口：结构 + data-narration
├── slides.css             # 所有样式（@font-face / 变量 / 布局 / 动画 / 响应式）
├── slides.js              # 所有逻辑（导航 / TTS / 字幕 / 录制按钮）
└── fonts/                 # 本地 woff2 字体

生成顺序（必须是这个顺序）：

1. slides.html  →  先写 HTML，确定所有 class/id/data 属性
2. slides.css   →  根据 HTML 的实际 class 名写样式
3. slides.js    →  根据 HTML 的实际 class/id 写选择器
4. fonts/       →  从 ../references/fonts/ 复制选定字体

关键：HTML 先行。 CSS 和 JS 必须根据 HTML 的实际 class/id 编写。

本地预览：

python3 -m http.server 8080 --directory /path/to/my-presentation
open http://localhost:8080/slides.html

禁止 file:// 协议打开模块化项目 — 浏览器会阻止外部资源加载。

---

命名契约核心（内联）

HTML 是 API 契约。 所有 class/id 在 HTML 中定义，CSS 和 JS 只是实现方。

1. 幻灯片包装器：.slide .slide-{type}

<section class="slide slide-cover active" data-narration="...">
<section class="slide slide-pain" data-narration="...">

常用 type：cover, pain, solution, grid, data, security, demo, quote, cta

2. 子元素：.{type}-{role}

slide-cover  → cover-tag, cover-title, cover-subtitle, cover-line
slide-pain   → pain-list, pain-item, pain-icon, pain-text
slide-grid   → grid-card, grid-icon, grid-title, grid-desc

3. 全局 UI：固定名称

<div class="progress-bar"></div>
<nav class="nav-dots" id="navDots"></nav>
<div id="subtitleBar" class="subtitle-bar"></div>
<div class="record-panel">
  <div id="recordStatus" class="record-status">就绪</div>
  <button id="recordBtn" class="record-btn" title="开始录制"></button>
</div>

4. 共享装饰类： .section-label, .fade-up, .fade-in, .slide-left, .scale-in, .stagger, .dot-grid, .glow-orb, .accent-line

5. 禁止： .card / .title / .desc（太泛化）、.slide-cover__title（BEM 下划线）

---

CSS 系统核心（内联）

.slide {
  width: 100vw; height: 100vh; height: 100dvh;
  position: absolute; top: 0; left: 0;    /* 禁止 inset:0 — Safari */
  display: none;                           /* 禁止 opacity:0 */
  flex-direction: column; justify-content: center; align-items: center;
  padding: 5vh 8vw; overflow: hidden;
}
.slide.active { display: flex; }

display:none/flex 是唯一可靠的显隐方式。 opacity:0 的元素仍占空间、可被点击。

---

事后对齐验证（安全网）

# 快速：CSS/JS 孤儿选择器检查
# 1. CSS 中是否有 HTML 不存在的类？
grep -o '\.[a-z][-a-z0-9]*' slides.css | sort -u | while read cls; do
  cls_name="${cls#.}"
  grep -q "$cls_name" slides.html || echo "CSS ORPHAN: $cls (not in HTML)"
done

# 2. JS 选择器是否在 HTML 中存在？
grep -oP "querySelector(?:All)?\(['\"]([^'\"]+)" slides.js | \
  sed "s/.*['\"]//" | while read sel; do
  sel_clean="${sel#.}"; sel_clean="${sel_clean#\#}"
  grep -q "$sel_clean" slides.html || echo "JS ORPHAN: $sel (not in HTML)"
done

# 完整：4-pass 质量验证
python3 ../scripts/slide_validator.py --html slides.html --css slides.css --json

---

文档索引

文档	内容	何时加载
naming-contract.md	完整命名规则 + 并行生成流程 + 验证命令	写 HTML/CSS/JS 时必须加载
font-size-rules.md	字号下限表 + 禁止模式	设置/检查字体大小时
recording-system.md	录制按钮 classList + 隐藏面板 + 完整 HTML	写录制相关代码时

全局共享文档

文档	内容
../references/layouts.md	布局代码库
../references/css-gotchas.md	CSS 陷阱速查
../references/fonts-integration.md	字体集成方式
../references/fonts/	24 个 woff2 字体 + 搭配推荐
../references/animations.md	动画代码库
../references/themes.md	主题配色方案