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(shared-standards): tighten prose, keep all rules and concrete values

hugohe39c369431f249
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 7ff70691..710d0527 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -6,18 +6,18 @@ Common technical constraints for PPT Master, eliminating cross-role file duplica
## 1. SVG Banned Features Blacklist
-The following features are **absolutely forbidden** when generating SVGs — PPT export will break if any are used:
+The following are **forbidden** in generated SVGs — PPT export breaks otherwise:
### 1.0 Text characters: must be well-formed XML
-SVG is strict XML. Two rules apply to all text and attribute values:
+SVG is strict XML. Two rules for all text and attribute values:
| Character category | Required form | Forbidden form |
|---|---|---|
| Typography & symbols (em dash, en dash, ©, ®, →, ·, NBSP, full-width punctuation, emoji…) | **Raw Unicode characters** — write `—` `–` `©` `®` `→` directly | HTML named entities — `—` `–` `©` `®` `→` `·` ` ` `…` `•` etc. |
| XML reserved characters (`&`, `<`, `>`, `"`, `'`) | **XML entities only** — `&amp;` `&lt;` `&gt;` `&quot;` `&apos;` (e.g. `R&amp;D`, `error &lt; 5%`) | Bare `&` `<` `>` (e.g. `R&D`, `error < 5%`) |
-A single offending character invalidates the whole file and aborts the deck export. Numeric character references (`&#160;` / `&#xa0;`) are XML-legal but discouraged.
+One offending character invalidates the file and aborts export. Numeric refs (`&#160;` / `&#xa0;`) are XML-legal but discouraged.
**Structural blacklist** (in addition to the character rules above):
@@ -39,7 +39,13 @@ A single offending character invalidates the whole file and aborts the deck expo
>
> **`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>`).
>
-> **Replacing `<mask>` effects** — DrawingML has no continuous per-pixel alpha channel, so `<mask>` cannot be mapped. Route by effect type: image gradient overlays (vignette, fade, tint) → stacked `<rect>` with `<linearGradient>` / `<radialGradient>` (see §6 Image Overlay); non-rectangular image crop (circle, rounded, hexagon) → `clipPath` on `<image>` (see §1.2); inner glow / soft-edge → `<filter>` with `<feGaussianBlur>` (see §6 Glow Effect); drop shadow → filter shadow or layered rect (see §6 Shadow). Effects requiring true pixel-level alpha — text-knockout image fills, arbitrary alpha composites — have no PPT-side path and MUST be baked into the source image at the Image_Generator stage.
+> **Replacing `<mask>` effects** — DrawingML has no per-pixel alpha. Route by effect:
+> - Image gradient overlay (vignette/fade/tint) → stacked `<rect>` with `<linearGradient>`/`<radialGradient>` (§6 Image Overlay)
+> - Non-rectangular image crop (circle/rounded/hexagon) → `clipPath` on `<image>` (§1.2)
+> - Inner glow / soft-edge → `<filter>` with `<feGaussianBlur>` (§6 Glow)
+> - Drop shadow → filter shadow or layered rect (§6 Shadow)
+>
+> Pixel-level alpha effects (text-knockout image fills, arbitrary alpha composites) have no PPT path — bake into the source image at Image_Generator stage.
---
@@ -57,9 +63,8 @@ A single offending character invalidates the whole file and aborts the deck expo
**Use boundary**:
-- Use `marker-start` / `marker-end` only for connector arrows where the line is primary.
-- Do **not** use `marker` for block / chunky / wide solid arrows where the arrow body is the main visual object.
-- For those solid arrows, draw a standalone closed `<path>` / `<polygon>` and reference `templates/charts/chevron_process.svg` or `templates/charts/process_flow.svg`.
+- `marker-start` / `marker-end`: only for connector arrows where the line is primary
+- For block / chunky / solid arrows (arrow body is the visual object), use standalone closed `<path>` / `<polygon>`; see `templates/charts/chevron_process.svg` or `templates/charts/process_flow.svg`
**Supported DrawingML mapping**:
@@ -83,7 +88,7 @@ A single offending character invalidates the whole file and aborts the deck expo
marker-end="url(#arrowHead)"/>
```
-> ⚠️ Unclassifiable marker shapes (curved paths, multi-segment, >4 vertices, etc.) are **silently dropped** by the converter with a warning — the line will still render, but without an arrow. Fall back to manual `<polygon>` triangles when you need exotic arrow shapes.
+> ⚠️ Unclassifiable marker shapes (curved paths, multi-segment, >4 vertices) are silently dropped — line renders without arrow. Use a manual `<polygon>` for exotic shapes.
---
@@ -100,9 +105,9 @@ A single offending character invalidates the whole file and aborts the deck expo
**Use boundary**:
-- Use `clip-path` **only** for cropping `<image>` elements into non-rectangular shapes (circular avatars, rounded photo frames, hexagonal portraits, etc.).
-- Do **not** use `clip-path` on shapes (`<rect>`, `<circle>`, `<path>`, `<g>`, `<text>`, etc.) — draw the target shape directly instead. A rect clipped to a circle is just a circle; draw the `<circle>`.
-- PowerPoint's SVG renderer **does not render `clipPath` correctly** (images become invisible, shapes lose clipping). The Native PPTX converter handles it, but the SVG reference version will display incorrectly.
+- Only on `<image>` for non-rectangular crops (circular avatars, rounded frames, hexagons)
+- NOT on shapes (`<rect>`/`<circle>`/`<path>`/`<g>`/`<text>`) — draw the target shape directly. A rect clipped to a circle is just a circle.
+- PowerPoint's SVG renderer doesn't handle `clipPath`; only the Native PPTX converter does.
**Supported DrawingML mapping**:
@@ -136,7 +141,7 @@ A single offending character invalidates the whole file and aborts the deck expo
clip-path="url(#cardClip)" preserveAspectRatio="xMidYMid slice"/>
```
-> ⚠️ `clip-path` on non-image elements is **FORBIDDEN** — the quality checker will report it as an error. For shapes, draw the target geometry directly; for groups, restructure the layout.
+> ⚠️ `clip-path` on non-image elements is FORBIDDEN — quality checker errors out. Draw target geometry directly.
---
@@ -150,7 +155,7 @@ A single offending character invalidates the whole file and aborts the deck expo
**Mnemonic**: PPT does not recognize rgba, group opacity, or image opacity.
-> Arrows: prefer `marker-end` with a qualifying `<marker>` (see §1.1) for connector lines — the converter produces native DrawingML arrow heads that auto-rotate. For block arrows / chunky arrows, use a standalone closed shape instead of `marker`; see `templates/charts/chevron_process.svg` for phase arrows and `templates/charts/process_flow.svg` for mixed flow layouts.
+> Arrows: prefer `marker-end` for connector lines (§1.1) — converter produces native auto-rotating arrow heads. For block/chunky arrows, use standalone closed shapes; see `templates/charts/chevron_process.svg` and `templates/charts/process_flow.svg`.
---
@@ -164,16 +169,16 @@ A single offending character invalidates the whole file and aborts the deck expo
- **viewBox** must match the canvas dimensions (`width`/`height` must match `viewBox`)
- **Background**: Use `<rect>` to define the page background color
-- **`<tspan>` has two purposes**: (1) manual line breaks within a `<text>` (use `dy` / explicit `y`); (2) inline run formatting on the **same** line — local color, weight, size — without splitting the line into separate text frames. `<foreignObject>` is FORBIDDEN. See "Single logical line = single `<text>`" rule below.
-- **Fonts**: Every `font-family` stack MUST end with a cross-platform pre-installed family (Microsoft YaHei / SimSun / Arial / Times New Roman / Consolas / etc.); `@font-face` is FORBIDDEN. See [`strategist.md §g — PPT-safe font discipline`](strategist.md) for the full HARD rule and seed combinations.
-- **Styles**: Use inline styles only (`fill="..."` `font-size="..."`); `<style>` / `class` are FORBIDDEN (`id` inside `<defs>` is legitimate)
-- **Colors**: Use HEX values; for transparency use `fill-opacity` / `stroke-opacity`
-- **Image references**: `<image href="../images/xxx.png" preserveAspectRatio="xMidYMid slice"/>`
-- **Icon placeholders**: `<use data-icon="<library>/<name>" x="" y="" width="48" height="48" fill="#HEX"/>` (auto-embedded during post-processing). Always include the library prefix. Generic icons must use exactly one stylistic library per presentation (`chunk-filled` / `tabler-filled` / `tabler-outline` / `phosphor-duotone`); `simple-icons` may co-exist only for real company / product / service brand marks. See [`../templates/icons/README.md`](../templates/icons/README.md).
+- **`<tspan>`** has two purposes: (1) manual line breaks (use `dy` or explicit `y`); (2) inline run formatting on the same line (color/weight/size). `<foreignObject>` is FORBIDDEN. See "Single logical line" rule below.
+- **Fonts**: every `font-family` stack MUST end with a pre-installed family (Microsoft YaHei / SimSun / Arial / Times New Roman / Consolas …); `@font-face` is FORBIDDEN. Full rule: [`strategist.md §g`](strategist.md).
+- **Styles**: inline only (`fill=""`, `font-size=""`); `<style>`/`class` FORBIDDEN (`id` inside `<defs>` is fine)
+- **Colors**: HEX only; transparency via `fill-opacity`/`stroke-opacity`
+- **Images**: `<image href="../images/xxx.png" preserveAspectRatio="xMidYMid slice"/>`
+- **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).
### Inline Text Runs (Single Logical Line = Single `<text>`)
-A logical single line of text — **even with mixed colors, weights, or sizes** — MUST be one `<text>` element containing inline `<tspan>` children, **never** multiple adjacent `<text>` elements positioned side by side. The `svg_to_pptx` converter maps each inline `<tspan>` to a run (`<a:r>`) within the same PowerPoint text frame, preserving the formatting variation while keeping the line as **one editable shape** in PPT.
+One logical line — even with mixed colors/weights/sizes — MUST be one `<text>` with inline `<tspan>` children. Never use multiple adjacent `<text>` elements. The converter maps each `<tspan>` to a `<a:r>` run within the same PPT text frame, keeping the line as one editable shape.
✅ **DO** — one `<text>` → one text frame with three runs:
@@ -191,9 +196,9 @@ A logical single line of text — **even with mixed colors, weights, or sizes**
<text x="240" y="200" font-size="24" fill="#333333">效率提升</text>
```
-**⚠️ Inline tspans must NOT carry `x` / `y` / `dy`.** Any of those marks the tspan as a new line, and the post-processing `flatten_tspan` step will split it into a separate text frame — defeating the purpose. `dx` is safe (used for kerning/spacing nudges and stays inline). Only set `x` / `y` / `dy` on tspans that genuinely start a new line.
+**⚠️ Inline tspans must NOT carry `x`/`y`/`dy`** — those mark a new line, and `flatten_tspan` will split into a separate text frame. `dx` is safe (kerning, stays inline). Only set `x`/`y`/`dy` on tspans that genuinely start a new line.
-**Multi-line `<text>` with per-line inline emphasis is supported.** An outer line-break tspan (carrying `x` + `dy` or `y`) MAY contain nested inline tspans for color/weight/size — `flatten_tspan` and the converter both walk nested tspans and emit one run per styled segment:
+**Multi-line `<text>` with per-line emphasis works**: an outer line-break tspan (with `x` + `dy` or `y`) MAY contain nested inline tspans for color/weight/size — converter walks nested tspans and emits one run per styled segment:
```xml
<text x="80" y="190" font-size="18" fill="#333333">
@@ -210,17 +215,17 @@ A logical single line of text — **even with mixed colors, weights, or sizes**
</text>
```
-Any `x` on a tspan starts a new line in `flatten_tspan`'s eyes, so the two columns become two independent `<text>` frames in PPT — fragile to edit as one row. For two-column layouts, write two `<text>` elements (or a real two-column structure) instead.
+`x` on a tspan starts a new line, splitting into two independent text frames. For two-column layouts, write two `<text>` elements.
-**Default behavior — lift key information out of running text.** Body paragraphs and conclusions rendered as uniform-styled text waste the inline-run capability and read as walls of text. By default, wrap the following in `<tspan fill="..." font-weight="bold">`:
+**Default — lift key information.** Uniform-styled paragraphs read as walls of text. Wrap these in `<tspan fill="..." font-weight="bold">`:
- **Numerical results** — percentages, multipliers (`10x`), absolute amounts (`¥120万`)
- **Contrasts** — gain/loss, before/after, target/actual
- **One or two load-bearing nouns per sentence** — the term that carries the insight
-Do **NOT** highlight: connectives, common verbs, every noun, decorative adjectives, or structural text (footer / axis label / legend / page number / simple field labels).
+Do NOT highlight: connectives, common verbs, every noun, decorative adjectives, structural text (footer/axis/legend/page number/labels).
-Color choice: prefer the deck's primary brand color for emphasis; reserve semantic green/red for text that genuinely encodes positive/negative.
+Color: use the deck's primary brand color for emphasis. Reserve green/red for actual positive/negative semantics.
❌ **DON'T** — uniform-styled paragraph buries the insight:
@@ -240,9 +245,9 @@ Color choice: prefer the deck's primary brand color for emphasis; reserve semant
### Element Grouping (Mandatory)
-Logically related elements **MUST** be wrapped in `<g>` tags. This produces PowerPoint groups in the exported PPTX, making slides easier to select, move, and edit.
+Wrap logically related elements in `<g>`. Produces PowerPoint groups in PPTX, making slides easier to select/move/edit.
-> ⚠️ **Only `<g opacity="...">` is banned** (see §2). Plain `<g>` for structural grouping is required.
+> ⚠️ Only `<g opacity="...">` is banned (§2). Plain `<g>` for grouping is required.
**What to group**:
@@ -269,7 +274,7 @@ Logically related elements **MUST** be wrapped in `<g>` tags. This produces Powe
</g>
```
-**Naming convention**: Use descriptive `id` attributes on `<g>` tags (e.g., `card-1`, `step-discover`, `header`, `footer`). IDs are optional but recommended for readability.
+**Naming**: descriptive `id` on `<g>` (e.g., `card-1`, `step-discover`, `header`, `footer`). Optional but recommended.
---
@@ -294,7 +299,7 @@ python3 scripts/svg_to_pptx.py <project_path> -s final
- NEVER export directly from `svg_output/` — MUST export from `svg_final/` (use `-s final`)
- NEVER add extra flags like `--only`
-**Re-run rule**: Any modification to `svg_output/` after post-processing has completed (including page revisions, additions, or deletions) requires re-running Steps 2 and 3. Step 1 only needs re-running if `notes/total.md` was also modified.
+**Re-run rule**: Any change to `svg_output/` after post-processing requires re-running Steps 2-3. Step 1 only re-runs if `notes/total.md` changed.
---
@@ -304,54 +309,53 @@ python3 scripts/svg_to_pptx.py <project_path> -s final
### Shadow
-> **Shadow is an aesthetic ingredient, not a default treatment.** Restraint, not abundance, produces the "designed" feel. The principles below override any temptation to add shadow "for depth" — read them before reaching for any shadow filter.
+> **Shadow is restraint, not default.** The "designed" feel comes from absence, not abundance.
-#### When to use shadow
+#### When to use
-Add shadow ONLY when the element genuinely floats above another layer:
-- A card / quote bubble / annotation **sitting on a photo or colored panel**
-- The single primary CTA or "recommended" item that needs to be **picked out from peers**
-- An overlay layer (callout, tooltip, modal-style emphasis)
-- A floating image card on a textured background
+Only when the element genuinely floats above another layer:
+- Card / quote bubble / annotation on a photo or colored panel
+- Single primary CTA or "recommended" item picked out from peers
+- Overlay layer (callout, tooltip, modal emphasis)
+- Floating image card on a textured background
-#### When NOT to use shadow
+#### When NOT to use
-Skip shadow entirely on:
-- **Background panels / section dividers / decorative bars** — they are the floor, the floor doesn't lift
-- **Equal peer cards in a 2/3/4-up grid** — if all are lifted, none are; keep all flat
-- **Containers that already have a visible border, gradient fill, or strong background tint** — the "this is a container" job is done; adding shadow is redundant and reads as PPT-template clutter
-- **Body-text paragraph containers** — reading surfaces should sit on the floor, lifting them disrupts scan rhythm
-- **Decorative lines / dividers / icons themselves** — they are symbols, not objects
-- **Pages with only one content container** — there is no second layer to lift above
-- **Dark backgrounds** — black shadows vanish on dark; use a 1px low-opacity white stroke or subtle outer glow instead
+- Background panels / dividers / decorative bars — they are the floor
+- Equal peer cards in a 2/3/4-up grid — keep all flat
+- Containers with visible border, gradient fill, or strong tint — redundant
+- Body-text paragraph containers — disrupts scan rhythm
+- Decorative lines / dividers / icons — they are symbols, not objects
+- Pages with only one content container — no second layer to lift above
+- Dark backgrounds — black shadows vanish; use 1px low-opacity white stroke or outer glow
-**Per-page budget**: at most 2–3 shadowed elements per slide. If you find yourself adding shadow to a 4th element, something else needs to lose its shadow first.
+**Per-page budget**: ≤2-3 shadowed elements. If you reach for a 4th, drop one first.
#### Single light source per page
-All `feOffset` values on a single page must share the same `dx` and `dy` direction. Real shadows obey one sun. Mixing dy=+6 on some cards and dy=-4 on others looks broken even when the viewer can't articulate why. Default: `dx="0"` with `dy="4"` to `dy="8"` (light from upper front).
+All `feOffset` on a page must share the same `dx`/`dy` direction. Default: `dx="0"`, `dy="4"`-`dy="8"` (light from upper front).
#### Restraint over visibility
-The high-end aesthetic standard is **"the shadow is felt, not seen."** If a viewer notices "there's a shadow here," it is already too strong.
-- Default `flood-opacity`: **0.06–0.12** for resting cards
-- Maximum `flood-opacity`: **0.20** for genuinely raised elements (CTA, overlay)
-- Above 0.20 = Office 2007 hard-shadow look — avoid
-- Color: near-black with low opacity, OR a darker tint of the page background. Brand-colored shadow only on accent elements that share that hue family.
+Standard: "the shadow is felt, not seen." If noticed, it's too strong.
+- Resting cards: `flood-opacity` 0.06-0.12
+- Raised elements (CTA, overlay): max `flood-opacity` 0.20
+- Above 0.20 = Office 2007 hard-shadow look
+- Color: near-black at low opacity, or a darker tint of background. Brand-color shadow only on accent elements sharing that hue.
#### Two-tier elevation maximum
-A page may have at most two non-floor elevation levels. More tiers fragment visual hierarchy.
+A page may have at most two non-floor tiers.
| Tier | When | dy | stdDeviation | flood-opacity |
|------|------|----|--------------|---------------|
| Floor (no shadow) | Backgrounds, peer-grid cards, dividers, body-text containers | — | — | — |
-| Resting | Cards on photos/panels, secondary callouts | 2–4 | 4–8 | 0.06–0.10 |
-| Raised | Primary CTA, focused/recommended card, overlay | 6–10 | 10–16 | 0.12–0.20 |
+| Resting | Cards on photos/panels, secondary callouts | 2-4 | 4-8 | 0.06-0.10 |
+| Raised | Primary CTA, focused/recommended card, overlay | 6-10 | 10-16 | 0.12-0.20 |
#### Don't stack visual-weight tools
-A container's "look at me" budget is small. Pick **one** of: shadow, visible border, gradient fill, strong background tint. Stacking shadow + border + rounded + gradient = instant template look.
+Pick **one** per container: shadow, border, gradient fill, or strong tint. Stacking = instant template look.
---
@@ -402,7 +406,7 @@ Best for: accent buttons, brand-colored cards. Use the element's own color famil
</filter>
```
-Replace `flood-color` with the element's brand color; keep `flood-opacity` between 0.12–0.20 (above 0.20 reads as Office 2007 hard-shadow). Reserve colored shadow for the **single primary CTA / accent element per page** — using it on every button defeats the "this one is special" cue.
+Replace `flood-color` with the element's brand color. Keep `flood-opacity` 0.12-0.20. Reserve for the single primary CTA per page — using on every button defeats the cue.
#### Glow Effect
@@ -430,7 +434,7 @@ flood-color: brand color or accent color (NOT black)
flood-opacity: 0.35–0.55 (stronger than shadow for visibility)
```
-**Key difference from shadow**: No `<feOffset>` element (or dx=0/dy=0). The converter uses this to distinguish glow from shadow.
+**vs shadow**: no `<feOffset>` (or dx=0/dy=0). The converter uses this to distinguish glow from shadow.
#### Layered Rect Shadow — High-Compatibility Fallback
@@ -621,7 +625,7 @@ Rotation converts to native PPTX `<a:xfrm rot="...">`. Supported on all element
### Arc Paths — Donut / Pie Charts
-When drawing donut or pie chart sectors with `<path>`, the arc endpoint coordinates must be calculated precisely using trigonometry. **Never estimate or approximate arc endpoints** — even small errors produce wildly incorrect shapes.
+Calculate arc endpoint coordinates precisely with trigonometry. Never estimate — small errors produce wildly wrong shapes.
**Calculation formula** (center `cx,cy`, radius `r`, angle `θ` in degrees):
```
@@ -647,11 +651,11 @@ Large-arc flag: 1 (270° > 180°)
### Polygon Arrows on Diagonal Lines
-> For connector lines, prefer `marker-end` / `marker-start` (see §1.1). For chunky / wide solid / non-connector arrows, use standalone polygon or path geometry instead of `marker`.
+> For connector lines prefer `marker-end`/`marker-start` (§1.1). For chunky/wide solid/non-connector arrows, use standalone polygon or path.
-When using `<polygon>` triangles as arrowheads, arrows on **horizontal or vertical lines** can use simple point offsets. But arrows on **diagonal lines** must have their triangle vertices rotated to match the line direction.
+Horizontal/vertical lines can use simple point offsets for `<polygon>` arrowheads. Diagonal lines need triangle vertices rotated to match line direction.
-**Method**: Calculate the triangle points using the line's direction vector:
+**Method** — calculate triangle points using the line's direction vector:
```
Given line from (x1,y1) to (x2,y2):
@@ -674,7 +678,7 @@ Back2: (370-8.1+3.7, 430-8.8-3.4) = (365.6, 417.8)
<polygon points="370,430 365.6,417.8 358.2,424.6" fill="#C8A96E"/>
```
-⚠️ **Never use a fixed downward/rightward triangle on a diagonal line** — the arrow will point in the wrong direction.
+⚠️ Never use a fixed downward/rightward triangle on a diagonal line — arrow will point wrong.
---