pptx-html-fidelity-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PPTX ↔ HTML Fidelity Audit

PPTX ↔ HTML 保真度审计

A repeatable workflow for catching the ways a

python-pptx

export silently drifts from its HTML source — and fixing them with a layout discipline that prevents the same regressions on the next pass.

一套可重复的工作流，用于排查

python-pptx

导出文件与HTML源文件之间的隐性偏差，并通过布局规范修复问题，避免后续导出出现相同回归。

When this skill applies

适用场景

The user has:

A source HTML slide deck (typically a single-file deck with

<section class="slide">

blocks):

html

<section class="slide light">
  <div class="chrome">2026 · Q2 review</div>
  <span class="kicker">Pillar 03</span>
  <h2 class="h-xl">Shipping <em>velocity</em> doubled</h2>
  <p class="lead">…</p>
  <div class="foot">page 5 / 14</div>
</section>

A PPTX file generated from that deck via python-pptx (or similar).
A suspicion (or visible evidence) that the PPTX doesn't match the HTML — text bleeding into the footer, italic words gone flat, hero slides not centered, sections cropped, tag styling lost.

If the user only has one of those two artifacts, this skill doesn't apply yet — first generate the missing one, or ask the user to provide it.

用户具备以下条件：

源HTML幻灯片（通常是包含

<section class="slide">

块的单文件幻灯片）：

html

<section class="slide light">
  <div class="chrome">2026 · Q2 review</div>
  <span class="kicker">Pillar 03</span>
  <h2 class="h-xl">Shipping <em>velocity</em> doubled</h2>
  <p class="lead">…</p>
  <div class="foot">page 5 / 14</div>
</section>

通过python-pptx（或类似工具）从上述HTML生成的PPTX文件。
怀疑（或已发现）PPTX与HTML不一致——内容溢出到页脚、斜体文字丢失、主幻灯片未居中、内容被裁剪、标签样式丢失。

若用户仅拥有上述两种文件中的一种，此技能暂不适用——需先生成缺失的文件，或请用户提供。

Why this is hard (and why a skill helps)

难点与技能价值

PPTX is a fixed-canvas, absolute-positioned medium. HTML is a fluid, flow-based medium. A naive python-pptx export pins each block at hand-picked

(top, left)

coordinates, which works for the first slide it was tested on and silently fails for every other slide whose content has different intrinsic height. The result is the most common drift modes:

Footer overflow — content's
```
top + height
```
crosses into the footer row.
Off-canvas content — bottom of last block exceeds
```
7.5"
```
(16:9 canvas).
Italic loss —
```
<em>
```
in HTML never gets
```
run.font.italic = True
```
.
Hero slides not centered — vertical-stack slides use
```
MARGIN_TOP
```
instead of computing center.
Box bounds intruding — the text fits, but the shape's bounding box is oversized and visually crosses the rail.
Tag/styling loss — colored chrome rows, kicker uppercase tracking, mono-vs-serif assignments quietly fall back to defaults.

Every one of these is a layout discipline problem, not a content problem. Once you adopt the discipline, they stop happening.

PPTX是固定画布、绝对定位的媒介，而HTML是流式、基于流布局的媒介。简单的python-pptx导出会将每个块固定在手动选择的

(top, left)

坐标上，这仅在测试的第一张幻灯片上有效，对于内容固有高度不同的其他幻灯片会悄然失效。常见的偏差类型包括：

页脚溢出 —— 内容的
```
top + height
```
超出页脚区域。
画布外内容 —— 最后一个块的底部超出7.5英寸（16:9画布）。
斜体丢失 —— HTML中的
```
<em>
```
标签未被设置为
```
run.font.italic = True
```
。
主幻灯片未居中 —— 垂直堆叠幻灯片使用
```
MARGIN_TOP
```
而非计算居中位置。
框边界越界 —— 文本虽能容纳，但形状的边界框过大，视觉上超出页脚边界。
标签/样式丢失 —— 彩色标题栏、小标题大写间距、等宽/衬线字体设置悄然回退为默认值。

所有这些问题都是布局规范问题，而非内容问题。一旦遵循规范，这些问题就不会再出现。

Workflow

工作流

The audit is five steps. Don't skip any of them — the discipline only works if the audit produces a real list of issues to drive the re-export. A fix-without-audit pass tends to leave half the issues alive.

