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.mdindex 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** — `&` `<` `>` `"` `'` (e.g. `R&D`, `error < 5%`) | Bare `&` `<` `>` (e.g. `R&D`, `error < 5%`) |-A single offending character invalidates the whole file and aborts the deck export. Numeric character references (` ` / ` `) are XML-legal but discouraged.+One offending character invalidates the file and aborts export. Numeric refs (` ` / ` `) 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 expomarker-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 expoclip-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.---