| name | epub-style-demo-maintainer |
| description | 维护 epub-style-demo 兼容 fixture、reader matrix、最终规则和验证循环。用于 EPUB 阅读器行为变化、需要新增 demo 覆盖、或需要把实测发现沉淀为最终生产规则时。 |
EPUB Style Demo 维护
当修改 templates/epub-style-demo/、新增阅读器兼容场景，或把阅读器发现转成最终 EPUB 生产规则时使用这个 skill。
固定工作流
- 从
templates/epub-style-demo/ 开始。新增或更新能暴露阅读器行为的最小 fixture。
- 构建 demo：
sh templates/epub-style-demo/build.sh
- 用 stdlib-only 脚本验证结构：
scripts/validate-epub-style-demo.sh --epub templates/epub-style-demo/dist/<artifact>.epub
scripts/validate-popup-notes.sh --epub templates/epub-style-demo/dist/<artifact>.epub
- 把产物记录到
docs/final/reader-matrix.yaml。需要人工复测或版本待确认时使用 warn，不要虚构 pass/fail。
- 只有 fixture 和 matrix 记录都存在后，才更新
docs/final/SPEC-实现约束.md，然后更新最终手册和速查表。
- 如果规则影响自动化行为，同步更新相关
skills/*/SKILL.md，但不要改变 frontmatter 字段名。
当前兼容规则
权威弹注结构源是 docs/final/SPEC-实现约束.md §1；以下兼容规则不得单方面新增或改名同族 class。
- 图片环绕主路径使用
figure.img-left / figure.img-right。float 和百分比 width 挂在 figure 上，先从 25% 到 35% 调整，再结合目标阅读器、视口和字号实测。
- 不固定图片高度，也不把
aspect-ratio 作为主路径。真实图片通过 height:auto 保持宽高比，figure 也需要自然高度以承载图注。
- direct
img float 不是主路径，因为部分阅读器会把图片渲染得过小。
- 书内图片以 JPEG / PNG 为生产主路径。WebP 只作为现代阅读器实验；demo WebP 在 Kindle conversion logs 中触发 W14012 / W14015。SVG 可作为增强测试，但 Kindle 目标构建需要在渲染不确定时提供 JPEG / PNG 栅格 fallback。
- 图文环绕测试需要足够长的周围正文。短段落只是阈值反例，不足以证明 float 失败。
- 波浪下划线必须拆开：先写
text-decoration: underline;，再写 text-decoration-style: wavy;。Kindle App fallback 为普通 underline。
- 含 MathML 的 XHTML manifest item 必须带
properties="mathml"。
- MathML 覆盖应保持在 KDP Enhanced Typesetting 和 EPUB 3 支持标签范围内，除非新实验有理由扩展。
- 多看旧版 fallback 使用
ol.footnote-list.duokan-footnote-content；单个 li.footnote-item 只加 duokan-footnote-item。
- 英文书籍规则先按类型拆分：小说/散文走
.english-fiction，非虚构后续单独 fixture；英文正文必须声明 lang，使用短 serif 链，首段无缩进、后续段缩进，未验证断字时不强制 justify。
- 英文小说插图默认居中
figure，不把图文环绕作为 fiction 主路径；首字优先用 ::first-letter 保持正文单词完整，旧式 span 首字和 float drop cap 只作增强并需大字号复测。
- 章节头图属于普通可重排章首结构，放
literary.css；头图只做装饰，标题必须是真实 h1。小章标保守宽度，满栏横幅用 width:100% 铺满正文内容栏并由源图比例控制高度。
- 便签/资料卡主路径使用 border、background、padding 和 left-rule；box-shadow、inset、不规则圆角和 outline-offset 只作为可丢失增强。
- 通用 demo 不使用
transform: rotate() 旋转便签块；Kindle Previewer 3.104（2026-05-23 实测）会触发 KFX 增强排版内部错误。需要斜角感时用不对称边框、圆角和投影模拟。
- SVG 花边只作为 demo 实验项，用来验证简单内联 SVG 边线可行性，不作为推荐边框；长条投影框必须保留真实文本和边框兜底。
验证期望
提交前至少运行：
sh templates/epub-style-demo/build.sh
scripts/validate-epub-style-demo.sh --epub templates/epub-style-demo/dist/<artifact>.epub
scripts/validate-popup-notes.sh --epub templates/epub-style-demo/dist/<artifact>.epub
xmllint --noout templates/epub-style-demo/OEBPS/package.opf templates/epub-style-demo/OEBPS/nav.xhtml templates/epub-style-demo/OEBPS/toc.ncx
git diff --check
如果本机没有 xmllint，Python 验证脚本仍会用标准库解析 XML，并捕获 manifest/link/MathML 错误。