审计分为五个步骤，请勿跳过任何一步——只有审计生成明确的问题列表，规范才能指导重新导出。未经审计直接修复往往会遗留半数问题。

Step 1 — Extract ground truth from the PPTX

步骤1 — 从PPTX提取基准数据

Run

scripts/extract_pptx.py <path-to.pptx> > pptx_dump.json

. The script walks every shape on every slide and dumps text, position (

top

left

), size (

width

height

), and per-run typography (font name, size pt, bold, italic, color). This is the actual state of the export — don't trust the export script's intent, trust the dump.

For 14-slide decks, the dump is ~30–60 KB and human-readable.

运行

scripts/extract_pptx.py <path-to.pptx> > pptx_dump.json

。该脚本遍历每张幻灯片的所有形状，导出文本、位置（

top

left

）、尺寸（

width

height

）以及逐段排版信息（字体名称、字号、加粗、斜体、颜色）。这是导出文件的实际状态——不要信任导出脚本的预期，要信任导出的结果。

对于14页的幻灯片，导出文件约30–60 KB，且易于阅读。

Step 2 — Walk the HTML structure

步骤2 — 遍历HTML结构

Read the source HTML and enumerate

<section class="slide">

blocks. For each, note:

The slide's theme (
```
light
```
/
```
dark
```
/
```
hero light
```
/
```
hero dark
```
).
The
```
chrome
```
row text (top metadata).
The
```
kicker
```
(small uppercase eyebrow above the headline).
The headline (h-hero / h-xl / etc.) and any sub-head.
The body copy and any structured blocks (pipeline steps, cards, pillars, observation cards).
The
```
foot
```
row (bottom metadata).
Any
```
<em>
```
or italic-styled spans — italic is the silent regression.

Map each HTML slide to a PPTX slide index. For decks following the convention "slide 1 = cover, slide N = closing", the mapping is positional.

读取源HTML，枚举所有

<section class="slide">

块。针对每个块，记录：

幻灯片主题（
```
light
```
/
```
dark
```
/
```
hero light
```
/
```
hero dark
```
）。
```
chrome
```
栏文本（顶部元数据）。
```
kicker
```
（标题上方的小型大写眉题）。
标题（h-hero/h-xl等）及任何副标题。
正文内容及结构化块（流程步骤、卡片、支柱、观察卡片）。
```
foot
```
栏（底部元数据）。
任何
```
<em>
```
或斜体样式的span标签——斜体是最容易隐性丢失的格式。

将每个HTML幻灯片映射到PPTX幻灯片索引。对于遵循“第1页为封面，第N页为结尾”惯例的幻灯片，映射关系为位置对应。

Step 3 — Build the audit table

步骤3 — 构建审计表格

For each slide, walk shapes from the dump and check against expected layout rules. Use this exact table format — the severity column is what drives the fix priority:

| Slide | Issue | Severity |
|---|---|---|
| 1 cover | meta-row 底端 6.95" 蓋過 footer (6.7") | 🔴 |
| 5 checklist | row B 步驟描述底端 7.2" 切到 footer | 🔴 |
| 8 3E | 收束段落直接坐在 footer 起點 | 🔴 |
| 9 on-day | step 描述底端剛好碰 footer，無安全距 | 🟠 |
| 多處 | em (Playfair italic) 未保留 | 🟡 |

Severity rubric:

🔴 critical — content cropped, text invisible, footer overlap, off-canvas. Must fix.
🟠 high — content visible but visual hierarchy broken, no breathing room, hero not centered. Should fix.
🟡 medium — italic/em missing, font fallback wrong, color drift. Fix in this pass.
🟢 low — minor spacing/alignment, sub-pixel offsets. Note but don't block.

After the table, write a short root-cause section: 90 % of the issues usually come from 2–3 systemic causes (e.g. "no footer rail enforced", "hero stacks pinned to MARGIN_TOP instead of centered", "italic never propagated"). Naming the systemic causes makes the re-export script much smaller and more correct.

针对每张幻灯片，遍历导出文件中的形状，对照预期布局规则检查。请使用以下表格格式——严重程度列将决定修复优先级：

