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): sweep residual clipPath bans in skill core and scripts

hugohe3b368c5c80735
diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.md
index 0ea0819f..80c55f45 100644
--- a/skills/ppt-master/references/svg-image-embedding.md
+++ b/skills/ppt-master/references/svg-image-embedding.md
@@ -155,11 +155,16 @@ project/
└── svg_final/ # Final version (images embedded)
```
-### Rounded Corner Handling (clipPath Forbidden)
+### Rounded Corner / Non-rectangular Image Cropping
-Since `clipPath` is incompatible with PPT, clipping paths for image rounded corners are FORBIDDEN. Alternatives:
-- Process rounded corners during image generation (export PNG with rounded corners)
-- Or overlay a same-size rounded rectangle over the edges (visual simulation)
+`clipPath` **on `<image>` elements** is conditionally allowed — the converter maps qualifying clip shapes to native DrawingML picture geometry (`<a:prstGeom>` / `<a:custGeom>`), so rounded corners, circular avatars, hexagonal portraits, etc. are fully supported end-to-end.
+
+Constraints (see [shared-standards.md §1.2](shared-standards.md) for the authoritative list):
+- The `<clipPath>` must live inside `<defs>` and contain exactly **one** shape child — `circle`, `ellipse`, `rect` with `rx`/`ry`, `path`, or `polygon`.
+- `clip-path` may appear **only** on `<image>` elements. Using it on shapes / groups / text is an error — draw the target geometry directly with the matching native element (`<circle>` / `<ellipse>` / `<rect rx="...">` / `<polygon>` / `<path>`). A rect clipped to a circle is just a `<circle>`.
+- PowerPoint's own SVG renderer does not render `clipPath` correctly. The Native PPTX converter handles it, but the SVG reference version in the `_svg.pptx` backup will display the image uncropped.
+
+Alternative for the rare case where `clipPath` does not fit (e.g. shape needs clipping): bake the rounded corners into the source image (PNG with alpha) before embedding.
---
diff --git a/skills/ppt-master/scripts/config.py b/skills/ppt-master/scripts/config.py
index 3797de32..275de308 100644
--- a/skills/ppt-master/scripts/config.py
+++ b/skills/ppt-master/scripts/config.py
@@ -374,7 +374,11 @@ SVG_CONSTRAINTS = {
# Forbidden elements - PPT incompatible
'forbidden_elements': [
# Clipping / Masking
- 'clipPath',
+ # Note: `clipPath` on <image> elements is conditionally allowed — the
+ # converter maps qualifying clip shapes to DrawingML picture geometry.
+ # See references/shared-standards.md §1.2. It is NOT listed here
+ # because this flat list has no per-parent-element semantics; the
+ # actual validation is in svg_quality_checker._check_forbidden_elements.
'mask',
# Style system
'style',
diff --git a/skills/ppt-master/scripts/error_helper.py b/skills/ppt-master/scripts/error_helper.py
index 424c8dee..49db738e 100644
--- a/skills/ppt-master/scripts/error_helper.py
+++ b/skills/ppt-master/scripts/error_helper.py
@@ -110,12 +110,21 @@ class ErrorHelper:
],
'severity': 'error'
},
- 'clippath_detected': {
- 'message': 'Forbidden <clipPath> element detected',
+ 'clippath_on_non_image': {
+ 'message': 'clip-path is only allowed on <image> elements',
'solutions': [
- 'Remove <clipPath> elements',
- 'PPT does not support SVG clipping paths',
- 'Use basic shape combinations as an alternative to clipping'
+ 'Remove clip-path from shapes / groups / text',
+ 'Draw the target geometry directly with the matching native element: <circle> / <ellipse> / <rect rx="..."> / <polygon> / <path>. A rect clipped to a circle is just a <circle>.',
+ 'clip-path on <image> is conditionally allowed — see references/shared-standards.md §1.2'
+ ],
+ 'severity': 'error'
+ },
+ 'clippath_def_missing': {
+ 'message': 'clip-path references a <clipPath> id that does not exist in <defs>',
+ 'solutions': [
+ 'Define the referenced <clipPath id="..."> inside <defs>',
+ 'The clipPath must contain exactly one shape child (circle / ellipse / rect with rx,ry / path / polygon)',
+ 'Reference: references/shared-standards.md §1.2'
],
'severity': 'error'
},
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 9641da10..de82d2c9 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -289,9 +289,10 @@ Generate corresponding speaker note files for each page, saved to the `notes/` d
2. Background uses `<rect>` elements
3. Text wrapping uses `<tspan>` (`<foreignObject>` FORBIDDEN)
4. Transparency uses `fill-opacity` / `stroke-opacity`; `rgba()` FORBIDDEN
-5. FORBIDDEN: `clipPath`, `mask`, `<style>`, `class`, `foreignObject`
+5. FORBIDDEN: `mask`, `<style>`, `class`, `foreignObject`
6. FORBIDDEN: `textPath`, `animate*`, `script`
7. `marker-start` / `marker-end` conditionally allowed: `<marker>` must be in `<defs>`, `orient="auto"`, shape must be triangle / diamond / circle (see shared-standards.md §1.1)
+8. `clipPath` conditionally allowed **only on `<image>` elements**: `<clipPath>` in `<defs>`, single shape child (circle / ellipse / rect with rx,ry / path / polygon). Do NOT apply to shapes / groups / text — draw the target geometry directly with the matching native element (`<circle>` / `<ellipse>` / `<rect rx>` / `<polygon>` / `<path>`). See shared-standards.md §1.2
### PPT Compatibility Rules:
diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.md
index cb58cd2f..1b0ad98f 100644
--- a/skills/ppt-master/templates/layouts/README.md
+++ b/skills/ppt-master/templates/layouts/README.md
@@ -246,7 +246,7 @@ cp templates/layouts/government_red/* projects/<project>/templates/
| Banned Element | Alternative |
|----------------|-------------|
| `<foreignObject>` | Use `<text>` + `<tspan>` |
-| `clipPath` | Redesign layout |
+| `clipPath` on shapes / groups / text | Draw the target geometry directly with the matching native element (`<circle>` / `<ellipse>` / `<rect rx>` / `<polygon>` / `<path>`). `clipPath` on `<image>` elements is conditionally allowed — see shared-standards.md §1.2 |
| `mask` | Use `fill-opacity` |
| `<style>` / `class` | Use inline styles |
| `textPath` | Use plain `<text>` |