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

docs(svg-authoring): allow static local use references

hugohe3a41ff00917fd
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 98b22f65..030aca42 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -92,12 +92,21 @@ If you're unsure, open an issue to ask — that's always welcome.
If your contribution involves SVG files, follow the technical constraints documented in [CLAUDE.md](./CLAUDE.md):
-- Do not use: `mask`, `<style>`, `class`, external CSS, `<foreignObject>`, `<animate*>`, `<script>`, `<symbol>+<use>`
+- Do not use: `mask`, `<style>`, `class`, external CSS, `<foreignObject>`, `<animate*>`, `<script>`
- Paint colors may use supported CSS forms: named colors, `rgb()` / `rgba()`,
`hsl()` / `hsla()`, and 3/4/6/8-digit HEX. Embedded alpha multiplies with
`opacity`, `fill-opacity`, or `stroke-opacity` during native export
- `marker-start` / `marker-end` are conditionally allowed — see `shared-standards.md` §1.1 (must live in `<defs>`, `orient="auto"`, shape must be triangle / diamond / oval)
- `clipPath` on `<image>` is conditionally allowed — see `shared-standards.md` §1.2 (must live in `<defs>`, single shape child, only on `<image>` elements)
+- Static local `<use>` / `<symbol>` reuse is conditionally allowed — see
+ `shared-standards.md` §1.3. Use only exact same-document `href="#id"` or
+ `xlink:href="#id"` references to the listed shape/group/text/image targets.
+ Symbol instances require a valid `viewBox` and positive unitless/`px`
+ `width`/`height`; `x`/`y` are unitless/`px`. External, missing, conflicting,
+ circular, or duplicate-ID references; `slice` / `refX` / `refY`; reusable
+ PPTX layer/native/placeholder metadata; and non-exact internal `url(#id)`
+ syntax are rejected. Reference depth is capped at 64 and expansion at 10,000
+ instances per SVG. PPTX-to-SVG import does not reconstruct `<use>`.
- All SVGs must use the correct `viewBox` for the target canvas format
## Reporting Bugs
diff --git a/docs/technical-design.md b/docs/technical-design.md
index b14f13f2..8cbd84b4 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -358,7 +358,9 @@ The catalog of *how an image is placed on a slide* (full vocabulary in [`referen
## SVG Constraints: Banned Features and Conditional Allowances
-PowerPoint's DrawingML is a strict subset of what SVG can express. The Executor operates inside an empirically-grown blacklist (mask, style/class, `@font-face`, foreignObject, symbol+use, textPath, animate*, script/iframe …) plus narrow conditional allowances for `marker-start`/`marker-end` and image-only `clip-path`. The authoritative list and exact per-feature constraints — including the substitute-effect routing table for `<mask>` (gradient overlays, clipPath, filter shadow, source-image bake-in) — live in [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md).
+PowerPoint's DrawingML is a strict subset of what SVG can express. The Executor operates inside an empirically-grown blacklist (mask, style/class, `@font-face`, foreignObject, textPath, animate*, script/iframe …) plus narrow conditional allowances for `marker-start`/`marker-end`, image-only `clip-path`, and static same-document `<use>` / `<symbol>` reuse. The authoritative list and exact per-feature constraints — including the substitute-effect routing table for `<mask>` (gradient overlays, clipPath, filter shadow, source-image bake-in) — live in [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md).
+
+**Why local `<use>` is compile-time reuse, not a retained PowerPoint object.** The accepted form is an exact same-document `href="#id"` or `xlink:href="#id"` targeting `symbol`, `g`, `use`, `rect`, `circle`, `ellipse`, `line`, `path`, `polygon`, `polyline`, `text`, or `image`; internal references use exact `url(#id)` fragments. `x` / `y` are finite unitless or `px` values. A symbol requires a valid `viewBox` whose dimensions are positive, positive unitless/`px` instance `width` / `height`, and either aligned `meet` or plain `none`; `slice`, `refX`, and `refY` are rejected. Symbol artwork must stay inside the `viewBox` because expansion does not reproduce overflow clipping. External, missing, conflicting, circular, and duplicate-ID references fail validation, as does reuse of `data-pptx-layer*`, `data-pptx-native*`, or `data-pptx-placeholder*` structure. The pipeline recursively materializes the subtree and rewrites cloned IDs before export. PPTX-to-SVG import returns the expanded primitives rather than reconstructing the authoring-time `<use>` graph.
The architectural reasons worth knowing here:
@@ -399,24 +401,26 @@ The post-processing and export stages work with distinct artifacts. Each one ser
| `exports/<name>_<ts>_svg.pptx` (preview, opt-in via `--svg-snapshot`) | cross-platform single-file distribution, multi-page browse, email attachment | self-contained, multi-page, opens in PowerPoint / Keynote / WPS / LibreOffice; an `svg_final/` folder is harder to distribute. Off by default — live preview already provides the SVG visual reference for dev/diagnostic work |
| `backup/<ts>/svg_output/` (always written in default-flow mode) | re-export from frozen SVG sources without re-running the LLM, archival | the only persisted copy of the Executor's raw SVG source after the project has been edited downstream |
-### The `svg_finalize/` package has TWO consumers
+### SVG preprocessors have TWO consumers
-This is the key insight that's easy to miss when reading the code. The same modules under `skills/ppt-master/scripts/svg_finalize/` are used in two places, for two different products.
+This is the key insight that's easy to miss when reading the code. Cleanup modules under `skills/ppt-master/scripts/svg_finalize/`, together with the local-reference expander, are used in two places for two different products.
-**Disk consumer** — `finalize_svg.py` writes `svg_output/` → `svg_final/` once per run. `svg_final/` then feeds IDE preview and the preview pptx.
+**Disk consumer** — `finalize_svg.py` writes `svg_output/` → `svg_final/` once per run, expanding both project icon placeholders and qualified local `<use>` references. `svg_final/` then feeds IDE preview and the preview pptx.
-**Memory consumer** — native pptx generation reads `svg_output/` directly (no disk hop), but DrawingML can't handle two SVG features inline, so the converter calls `svg_finalize` modules **in memory**:
+**Memory consumer** — native pptx generation reads `svg_output/` directly (no disk hop), but DrawingML cannot consume project icon placeholders, retained SVG reference instances, or positional text runs inline, so the converter applies the matching preprocessors **in memory**:
-| In-memory call site | Module reused | Why native pptx needs it |
+| In-memory call site | Preprocessor | Why native pptx needs it |
| --- | --- | --- |
| `svg_to_pptx/use_expander.py` | `svg_finalize.embed_icons` | DrawingML doesn't recognize `<use data-icon="...">`; without expansion every icon silently drops |
+| `svg_to_pptx/use_expander.py` | static local-reference expansion | DrawingML does not preserve SVG `<use>` instance graphs; qualifying subtrees must be materialized with instance-local IDs |
| `svg_to_pptx/tspan_flattener.py` | `svg_finalize.flatten_tspan` | DrawingML text runs cannot reposition mid-paragraph; a dy-stacked block of `<tspan>`s would otherwise collapse onto one baseline, and an x-anchored tspan would render in the wrong column |
### Per-module consumer table
| Module | Disk consumer | Memory consumer | Delete impact |
| --- | --- | --- | --- |
-| `embed_icons.py` | `finalize_svg` `embed-icons` step | `svg_to_pptx/use_expander.py` | native pptx loses all icons + `svg_final/` not self-contained |
+| `embed_icons.py` | `finalize_svg` `embed-icons` step (followed by local-use expansion) | `svg_to_pptx/use_expander.py` | native pptx loses all icons + `svg_final/` not self-contained |
+| `svg_to_pptx/use_expander.py` (local references) | `finalize_svg` `embed-icons` step | native converter preflight | finalize/native export can no longer materialize qualified local reuse |
| `flatten_tspan.py` | `finalize_svg` `flatten-text` step | `svg_to_pptx/tspan_flattener.py` | **native pptx multi-line `dy`-stacked text collapses to one line** |
| `align_embed_images.py` | `finalize_svg` `align-images` step | — | `svg_final/` loses image embedding → IDE preview / preview pptx have no images |
| `crop_images.py` / `embed_images.py` / `fix_image_aspect.py` | imported by `align_embed_images.py` | — | `align_embed_images` `ImportError`, full chain broken |
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 32f87120..721a42df 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -358,7 +358,9 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
## SVG 约束:禁用特性与条件允许
-PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份经验生长起来的黑名单(mask、style/class、`@font-face`、foreignObject、symbol+use、textPath、animate*、script/iframe ……)里运行,外加对 `marker-start`/`marker-end` 和仅 `<image>` 上的 `clip-path` 的窄条件允许。权威清单和每条特性的具体约束——包括 `<mask>` 的替代效果路由表(渐变叠加、clipPath、filter shadow、源图烘焙)——住在 [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md)。
+PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份经验生长起来的黑名单(mask、style/class、`@font-face`、foreignObject、textPath、animate*、script/iframe ……)里运行,外加对 `marker-start`/`marker-end`、仅 `<image>` 上的 `clip-path` 和同文档静态 `<use>` / `<symbol>` 复用的窄条件允许。权威清单和每条特性的具体约束——包括 `<mask>` 的替代效果路由表(渐变叠加、clipPath、filter shadow、源图烘焙)——住在 [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md)。
+
+**为什么本地 `<use>` 是编译期复用,不是 PowerPoint 保留对象。** 允许的引用必须是精确的同文档 `href="#id"` 或 `xlink:href="#id"`,目标仅限 `symbol`、`g`、`use`、`rect`、`circle`、`ellipse`、`line`、`path`、`polygon`、`polyline`、`text`、`image`,内部引用使用精确的 `url(#id)` 片段。`x` / `y` 只能是有限 unitless 或 `px` 值。`symbol` 必须有合法且维度为正数的 `viewBox`,实例必须提供正数 unitless/`px` `width` / `height`,并使用对齐的 `meet` 或纯 `none`;`slice`、`refX`、`refY` 会被拒绝。由于展开不会复现 overflow clipping,symbol 图形必须留在 `viewBox` 内。外部、缺失、冲突、循环、重复 ID 引用,以及对 `data-pptx-layer*`、`data-pptx-native*`、`data-pptx-placeholder*` 结构的复用都会校验失败。流水线会递归实体化子树并重写克隆 ID 后再导出;PPTX 回导只返回展开后的原语,不重建创作期 `<use>` 图。
值得在架构层标记的理由:
@@ -399,24 +401,26 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份
| `exports/<name>_<ts>_svg.pptx`(preview,需 `--svg-snapshot` 显式开启) | 跨平台单文件分发、整体多页浏览、邮件附件 | 自包含、多页、PowerPoint / Keynote / WPS / LibreOffice 都能直接打开;`svg_final/` 是文件夹,分发不便。默认关闭——live preview 已经覆盖 dev / 诊断场景的 SVG 视觉参考需求 |
| `backup/<ts>/svg_output/`(默认流程下始终生成) | 不重跑 LLM 的前提下从冻结 SVG 源重建 pptx、长期存档 | 项目下游被改动后,Executor 原始 SVG 唯一的留存副本 |
-### `svg_finalize/` 包有**两种**消费者
+### SVG 预处理器有**两种**消费者
-这是读代码时容易忽略的关键事实。同一组 `skills/ppt-master/scripts/svg_finalize/` 下的模块,在两个地方被使用,服务两份不同的产物。
+这是读代码时容易忽略的关键事实。`skills/ppt-master/scripts/svg_finalize/` 下的清理模块和本地引用展开器,会在两个地方被使用,服务两份不同的产物。
-**写盘消费者** —— `finalize_svg.py` 每次运行都把 `svg_output/` → `svg_final/` 写到磁盘一次。`svg_final/` 随后供 IDE 预览和 preview pptx 使用。
+**写盘消费者** —— `finalize_svg.py` 每次运行都把 `svg_output/` → `svg_final/` 写到磁盘一次,同时展开项目图标占位符和合规的本地 `<use>` 引用。`svg_final/` 随后供 IDE 预览和 preview pptx 使用。
-**内存消费者** —— native pptx 直接读 `svg_output/`(不经磁盘中转),但 DrawingML 无法内联处理两种 SVG 特性,所以转换器在内存中调用 `svg_finalize` 模块:
+**内存消费者** —— native pptx 直接读 `svg_output/`(不经磁盘中转),但 DrawingML 无法内联处理项目图标占位符、保留的 SVG 引用实例和定位文本 run,所以转换器在内存中应用对应预处理器:
-| 内存调用点 | 复用的模块 | native pptx 为何需要 |
+| 内存调用点 | 预处理器 | native pptx 为何需要 |
| --- | --- | --- |
| `svg_to_pptx/use_expander.py` | `svg_finalize.embed_icons` | DrawingML 不识别 `<use data-icon="...">`;不展开图标会静默丢失 |
+| `svg_to_pptx/use_expander.py` | 静态本地引用展开 | DrawingML 不保留 SVG `<use>` 实例图;合规子树必须实体化并获得实例级独立 ID |
| `svg_to_pptx/tspan_flattener.py` | `svg_finalize.flatten_tspan` | DrawingML 文本块无法在段落中跳位置;`dy` 堆叠的多行 `<tspan>` 会塌成一行,`x` 锚定的 tspan 会跑到错误的列 |
### 各模块消费者一览
| 模块 | 写盘消费者 | 内存消费者 | 删除影响 |
| --- | --- | --- | --- |
-| `embed_icons.py` | `finalize_svg` 的 `embed-icons` 步骤 | `svg_to_pptx/use_expander.py` | native pptx 丢失全部图标 + `svg_final/` 不再自包含 |
+| `embed_icons.py` | `finalize_svg` 的 `embed-icons` 步骤(随后展开本地 use) | `svg_to_pptx/use_expander.py` | native pptx 丢失全部图标 + `svg_final/` 不再自包含 |
+| `svg_to_pptx/use_expander.py`(本地引用) | `finalize_svg` 的 `embed-icons` 步骤 | native 转换器预检 | finalize/native 导出失去实体化合规本地复用的能力 |
| `flatten_tspan.py` | `finalize_svg` 的 `flatten-text` 步骤 | `svg_to_pptx/tspan_flattener.py` | **native pptx 中 `dy` 堆叠的多行文本塌成一行** |
| `align_embed_images.py` | `finalize_svg` 的 `align-images` 步骤 | — | `svg_final/` 失去图片嵌入 → IDE 预览 / preview pptx 都没图 |
| `crop_images.py` / `embed_images.py` / `fix_image_aspect.py` | 被 `align_embed_images.py` import | — | `align_embed_images` `ImportError`,整条链路 broken |
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 91eeb978..90843b18 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -4,7 +4,7 @@ Common technical constraints for PPT Master, eliminating cross-role file duplica
---
-## 1. SVG Banned Features Blacklist
+## 1. SVG Banned Features and Conditional Allowances
The following are **forbidden** in generated SVGs — PPT export breaks otherwise:
@@ -25,10 +25,9 @@ One offending character invalidates the file and aborts export. Numeric refs (`&
|----------------|-------------|
| `mask` | Masks |
| `<style>` | Embedded stylesheets |
-| `class` | CSS selector attributes (`id` inside `<defs>` is a legitimate reference and is NOT banned) |
+| `class` | CSS selector attributes (`id` remains allowed for local references and semantic markers when no `<style>` selector is used) |
| External CSS | External stylesheet links |
| `<foreignObject>` | Embedded external content |
-| `<symbol>` + `<use>` | Symbol reference reuse |
| `textPath` | Text along a path |
| `@font-face` | Custom font declarations |
| `<animate*>` / `<set>` | SVG animations |
@@ -39,6 +38,10 @@ One offending character invalidates the file and aborts export. Numeric refs (`&
>
> **`clipPath` on `<image>` is conditionally allowed** — see §1.2 for constraints. The converter maps qualifying clip shapes to native DrawingML picture geometry (`<a:prstGeom>` or `<a:custGeom>`).
>
+> **Static same-document `<use>` is conditionally allowed** — see §1.3. The
+> pipeline materializes qualifying references before SVG snapshot/native PPTX
+> conversion; PowerPoint does not retain the reference structure.
+>
> **`<pattern>` fills are conditionally allowed** — see §7 *Pattern Fill* for the required `data-pptx-pattern` annotation and the closed OOXML preset enum. Hand-drawn pattern geometry is NOT honored; the converter emits the named PPTX preset only. Missing or invalid preset values produce diagonal stripes (warning) or schema-failed PPTX (error).
>
> **Replacing `<mask>` effects** — DrawingML has no per-pixel alpha. Route by effect:
@@ -147,6 +150,55 @@ One offending character invalidates the file and aborts export. Numeric refs (`&
---
+### 1.3 Static Same-Document `<use>` (Conditionally Allowed)
+
+**Expansion contract**: Static local reuse is compile-time authoring shorthand. `finalize_svg.py` and
+native export replace each qualifying instance with cloned primitive content;
+PPTX-to-SVG import emits the resulting primitives and does **not** reconstruct
+the original `<use>` / `<symbol>` structure.
+
+| Concern | Required form |
+|---|---|
+| Reference syntax | Exact same-document fragment: `href="#id"` or `xlink:href="#id"`. If both attributes exist, their values MUST match. |
+| Referenced target | One of `<symbol>`, `<g>`, `<use>`, `<rect>`, `<circle>`, `<ellipse>`, `<line>`, `<path>`, `<polygon>`, `<polyline>`, `<text>`, or `<image>`. Nested local `<use>` is recursively expanded. |
+| Instance position | `<use x>` / `<use y>` are finite unitless or `px` values; omitted values default to `0`. |
+| Symbol viewport | A referenced `<symbol>` MUST have a finite four-number `viewBox` with positive width/height. Its `<use>` MUST have positive finite unitless or `px` `width` and `height`. |
+| Aspect ratio | Default/aligned `meet` values and plain `preserveAspectRatio="none"` are supported. `slice`, `refX`, and `refY` are forbidden. |
+| Viewport boundary | Symbol artwork MUST stay inside its `viewBox`; expansion does not reproduce symbol overflow clipping. |
+| Internal references | Reusable subtrees use exact fragment forms: `href="#id"`, `xlink:href="#id"`, and `url(#id)`. The expander rewrites these references together with instance-local cloned IDs. |
+| Structural metadata | Neither the `<use>` instance nor its referenced subtree may carry `data-pptx-layer*`, `data-pptx-native*`, or `data-pptx-placeholder*`. Author those objects directly instead of reusing them. |
+| Safety limits | A reachable reference chain may contain at most 64 instances, and one SVG may expand at most 10,000 local `<use>` instances. |
+
+**Forbidden — unsafe local references**:
+
+- External/file/data URLs, missing targets, conflicting `href` / `xlink:href`,
+ unsupported target elements, and circular reference chains
+- Duplicate IDs on the referenced target, the `<use>` instance, or anywhere in
+ the reused subtree
+- Quoted/whitespace CSS fragment variants such as `url('#id')`; use exact
+ `url(#id)` when an internal paint/filter/clip reference must be rewritten
+
+**Supported example**:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+ <defs>
+ <symbol id="statusDot" viewBox="0 0 20 20" preserveAspectRatio="xMidYMid meet">
+ <circle cx="10" cy="10" r="8" fill="#16A34A"/>
+ </symbol>
+ <g id="legendRow">
+ <rect width="120" height="32" rx="8" fill="#F1F5F9"/>
+ <text x="42" y="22" font-size="16" fill="#0F172A">Ready</text>
+ </g>
+ </defs>
+ <use href="#statusDot" x="80" y="120" width="32" height="32"/>
+ <use xlink:href="#legendRow" x="120" y="120"/>
+</svg>
+```
+
+---
+
## 2. PPT Compatibility Mappings
**Allowed — CSS paint colors**: fills, strokes, gradient stops, and supported
@@ -217,6 +269,7 @@ metadata. See
3/4/6/8-digit HEX; embedded and explicit opacity values multiply
- **Images**: `<image href="../images/xxx.png" preserveAspectRatio="xMidYMid slice"/>`; optional `opacity="0..1"` maps to native picture transparency
- **Icons**: `<use data-icon="<library>/<name>" x="" y="" width="48" height="48" fill="#HEX"/>` (auto-embedded post-processing). Always include library prefix. One stylistic library per deck (`chunk-filled`/`tabler-filled`/`tabler-outline`/`phosphor-duotone`); `simple-icons` only for real brand marks. See [`../templates/icons/README.md`](../templates/icons/README.md).
+- **Static local reuse**: `<use href="#id" .../>` / `<use xlink:href="#id" .../>` is allowed only under §1.3. This is separate from `data-icon` placeholders and is expanded before export.
### Inline Text Runs (Single Logical Line = Single `<text>`)
diff --git a/skills/ppt-master/scripts/config.py b/skills/ppt-master/scripts/config.py
index 622f7bca..733f0399 100644
--- a/skills/ppt-master/scripts/config.py
+++ b/skills/ppt-master/scripts/config.py
@@ -522,7 +522,6 @@ SVG_CONSTRAINTS = {
# <a:headEnd>/<a:tailEnd>.
'forbidden_attributes': [
'class',
- 'id',
'onclick', 'onload', 'onmouseover', 'onmouseout',
'onfocus', 'onblur', 'onchange',
],
@@ -533,7 +532,6 @@ SVG_CONSTRAINTS = {
r'<link[^>]*rel\s*=\s*["\']stylesheet["\']',
r'@import\s+', # External CSS
r'\bon\w+\s*=', # Event attributes
- r'(?s)(?=.*<symbol)(?=.*<use\b)', # <symbol> + <use> complex usage (order-independent)
],
'recommended_fonts': [
'system-ui',
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 038108e0..fd5d2acb 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -20,6 +20,7 @@ Unified post-processing entry point. This is the preferred way to run SVG cleanu
It aggregates:
- `embed_icons.py`
+- static same-document `<use>` expansion from `svg_to_pptx/use_expander.py`
- `align_embed_images.py` (`crop-images` / `fix-aspect` / `embed-images` aliases route here)
- `flatten_tspan.py`
- `svg_rect_to_path.py`
@@ -236,6 +237,21 @@ SVG fallback rather than `--native-objects`.
`<image opacity="0..1">` is supported directly. Native export writes
DrawingML `a:alphaModFix`, and PPTX import restores the SVG opacity value.
+Static same-document `<use>` is supported as compile-time reuse. Use exact
+`href="#id"` or `xlink:href="#id"` references to `symbol`, `g`, `use`, `rect`,
+`circle`, `ellipse`, `line`, `path`, `polygon`, `polyline`, `text`, or `image`;
+internal subtree references use exact `url(#id)` syntax. `x` / `y` accept only
+finite unitless or `px` values. A symbol needs a valid four-number `viewBox`
+with positive width/height and a positive unitless/`px` instance `width` /
+`height`; aligned `meet` and plain `none` are supported, while `slice`, `refX`,
+and `refY` are rejected. Symbol artwork must stay inside the `viewBox` because
+overflow clipping is not reproduced. External, missing, conflicting, circular,
+and duplicate-ID references fail, as does reuse of `data-pptx-layer*`,
+`data-pptx-native*`, or `data-pptx-placeholder*` metadata. Finalize and native
+export recursively materialize the subtree with rewritten instance-local IDs.
+Reference depth is capped at 64 and expansion at 10,000 instances per SVG;
+PPTX import does not reconstruct `<use>` / `<symbol>`.
+
PowerPoint also has trouble with unsupported filters and direct SVG features
not mapped to DrawingML. Connector arrows may use qualified
`marker-start` / `marker-end`; chunky or exotic arrows should be standalone
diff --git a/skills/ppt-master/scripts/error_helper.py b/skills/ppt-master/scripts/error_helper.py
index 1d7ccc7b..6446e2f6 100644
--- a/skills/ppt-master/scripts/error_helper.py
+++ b/skills/ppt-master/scripts/error_helper.py
@@ -162,11 +162,11 @@ class ErrorHelper:
'severity': 'error'
},
'id_attribute_detected': {
- 'message': 'Forbidden id attribute detected',
+ 'message': 'Forbidden CSS selector usage with id detected',
'solutions': [
- 'Remove all id attributes',
- 'Use inline styles instead',
- 'Avoid relying on selectors for positioning or style reuse'
+ 'Keep IDs for local references or documented semantic/animation groups',
+ 'Remove <style> rules and CSS selectors',
+ 'Use inline presentation attributes instead'
],
'severity': 'error'
},
@@ -180,15 +180,6 @@ class ErrorHelper:
],
'severity': 'error'
},
- 'symbol_use_detected': {
- 'message': 'Forbidden <symbol> + <use> complex usage detected',
- 'solutions': [
- 'Expand <symbol> into actual SVG code',
- 'Avoid <symbol> + <use> reuse structures',
- 'Embed SVG paths directly when icons are needed'
- ],
- 'severity': 'error'
- },
# Note: <marker> and marker-end are NO LONGER forbidden — they are
# conditionally allowed (see references/shared-standards.md §1.1).
# The converter maps qualifying markers to native DrawingML arrow heads.
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index ea71b0b2..4d6aa61c 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -89,6 +89,13 @@ except ImportError:
})
_validate_semantic_markers = None
+try:
+ from svg_to_pptx.use_expander import (
+ validate_local_use_references as _validate_local_use_references,
+ )
+except ImportError:
+ _validate_local_use_references = None
+
try:
from svg_to_pptx.pptx_package.template_structure import (
TemplateStructureError as _TemplateStructureError,
@@ -604,10 +611,19 @@ class SVGQualityChecker:
if 'foreignobject' in local_names:
result['errors'].append(
"Detected forbidden <foreignObject> element (use <tspan> for manual line breaks)")
- has_symbol = 'symbol' in local_names
- has_use = 'use' in local_names
- if has_symbol and has_use:
- result['errors'].append("Detected forbidden <symbol> + <use> complex usage (use basic shapes or simple <use> instead)")
+ has_generic_use = any(
+ _local_name(elem).lower() == 'use' and elem.get('data-icon') is None
+ for elem in elems
+ )
+ if has_generic_use:
+ if _validate_local_use_references is None:
+ result['warnings'].append(
+ "Detected local <use> references, but the shared validator "
+ "could not be imported; native export will still validate them."
+ )
+ else:
+ for error in _validate_local_use_references(root):
+ result['errors'].append(f"Invalid local <use> reference: {error}")
# marker-start / marker-end are conditionally allowed (see shared-standards.md §1.1).
# The converter maps qualifying <marker> defs to native DrawingML <a:headEnd>/<a:tailEnd>.
# We only warn when a marker is used without an obvious <defs> definition in the same file.
diff --git a/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md b/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md
index a4baa3e7..19bd4c86 100644
--- a/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md
+++ b/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md
@@ -286,10 +286,9 @@ font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Micr
|---------|---------|
| HTML 命名实体(`&nbsp;` `&mdash;` `&copy;` `&ndash;` `&reg;` `&hellip;` `&bull;` …) | 直接写原生 Unicode 字符(`—` `–` `©` `®` `→` NBSP …) |
| 文本/属性值中裸写 `& < > " '` | 必须写成 XML 实体 `&amp;` `&lt;` `&gt;` `&quot;` `&apos;` |
-| `<style>` / `class` | 内联属性(`id` 在 `<defs>` 内合法) |
+| `<style>` / `class` | 内联属性(`id` 可用于本地引用和语义标记) |
| `<foreignObject>` | `<text>` + `<tspan>` |
| `mask` | 叠加遮罩矩形 / gradient overlay |
-| `<symbol>` + `<use>` | 直接写出完整元素 |
| `textPath` | 手动排列 `<text>` |
| `@font-face` | 系统字体栈 |
| `<animate*>` / `<set>` | 无(PPT 侧处理动画) |
@@ -308,13 +307,19 @@ HEX。颜色内嵌 alpha 会与 `opacity`、`fill-opacity`、`stroke-opacity`、
|------|------|----------|
| `<g opacity="...">` | 数值范围 `0..1`;不包裹 `data-pptx-native` 图表/表格 | 后代对象分别写入 DrawingML alpha;重叠区域为近似 |
| `<image opacity="...">` | 数值范围 `0..1` | DrawingML `<a:alphaModFix>` |
+| 本文档内静态 `<use href="#id">` / `xlink:href="#id"` | 目标为 `symbol/g/use/rect/circle/ellipse/line/path/polygon/polyline/text/image`;`x/y` 仅 unitless/`px`;`symbol` 还需合法 `viewBox` 与正数 unitless/`px` `width/height` | 导出前递归展开为带独立 ID 的完整元素 |
| `marker-start` / `marker-end` | `<marker>` 在 `<defs>` 中,`orient="auto"`,形状为三角/菱形/圆 | DrawingML `<a:headEnd>` / `<a:tailEnd>` |
| `clipPath` on `<image>` | `<clipPath>` 在 `<defs>` 中,单子元素,**仅用于 image** | DrawingML `<a:prstGeom>` / `<a:custGeom>` |
| `stroke-dasharray` | 使用预设值 `4,4` / `2,2` / `8,4` / `8,4,2,4` | PPTX `<a:prstDash>` |
| `text-decoration` | `underline` / `line-through` | PPTX 原生文本格式 |
| `transform="rotate(...)"` | 所有元素类型均支持 | PPTX `<a:xfrm rot="...">` |
-> 完整条件约束见 [`shared-standards.md`](../../references/shared-standards.md) SS1.1(marker 约束)和 SS1.2(clipPath 约束)。
+> 本地 `<use>` 只接受精确 `#id` / `url(#id)` 内部片段。外部、缺失、
+> 冲突、循环、重复 ID,`symbol` 的 `slice` / `refX` / `refY`,以及对
+> `data-pptx-layer*` / `data-pptx-native*` / `data-pptx-placeholder*` 结构元数据的
+> 复用均禁止;PPTX 回导不重建 `<use>`。完整条件约束见
+> [`shared-standards.md`](../../references/shared-standards.md) SS1.1(marker)、
+> SS1.2(clipPath)和 SS1.3(本地 use)。
### 6.4 虚线预设对照
diff --git a/skills/ppt-master/templates/charts/harvey_balls_table.svg b/skills/ppt-master/templates/charts/harvey_balls_table.svg
index 5fd076a2..887ec50c 100644
--- a/skills/ppt-master/templates/charts/harvey_balls_table.svg
+++ b/skills/ppt-master/templates/charts/harvey_balls_table.svg
@@ -4,7 +4,8 @@
Purpose: Qualitative assessment, scoring, and vendor comparison
Use cases: Vendor evaluations, project status, skill matrices
Design Principles: Left-aligned features, centered Harvey balls, clean minimalist consulting grid
- Note: Harvey ball shapes are inlined (no <use>/<defs>) so the SVG-to-PPTX converter renders them.
+ Note: Harvey ball shapes stay inlined for direct per-cell editing.
+ Static same-document <use> is supported, but PPTX import does not reconstruct reuse structure.
-->
<rect width="1280" height="720" fill="#FFFFFF"/>
<!-- ==================== Header ==================== -->
diff --git a/skills/ppt-master/templates/layouts/ai_ops/design_spec.md b/skills/ppt-master/templates/layouts/ai_ops/design_spec.md
index 4125de34..5c73d993 100644
--- a/skills/ppt-master/templates/layouts/ai_ops/design_spec.md
+++ b/skills/ppt-master/templates/layouts/ai_ops/design_spec.md
@@ -264,12 +264,13 @@ This template emulates the visual language of telecom technical reports. The cor
2. Use `<rect>` elements for backgrounds
3. Use `<tspan>` for text wrapping (**`<foreignObject>` is strictly prohibited**)
4. CSS alpha colors and explicit `fill-opacity` / `stroke-opacity` are both supported; values multiply
-5. Prohibited: `mask`, `<style>`, `class`, `foreignObject` (`id` inside `<defs>` is allowed). `clipPath` is allowed only on `<image>` under `shared-standards.md` §1.2
+5. Prohibited: `mask`, `<style>`, `class`, `foreignObject` (`id` is allowed for local references and semantic markers). `clipPath` is allowed only on `<image>` under `shared-standards.md` §1.2
6. Prohibited: `textPath`, `animate*`, `script`
-7. Prohibited: `<symbol>+<use>`, `<iframe>`, `@font-face`
-8. `<g opacity="0..1">` is allowed as per-descendant alpha; overlapping children may composite differently
-9. `marker-start` / `marker-end` conditionally allowed (marker in `<defs>`, `orient="auto"`, shape = triangle/diamond/oval) — see shared-standards.md §1.1
-10. Use only system fonts and inline styles
+7. Static same-document `<use>` / `<symbol>` reuse is allowed only under `shared-standards.md` §1.3: exact `href="#id"` / `xlink:href="#id"` and `url(#id)` fragments; targets limited to `symbol/g/use/rect/circle/ellipse/line/path/polygon/polyline/text/image`; unitless/`px` `x/y`; valid symbol `viewBox` plus positive unitless/`px` use `width/height`; aligned `meet` or plain `none`. External/missing/conflicting/circular/duplicate-ID references, `slice` / `refX` / `refY`, and reused `data-pptx-layer*` / `data-pptx-native*` / `data-pptx-placeholder*` metadata are prohibited. PPTX import does not reconstruct `<use>`
+8. Prohibited: `<iframe>`, `@font-face`
+9. `<g opacity="0..1">` is allowed as per-descendant alpha; overlapping children may composite differently
+10. `marker-start` / `marker-end` conditionally allowed (marker in `<defs>`, `orient="auto"`, shape = triangle/diamond/oval) — see shared-standards.md §1.1
+11. Use only system fonts and inline styles
### PPT Compatibility Rules
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index 38b28e5f..91a9ab35 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -191,5 +191,16 @@
## forbidden
- Mixing icon libraries
-- `<style>`, `class`, `<foreignObject>`, `textPath`, `@font-face`, `<animate*>`, `<script>`, `<iframe>`, `<symbol>`+`<use>`
+- `<style>`, `class`, `<foreignObject>`, `textPath`, `@font-face`, `<animate*>`, `<script>`, `<iframe>`
- HTML named entities in text (`&nbsp;`, `&mdash;`, `&copy;`, `&ndash;`, `&reg;`, `&hellip;`, `&bull;` …) — write as raw Unicode (`—`, `©`, `→`, NBSP, etc.); XML reserved chars `& < > " '` must be escaped as `&amp; &lt; &gt; &quot; &apos;`. See shared-standards.md §1.0
+
+> Static same-document `<use>` / `<symbol>` is allowed only under
+> `shared-standards.md` §1.3: exact `href="#id"` / `xlink:href="#id"` and
+> `url(#id)` fragments; targets limited to
+> `symbol/g/use/rect/circle/ellipse/line/path/polygon/polyline/text/image`;
+> unitless/`px` `x/y`; valid symbol `viewBox` plus positive unitless/`px`
+> `width/height`; aligned `meet` or plain `none`. External, missing,
+> conflicting, circular, or duplicate-ID references; `slice` / `refX` / `refY`;
+> and reused `data-pptx-layer*` / `data-pptx-native*` /
+> `data-pptx-placeholder*` metadata remain forbidden. PPTX import does not
+> reconstruct `<use>`.