| 幻灯片 | 问题 | 严重程度 |
|---|---|---|
| 1 封面 | meta-row底端6.95英寸，覆盖页脚（6.7英寸） | 🔴 |
| 5 检查表 | row B步骤描述底端7.2英寸，被页脚截断 | 🔴 |
| 8 3E | 收尾段落直接位于页脚起始位置 | 🔴 |
| 9 当日步骤 | 步骤描述底端刚好触碰页脚，无安全间距 | 🟠 |
| 多处 | em（Playfair italic）未保留 | 🟡 |

严重程度规则：

🔴 关键 —— 内容被裁剪、文本不可见、页脚重叠、超出画布。必须修复。
🟠 高 —— 内容可见但视觉层级被破坏、无留白、主幻灯片未居中。应该修复。
🟡 中 —— 斜体/em缺失、字体回退错误、颜色偏差。本次修复需处理。
🟢 低 —— 微小间距/对齐问题、亚像素偏移。记录但不阻塞导出。

表格后需添加简短的根因分析部分：90%的问题通常源于2–3个系统性原因（例如“未强制页脚边界”、“主幻灯片固定在MARGIN_TOP而非居中”、“斜体未被传递”）。明确系统性原因能让重新导出的脚本更精简、更准确。

Step 4 — Re-export with footer-rail + cursor-flow layout discipline

步骤4 — 遵循页脚边界+光标流布局规范重新导出

This is the load-bearing technique. See

references/layout-discipline.md

for the full rules; the summary:

Define the rails up front, once, for the whole deck:

python

from pptx.util import Inches

CANVAS_W       = Inches(13.333)   # 16:9
CANVAS_H       = Inches(7.5)
MARGIN_X       = Inches(0.6)
MARGIN_TOP     = Inches(0.5)
CONTENT_MAX_Y  = Inches(6.70)     # NOTHING in content area may cross this
FOOTER_TOP     = Inches(6.85)     # footer row pinned here, edge-to-edge

Customizing the rails. The defaults above suit a 16:9 canvas with a slim footer. If your design system uses a wider footer or a 4:3 canvas, override these constants in your export script and pass the same values to
verify_layout.py
via
--content-max-y
/
--canvas-h
/
--canvas-w
. See
references/layout-discipline.md
§1 for the full constant table.

Use a cursor for content blocks instead of pinning each block at an absolute y:

python

class Cursor:
    """Advances down the slide; refuses to cross the footer rail."""
    def __init__(self, y_start, cap=CONTENT_MAX_Y):
        self.y = y_start
        self.cap = cap
    def take(self, h, gap=Inches(0.12)):  # ~1 line of whitespace at 14pt; tighten/loosen per design system
        top = self.y
        self.y = top + h + gap
        if self.y > self.cap:
            raise OverflowError(
                f"cursor at {self.y} exceeds footer rail {self.cap}; "
                f"reduce block height or split slide"
            )
        return top

For each slide, instantiate

Cursor(MARGIN_TOP)

and

take(height)

each block in reading order. The slide refuses to render if any block would cross the rail, so overflows become loud build errors instead of silent visual bugs.

Hero (vertically-centered) slides use a budget instead of a cursor:

python

def hero_layout(blocks):
    """blocks = list of (height, gap_after) tuples in reading order."""
    total = sum(h + g for h, g in blocks)
    y_start = (CANVAS_H - total) / 2
    return Cursor(y_start)

That single change kills "hero slide content sticks to top" — the most common hero defect.

Tighten box height to fit text + minimal padding. PowerPoint reveals shape bounds when they overlap (selection halos, Z-order conflicts), and an oversized box can visually cross the footer rail even when the text inside doesn't. Compute box height from text metrics + ~0.05" pad, not from generous wrappers.

Preserve italic / em explicitly:

python

def add_run(p, text, font, size_pt, italic=False, bold=False, color=None):
    r = p.add_run()
    r.text = text
    r.font.name = font
    r.font.size = Pt(size_pt)
    r.font.italic = italic
    r.font.bold = bold
    if color:
        r.font.color.rgb = color
    return r

When walking HTML, detect

<em>

<i>

/ inline style

font-style: italic

and pass

italic=True

. Use the EN serif face (Playfair Display, Source Serif, or fallback Georgia) for italic display copy — the CJK serif typically has no italic and looks broken if you try to italicize it.

