Open Design PPTX ↔ HTML Fidelity Audit 技能指南

技能概述

PPTX ↔ HTML Fidelity Audit 係一個專門針對 python-pptx 導出流程嘅質量審計技能。PPTX 係 fixed-canvas、absolute-positioned medium，而 HTML 係 fluid、flow-based medium。一個 naive 嘅 python-pptx export 往往喺第一張 slide 啱晒，但其他 slide 就靜靜出問題。呢個技能幫搵出啲 drift，用一套 layout discipline 防止同樣問題再生。

6 種常見漂移模式：

• Footer overflow — 內容底端蓋過 footer rail
• Off-canvas content — 最後一個 block 超出 7.5" canvas
• Italic loss — HTML 入面嘅 <em> 到咗 PPTX 變平體
• Hero slides not centered — 用 MARGIN_TOP 代替居中計算
• Box bounds intruding — shape 嘅 bounding box 太大，視覺上壓到 footer
• Tag/styling loss — colored chrome、kicker tracking 靜靜變返 default

觸發關鍵字

• pptx fidelity、pptx audit、ppt 跑掉、字型不對
• footer overlap、verify pptx、html to pptx
• compare ppt with html、fix the pptx、ppt is cut off
• re-export the deck、pptx-html-fidelity-audit

什麼時候用

• 用 python-pptx 由 HTML 導出 .pptx 後，懷疑內容走樣
• PPTX 同 HTML 放埋一齊對照，發現視覺差異
• 用戶投訴「頁腳遮住內容」「italic 冇咗」「排版唔啱」
• 需要一個可重複執行嘅 layout 審計流程

使用方法

工作流程（5 步，唔好跳過任何一步）

1. Extract ground truth — 跑 scripts/extract_pptx.py dump 出每個 shape 嘅 text、position、size、typography（font name、size、bold、italic、color）。呢個係 export 嘅真實狀態，唔好信 export script 嘅 intent，要信 dump。

2. Walk HTML structure — 讀源 HTML，枚舉每個 <section class="slide">，記錄 theme、chrome、kicker、headline、body、foot、italic spans。將每張 HTML slide 對應到 PPTX slide index。

3. Build audit table — 用指定格式列出所有問題，分 4 個嚴重度等級：

4. Root cause analysis — 90% 問題通常來自 2-3 個 systemic causes（例如 "no footer rail enforced"、"hero stacks pinned to MARGIN_TOP"）。搵出系統性原因先好過逐個 slide 修。

5. Re-export with layout discipline — 用 footer-rail + cursor-flow 紀律重新導出：

   • 定義 rails：CANVAS_W、CANVAS_H、CONTENT_MAX_Y、FOOTER_TOP
   • 用 Cursor 類代替 absolute pinning，每個 block 按閱讀順序 take(height)
   • Hero slides 用 budget centering：y_start = (CANVAS_H - total) / 2
   • Italic/em 顯式保留：detect <em> / <i> / font-style: italic，傳 italic=True
   • Box height 按 text metrics + 最小 padding 計算

6. Verify post-export — 跑 scripts/verify_layout.py，斷言每個 shape 嘅 top + height ≤ CONTENT_MAX_Y。Zero violations 先係 shippable。

輸出格式

審計完成後報告：

1. Audit table（Step 3 表格）
2. Root causes（系統性原因段落）
3. Fix list（改咗乜同點解）
4. Verification（"0 rail violations across N slides, file size X KB"）
5. 重新導出嘅 .pptx 絕對路徑

反模式

• 逐個 slide patch 而唔搵 systemic cause — 修 slide 5 降 0.2"，下次仲係要修 slide 9、11、14
• 信 export script 嘅 intent — 一定要 run extractor 對實際文件
• 跳過 verification — 預覽 anti-aliasing 會隱瞞 1-2mm overflow
• CJK 文字強行 italic — 中文、阿拉伯文、希伯來文嘅 italic 會變合成傾斜，視覺上變形
• Hero slides 用 MARGIN_TOP — Hero 需要 budget centering，唔係 top-anchored

點解用幾何驗證而唔係視覺 diff

之前版本用過視覺 diff（Keynote → PDF → PNG + Chrome headless screenshot + magick stitch），但有三大缺點：平台鎖定（macOS-only）、不精確（1-2mm overflow 被 anti-aliased 掉）、setup 成本高。幾何驗證只需要 python-pptx，數值判斷零失誤。

捆綁資源

• scripts/extract_pptx.py — dump 每個 shape 嘅 JSON
• scripts/verify_layout.py — post-export rail checker（CI 可用）
• references/layout-discipline.md — 完整 footer-rail + cursor-flow 規則集
• references/font-discipline.md — 五層 font audit：mapping / presence / variable traps / XML slots / CJK italic
• references/audit-table-template.md — 可複製嘅審計表格模板

相關技能

• HTML-PPT
• Motion Frames
• Sprite Animation