Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

fix(svg-checker): keep compatible SVG spellings advisory

hugohe33e43908cc95b
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 2169a891..8a6bba01 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -40,7 +40,7 @@ The past two months' structural capability growth. Single flags / incremental po
- **Kubernetes Blueprint example deck shipped** ([`examples/ppt169_kubernetes_blueprint_2026/`](../examples/ppt169_kubernetes_blueprint_2026/)) — second of the three P0 capability-backing demos: isometric technical-drawing aesthetic + blueprint cyan/amber palette + hand-authored SVG geometry (no raster images) + custom drawing-in animation; 10-page Kubernetes architecture walkthrough stressing geometric shape generalization and chart-structure extensibility
- **AI image `custom` escape hatch** — `rendering` / `palette` / hero composition each accept `custom` + a one-paragraph `*_behavior` prose, replacing the false "default to vector-illustration / cool-corporate" fallback; end-to-end contract spans [`image-renderings/_index.md`](../skills/ppt-master/references/image-renderings/_index.md) §1.5, [`image-palettes/_index.md`](../skills/ppt-master/references/image-palettes/_index.md) §2, Strategist h.5 hard-rule (≤1 custom per dimension; one candidate may carry both), spec_lock fields, and Image_Generator Step 2 consumption branch
- **Template architecture: three-kind consolidation** ([`docs/templates-architecture.md`](./templates-architecture.md)) — brand / layout / deck split into three independent dirs with per-kind schemas + segment-level fusion + git-style conflict resolution; SKILL.md Step 3 dispatches per `kind`, trigger rule remains "explicit path only"
-- **Pattern fill PPTX safety net** — `svg_quality_checker.py` rejects a referenced `<pattern>` that lacks `data-pptx-pattern`, uses `patternTransform`, or names a value outside OOXML `ST_PresetPatternVal`; the converter keeps its `ltUpDiag` fallback for historical input only. `shared-standards.md §7` documents the closed preset enum and color resolution from importer metadata or child paint
+- **Pattern fill PPTX safety net** — `svg_quality_checker.py` warns when a referenced `<pattern>` lacks `data-pptx-pattern` and the converter will use its compatible `ltUpDiag` fallback; it still rejects `patternTransform` and values outside OOXML `ST_PresetPatternVal`. `shared-standards.md §7` documents the closed preset enum and color resolution from importer metadata or child paint
- **LaTeX math formula rendering shipped** ([`scripts/latex_render.py`](../skills/ppt-master/scripts/latex_render.py)) — Strategist locks one of three policies (`mixed` / `render-all` / `text-only`) inside the Typography confirmation and writes an explicit `images/formula_manifest.json`; the renderer walks a codecogs → quicklatex → mathpad → wikimedia fallback chain and emits transparent PNGs that land in §VIII as `Acquire Via: formula` / `Status: Rendered` rows; formula-heavy decks (academic / engineering / educational) finally have a native rendering route. Formula selection is a Strategist decision — the renderer never scans source files for `$...$` markers
- **Live preview direct editing — L1 / L2 / L3** ([`workflows/live-preview.md`](../skills/ppt-master/workflows/live-preview.md)) — the browser editor gains deterministic in-place edits with no AI round-trip: text content (L1), presentation attributes like fill / stroke / font-size (L2), and on-canvas geometry (L3) — drag a selected element to move it, arrow-key nudge (`Shift` = 10px), multi-select, plus a right-click overlap picker for stacked shapes. Edits stage with `Ctrl+Z` undo + coalescing and write to `svg_output/` on **Apply changes**; moves persist through finalize / export (moved text frames, promoted multi-line tspans, repositioned icons all reproduce in the PPTX). Re-export stays chat-driven; on-canvas resize handles are not yet implemented (resize via the geometry inputs)
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 6003140a..500e7751 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -179,6 +179,15 @@ This table shows conceptual counterparts, not an authoring allowlist or a
promise of lossless semantics. Restricted or approximate mappings are owned by
[`shared-standards.md`](../skills/ppt-master/references/shared-standards.md).
+The boundary deliberately uses **recommended narrow writes and broad reads**.
+New `svg_output/` and reusable templates default to one paint spelling:
+uppercase opaque `#RRGGBB`, with transparency carried by the matching
+`fill-opacity`, `stroke-opacity`, `stop-opacity`, `flood-opacity`, or atomic
+element `opacity`. The converter still accepts named colors, functional CSS
+colors, short/alpha HEX, and other documented historical forms at import or
+direct-read boundaries. The checker may recommend the default spelling, but a
+supported alternative remains valid and does not block export.
+
The conversion is a translation between two dialects of the same idea — not a format mismatch.
SVG is also the only format that simultaneously satisfies every role in the pipeline: **AI can reliably generate it, humans can preview and debug it in any browser, and scripts can translate it under an explicit compatibility contract** — all before a single line of DrawingML is written.
@@ -388,7 +397,7 @@ The architectural reasons worth knowing here:
- **Why an exception list, not an allowlist.** SVG is a wide specification; enumerating every allowed feature would require constant maintenance as the converter grows. A centralized exception list leaves ordinary implemented constructs available by default.
- **Why empirical, not derived from spec.** The compatibility boundary grew from real PPT export failures, not from reading the OOXML specification. Some theoretically representable effects remain unreliable across PowerPoint versions, so the contract reflects the actually shippable subset.
- **XML well-formedness remains a precondition.** Malformed SVG fails before DrawingML compatibility matters. The canonical contract owns the accepted authoring forms so XML guidance cannot drift across architecture and prompt documents.
-- **Compatibility validation runs before post-processing.** `svg_quality_checker.py` evaluates `svg_output/`; post-processing rewrites SVG and could mask source-level violations. Fixes are always re-authoring in the Executor — there is intentionally no auto-fix mode (see Quality Gate).
+- **Compatibility validation runs before post-processing.** `svg_quality_checker.py` evaluates `svg_output/`; post-processing rewrites SVG and could mask source-level violations. Blocking errors are re-authored by the Executor; warnings do not trigger a rewrite, and there is intentionally no auto-fix mode (see Quality Gate).
---
@@ -398,7 +407,7 @@ The architectural reasons worth knowing here:
**Why placed before post-processing, not after.** Post-processing rewrites SVG (icon embedding, image inlining), which would mask source-level violations. Reading `svg_output/` directly catches the Executor's actual output, before any cleanup that might paper over a bug.
-**Severity model: errors block, warnings don't, and there is intentionally no auto-fix.** Errors require the Executor to re-author the offending page in context — a compatibility violation is not necessarily a mechanical patch, because the replacement must preserve the same design intent. Auto-fix would silently lose that intent and ship a worse-looking page.
+**Severity model: errors block, warnings don't, and there is intentionally no auto-fix.** Errors require the Executor to re-author the offending page in context — a compatibility violation is not necessarily a mechanical patch, because the replacement must preserve the same design intent. Warnings never require a return modification or acknowledgement: recommendation warnings expose the generated default, while fidelity/quality warnings describe optional review. Auto-fix would silently overwrite valid user intent and can ship a worse-looking page.
**Why chart coordinate verification hangs off the same gate.** Chart pages have geometric correctness requirements (bar heights / pie sweep angles / axis tick positions) that aren't structural and aren't caught by SVG validity rules. The natural place to catch them is the same gate where the AI is asked to revisit its output — bundling the cognitive context "look at what you generated and fix it" into one phase, rather than splitting structural and geometric review into separate review rounds.
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index 9ef3708f..2473e425 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -40,7 +40,7 @@
- **Kubernetes Blueprint 示例 deck 交付**([`examples/ppt169_kubernetes_blueprint_2026/`](../../examples/ppt169_kubernetes_blueprint_2026/)) — P0 三档第二档落地:等距工程图美学 + 蓝图青/琥珀色板 + 全手写 SVG 几何(无 raster 图)+ 自定义"逐笔绘制"动画,10 页 Kubernetes 架构走读实压「几何形状泛化 + chart 结构扩展性」
- **AI 图 `custom` 兜底出口** — `rendering` / `palette` / hero 构图三处允许声明 `custom` + 一段 `*_behavior` prose,替换原"找不到匹配就硬塞 vector-illustration / cool-corporate"的假兜底;端到端契约:[`image-renderings/_index.md`](../../skills/ppt-master/references/image-renderings/_index.md) §1.5 + [`image-palettes/_index.md`](../../skills/ppt-master/references/image-palettes/_index.md) §2 + Strategist h.5 hard-rule(每维 ≤1 custom,单候选可双 custom)+ spec_lock 字段 + Image_Generator Step 2 消费分支
- **Template 架构三分类收口**([`docs/zh/templates-architecture.md`](./templates-architecture.md)) — brand / layout / deck 三独立目录 + 每类独立 schema + 段级合成 + git-style 冲突解决;SKILL.md Step 3 按 kind 分支处理,触发规则仍是「显式路径才触发」
-- **Pattern 填充 PPTX 安全网** — `svg_quality_checker.py` 现在拒绝被引用但缺少 `data-pptx-pattern`、使用 `patternTransform`,或命名超出 OOXML `ST_PresetPatternVal` 枚举值的 `<pattern>`;转换器仅为历史输入保留 `ltUpDiag` 回退。`shared-standards.md §7` 落地了完整 preset 清单,以及从导入元数据或子元素 paint 解析颜色的合同
+- **Pattern 填充 PPTX 安全网** — 被引用的 `<pattern>` 缺少 `data-pptx-pattern` 时,`svg_quality_checker.py` 现在给出 warning,转换器继续使用兼容的 `ltUpDiag` 回退;`patternTransform` 或超出 OOXML `ST_PresetPatternVal` 枚举的值仍然报错。`shared-standards.md §7` 落地了完整 preset 清单,以及从导入元数据或子元素 paint 解析颜色的合同
- **LaTeX 数学公式渲染上线**([`scripts/latex_render.py`](../../skills/ppt-master/scripts/latex_render.py)) — Strategist 在 Typography 确认中锁定 `mixed` / `render-all` / `text-only` 三档策略,显式写 `images/formula_manifest.json`;脚本走 codecogs → quicklatex → mathpad → wikimedia 四源 fallback chain,输出透明 PNG 进 §VIII 表的 `Acquire Via: formula` / `Status: Rendered` 行;公式密集型 deck(学术 / 工程 / 教学)首次拥有原生渲染路径,规则面禁止扫源文件 `$...$` 自动渲染(公式选取是 Strategist 决策)
- **实时预览直接编辑 — L1 / L2 / L3**([`workflows/live-preview.md`](../../skills/ppt-master/workflows/live-preview.md)) — 浏览器编辑器新增无需 AI 往返的确定性就地编辑:文字内容(L1)、fill / stroke / font-size 等样式属性(L2)、以及画布上的几何操作(L3)——在选中元素上拖拽即移动、方向键微调(`Shift` = 10px)、多选、加右键重叠选择器选取堆叠元素。编辑支持 `Ctrl+Z` 撤销 + 合并,点 **Apply changes** 写回 `svg_output/`;移动经 finalize / 导出保位(移动的 text、提升的多行 tspan、重定位的 icon 都在 PPTX 中如实再现)。重新导出仍由对话触发;画布上的缩放手柄尚未实现(缩放走几何输入框)
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 985d5c48..95add1c8 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -178,6 +178,8 @@ SVG 胜出,因为它与 DrawingML 拥有相同的世界观:两者都是绝
这张表只展示概念对应关系,不是创作允许清单,也不承诺语义无损。受限或近似的映射统一由 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 定义。
+这条边界明确采用**推荐窄写入、兼容宽读取**。新生成的 `svg_output/` 与可复用模板默认使用一种颜色写法:不透明的六位大写 `#RRGGBB`,透明度放在对应的 `fill-opacity`、`stroke-opacity`、`stop-opacity`、`flood-opacity` 或原子元素 `opacity` 中。转换器在导入或直接读取边界仍兼容命名色、CSS 函数色、短 HEX、带 alpha 的 HEX 及其他已记录的历史形式。Checker 可以提示推荐写法,但受支持的替代写法仍然有效,也不会阻断导出。
+
转换不是格式错配,而是在两种结构相近的方言之间做翻译。
SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可靠地生成它,人能在任意浏览器里直接预览和调试,脚本能按明确的兼容合同转换它**——在生成任何 DrawingML 之前,设计稿就已经完全透明可见。
@@ -388,7 +390,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
- **为什么是例外清单,不是允许清单。** SVG 是个宽规范;穷举所有允许能力会随着转换器演进而持续增加维护成本。集中维护例外,才能让已实现的普通构造默认可用。
- **为什么是经验性,不是从规范推导。** 兼容性边界从真实的 PPT 导出失败长出来,不是读 OOXML 规范推导出来的。有些理论上能表达的效果跨 PowerPoint 版本仍不可靠,因此合同反映的是实际能交付的子集。
- **XML 良构性仍是前置条件。** SVG 一旦不是合法 XML,尚未进入 DrawingML 兼容性阶段就会失败。接受的创作形式集中在权威合同中,避免架构与提示文档分别维护后发生漂移。
-- **兼容性校验在后处理之前执行。** `svg_quality_checker.py` 在 `svg_output/` 上执行;后处理会重写 SVG,可能掩盖源级别违规。修复永远是 Executor 重新写——有意没有 auto-fix 模式(见 § 质量门)。
+- **兼容性校验在后处理之前执行。** `svg_quality_checker.py` 在 `svg_output/` 上执行;后处理会重写 SVG,可能掩盖源级别违规。阻断性 error 由 Executor 重新写,warning 不触发回改;系统有意不提供 auto-fix 模式(见 § 质量门)。
---
@@ -398,7 +400,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么放在后处理之前,而不是之后。** 后处理会重写 SVG(图标嵌入、图片内联),会掩盖源级别违规。直接读 `svg_output/` 抓的是 Executor 的实际输出,先于任何可能掩盖 bug 的清理动作。
-**严重性模型:error 阻塞、warning 不阻塞,且有意没有 auto-fix。** error 要求 Executor 在上下文里重新写出错的页面——兼容性违规不一定能机械 patch,因为替代方案必须重新承载同样的设计意图。Auto-fix 会静默丢失这份意图,交付一个更难看的页面。
+**严重性模型:error 阻塞、warning 不阻塞,且有意没有 auto-fix。** error 要求 Executor 在上下文里重新写出错的页面——兼容性违规不一定能机械 patch,因为替代方案必须重新承载同样的设计意图。Warning 不要求返回修改或逐条确认:推荐性 warning 说明生成默认写法,保真度 / 质量 warning 只提供可选复核信息。Auto-fix 会静默覆盖有效的用户意图,也可能交付一个更差的页面。
**为什么图表坐标验证挂在同一道 gate。** 图表页面有几何正确性需求(柱高、饼图扇角、坐标轴刻度位置),这些不是结构问题,SVG 合法性规则也抓不到。最自然的捕捉位置就是已经要求 AI 回看自己输出的那道 gate——把「看一眼你刚生成的东西然后修」的认知上下文打包到一个阶段,比把结构和几何审查分到两轮 review 更高效。
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 0bb8d27d..2b52a704 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -651,9 +651,9 @@ Fix every `error` on page 1 first — structural violations are systematic, and
```bash
python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
```
-- Any `error` (banned SVG features, viewBox mismatch, spec_lock drift, etc.) MUST be fixed before proceeding — return to Visual Construction, regenerate that page, re-run check.
-- `warning` entries (low-res image, non-PPT-safe font tail, etc.): fix when straightforward, otherwise acknowledge and release.
-- **Structured template routes only — PPTX-structure warnings are the exception.** For each empty-Layout / framing-only-Layout / bare-Master / duplicate-layout-key warning, output one disposition line: either the fix applied (merge keys in `spec_lock.md pptx_layouts` + SVG roots, mark the missing slots/layers) or why the flagged state is intended (e.g. "P01 cover is a fixed composition, zero-slot by design"). Flat free-design and brand-only routes have no positive Master/Layout checkpoint; the checker instead enforces a complete flat lock including colors/fonts/title-body defaults, plus the absence of Master/Layout/layer/placeholder metadata. "0 errors" alone does not pass a structured template gate when such warnings remain undispositioned.
+- Any `error` (banned/unsupported SVG features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed before proceeding — return to Visual Construction, regenerate that page, re-run check.
+- Every `warning` is advisory and non-blocking: do not return the page for mandatory modification, do not auto-normalize user-authored compatible syntax, and do not require an acknowledgement/disposition line. Recommendation warnings identify the generated-SVG default; fidelity/quality warnings may be reported when material, but the existing input may ship unchanged. If a condition must be corrected before release, the checker must classify it as an `error`, not a `warning`.
+- The same rule applies to structured-template warnings (empty/framing-only Layout, bare Master, duplicate layout keys): they may guide an optional template cleanup, but warnings alone never fail the quality gate. Flat free-design and brand-only routes still rely on their existing hard errors for invalid structure metadata or incomplete required locks.
- Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations).
**Logic Construction Phase**: generate speaker notes → `<project_path>/notes/total.md`
@@ -665,7 +665,6 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
- [x] First-page gate run after page 1 (errors fixed before page 2)
- [x] All SVGs generated to svg_output/
- [x] svg_quality_checker.py passed (0 errors)
-- [x] Structured-template PPTX warnings dispositioned one by one when applicable
- [x] Speaker notes generated at notes/total.md
```
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 2d72cafd..222fcdbb 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -255,7 +255,7 @@ Before drawing each page, look up its entry in `page_charts` to decide which cha
- **Reference — image-led promotional pages (not a constraint)**: for travel, venue, product-introduction, hospitality, event, real-estate, and brochure-style decks, let images define the page skeleton before placing text. Consult [`image-layout-patterns.md`](image-layout-patterns.md) §Imported Deck Patterns and prefer patterns such as `#74` TOC image-navigation cards, `#75` asymmetric chapter banners, `#77` photo mosaic with a text cell, `#78` ambient banner + evidence photo + text panel, `#79` ribbon-header image cards, and `#80` side hero image + staggered evidence cards before falling back to plain left/right image-text splits.
- **Phased batch generation** (recommended):
1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per §3.1 below on every chart page — coordinate calibration is a post-generation step (see [`workflows/verify-charts.md`](../workflows/verify-charts.md)) that depends on these markers — and **native object metadata** per §3.2 on every eligible data-chart page. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 scripts/svg_quality_checker.py <project_path>/svg_output/<first_page>.svg` and fix every error before drawing page 2 — structural violations are systematic, and a first-page error repeated deck-wide costs a whole-deck rewrite.
- 2. **Quality Check Gate**: run `python3 scripts/svg_quality_checker.py <project_path>` on `svg_output/`. Any `error` (banned features, viewBox mismatch, spec_lock drift, non-PPT-safe font, etc.) MUST be fixed on the offending page before proceeding — regenerate and re-check. Address `warning`s when straightforward. On a structured deck/layout template route, PPTX-structure warnings (empty Layout, framing-only Layout, bare Master, duplicate layout keys) are never acknowledge-and-release: list each one and either fix the page/lock or state per warning why the flagged state is intended (e.g. a zero-slot cover) before proceeding. Flat free-design/brand-only routes have no Master/Layout checkpoint. Do NOT defer to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
+ 2. **Quality Check Gate**: run `python3 scripts/svg_quality_checker.py <project_path>` on `svg_output/`. Any `error` (banned/unsupported features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed on the offending page before proceeding — regenerate and re-check. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. This includes structured deck/layout-template warnings. If release truly depends on a condition, it belongs in `errors`. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
3. **Logic Construction Phase**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity.
### 3.0 Native Preset Shape Selection
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index cb921552..6b6fba48 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -557,7 +557,7 @@ Triggered automatically when `IMAGE_BACKEND` is not configured (or Path A fails)
- Do **not** run `image_gen.py --manifest` in Path B. That command is Path A and may use configured API/proxy backends even when the user confirmed host-native.
- Still run `python3 scripts/image_gen.py --render-md project/images/image_prompts.json` so the human-readable sidecar exists without touching any backend.
- **Batch for speed, mind the rate**: when the host can run independent tool calls in parallel (e.g. Claude Code issues independent calls concurrently), fire several generations together in modest groups — a few rows at a time (~3–4), not the whole manifest at once — so their latency overlaps without flooding the host's image quota. When the host only runs tools serially, generate one row at a time. This mirrors Path A's default concurrency of 3.
-- Outputs **must** land at `project/images/<filename-from-resource-list>`. Match the Image Resource List dimensions when the host supports arbitrary sizes. Hosts with **fixed native resolutions** (common — e.g. ~1672x941 landscape / ~1086x1448 portrait) generate at the closest native size and backfill the actual pixels into the resource list `Dimensions` column — same convention as formula rows ("actual dimensions from formula manifest") and slice rows ("dimensions filled after slicing"). Do **not** upscale the file to fake the requested size (interpolation adds no detail); minor display-side upscaling (up to ~1.3x in practice) surfaces as a quality-checker warning — acknowledge and release per the warning policy.
+- Outputs **must** land at `project/images/<filename-from-resource-list>`. Match the Image Resource List dimensions when the host supports arbitrary sizes. Hosts with **fixed native resolutions** (common — e.g. ~1672x941 landscape / ~1086x1448 portrait) generate at the closest native size and backfill the actual pixels into the resource list `Dimensions` column — same convention as formula rows ("actual dimensions from formula manifest") and slice rows ("dimensions filled after slicing"). Do **not** upscale the file to fake the requested size (interpolation adds no detail); minor display-side upscaling (up to ~1.3x in practice) may surface as a non-blocking quality-checker warning and requires no acknowledgement.
- Mark each item's `status` `Generated` in the manifest the moment its file lands — as each completes, not in one pass at the end (so an interrupted batch leaves accurate state)
- Executor downstream is path-agnostic — no spec change required between Path A and Path B
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.md
index 82b845ca..5de01a4a 100644
--- a/skills/ppt-master/references/image-searcher.md
+++ b/skills/ppt-master/references/image-searcher.md
@@ -281,7 +281,7 @@ Applied by Executor when an image's `license_tier == "attribution-required"`. Th
- **Position**: bottom-right of the image's container, hugging the image edge (within ~8 px)
- **Font size**: 6–8pt equivalent (≈ 0.7–1 % of canvas short edge)
-- **Color**: `#999` on light/photo backgrounds; `rgba(255,255,255,0.6)` on dark/photo
+- **Color**: `fill="#999999"` on light/photo backgrounds; `fill="#FFFFFF" fill-opacity="0.6"` on dark/photo
- **Content**: `© {author} / {provider_short} / {license_short}`
- `provider_short`: `Openverse` / `Wikimedia` / `Pexels` / `Pixabay`
- `license_short`: `CC BY 4.0` / `CC BY-SA 4.0` / `Public Domain`
@@ -301,8 +301,8 @@ Use single-letter labels (a/b/c) only when needed for disambiguation.
### 7.3 Hero / full-bleed image
-- Bottom 1.5 cm gradient overlay: transparent → `rgba(0,0,0,0.5)`
-- 7pt white semi-transparent text inside the overlay band, right-aligned ~24 px from edge
+- Bottom 1.5 cm gradient overlay: `stop-color="#000000" stop-opacity="0"` → `stop-color="#000000" stop-opacity="0.5"`
+- 7pt text with `fill="#FFFFFF" fill-opacity="0.6"` inside the overlay band, right-aligned ~24 px from edge
### 7.4 Source for the credit text
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index b421870b..a90a81d9 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -8,7 +8,7 @@ Other files link here instead of restating its contracts.
| Section | Owns | Strength |
|---|---|---|
| §1 Required Foundation, Forbidden Features, and Conditional Interfaces | XML validity, the closed generated-authoring surface, structural blacklist, native line ends, image clipping, static local reuse, and imported/authored native-shape semantics | Required / Forbidden / Conditional |
-| §2 Conditional Compatibility Mappings | Literal inline geometry and the converter-only group-opacity boundary | Conditional / Forbidden |
+| §2 Conditional Compatibility Mappings | Literal inline geometry and the approximate group-opacity compatibility boundary | Conditional / Default |
| §3 Canvas Format Quick Reference | Pointer to the complete canvas catalog | Reference |
| §4 Required Page Contract and Conditional Packaging | Complete-page authority, semantic markers, editable text/grouping, and package promotion | Required / Conditional |
| §5 Workflow Authority | Pointer to the serial post-processing/export procedure | Workflow pointer |
@@ -20,7 +20,7 @@ Other files link here instead of restating its contracts.
| Capability family | Available authoring vocabulary | Detail |
|---|---|---|
-| Color and transparency | CSS alpha colors; fill, stroke, text, picture, stop, and element opacity; converter-only group-opacity compatibility | §2.2, §6.2 |
+| Color and transparency | Default opaque `#RRGGBB` paint plus channel-specific alpha; compatible CSS-color spellings, picture/atomic-element opacity, and approximate group opacity | §2.2, §6.2 |
| Gradients and paint | Linear/radial fills, transparent stops, gradient text, gradient strokes, and preset patterns | §6.3, §7 |
| Depth and light | Soft/colored/directional shadow, glow, layered-geometry fallback, and paper-layer elevation | §6.4 |
| Image treatment | Directional scrim, bottom fade, vignette, spotlight, brand wash, picture fading, and glass-like surfaces | §1.2, §6.5 |
@@ -54,13 +54,16 @@ Other files link here instead of restating its contracts.
**Hard rule — generated authoring is fail-closed**: `svg_output/` and reusable
template SVGs may use only properties and conditional interfaces explicitly
listed in this file. `svg_quality_checker.py` rejects unknown inline visual
-properties and incomplete conditional contracts before export.
+properties and conditional contracts that have no reliable compatibility
+mapping; documented fallback forms remain valid and receive warnings.
-**Hard rule — compatibility is not authoring permission**: the converter may
-retain broader read compatibility for imported or historical SVG, including
-normalization and documented approximation. That compatibility does not add a
-feature to the generated-authoring surface. Do not remove converter support
-merely to enforce a narrower authoring contract.
+**Default — recommended authoring and supported input stay separate (may
+preserve supported input)**: generated SVG uses one predictable default
+spelling, while converter-supported equivalent spellings remain valid input.
+The checker may recommend normalization, but such warnings do not require
+modification or block export. Only invalid, unsafe, or unreliably convertible
+input is an error; do not remove converter support to enforce a narrower
+generation preference.
**Hard rule — one-way fidelity vocabulary**: the labels above describe the
`svg_output/` → generated PPTX path. They do not promise reconstruction of the
@@ -118,6 +121,12 @@ below; unlisted visual properties are unsupported.
| Literal geometry | The element-specific properties in §2.1 |
| Preview-only | `shape-rendering`; it does not change native geometry |
+**Default — one generated value spelling (may preserve supported input)**: the
+table allows inline placement of those property names. New generated paint
+prefers the spelling in §6.2 whether it appears as an attribute or inside
+`style`. Converter-compatible aliases remain valid input in both locations and
+produce recommendation warnings rather than errors.
+
Conditional properties with a required XML form stay out of inline style:
write `filter="url(#id)"`, `clip-path="url(#id)"`, and
`marker-start` / `marker-end` as direct attributes. `!important`, unknown CSS
@@ -133,8 +142,8 @@ properties, blend modes, isolation, and backdrop filters fail quality check.
>
> **Authored native preset fragments are conditional** — see §1.5.
>
-> **Inline CSS geometry, simple gradients, and filters are conditional;
-> generated group opacity is forbidden** — see §2 and §6.
+> **Inline CSS geometry, simple gradients, filters, and approximate group
+> opacity are conditional** — see §2 and §6.
>
> **PPT preset patterns and native chart/table/template metadata are
> conditional** — see §7.
@@ -408,19 +417,20 @@ only for literal declarations in an element's own `style` attribute; PPT Master
does not compute CSS cascade or custom properties. Root canvas authority remains
the `viewBox`, regardless of root `<svg>` compatibility width/height values.
-### 2.2 Group Opacity Is Converter-Only Compatibility
+### 2.2 Group Opacity Compatibility
-**Forbidden — generated group opacity**: Do not author `<g opacity="...">` or
-inline group `opacity` below `1` in `svg_output/` or reusable templates. Put the
-required alpha on each descendant paint, text run, picture, or supported effect.
-The quality checker rejects generated group opacity because DrawingML has no
-isolated group-alpha model and overlapping descendants produce a different
-result.
+**Default — descendant alpha (may preserve compatible group opacity)**: New
+`svg_output/` and reusable templates put alpha on the affected descendant
+paint, text run, picture, or supported effect. DrawingML has no isolated
+group-alpha model, so overlapping descendants can look different when one
+group value is distributed across them.
-The converter retains direct-read compatibility for historical/imported SVG by
-multiplying group alpha into descendants. That path is `Approximate`; nested
-group/child alpha multiplies, and `--native-objects` rejects transparent native
-table/chart markers. It is not an authoring permission.
+The converter nevertheless accepts `<g opacity="...">` and inline group
+`opacity` by multiplying group alpha into descendants. That path is
+`Approximate`; nested group/child alpha multiplies, and `--native-objects`
+rejects transparent native table/chart markers. The quality checker reports a
+non-blocking fidelity warning so existing or intentionally authored input can
+continue without modification.
---
@@ -547,34 +557,59 @@ when the effect carries material meaning.
### 6.2 Color, Alpha, and Opacity
-Supported paint grammar: recognized named colors, `rgb()` / `rgba()`, `hsl()` /
-`hsla()`, and `#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`. Bare hexadecimal
-without `#` is invalid.
+Compatible paint grammar includes recognized named colors, `rgb()` / `rgba()`,
+`hsl()` / `hsla()`, and `#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`. The
+converter also tolerates legacy bare 3/4/6/8-digit hexadecimal tokens.
+
+**Default — canonical generated paint tokens (may preserve compatible
+alternatives)**: New `svg_output/` and reusable template SVGs write solid paint
+as uppercase six-digit `#RRGGBB`. `fill` / `stroke` may instead use lowercase
+`none` or the exact local reference form `url(#id)`. Named colors, lowercase or
+short/alpha HEX, functional colors, and bare legacy HEX remain supported input.
+The quality checker prints an optional canonical rewrite as a recommendation
+warning; it does not require modification or block export.
-| Authoring surface | Native result | Fidelity |
+| Intent | Canonical authoring | Native result / fidelity |
|---|---|---|
-| `fill-opacity`; `stroke-opacity` | Fill, text, line, or outline alpha | `Native-stable` |
-| CSS color alpha | Alpha-bearing named/functional/HEX paint | `Native-normalized` |
-| Element `opacity` | Alpha compiled into supported paint/effect channels | `Native-normalized` |
-| `<image opacity>` | Picture `<a:alphaModFix>` | `Native-stable` |
-| `<stop stop-opacity>` | Per-stop gradient alpha | `Native-stable` |
-| `<g opacity>` | Direct-converter compatibility only; generated SVG authoring is forbidden | `Approximate`; §2.2 |
-| Pattern child/color alpha | Preset-pattern foreground/background alpha | Conditional; §7 |
+| Solid fill or text paint | `fill="#RRGGBB"` | Solid DrawingML paint; `Native-stable` |
+| Fill/text alpha | Opaque `fill` + `fill-opacity="0..1"` | Fill/run alpha; `Native-stable` |
+| Stroke alpha | Opaque `stroke` + `stroke-opacity="0..1"` | Line/outline alpha; `Native-stable` |
+| Gradient-stop alpha | Opaque `stop-color` + `stop-opacity="0..1"` | Per-stop alpha; `Native-stable` |
+| Shadow/glow alpha | Opaque `flood-color` + `flood-opacity="0..1"` | Effect alpha; `Native-stable` within §6.4 |
+| Picture fade | `<image opacity="0..1">` | Picture `<a:alphaModFix>`; `Native-stable` |
+| One atomic whole-object fade | Non-group element `opacity="0..1"` | Alpha compiled into its supported paint/effect channels; `Native-normalized` |
+| Pattern alpha | Opaque pattern child paint + child fill/stroke opacity | Conditional; §7 |
+| CSS color alpha | Alpha-bearing named/functional/HEX paint | `Native-normalized`; recommendation warning only |
+| Group fade | `<g opacity>` compatibility | `Approximate`; fidelity warning; §2.2 |
```text
effective fill alpha
-= color alpha × element opacity × fill-opacity
+= color alpha × ancestor group opacity × element opacity × fill-opacity
```
-The converter-only historical path may additionally multiply ancestor group
-opacity; generated SVG never depends on that approximation.
-
-**Hard rule — alpha grammar**: write `opacity`, `fill-opacity`,
-`stroke-opacity`, `stop-opacity`, and `flood-opacity` as finite unitless numbers
-from `0` to `1`.
+**Default — opaque color authority (may preserve compatible alpha colors)**:
+New generated SVG puts alpha on the semantic channel that owns it. Existing or
+intentional alpha-bearing color tokens remain convertible; they normalize into
+the matching DrawingML color/alpha channels.
+
+**Default — channel-specific alpha (may override for one atomic whole-object
+fade)**: use `fill-opacity`, `stroke-opacity`, `stop-opacity`, or
+`flood-opacity` when only that channel fades. Use element `opacity` only when
+an image or one non-group atomic object intentionally fades all of its
+supported paint/effect channels together. Do not use element `opacity` as an
+alias for `rgba()` on a fill-only object.
+
+**Default — alpha grammar (may preserve compatible alternatives)**: write
+`opacity`, `fill-opacity`, `stroke-opacity`, `stop-opacity`, and
+`flood-opacity` as finite unitless numbers from `0` to `1`. The converter also
+accepts finite numeric values that SVG/CSS clamps into that interval;
+`stop-opacity` and `flood-opacity` additionally accept finite percentages. The
+checker reports those supported non-default spellings as recommendation warnings.
+Malformed or non-finite values remain errors because the exporter cannot
+preserve their intent.
`fill="transparent"` / `stroke="transparent"` become no fill/line; use a color
-plus alpha when a painted transparent layer must remain represented. Group
-opacity below `1` is forbidden in generated SVG; assign alpha to descendants.
+plus alpha when a painted transparent layer must remain represented. Prefer
+descendant alpha over group opacity when isolated compositing matters (§2.2).
---
@@ -629,8 +664,9 @@ Filters are native-effect metadata, not a general pixel-filter surface.
| Classification | Meaningful non-zero offset → one outer shadow; zero/no offset → one glow |
| Fidelity | `Approximate`; one filter becomes one DrawingML effect |
-Flood/color alpha, linear `feFuncA slope`, and element opacity multiply. The
-converter-only historical path may also multiply ancestor group opacity.
+Flood opacity, linear `feFuncA slope`, and element opacity multiply. The
+converter-only historical path may also multiply flood-color alpha and
+ancestor group opacity.
Native export does not preserve filter-region, `in/in2/result`, merge order, or
composite topology. Other primitives, multiple independent effects, filters on
`<image>` / `<tspan>` / `<g>` / unsupported targets are forbidden; apply the
@@ -747,6 +783,7 @@ matters, use one multi-subpath path rather than a fixed-density preset pattern:
|---|---|---|
| Underline / strike / both | `text-decoration="underline"`, `line-through`, or both | `Native-stable`; both emits both run properties |
| Mixed runs | Non-positional `<tspan>` | One `Native-normalized` editable frame; §4.2 |
+| Font size | Generated default is a finite unitless SVG px value; compatible `px`, `pt`, `pc`/`pica`, `in`, `cm`, `mm`, `q`, `em`, and `rem` values receive a recommendation warning only | Converted to SVG px, then editable DrawingML point size; unsupported units/percentages error |
| Tracking | Numeric `letter-spacing` | `Native-normalized`; unitless/`px` = SVG px, `pt` converts to px, `em` resolves against run size |
| Transparency | `opacity` / `fill-opacity` on text/run | `Native-normalized` run alpha, not isolated compositing |
| Gradient fill | §6.3 gradient on text/run | Editable fill; geometry normalizes |
@@ -778,7 +815,7 @@ modes, generated effects, and text-image knockouts are outside editable text.
| Positive scale / negative mirror | Geometry/image only; explicit pivot; `Native-normalized` |
| `matrix(a b c d e f)` | Geometry/image only; transformed axes finite, non-zero, orthogonal; excludes rounded rects; `Native-normalized` |
| Source order | Back-to-front PPT z-order; `Native-stable` |
-| `<g opacity>` | Converter-only historical compatibility; forbidden in generated SVG, §2.2 |
+| `<g opacity>` | Compatible approximate mapping; generated SVG prefers descendant alpha, §2.2 |
| Local `<use>` | §1.3 compile-time reuse; `Native-normalized` |
Set text size/position directly; do not scale or general-matrix text. `skewX`,
@@ -1001,9 +1038,11 @@ required.
the tile's arbitrary geometry. Use this interface only when that preset mapping
is intended.
-`data-pptx-pattern="<preset>"` is required to select the intended preset from
-the enum below. The converter retains an `ltUpDiag` fallback for historical
-input, but generated authoring without the annotation fails quality check.
+`data-pptx-pattern="<preset>"` is the generated default for selecting the
+intended preset from the enum below. The converter retains an `ltUpDiag`
+fallback when the annotation is absent; the checker reports that fallback as a
+non-blocking fidelity warning. Invalid explicit preset names remain errors
+because they violate the closed OOXML enum.
Pattern colors may come from importer metadata (`data-pptx-fg` /
`data-pptx-bg`) or from the pattern's child paint. Without metadata, the first
@@ -1023,8 +1062,9 @@ itself is never used as a repeatable tile.
| Checks & confetti | `smCheck` · `lgCheck` · `smConfetti` · `lgConfetti` |
| Decorative | `horzBrick` · `diagBrick` · `weave` · `plaid` · `trellis` · `zigZag` · `wave` · `sphere` · `divot` · `shingle` · `solidDmnd` · `openDmnd` · `dotDmnd` |
-`svg_quality_checker.py` errors when a referenced pattern lacks the annotation,
-uses `patternTransform`, or names a preset outside this enum.
+`svg_quality_checker.py` warns when a referenced pattern lacks the annotation;
+it errors when the pattern uses `patternTransform` or names a preset outside
+this enum.
### Native PPTX Table / Chart Markers (Opt-in)
@@ -1284,10 +1324,10 @@ the visible SVG fallback: the largest panel-like `<rect>` becomes the chart
background, fallback text supplies label color, and fallback strokes supply
axis/grid colors. Override any of them explicitly under `style` with
`chart_area_fill`, `plot_area_fill`, `text_color`, `axis_color`, and
-`grid_color`; use `"none"` for transparent chart or plot area fill. Color
-values may be `#RRGGBB`, `#RGB`, `rgb(...)` / `rgba(...)`, or common CSS names
-such as `white`, `black`, and `gray`; the exporter normalizes them to 6-digit
-OOXML RGB. Bar and column series also disable PowerPoint's negative-value
+`grid_color`; use `"none"` for transparent chart or plot area fill. Generated
+payloads default to uppercase `#RRGGBB`. The exporter retains compatibility for
+`#RGB`, `rgb(...)` / `rgba(...)`, and common CSS names, normalizing them to
+6-digit OOXML RGB. Bar and column series also disable PowerPoint's negative-value
inversion so negative bars keep the same series fill instead of turning into
white/theme fill.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 1fdd9804..9eec546a 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -182,10 +182,14 @@ python3 scripts/svg_quality_checker.py path/to/template/templates --template-mod
Checks include:
- `viewBox`
- banned elements
+- paint compatibility: unsupported values error; supported non-default spellings such as `rgba()` receive non-blocking recommendations for `#RRGGBB` plus explicit alpha
- line-break structure
- explicit Master/Layout/slot structure for reusable templates
- duplicate empty Layout contracts under different keys
+Warnings are advisory: they require no modification or acknowledgement and do
+not affect the command's zero exit status. Only errors block the quality gate.
+
Template mode accepts compact canonical preset shapes marked with
`data-pptx-authoring="preset"`. It validates the explicit structured SVG
contract; it does not implement a separate source-payload opt-in marker.
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index 0ffa79aa..49e15b14 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -60,6 +60,7 @@ try:
parse_font_family as _parse_export_font_family,
parse_inline_style as _parse_inline_style,
parse_svg_color as _parse_export_color,
+ parse_svg_length as _parse_export_length,
rect_to_dml_xfrm as _rect_to_dml_xfrm,
validate_dml_shape_matrix as _validate_dml_shape_matrix,
)
@@ -70,6 +71,7 @@ except ImportError:
_parse_export_font_family = None
_parse_inline_style = None
_parse_export_color = None
+ _parse_export_length = None
_rect_to_dml_xfrm = None
_validate_dml_shape_matrix = None
@@ -246,6 +248,21 @@ _CHECK_PPTX_STRUCTURED_PROJECT = True
_BARE_HEX_VALUE_RE = re.compile(
r"(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})"
)
+_CANONICAL_SOLID_PAINT_RE = re.compile(r"#[0-9A-F]{6}")
+_CANONICAL_PAINT_PROPERTIES = (
+ 'fill',
+ 'stroke',
+ 'stop-color',
+ 'flood-color',
+ 'data-pptx-fg',
+ 'data-pptx-bg',
+)
+_CANONICAL_PAINT_ALPHA_PROPERTY = {
+ 'fill': 'fill-opacity',
+ 'stroke': 'stroke-opacity',
+ 'stop-color': 'stop-opacity',
+ 'flood-color': 'flood-opacity',
+}
SVG_NS = "http://www.w3.org/2000/svg"
XLINK_NS = "http://www.w3.org/1999/xlink"
_NON_VISUAL_SVG_TAGS = frozenset({
@@ -743,6 +760,36 @@ def _finite_unit_interval(raw: str) -> float | None:
return value
+def _compatible_opacity(
+ raw: str,
+ *,
+ allow_percentage: bool = False,
+) -> float | None:
+ """Parse a finite opacity form supported by the matching converter path.
+
+ Every exported opacity path accepts and clamps unitless numbers. Gradient
+ stops and filter flood alpha additionally accept percentages; ordinary
+ element, fill, stroke, text, picture, and group opacity paths do not.
+ """
+ value_text = raw.strip()
+ is_percent = value_text.endswith('%')
+ if is_percent and not allow_percentage:
+ return None
+ if is_percent:
+ value_text = value_text[:-1].strip()
+ if re.fullmatch(_NUMBER_TOKEN, value_text) is None:
+ return None
+ try:
+ value = float(value_text)
+ except ValueError:
+ return None
+ if not math.isfinite(value):
+ return None
+ if is_percent:
+ value /= 100.0
+ return max(0.0, min(1.0, value))
+
+
def _normalized_gradient_value(raw: str) -> float | None:
"""Parse a normalized gradient coordinate or percentage."""
value_text = raw.strip()
@@ -998,6 +1045,8 @@ class SVGQualityChecker:
# 2b. Validate the closed authoring-property surface and
# conditional definition interfaces before export.
self._check_authoring_property_contract(root, result)
+ self._check_paint_compatibility(root, result)
+ self._check_reference_spelling(root, result)
self._check_definition_contract(root, result)
self._check_marker_contract(root, result)
self._check_clip_path_contract(root, result)
@@ -1316,44 +1365,165 @@ class SVGQualityChecker:
)
result['errors'].extend(sorted(paint_reference_errors))
- # Paint grammar: use the exporter's parser so authoring validation and
- # native conversion accept the same CSS color subset.
- paint_values = [
- (attr, value)
- for attr in (
- 'fill', 'stroke', 'stop-color', 'flood-color',
- 'data-pptx-fg', 'data-pptx-bg',
- )
- for value in self._svg_property_values(content, attr)
- ]
+ @staticmethod
+ def _canonical_alpha_literal(value: float) -> str:
+ """Return a compact deterministic alpha literal in the closed interval."""
+ bounded = max(0.0, min(1.0, value))
+ return f'{bounded:.6f}'.rstrip('0').rstrip('.') or '0'
+
+ def _check_paint_compatibility(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject unsupported paint and advise one generated-SVG spelling.
+
+ The exporter parser owns compatibility. Any paint it can parse remains
+ valid input; the checker only warns when that spelling differs from the
+ generated-SVG default (uppercase ``#RRGGBB`` plus explicit alpha).
+ """
if _parse_export_color is None:
result['warnings'].append(
"Unable to import svg_to_pptx color parser; skipped paint syntax check"
)
- else:
- invalid_paints = set()
- for attr, value in paint_values:
- normalized = value.strip()
- if attr in {'fill', 'stroke'} and (
- normalized.lower() == 'none'
- or re.fullmatch(r'url\(#[^)]+\)', normalized)
- ):
+ return
+
+ unsupported: Counter[tuple[str, str]] = Counter()
+ recommendations: Counter[tuple[str, str, str]] = Counter()
+ unsupported_examples: Dict[tuple[str, str], List[str]] = defaultdict(list)
+ recommendation_examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
+
+ def remember_example(store: Dict, key: tuple, label: str) -> None:
+ labels = store[key]
+ if label not in labels and len(labels) < 3:
+ labels.append(label)
+
+ for elem in root.iter():
+ label = _element_label(elem)
+ style_declarations: list[tuple[str, str]] = []
+ for fragment in (elem.get('style') or '').split(';'):
+ fragment = fragment.strip()
+ if not fragment or ':' not in fragment:
continue
- if _BARE_HEX_VALUE_RE.fullmatch(normalized):
- invalid_paints.add(value)
+ name, value = fragment.split(':', 1)
+ name = name.strip().lower()
+ value = value.strip()
+ if name and value:
+ style_declarations.append((name, value))
+ style_values = dict(style_declarations)
+
+ paint_entries = [
+ (name, elem.get(name), 'attribute')
+ for name in _CANONICAL_PAINT_PROPERTIES
+ if elem.get(name) is not None
+ ]
+ paint_entries.extend(
+ (name, value, 'inline style')
+ for name, value in style_declarations
+ if name in _CANONICAL_PAINT_PROPERTIES
+ )
+
+ for name, raw_value, source in paint_entries:
+ assert raw_value is not None
+ value = raw_value.strip()
+ source_label = f'{label} {source}'
+
+ if name in {'fill', 'stroke'}:
+ if value == 'none' or re.fullmatch(r'url\(#[^)]+\)', value):
+ continue
+ if value.lower() == 'none':
+ key = (name, raw_value, f'{name}="none"')
+ recommendations[key] += 1
+ remember_example(recommendation_examples, key, source_label)
+ continue
+ if value.lower() == 'transparent':
+ key = (name, raw_value, f'{name}="none"')
+ recommendations[key] += 1
+ remember_example(recommendation_examples, key, source_label)
+ continue
+
+ if _CANONICAL_SOLID_PAINT_RE.fullmatch(value):
continue
- color, _alpha = _parse_export_color(normalized)
+
+ color, color_alpha = _parse_export_color(value)
if color is None:
- invalid_paints.add(value)
- if invalid_paints:
- shown = ', '.join(sorted(invalid_paints)[:5])
- more = len(invalid_paints) - 5
- suffix = f" (+{more} more)" if more > 0 else ""
- result['errors'].append(
- "Unsupported SVG paint value(s) for PPTX export: "
- f"{shown}{suffix}. Use a supported named color, rgb()/rgba(), "
- "hsl()/hsla(), or #RGB/#RGBA/#RRGGBB/#RRGGBBAA."
- )
+ key = (name, raw_value)
+ unsupported[key] += 1
+ remember_example(unsupported_examples, key, source_label)
+ continue
+
+ replacement = f'{name}=\"#{color}\"'
+ alpha_name = _CANONICAL_PAINT_ALPHA_PROPERTY.get(name)
+ if color_alpha < 1.0 and alpha_name is not None:
+ existing_alpha_raw = (
+ style_values.get(alpha_name) or elem.get(alpha_name)
+ )
+ existing_alpha = (
+ _compatible_opacity(
+ existing_alpha_raw,
+ allow_percentage=alpha_name in {
+ 'stop-opacity',
+ 'flood-opacity',
+ },
+ )
+ if existing_alpha_raw is not None else 1.0
+ )
+ effective_alpha = (
+ color_alpha * existing_alpha
+ if existing_alpha is not None else color_alpha
+ )
+ replacement += (
+ f' {alpha_name}=\"'
+ f'{self._canonical_alpha_literal(effective_alpha)}\"'
+ )
+ elif color_alpha < 1.0:
+ replacement += (
+ '; put alpha on the matching pattern child fill/stroke '
+ 'opacity'
+ )
+ key = (name, raw_value, replacement)
+ recommendations[key] += 1
+ remember_example(recommendation_examples, key, source_label)
+
+ for (name, raw_value), count in sorted(unsupported.items()):
+ allowed = (
+ '#RRGGBB, none, or url(#id)'
+ if name in {'fill', 'stroke'} else '#RRGGBB'
+ )
+ examples = ', '.join(unsupported_examples[(name, raw_value)])
+ result['errors'].append(
+ f"Unsupported SVG paint {name}={raw_value!r} in {count} "
+ f"location(s) ({examples}); use {allowed} or another color "
+ "accepted by svg_to_pptx"
+ )
+
+ for (name, raw_value, replacement), count in sorted(recommendations.items()):
+ examples = ', '.join(
+ recommendation_examples[(name, raw_value, replacement)]
+ )
+ result['warnings'].append(
+ f"Recommendation: {name}={raw_value!r} is converter-compatible "
+ f"in {count} location(s) ({examples}); generated SVG should "
+ f"prefer {replacement}. No change is required for export."
+ )
+
+ def _check_reference_spelling(self, root: ET.Element, result: Dict) -> None:
+ """Recommend SVG 2 ``href`` while retaining legacy XLink input."""
+ labels = []
+ xlink_href = f'{{{XLINK_NS}}}href'
+ for elem in root.iter():
+ if _local_name(elem).lower() not in {'image', 'use'}:
+ continue
+ if elem.get(xlink_href) is not None:
+ labels.append(_element_label(elem))
+ if labels:
+ examples = ', '.join(labels[:3])
+ suffix = f' (+{len(labels) - 3} more)' if len(labels) > 3 else ''
+ result['warnings'].append(
+ f"Recommendation: legacy xlink:href is supported on {len(labels)} "
+ f"reference(s) ({examples}{suffix}); generated SVG should prefer "
+ "href. No change is required for export."
+ )
def _check_authoring_property_contract(
self,
@@ -1361,7 +1531,9 @@ class SVGQualityChecker:
result: Dict,
) -> None:
"""Validate inline CSS and alpha values against the authoring surface."""
- issues: set[str] = set()
+ errors: set[str] = set()
+ recommendations: set[str] = set()
+ fidelity_warnings: set[str] = set()
for elem in root.iter():
label = _element_label(elem)
style_declarations: list[tuple[str, str]] = []
@@ -1370,7 +1542,7 @@ class SVGQualityChecker:
if not fragment:
continue
if ':' not in fragment:
- issues.add(
+ errors.add(
f"{label} has malformed inline style declaration {fragment!r}"
)
continue
@@ -1378,46 +1550,67 @@ class SVGQualityChecker:
name = name.strip().lower()
value = value.strip()
if not name or not value:
- issues.add(
+ errors.add(
f"{label} has malformed inline style declaration {fragment!r}"
)
continue
style_declarations.append((name, value))
if name in _BAKE_REQUIRED_VISUAL_PROPERTIES:
- issues.add(
+ errors.add(
f"{label} uses Bake-required visual property {name!r}; "
"bake the effect or rebuild it with supported geometry"
)
elif name not in _SUPPORTED_INLINE_STYLE_PROPERTIES:
- issues.add(
+ errors.add(
f"{label} uses unsupported inline style property {name!r}; "
"native PPTX export would ignore it"
)
if '!important' in value.lower():
- issues.add(
+ errors.add(
f"{label} inline style property {name!r} cannot use !important"
)
for attr_name in elem.attrib:
local_attr = attr_name.rsplit('}', 1)[-1]
if local_attr in _BAKE_REQUIRED_VISUAL_PROPERTIES:
- issues.add(
+ errors.add(
f"{label} uses Bake-required visual attribute {local_attr!r}; "
"bake the effect or rebuild it with supported geometry"
)
for name in _ALPHA_PROPERTIES:
direct_value = elem.get(name)
- if direct_value is not None and _finite_unit_interval(direct_value) is None:
- issues.add(
- f"{label} {name} must be a finite unitless number from "
- f"0 to 1; got {direct_value!r}"
+ alpha_entries = []
+ if direct_value is not None:
+ alpha_entries.append((name, direct_value))
+ alpha_entries.extend(
+ (f'style {name}', style_value)
+ for style_name, style_value in style_declarations
+ if style_name == name
+ )
+ for entry_name, raw_value in alpha_entries:
+ allow_percentage = name in {'stop-opacity', 'flood-opacity'}
+ compatible_value = _compatible_opacity(
+ raw_value,
+ allow_percentage=allow_percentage,
)
- for style_name, style_value in style_declarations:
- if style_name == name and _finite_unit_interval(style_value) is None:
- issues.add(
- f"{label} style {name} must be a finite unitless number "
- f"from 0 to 1; got {style_value!r}"
+ if compatible_value is None:
+ accepted_form = (
+ 'a finite number or percentage opacity'
+ if allow_percentage
+ else 'a finite unitless numeric opacity'
+ )
+ errors.add(
+ f"{label} {entry_name} must be {accepted_form}; "
+ f"got {raw_value!r}"
+ )
+ elif _finite_unit_interval(raw_value) is None:
+ recommendations.add(
+ f"Recommendation: {label} {entry_name}={raw_value!r} "
+ "is converter-compatible; generated SVG should prefer "
+ f"the unitless 0..1 value "
+ f"{self._canonical_alpha_literal(compatible_value)!r}. "
+ "No change is required for export."
)
if _local_name(elem).lower() != 'g':
@@ -1429,15 +1622,19 @@ class SVGQualityChecker:
raw_opacity = style_opacity if style_opacity is not None else elem.get('opacity')
if raw_opacity is None:
continue
- opacity = _finite_unit_interval(raw_opacity)
+ opacity = _compatible_opacity(raw_opacity)
if opacity is not None and opacity < 1.0:
- issues.add(
- f"{label} uses <g opacity={raw_opacity!r}>; generated SVG "
- "must put alpha on individual descendants because native "
- "PPTX export cannot preserve isolated group compositing"
+ fidelity_warnings.add(
+ f"Fidelity warning: {label} uses group opacity={raw_opacity!r}. "
+ "The converter distributes this alpha to descendants and "
+ "cannot preserve isolated group compositing; generated SVG "
+ "should prefer descendant alpha. Existing input remains "
+ "convertible and does not require modification."
)
- result['errors'].extend(sorted(issues))
+ result['errors'].extend(sorted(errors))
+ result['warnings'].extend(sorted(recommendations))
+ result['warnings'].extend(sorted(fidelity_warnings))
def _check_definition_contract(
self,
@@ -1884,28 +2081,51 @@ class SVGQualityChecker:
result['errors'].extend(sorted(issues))
def _check_font_size_values(self, content: str, result: Dict):
- """Require font-size values to be unitless numeric SVG px values."""
- numeric_re = re.compile(r'^(?:\d+(?:\.\d+)?|\.\d+)$')
- bad_values = set()
+ """Keep supported font-size units compatible and recommend unitless px."""
+ canonical_re = re.compile(r'^(?:\d+(?:\.\d+)?|\.\d+)$')
+ values = set()
for match in re.finditer(r'\bfont-size\s*=\s*(["\'])(.*?)\1', content, re.IGNORECASE):
- raw = match.group(2).strip()
- if not numeric_re.fullmatch(raw):
- bad_values.add(raw)
+ values.add(match.group(2).strip())
for match in re.finditer(r'\bfont-size\s*:\s*([^;"\']+)', content, re.IGNORECASE):
- raw = match.group(1).strip()
- if not numeric_re.fullmatch(raw):
- bad_values.add(raw)
+ values.add(match.group(1).strip())
+
+ if _parse_export_length is None:
+ result['warnings'].append(
+ "Unable to import svg_to_pptx length parser; skipped font-size syntax check"
+ )
+ return
+
+ unsupported = set()
+ compatible_noncanonical = set()
+ for raw in values:
+ parsed_px = _parse_export_length(raw, math.nan, font_size=16)
+ if not math.isfinite(parsed_px) or parsed_px < 0:
+ unsupported.add(raw)
+ continue
+ if not canonical_re.fullmatch(raw):
+ compatible_noncanonical.add(raw)
- if bad_values:
- shown_values = sorted(bad_values)
+ if unsupported:
+ shown_values = sorted(unsupported)
shown = ', '.join(shown_values[:5])
more = len(shown_values) - 5
suffix = f" (+{more} more)" if more > 0 else ""
result['errors'].append(
- f"font-size must be a unitless numeric px value; found {shown}{suffix}. "
- "Write e.g. font-size=\"28\", never font-size=\"28px\" or \"21pt\"."
+ f"Unsupported font-size value(s): {shown}{suffix}. Use a finite "
+ "non-negative SVG length supported by svg_to_pptx."
+ )
+
+ if compatible_noncanonical:
+ shown_values = sorted(compatible_noncanonical)
+ shown = ', '.join(shown_values[:5])
+ more = len(shown_values) - 5
+ suffix = f" (+{more} more)" if more > 0 else ""
+ result['warnings'].append(
+ f"Recommendation: font-size value(s) {shown}{suffix} are "
+ "converter-compatible; generated SVG should prefer unitless px "
+ "values such as font-size=\"28\". No change is required for export."
)
def _check_fonts(self, content: str, result: Dict):
@@ -2415,14 +2635,15 @@ class SVGQualityChecker:
pat_id = pattern.get('id', '<unnamed>')
prst = pattern.get('data-pptx-pattern')
if pat_id in referenced_patterns and not prst:
- result['errors'].append(
- f"<pattern id=\"{pat_id}\"> has no data-pptx-pattern attribute — "
- "generated SVG cannot rely on the converter's `ltUpDiag` "
- "compatibility fallback. Add a valid data-pptx-pattern; "
+ result['warnings'].append(
+ f"Fidelity warning: <pattern id=\"{pat_id}\"> has no "
+ "data-pptx-pattern attribute, so the converter will use its "
+ "compatible `ltUpDiag` fallback. Generated SVG should declare a valid "
+ "data-pptx-pattern to make the intended preset explicit; "
"set data-pptx-fg/data-pptx-bg or matching child paints "
- "when explicit pattern colors are required."
+ "when explicit pattern colors are required. No change is "
+ "required for export."
)
- continue
if pat_id in referenced_patterns and pattern.get('patternTransform'):
result['errors'].append(
f"<pattern id=\"{pat_id}\"> cannot use patternTransform; "
@@ -2629,8 +2850,8 @@ class SVGQualityChecker:
"""Warn on mapped pages that compile to bare Masters / empty Layouts.
Zero-slot and framing-only Layouts are legal contracts, so these stay
- warnings; the workflow gate requires each one to be fixed or
- explicitly kept with a stated reason.
+ advisory warnings. They neither fail the workflow gate nor require a
+ per-warning disposition.
"""
if not (root.get('data-pptx-layout') or '').strip():
return
@@ -2650,26 +2871,29 @@ class SVGQualityChecker:
result['warnings'].append(
'Mapped page declares data-pptx-layout but no data-pptx-layer '
'mark; the exported Master gets no shared background/chrome '
- 'and the Layout gets no static framing. Mark the deck-wide '
+ 'and the Layout gets no static framing. Generated templates '
+ 'should mark the deck-wide '
'background data-pptx-layer="master" and this layout key\'s '
- 'framing data-pptx-layer="layout".'
+ 'framing data-pptx-layer="layout". No change or disposition '
+ 'is required.'
)
if not has_placeholder and not has_layout_atom:
result['warnings'].append(
'Mapped page has no placeholder slot and no '
'data-pptx-layer="layout" atom; its Layout exports empty. '
- 'Declare the slots the page actually has (title / subtitle / '
+ 'Generated templates should declare the slots the page actually '
+ 'has (title / subtitle / '
'body / picture / slide-number / footer) and mark the layout '
- 'key\'s static framing, or state why this fixed composition '
- 'is intentionally zero-slot.'
+ 'key\'s static framing unless this is intentionally a fixed '
+ 'zero-slot composition. No change or disposition is required.'
)
elif not has_placeholder:
result['warnings'].append(
'Mapped Layout has static framing but no insertable '
- 'placeholder slot. Keep it only when zero-slot is the '
- 'intended reusable contract; otherwise declare the slots the '
- 'page actually has (title / subtitle / body / picture / '
- 'slide-number / footer).'
+ 'placeholder slot. Generated templates should declare the '
+ 'slots the page actually has (title / subtitle / body / '
+ 'picture / slide-number / footer) unless zero-slot is the '
+ 'intended reusable contract. No change or disposition is required.'
)
def _check_semantic_markers(
@@ -3043,6 +3267,8 @@ class SVGQualityChecker:
return 'viewBox issues'
elif 'foreignObject' in error_msg:
return 'foreignObject'
+ elif 'paint' in error_msg.lower() or 'color value' in error_msg.lower():
+ return 'Paint issues'
elif 'font' in error_msg.lower():
return 'Font issues'
else:
@@ -3393,7 +3619,8 @@ class SVGQualityChecker:
"contracts genuinely differ — assign distinct explicit default "
"placeholder bounds and/or mark only truly stable framing as "
'data-pptx-layer="layout". Slide-local content geometry does not '
- "define a Layout."
+ "define a Layout. This recommendation is advisory; no change or "
+ "disposition is required."
)
return messages
@@ -4365,8 +4592,13 @@ class SVGQualityChecker:
print(f"\n[TIP] Common fixes:")
print(f" 1. XML well-formedness: write typography as raw Unicode (—, ©, →, NBSP); escape XML reserved chars as &amp; &lt; &gt; &quot; &apos; — never use HTML named entities like &nbsp; &mdash; &copy;")
print(f" 2. viewBox issues: root viewBox is the canvas authority (see references/canvas-formats.md)")
- print(f" 3. foreignObject: Use <text> + <tspan> for manual line breaks")
- print(f" 4. Font issues: use PPT-safe exported typefaces (e.g. Microsoft YaHei / Arial / Consolas)")
+ print(
+ " 3. Paint recommendation: generated SVG prefers uppercase "
+ "#RRGGBB plus channel-specific opacity; compatible alternatives "
+ "remain non-blocking"
+ )
+ print(f" 4. foreignObject: Use <text> + <tspan> for manual line breaks")
+ print(f" 5. Font issues: use PPT-safe exported typefaces (e.g. Microsoft YaHei / Arial / Consolas)")
def _print_animation_summary(self):
"""Print animations.json validation issues if present."""
@@ -4572,6 +4804,8 @@ def print_usage() -> None:
print(" per-file and cross-page structure validation. Legacy")
print(" native_structure_mode: template fails and must run")
print(" restore-pptx-structure before validation.")
+ print(" Warnings are advisory: they require no modification and do not affect exit status;")
+ print(" only errors make the command exit with status 1.")
def main() -> None:
diff --git a/skills/ppt-master/scripts/test_svg_quality_checker.py b/skills/ppt-master/scripts/test_svg_quality_checker.py
new file mode 100644
index 00000000..ea0beddd
--- /dev/null
+++ b/skills/ppt-master/scripts/test_svg_quality_checker.py
@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""Regression tests for SVG checker compatibility severity."""
+
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+ sys.path.insert(0, str(SCRIPT_DIR))
+
+from svg_quality_checker import SVGQualityChecker
+
+
+class SVGQualityCheckerCompatibilityTests(unittest.TestCase):
+ """Keep supported aliases advisory and unsupported input blocking."""
+
+ def _check(self, content: str) -> dict:
+ with tempfile.TemporaryDirectory() as tmp_dir:
+ svg_path = Path(tmp_dir) / 'fixture.svg'
+ svg_path.write_text(content, encoding='utf-8')
+ return SVGQualityChecker().check_file(str(svg_path))
+
+ def test_canonical_generated_spelling_has_no_compatibility_warning(self):
+ result = self._check(
+ '''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720">
+ <rect x="80" y="80" width="300" height="180"
+ fill="#FF0000" fill-opacity="0.5"/>
+ <text x="80" y="340" font-family="Arial" font-size="28"
+ fill="#000080">Canonical</text>
+</svg>'''
+ )
+
+ self.assertTrue(result['passed'])
+ self.assertEqual(result['errors'], [])
+ self.assertEqual(result['warnings'], [])
+
+ def test_supported_aliases_are_non_blocking_warnings(self):
+ result = self._check(
+ '''<svg xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ viewBox="0 0 1280 720">
+ <defs>
+ <g id="dot"><circle cx="0" cy="0" r="8" fill="#00AA00"/></g>
+ <linearGradient id="legacy-gradient">
+ <stop offset="0" stop-color="#0000FF" stop-opacity="50%"/>
+ <stop offset="1" stop-color="#0000FF"/>
+ </linearGradient>
+ <pattern id="legacy-pattern" width="8" height="8">
+ <rect width="8" height="8" fill="#FFFFFF"/>
+ <path d="M0 8 L8 0" stroke="#999999"/>
+ </pattern>
+ </defs>
+ <g id="faded" opacity="0.6">
+ <rect x="80" y="80" width="300" height="180"
+ fill="rgba(255, 0, 0, 0.5)" fill-opacity="1.2"/>
+ </g>
+ <rect x="420" y="80" width="300" height="180"
+ fill="url(#legacy-pattern)"/>
+ <rect x="760" y="80" width="300" height="180"
+ fill="url(#legacy-gradient)"/>
+ <text x="80" y="340" font-family="Arial" font-size="21pt"
+ fill="navy">Aliases</text>
+ <use xlink:href="#dot" x="100" y="420"/>
+</svg>'''
+ )
+
+ warning_text = '\n'.join(result['warnings'])
+ self.assertTrue(result['passed'])
+ self.assertEqual(result['errors'], [])
+ self.assertIn("fill='rgba(255, 0, 0, 0.5)'", warning_text)
+ self.assertIn("fill-opacity='1.2'", warning_text)
+ self.assertIn("stop-opacity='50%'", warning_text)
+ self.assertIn('group opacity', warning_text)
+ self.assertIn('font-size value(s) 21pt', warning_text)
+ self.assertIn('legacy xlink:href', warning_text)
+ self.assertIn('compatible `ltUpDiag` fallback', warning_text)
+ self.assertTrue(all('No change is required' in item or 'does not require' in item
+ for item in result['warnings']))
+
+ def test_unsupported_values_remain_errors(self):
+ result = self._check(
+ '''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720">
+ <rect x="80" y="80" width="300" height="180"
+ fill="var(--brand)" opacity="bogus" fill-opacity="50%"/>
+ <text x="80" y="340" font-family="Arial" font-size="12%">Broken</text>
+</svg>'''
+ )
+
+ error_text = '\n'.join(result['errors'])
+ self.assertFalse(result['passed'])
+ self.assertIn('Unsupported SVG paint', error_text)
+ self.assertIn('must be a finite unitless numeric opacity', error_text)
+ self.assertIn('Unsupported font-size', error_text)
+
+ def test_pattern_transform_stays_blocking_without_explicit_preset(self):
+ result = self._check(
+ '''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720">
+ <defs>
+ <pattern id="legacy-pattern" width="8" height="8"
+ patternTransform="rotate(45)">
+ <rect width="8" height="8" fill="#FFFFFF"/>
+ <path d="M0 8 L8 0" stroke="#999999"/>
+ </pattern>
+ </defs>
+ <rect x="80" y="80" width="300" height="180"
+ fill="url(#legacy-pattern)"/>
+</svg>'''
+ )
+
+ self.assertFalse(result['passed'])
+ self.assertTrue(any('cannot use patternTransform' in item
+ for item in result['errors']))
+ self.assertTrue(any('compatible `ltUpDiag` fallback' in item
+ for item in result['warnings']))
+
+
+if __name__ == '__main__':
+ unittest.main()
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index b48b7f0f..bbe6dbbc 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -207,4 +207,11 @@
- `mask`, `<style>`, `class`, external CSS, `<foreignObject>`, `textPath`, `@font-face`, `<animate*>`, `<set>`, `<script>` / event attributes, `<iframe>`
- HTML named entities in text; write typography as raw Unicode and escape XML reserved characters
-> **Execution reminder — not authoring authority**: the baseline blacklist above is intentionally terse. Add only deck-specific execution locks. General SVG required / forbidden / conditional rules are owned by [`shared-standards.md`](../references/shared-standards.md); do not copy its feature matrix or parameter contracts into `spec_lock.md`.
+> **Execution reminder — not authoring authority**: the baseline blacklist above
+> is intentionally terse. Add only deck-specific execution locks. General SVG
+> required / forbidden / conditional rules are owned by
+> [`shared-standards.md`](../references/shared-standards.md); do not copy its
+> feature matrix or parameter contracts into `spec_lock.md`. In particular, do
+> not move supported-but-non-default spellings such as `rgba()` or compatible
+> `<g opacity>` into the generic forbidden list merely to enforce a generation
+> preference; their checker warnings remain advisory.
diff --git a/skills/ppt-master/workflows/failure-recovery.md b/skills/ppt-master/workflows/failure-recovery.md
index 73132b5e..71cf0604 100644
--- a/skills/ppt-master/workflows/failure-recovery.md
+++ b/skills/ppt-master/workflows/failure-recovery.md
@@ -28,7 +28,7 @@ Central recovery rules for common PPT Master failures. Route-specific workflow f
| Live preview closed by user | No | Continue generation | No | Restart through `live-preview` only if requested |
| Browser annotations submitted during generation | No | Defer application until after Step 7 | User asks to apply annotations | `live-preview` Step 2 |
| `svg_quality_checker.py` error | Yes | Fix the affected SVG, then rerun checker | No unless required asset is missing | Step 6 Visual Construction |
-| `svg_quality_checker.py` warning | No | Fix when straightforward; otherwise acknowledge residual risk | No | Step 6 warning handling |
+| `svg_quality_checker.py` warning | No | Continue without mandatory modification or acknowledgement; preserve compatible user syntax, and report material fidelity/quality advice when useful | No | Step 6 advisory warning handling |
| Missing `notes/total.md` | Yes | Generate speaker notes before Step 7 | No | Step 6 Logic Construction |
| Step 7 image readiness missing manual files | Yes | None for manual assets; list required filenames and prompts | Yes | Step 7 image readiness gate |
| `total_md_split.py` failure | Yes | Fix notes format/path, rerun only Step 7.1 | Usually no | Step 7.1 |