For deeper font issues that the layout rails can't catch — variable-font traps where PowerPoint silently swaps to Calibri / Microsoft JhengHei, missing

<a:ea>

slot causing CJK runs to fall back, fake-italic on Han characters — read

references/font-discipline.md

. The five layers there cover everything

verify_layout.py

can't see.

这是核心技术。完整规则请参阅

references/layout-discipline.md

，以下是摘要：

预先为整个幻灯片定义边界：

python

from pptx.util import Inches

CANVAS_W       = Inches(13.333)   # 16:9
CANVAS_H       = Inches(7.5)
MARGIN_X       = Inches(0.6)
MARGIN_TOP     = Inches(0.5)
CONTENT_MAX_Y  = Inches(6.70)     # 内容区域不得超出此边界
FOOTER_TOP     = Inches(6.85)     # 页脚栏固定在此位置，贯穿整个画布宽度

自定义边界 上述默认值适用于带窄页脚的16:9画布。若你的设计系统使用宽页脚或4:3画布，请在导出脚本中覆盖这些常量，并通过
--content-max-y
/
--canvas-h
/
--canvas-w
参数将相同值传递给
verify_layout.py
。完整常量表请参阅
references/layout-discipline.md
第1节。

使用光标管理内容块，而非固定每个块的绝对y坐标：

python

class Cursor:
    """沿幻灯片向下移动；拒绝越过页脚边界。"""
    def __init__(self, y_start, cap=CONTENT_MAX_Y):
        self.y = y_start
        self.cap = cap
    def take(self, h, gap=Inches(0.12)):  # 14pt字号下约1行空白；可根据设计系统调整松紧
        top = self.y
        self.y = top + h + gap
        if self.y > self.cap:
            raise OverflowError(
                f"光标位置{self.y}超出页脚边界{self.cap}; "
                f"请减小块高度或拆分幻灯片"
            )
        return top

针对每张幻灯片，实例化

Cursor(MARGIN_TOP)

，并按阅读顺序为每个块调用

take(height)

。若任何块会越过边界，幻灯片将拒绝渲染，从而将溢出问题转化为明确的构建错误，而非隐性视觉bug。

主（垂直居中）幻灯片使用预算法而非光标：

python

def hero_layout(blocks):
    """blocks = 按阅读顺序排列的（高度，后续间距）元组列表。"""
    total = sum(h + g for h, g in blocks)
    y_start = (CANVAS_H - total) / 2
    return Cursor(y_start)

这一项修改即可解决“主幻灯片内容贴顶”这一最常见的主幻灯片缺陷。

收紧框高度以适配文本+最小内边距。 PowerPoint会在形状重叠时显示边界（选择光晕、Z顺序冲突），即使文本未超出，过大的边界框也可能视觉上越过页脚边界。根据文本尺寸+约0.05英寸内边距计算框高度，而非使用宽松的容器。

显式保留斜体/em：

python

def add_run(p, text, font, size_pt, italic=False, bold=False, color=None):
    r = p.add_run()
    r.text = text
    r.font.name = font
    r.font.size = Pt(size_pt)
    r.font.italic = italic
    r.font.bold = bold
    if color:
        r.font.color.rgb = color
    return r

遍历HTML时，检测

<em>

<i>

/内联样式

font-style: italic

，并传递

italic=True

。对于斜体展示文本，使用英文衬线字体（Playfair Display、Source Serif或 fallback Georgia）——中日韩衬线字体通常没有斜体，强制斜体会产生倾斜位图，效果不佳。

若遇到布局边界无法覆盖的深层字体问题——PowerPoint悄然切换为Calibri/Microsoft JhengHei的可变字体陷阱、缺失

<a:ea>

槽导致中日韩文本回退、汉字伪斜体等——请阅读

references/font-discipline.md

。其中的五层审计覆盖了

verify_layout.py

无法检测的所有问题。

Step 5 — Verify post-export

步骤5 — 验证导出结果

After writing the new

.pptx

, run

scripts/verify_layout.py <path-to.pptx>

. The script:

Walks every shape on every slide.
Asserts
```
top + height ≤ CONTENT_MAX_Y
```
for content shapes (footer/page-number shapes are allowed below the rail).
Asserts
```
top + height ≤ CANVAS_H
```
for all shapes (no off-canvas).
Asserts
```
left + width ≤ CANVAS_W
```
and
```
left ≥ 0
```
.
Reports violations as a single block: slide index, shape name, observed bottom, rail.

Zero violations is the gate for "this re-export is shippable". Don't claim the audit is fixed without running the verifier — the human eye misses 1–2 mm overflow at zoom-out, the script doesn't.

生成新的

.pptx

后，运行

scripts/verify_layout.py <path-to.pptx>

。该脚本：

遍历每张幻灯片的所有形状。
断言内容形状的
```
top + height ≤ CONTENT_MAX_Y
```
（页脚/页码形状可超出边界）。
断言所有形状的
```
top + height ≤ CANVAS_H
```
（无超出画布）。
断言
```
left + width ≤ CANVAS_W
```
且
```
left ≥ 0
```
。
将违规情况汇总报告：幻灯片索引、形状名称、实际底部位置、边界值。

零违规是“此重新导出文件可交付”的标准。未运行验证脚本前，请勿声称审计已完成——缩放预览时人眼会忽略1–2毫米的溢出，但脚本不会。

Output to the user

向用户交付的内容

After Step 5 passes, report:

Audit table — the table from Step 3.
Root causes — 1-paragraph systemic explanation.
Fix list — terse list of what was changed and why (e.g. "hero slides switched to budget centering", "all content blocks routed through Cursor", "em runs explicitly italic").
Verification — "0 rail violations across N slides, file size X KB".
Path — absolute path to the re-exported
```
.pptx
```
.

The user is reading for two reasons: confirming the visible bugs are fixed, and trusting the systemic fix is right. Cover both.

步骤5通过后，向用户报告：

审计表格 —— 步骤3中的表格。
根因分析 —— 一段关于系统性问题的解释。
修复列表 —— 简洁列出修改内容及原因（例如“主幻灯片改用预算法居中”、“所有内容块通过Cursor管理”、“em段落显式设置斜体”）。
验证结果 —— “N张幻灯片零边界违规，文件大小X KB”。
文件路径 —— 重新导出的
```
.pptx
```
的绝对路径。

用户关注两点：确认可见bug已修复，以及信任系统性修复方案正确。需覆盖这两方面。

Bundled resources

配套资源

```
scripts/extract_pptx.py
```
— dump every shape on every slide as JSON. Run before the audit. Important: also run on the original export to compare, and on the re-exported one to confirm.
```
scripts/verify_layout.py
```
— post-export rail checker. Returns nonzero exit code on violations so it slots into a CI pipeline if needed.
```
references/layout-discipline.md
```
— the full footer-rail + cursor-flow rule set with code snippets for each common slide type (hero, content, pipeline, two-column, observation grid).
```
references/font-discipline.md
```
— five-layer font audit: mapping, presence, variable-vs-static traps, the three XML language slots (
```
latin
```
/
```
ea
```
/
```
cs
```
), CJK + Latin italic interaction.
```
references/audit-table-template.md
```
— copy-pasteable table template with severity legend.

Read the references when:

The deck has slide types beyond what the SKILL.md covers (multi-column dashboards, embedded images, charts) →
```
layout-discipline.md
```
.
The audit shows 🟡 typography issues — italic missing, CJK falling back, unexpected
```
Calibri
```
/
```
Microsoft JhengHei
```
in the XML →
```
font-discipline.md
```
.
You want to drop the audit table directly into a report or markdown deliverable →
```
audit-table-template.md
```
.

```
scripts/extract_pptx.py
```
—— 将每张幻灯片的所有形状导出为JSON。审计前运行。重要提示： 也需在原始导出文件和重新导出文件上运行，以便对比和确认。
```
scripts/verify_layout.py
```
—— 导出后边界检查工具。违规时返回非零退出码，可集成到CI流水线中。
```
references/layout-discipline.md
```
—— 完整的页脚边界+光标流规则集，包含每种常见幻灯片类型（主幻灯片、内容幻灯片、流程幻灯片、双栏幻灯片、观察网格）的代码片段。
```
references/font-discipline.md
```
—— 五层字体审计：映射、存在性、可变/静态字体陷阱、三个XML语言槽（
```
latin
```
/
```
ea
```
/
```
cs
```
）、中日韩与英文斜体交互。
```
references/audit-table-template.md
```
—— 可复制粘贴的审计表格模板，含严重程度图例。

遇到以下情况时请查阅参考文档：

幻灯片类型超出本SKILL.md覆盖范围（多栏仪表盘、嵌入图片、图表）→
```
layout-discipline.md
```
。
审计发现🟡级排版问题——斜体缺失、中日韩字体回退、XML中出现意外的
```
Calibri
```
/
```
Microsoft JhengHei
```
→
```
font-discipline.md
```
。
需要将审计表格直接插入报告或markdown交付物 →
```
audit-table-template.md
```
。

Anti-patterns to avoid

需避免的反模式

Patching individual slides without naming the systemic cause. If you fix slide 5 by lowering its block by 0.2", you'll be back fixing slide 9, 11, and 14 next. Find the rule that produced all four problems.
Trusting the original export script's intent. Always run the extractor against the actual file. Drift between intent and reality is the bug.
Skipping verification because "it looked fine in PowerPoint preview". Preview anti-aliasing hides 1–2 mm overflows. The script doesn't.
Italicizing CJK display type. No CJK serif on macOS / Windows ships with a real italic — synthesizing it produces a slanted bitmap. Italicize only runs that are EN/Latin display copy.
Using
MARGIN_TOP
for hero slides. Hero slides need budget centering, not top-anchored. This is the most common hero defect and the cheapest to fix.

未明确系统性原因就单独修复幻灯片。若通过将第5页的块下移0.2英寸来修复问题，后续还需修复第9、11、14页。找出导致所有问题的规则漏洞。
信任原始导出脚本的预期。始终针对实际文件运行提取工具。预期与实际的偏差就是bug。
因“PowerPoint预览看起来没问题”而跳过验证。预览的抗锯齿效果会掩盖1–2毫米的溢出，脚本不会。
为中日韩展示文本设置斜体。macOS/Windows上没有带真实斜体的中日韩衬线字体——合成斜体会产生倾斜位图。仅为英文/拉丁展示文本设置斜体。
为主幻灯片使用
MARGIN_TOP
。主幻灯片需要预算法居中，而非顶部锚定。这是最常见的主幻灯片缺陷，也是修复成本最低的问题。

Why geometry-based verification, not visual diff

为何基于几何验证而非视觉对比

An earlier iteration of this skill leaned on visual diffing — render the .pptx through Keynote → PDF → PNG, screenshot the HTML through Chrome headless, stitch them side-by-side with

magick

. It worked, but with three sharp drawbacks:

Platform lock-in. Keynote AppleScript is macOS-only;
```
magick
```
and font-discovery commands vary across OSes; CI pipelines on Linux can't reproduce the chain.
Imprecision. A 1-2 mm overflow gets anti-aliased away in a PNG preview. The human eye misses it; the script catches it as a hard numeric violation.
Setup cost. Every contributor needs the full graphics toolchain installed before they can audit. Geometry checks need only
```
python-pptx
```
.

Geometry-based verification gives up one thing the visual diff is good at: catching cases where shape positions are correct but the rendered glyph looks wrong (font fallback, kerning bugs, missing weight). When that case appears, fall back to a manual screenshot review — the five-layer audit in

references/font-discipline.md

covers most of the underlying causes.

此技能的早期版本依赖视觉对比——通过Keynote将.pptx渲染为PDF→PNG，通过无头Chrome截取HTML截图，使用

magick

并排拼接。这种方法有效，但存在三个明显缺陷：

平台锁定。Keynote AppleScript仅支持macOS；
```
magick
```
和字体发现命令因操作系统而异；Linux上的CI流水线无法复现整个流程。
精度不足。1–2毫米的溢出在PNG预览中会被抗锯齿掩盖，人眼无法察觉，但脚本会将其视为明确的数值违规。
设置成本高。每个贡献者都需安装完整的图形工具链才能进行审计。而几何验证仅需
```
python-pptx
```
。

基于几何验证放弃了视觉对比的一个优势：无法检测形状位置正确但渲染字形错误的情况（字体回退、字距调整bug、字重缺失）。遇到这种情况时，需回退到手动截图检查——

references/font-discipline.md

中的五层审计覆盖了大部分潜在原因。