| 1 | # PowerPoint Feature ↔ Project SVG Mapping Guide |
| 2 | |
| 3 | [English](./powerpoint-svg-mapping.md) | [Chinese](./zh/powerpoint-svg-mapping.md) |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Purpose and authority |
| 8 | |
| 9 | This guide answers one question from the PowerPoint user's point of view: **for a PowerPoint feature, what project representation owns it, and what survives export or import?** PowerPoint semantics are therefore the primary index. SVG elements appear only as the implementation of a specific PowerPoint capability. |
| 10 | |
| 11 | This is a public capability and import-behavior map, not a second generated-SVG syntax specification and not a promise to convert arbitrary SVG or arbitrary OOXML. The canonical generated-authoring contract is the authority set selected through [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md); when generated syntax differs, the applicable module wins. PPTX import recovery modes and user-visible degradation belong to §11 here and to the [conversion command reference](../skills/ppt-master/scripts/docs/conversion.md), while the parser implementation remains the exact source of truth. A feature not listed here is not implicitly supported. |
| 12 | |
| 13 | The main route compiles **project-canonical SVG**, not general browser SVG: |
| 14 | |
| 15 | ```text |
| 16 | PowerPoint intent |
| 17 | ↔ project-canonical SVG or an explicit sidecar |
| 18 | ↔ DrawingML / PPTX package semantics |
| 19 | ``` |
| 20 | |
| 21 | Some PowerPoint features have no honest SVG equivalent. They are shown as sidecar/package features, direct-PPTX preservation features, or unsupported features instead of being forced into decorative SVG metadata. |
| 22 | |
| 23 | ## How to read the tables |
| 24 | |
| 25 | Each row owns one PowerPoint capability. The mapping cardinality is not always one object to one object: one SVG text node may produce several PowerPoint runs, a native chart marker group may collapse into one `p:graphicFrame`, and an imported PowerPoint object may be reconstructed as several SVG elements. |
| 26 | |
| 27 | | Term | Meaning | |
| 28 | |---|---| |
| 29 | | `Native-stable` | Export uses the corresponding editable DrawingML property or object within the documented limits. | |
| 30 | | `Native-normalized` | Export remains editable, but the source is normalized into an equivalent DrawingML structure. | |
| 31 | | `Approximate` | PowerPoint has no exact counterpart; review the generated PPTX when the effect is material. | |
| 32 | | `Bake-required` | Pre-render to an image or rebuild with supported explicit geometry. | |
| 33 | | `Sidecar/package` | The capability belongs to a project sidecar or PPTX package writer, not the SVG page design. | |
| 34 | | `Direct preservation` | A direct-PPTX workflow may retain the source OOXML; the main SVG compiler does not recreate it. | |
| 35 | | `Unsupported` | The main generation route has no registered mapping and must not guess. | |
| 36 | |
| 37 | “Import” below means a semantic projection produced by the PPTX-to-SVG route, not recovery of an original SVG or absent design intent. It does not promise the original `<defs>` graph, `<use>` structure, path commands, or `<tspan>` layout. |
| 38 | |
| 39 | ## 1. Presentation, slide, and coordinate model |
| 40 | |
| 41 | | PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary | |
| 42 | |---|---|---|---|---| |
| 43 | | Presentation slide size | Root SVG `viewBox="0 0 W H"`, selected through the project canvas contract | Presentation width and height; `1 SVG px = 9,525 EMU` at 96 DPI | `Native-stable`; imported custom PPTX sizes may use compatible fractional dimensions | Values must be finite with a zero origin and positive supported dimensions; every public page/internal Layout prototype must match the lock; a root transform is forbidden | |
| 44 | | Slide | One complete `svg_output/<slide>.svg` page | One `p:sld` with its relationships | Reconstructed as one complete SVG page | SVG is the visible page authority; notes and package behavior are separate | |
| 45 | | Object position and size | Absolute SVG coordinates and element bounds | `a:xfrm` offsets and extents | `Native-normalized` through coordinate conversion | Values must be finite and use the registered coordinate grammar | |
| 46 | | Z-order | SVG source order, back to front | PowerPoint shape-tree order | Reconstructed in shape-tree order | Do not rely on browser-only stacking behavior | |
| 47 | | Rotation, scale, translation, and mirror | Supported SVG transform forms | DrawingML transform or normalized geometry | `Native-normalized`; matrices may be decomposed | Skew and shear outside the registered transform contract are not accepted | |
| 48 | | Theme colors and fonts | Stable roles anchored in `spec_lock.md`; canonical SVG uses those roles plus contextual page values | Theme-aware tokens where an exact anchor role can be retained; otherwise direct DrawingML values | `Native-stable` for registered roles/direct values | Core roles and structural sizes stay stable; contextual colors and export-safe one-off fonts are allowed, while invalid/unavailable values fail | |
| 49 | | PowerPoint-only package identity | `spec_lock.md` structure declarations and the package builder | Presentation, Master, Layout, relationship, and content-type registrations | Read back from package structure, not inferred from page appearance | Final-package read-back must match the declared roster | |
| 50 | |
| 51 | See [`canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md) for supported canvases and [`shared-standards-core.md` §4.1](../skills/ppt-master/references/shared-standards-core.md#41-semantic-svg-marker-contract) for the normative root-`viewBox` contract. |
| 52 | |
| 53 | ## 2. Master, Layout, background, and placeholder features |
| 54 | |
| 55 | **Route boundary**: Free-design and brand-only projects in the main SVG pipeline remain on `pptx_structure.mode: flat` from planning through export; `flat` is not a provisional state awaiting an exporter upgrade. Repeated logos, footers, or layouts never cause export to switch to `structured`, promote content into a Master/Layout, infer placeholders, or deduplicate objects. Output that requires reusable native Master, Layout, or placeholder behavior must enter Step 3 with a validated deck/layout template workspace; when none exists, run [`create-template`](../skills/ppt-master/workflows/create-template.md) first and return to the main pipeline with that workspace. The minimal Master and Blank Layout emitted by flat export are PPTX package scaffolding, not a design master derived from the slides. Filling new content into a raw PPTX template remains the [`template-fill-pptx`](../skills/ppt-master/workflows/template-fill-pptx.md) route. |
| 56 | |
| 57 | | PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary | |
| 58 | |---|---|---|---|---| |
| 59 | | Free-design deck structure | `pptx_structure.mode: flat`; page content remains slide-local | One clean project Master and one Blank Layout, with represented objects on slides | `Native-stable` package topology for the flat route | No authored Master/Layout/layer/placeholder metadata is allowed | |
| 60 | | Template-backed deck structure | `pptx_structure.mode: structured` plus explicit Master/Layout/page assignments | Declared `p:sldMaster`, `p:sldLayout`, registrations, and slide parentage | `Native-stable` within the explicit structure contract | The exporter never guesses a Master, Layout, or placeholder topology | |
| 61 | | Slide Master | Root Master identity plus atomic `data-pptx-layer="master"` objects; one validated compact authored-preset `<g>` counts as one semantic atom | Reusable Master part and picker identity | Create Template mirror may preserve validated source-package facts in a new workspace; authored modes create a new identity | Master atoms must be direct, stable, and identical across their slides; ordinary or expanded authored groups do not qualify | |
| 62 | | Slide Layout | Root Layout identity plus atomic `data-pptx-layer="layout"` objects; one validated compact authored-preset `<g>` counts as one semantic atom | Reusable Layout part under one Master | Create Template mirror may preserve a validated source Layout in a new workspace; Strategist's adaptive plan may declare a new Layout | Reuse a Layout key only when its fixed atoms and slot contract are identical; ordinary or expanded authored groups do not qualify | |
| 63 | | Imported inherited-shape visibility | Layered analysis records normalized source booleans; a materialized structured mirror writes exact lowercase root `data-pptx-show-inherited-shapes` and `data-pptx-show-master-shapes` | Declared source values written to `p:sld@showMasterSp` and `p:sldLayout@showMasterSp` | `Native-stable`: Slide false hides Layout and Master shapes; Layout false hides only Master shapes | Omission means true; every page using one Layout key must agree on the Layout value. Backgrounds, Slide-local objects, placeholder inheritance, parts, and parent relationships remain intact | |
| 64 | | Strict template Layout | Selected prototype contract | Existing declared Layout topology is preserved | `Native-stable` when the page follows the prototype | Fixed Layout atoms and slot structure may not change | |
| 65 | | Adaptive template Layout | Selected Master plus an explicit current or new Layout declared by Strategist | A declared new Layout identity is created when reusable structure changes | `Native-stable` after Strategist updates the plan/lock mapping and execution resumes | Construction-discovered changes return upstream; never mutate a reused Layout key downstream | |
| 66 | | Slide background fill outside structured mode | First eligible full-canvas `<rect>`, direct or in a simple single-child group, with a registered solid, linear/radial gradient, or preset-pattern fill | Native slide `p:bg` | Fidelity follows the corresponding paint row below | Transform, filter, clip, rounding, visible stroke, or an unmapped fill prevents promotion | |
| 67 | | Master/Layout/slide background fill in structured mode | One direct full-canvas solid `<rect>` in the declared structural layer | Native `p:bg` at Master, Layout, or slide scope | `Native-stable` | Explicit scoped background ownership is intentionally solid-only | |
| 68 | | Gradient or pattern backdrop in structured mode | Ordinary gradient/pattern `<rect>` on its declared Master/Layout layer or as slide-local content | Editable shape on the owning part | Fidelity follows the corresponding paint row below | Structured export disables generic background promotion; do not use `data-pptx-layer="slide"` | |
| 69 | | Picture backdrop | Ordinary project `<image>` on its declared Master/Layout layer or as slide-local content | Editable `p:pic` on the owning part | Fidelity follows the picture rows below | An image element is never promoted to `p:bg` | |
| 70 | | Title placeholder | Structured slot group with one text carrier | Layout and slide `p:ph` of type `title` | `Native-stable` | Carrier count, bounds, type, and effective index must match the Layout contract | |
| 71 | | Subtitle placeholder | Structured slot group with one text carrier | `p:ph` type `subTitle` | `Native-stable` | Same slot rules as title | |
| 72 | | Body placeholder | Structured slot group with one text carrier | `p:ph` type `body` | `Native-stable` | A multiline carrier remains one text frame | |
| 73 | | Imported mirror text-placeholder frame | Positive source `data-pptx-frame="x y width height"` on the slot's `<text>` carrier, separate from the slot's reusable bounds | The Slide carrier keeps that exact `a:xfrm`; text remains editable and source hard breaks remain explicit paragraphs | `Native-stable` within supported imported text | `data-pptx-bounds` still owns the Layout default and may differ; authored standard/fidelity slots do not duplicate bounds into this frame | |
| 74 | | Date, footer, and slide-number placeholders | Structured text slots | `p:ph` types `dt`, `ftr`, and `sldNum`, with matching Layout header/footer flags | `Native-stable` | Placeholder indices must be unique and legal | |
| 75 | | Picture placeholder | Structured slot with one image or supported crop carrier | `p:ph` type `pic` | `Native-stable` within the picture contract | The slot must contain exactly one compatible direct carrier | |
| 76 | | Chart or table placeholder | Structured slot with one matching native-object carrier | `p:ph` type `chart` or `tbl` | `Native-stable` only on native Chart/Table export | Requires valid JSON metadata and `--native-charts-and-tables` | |
| 77 | | Generic object placeholder | One compatible carrier—including one validated compact authored-preset `<g>`—or an explicit composite proxy binding | `p:ph` type `obj` | Native binding; composite visible content remains ordinary shapes | Composite slots must use the registered proxy downgrade; expanded authored groups are not single-object carriers | |
| 78 | | Media placeholder | One image or supported crop carrier | `p:ph` type `media` | Native placeholder binding only | It does not synthesize video or audio from decorative SVG content | |
| 79 | | Empty text placeholder | Empty or whitespace-only marked text carrier | Invisible U+200B run at the legal 1 pt minimum, producing one native text shape | `Native-stable` | Do not add a dummy dash, sub-1 pt text, or background-colored visible glyph | |
| 80 | | Page role such as cover/content/ending | Flat-route root `data-pptx-page-role` compiler hint | Routing/validation hint; not a native PowerPoint page type | No independent OOXML object | Structured pages use explicit Master/Layout identity instead | |
| 81 | | Slide sections and custom shows | No SVG mapping | Not authored by the main generation route | `Direct preservation` where a source-preserving workflow owns them | Do not encode them as visual metadata | |
| 82 | |
| 83 | The exact structured metadata and slot grammar live in the [PPTX Structure Interface](../skills/ppt-master/references/pptx-structure-interface.md#1-pptx-structure-routing). |
| 84 | |
| 85 | Internal identifiers and PowerPoint display names are separate concerns: Master and Layout keys use the restricted project ASCII identifier grammar, while picker names may contain spaces. Every Layout definition also names its parent Master and one explicit prototype source. The PPTX Structure Interface owns the exact row syntax. |
| 86 | |
| 87 | ## 3. PowerPoint shapes and drawing objects |
| 88 | |
| 89 | | PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary | |
| 90 | |---|---|---|---|---| |
| 91 | | Rectangle | `<rect>` | Editable `p:sp` with `a:prstGeom prst="rect"` | `Native-stable`; imports as a primitive when possible | Use registered paint, line, and transform properties only | |
| 92 | | Symmetric rounded rectangle | `<rect>` with equal supported corner radii | `a:prstGeom prst="roundRect"` with adjustment | `Native-stable` | Asymmetric corners follow the freeform row | |
| 93 | | Circle or ellipse | `<circle>` or `<ellipse>` | `a:prstGeom prst="ellipse"` | `Native-stable` | Bounds and radii must be finite and positive where required | |
| 94 | | Straight line | `<line>` | Editable line/freeform shape | `Native-normalized` | Browser-only line effects are rejected | |
| 95 | | Arrowhead line | `<line>` or supported path with registered triangle, stealth, arrow, diamond, or oval start/end markers | Native DrawingML line head/tail ends | `Native-normalized`; marker size is approximate | Marker definitions must follow the conditional marker contract | |
| 96 | | Native connector | Compact project-authored preset group with connector metadata and direct visible paths | `p:cxnSp` | Imported connectors retain the expanded round-trip evidence needed for source topology | `Native-stable` for the registered preset/connector schema | |
| 97 | | Freeform shape | `<path>` | `p:sp` with `a:custGeom` | Imported custom geometry reconstructs as a path | `Native-normalized`; SVG arcs are converted to cubic segments | |
| 98 | | Materialized Merge Shapes result | Ordinary `<path>` output from `shape_boolean_svg.py`; Fragment returns sibling paths | One `p:sp` with `a:custGeom` per returned path | `Native-normalized`; imports as final freeform geometry, not replayable operation history | Supported closed geometry or horizontal implicit-LTR direct text with an exact resolvable font face; text becomes glyph geometry, the first source owns style/order, and no clip, mask, or explicit fill rule is emitted | |
| 99 | | Polygon | `<polygon>` | Closed custom geometry | `Native-normalized` | Points must be finite and valid | |
| 100 | | Polyline | `<polyline>` | Open custom geometry | `Native-normalized` | Points use the same finite, registered grammar as other generated geometry | |
| 101 | | PowerPoint preset shape | Registry-generated compact `<g>` with preset intent/base paint and direct visible `<path>` children | One editable preset `p:sp` | Preset identity and adjustments can survive import/export | Quality check and export rerender the registry dynamically; canonical authoring has no hidden carrier, preview wrapper, or stored preview hash | |
| 102 | | Imported preset shape | Expanded import/round-trip group with a hidden native carrier, visible preview evidence, and freshness metadata | Restored preset when the payload is valid and unchanged | `Native-stable` within the import contract | Unsupported presets remain explicit diagnostic fallbacks, not guessed geometry | |
| 103 | | Action button shape | Compact authored `actionButton*` preset group | Visual preset geometry only | Shape geometry can round-trip | No click action, navigation target, or hyperlink is created | |
| 104 | | Group | `<g>` | `p:grpSp`, or a documented flatten/collapse for a special carrier | Grouped content can reconstruct as `<g>` | Structural atoms and placeholder contracts override ordinary grouping | |
| 105 | | Reused local symbol | Registered same-document `<use>` contract or project icon placeholder | Expanded editable shapes in the generated slide | Original symbol graph is not promised on import | External use, unsupported symbol features, and structural metadata reuse are rejected | |
| 106 | | Icon / imported vector | `<use data-icon="library/name">` resolved by the project icon pipeline; create-template imports use `imported/<name>` | Editable vector primitives/group after expansion | Reconstructed geometry, not the original library reference | Identifiers are case-sensitive; imported assets exist once at workspace-root `icons/imported/<name>.svg` | |
| 107 | | SmartArt / DiagramML | No main SVG object mapping | Main redesign route may rebuild the meaning with ordinary shapes | `Direct preservation` in native/template routes; otherwise a preview or explicit fallback | Do not label a decorative group as native SmartArt | |
| 108 | |
| 109 | Project-authored presets deliberately use a compact representation, while PPTX |
| 110 | import keeps the expanded evidence needed for lossless round-trip decisions. |
| 111 | The exact machine contract remains in |
| 112 | [`shared-standards-core.md`](../skills/ppt-master/references/shared-standards-core.md), and |
| 113 | preset selection and authoring behavior are documented in |
| 114 | [`native-shape-authoring.md`](../skills/ppt-master/references/native-shape-authoring.md). |
| 115 | |
| 116 | ## 4. PowerPoint text features |
| 117 | |
| 118 | | PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary | |
| 119 | |---|---|---|---|---| |
| 120 | | Text box | `<text>` | Editable `p:sp` with `p:txBody` | Reconstructed as `<text>` and, when needed, `<tspan>` | Text must be well-formed XML and use registered attributes | |
| 121 | | Mixed formatting within a line | Non-positioned `<tspan>` runs | DrawingML runs in one text frame | `Native-normalized`; registered run formatting remains editable | Positioning that changes frame geometry may split the result | |
| 122 | | Authored multiline and paragraph text | One `<text>` with positioned direct `<tspan>` lines | By default, one no-wrap text frame retains authored line breaks; ordinary generated frames resize to fit later edits, while exact frames and structured multiline placeholder carriers retain fixed-size behavior; semantic paragraph boundaries remain `a:p` | `Native-normalized` | `--reflow-text` permits PowerPoint reflow; `--no-merge` emits one shape per visual line | |
| 123 | | Significant text whitespace | Exact `xml:space="default"` or `xml:space="preserve"` on `<text>`/`<tspan>` | Normalized or preserved U+0020 text in editable DrawingML runs | `Native-normalized`; inline run ownership is retained | Uses the project Chromium/SVG2 contract: LF/TAB become spaces, `default` collapses across runs, `preserve` retains them, and Unicode spacing characters remain literal; CSS `white-space` and legacy SVG 1.1 newline deletion are outside the mapping | |
| 124 | | Font family | Canonical `font-family` resolved as a structural lock role or contextual export-safe choice | Direct typeface or registered theme font | `Native-stable` within installed/font-substitution limits | Unavailable/unsafe fonts are reported; a contextual safe family is informational, not a lock failure | |
| 125 | | Font size | Finite unitless SVG pixels, for example `font-size="24"` | DrawingML hundredths of a point; `1 px = 0.75 pt` | `Native-stable` after unit conversion | Generated authoring uses only unitless px; registered legacy units are compatible input and warn, while unknown units error; DrawingML minimum is 1 pt | |
| 126 | | Font weight | Registered `font-weight` on `<text>`/`<tspan>` | DrawingML regular/bold run switch | `Native-normalized`; numeric weights collapse to the DrawingML boolean boundary | The exact value grammar and aliases belong to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) | |
| 127 | | Italic, underline, and strike | Registered `font-style` / `text-decoration` on `<text>`/`<tspan>` | DrawingML italic, underline, and strike run properties | `Native-stable` for registered tokens | Unknown tokens are rejected; the exact grammar belongs to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) | |
| 128 | | Text fill and transparency | Canonical fill plus run alpha | DrawingML run fill and alpha | `Native-normalized` | Use the semantic alpha channel, not an unregistered CSS effect | |
| 129 | | Text outline | Registered stroke on text | DrawingML run outline | `Native-normalized` | Review when outline carries fine visual meaning | |
| 130 | | Text alignment | Registered `text-anchor` and paragraph semantics | Paragraph alignment plus normalized text-frame position | `Native-normalized` | Run-level anchoring and browser baseline heuristics are unsupported; exact placement belongs to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) | |
| 131 | | Vertical text-frame alignment | No canonical generated-SVG control; generated text boxes use top anchoring | Top-anchored DrawingML text body | Imported vertical text may be normalized, but the main route does not expose a general authoring control | Do not infer vertical alignment from SVG baseline or browser layout behavior | |
| 132 | | Character spacing | Registered `letter-spacing` | DrawingML character spacing | `Native-normalized` | Unsupported CSS typography, out-of-range DrawingML spacing, and negative tracking that collapses a generated run advance or text-frame extent to a non-positive value are rejected under [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) | |
| 133 | | Bulleted paragraph | Recognized leading bullet form | Native DrawingML bullet | `Native-normalized` | Only the registered bullet grammar is promoted | |
| 134 | | Rotated text | Supported transform on the text object | Rotated text shape | `Native-normalized` | Skewed text and browser-only transforms are unsupported | |
| 135 | | Text shadow or glow | Supported filter/effect contract | One native outer shadow or glow | `Approximate` | One supported effect graph only; review material effects | |
| 136 | | WordArt, text warp, or text-on-path | No registered main-route mapping | Not generated as native WordArt | `Bake-required` or rebuild with ordinary text/geometry | Browser rendering does not imply PowerPoint support | |
| 137 | |
| 138 | ## 5. PowerPoint picture features |
| 139 | |
| 140 | | PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary | |
| 141 | |---|---|---|---|---| |
| 142 | | Picture | `<image>` with explicit positive dimensions and exactly one project-asset or image data-URI source | `p:pic`, media part, and relationship | Reconstructed as `<image>` | Source must resolve, use a registered format, and contain decodable bytes matching its MIME/extension; invalid frames or media fail before packaging | |
| 143 | | Explicit complex-SVG picture | A direct `<image>` referencing a tight, self-contained `.svg` created from one exact `<g id>` by `extract_svg_pictures.py` during `create-template` normalization | One `p:pic` backed by SVG media | Reconstructed as one `<image>`; its internal paths are not promoted to separate PowerPoint shapes | Selection is explicit and limited to `standard` / `fidelity`; no import, repetition, Master/Layout, finalize, or export heuristic may convert a group into this representation automatically | |
| 144 | | Stretch picture to frame | `preserveAspectRatio="none"` | Stretched native picture frame | `Native-stable` | `none` must stand alone; it intentionally changes the source aspect ratio | |
| 145 | | Crop picture to fill | One registered alignment plus explicit `slice` | Native `a:srcRect` crop | `Native-stable` when source dimensions are readable | Alignment is case-sensitive; unknown modes and extra tokens are errors | |
| 146 | | Fit picture inside frame | Omitted default, or one registered alignment plus explicit `meet` | Native fitted picture frame | `Native-normalized` | Alignment-only shorthand is compatible input that receives a normalization recommendation | |
| 147 | | Picture transparency | Atomic image `opacity` | Native `a:alphaModFix` | `Native-stable` | Value must be finite and within the accepted opacity grammar | |
| 148 | | Picture shadow or glow | One registered effect filter directly on an unclipped `<image>`; a clipped image or imported crop uses its exact single-picture outer carrier | Native `p:pic/p:spPr/a:effectLst` | `Approximate`; one effect round-trips as one editable picture, including a direct Master/Layout atom | `filter` and `clip-path` cannot share one `<image>`; only a direct fixed atom may put `data-pptx-layer="master|layout"` on the carrier, while Placeholder/Binding/replacement ownership stays outside; ordinary group filters, other primitives, effect DAGs, and multiple independent effects remain unsupported | |
| 149 | | Picture clipped to a shape | Registered image/crop-wrapper `clip-path` with one SVG-namespace shape | Picture preset or custom geometry | `Native-normalized` | Circle/ellipse/rect presets must cover the complete picture frame; use path/polygon for partial or offset contours; masks and winding-rule-dependent contours are not accepted | |
| 150 | | Imported cropped picture | Exact SVG-namespace nested crop wrapper produced by import, containing one direct unit-frame image in the visual root/`g` tree | Native signed `a:srcRect` on re-export | `Native-stable` within the crop contract, including negative crop values | Any generalized nested viewport, non-visual/render-only owner, extra visual child, unrepresentable crop window, redundant uncropped wrapper, or unresolved clip-marker pair is rejected | |
| 151 | | Picture recolor, artistic filter, blur, or complex mask | No general authoring mapping | Rebuild with supported overlays or pre-render | `Bake-required` | Unregistered SVG filters and blend modes fail the main contract | |
| 152 | |
| 153 | ## 6. PowerPoint fill, line, and effect features |
| 154 | |
| 155 | | PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary | |
| 156 | |---|---|---|---|---| |
| 157 | | No fill | `fill="none"` | `a:noFill` | `Native-stable` | Use lowercase canonical spelling in generated SVG | |
| 158 | | Solid fill | Canonical `fill="#RRGGBB"`, either a named lock anchor or contextual page paint | `a:solidFill`, with a theme token when an anchor role is exactly reusable | `Native-stable` | Compatible spellings may warn; malformed colors fail, while valid contextual colors are informational | |
| 159 | | Fill transparency | Opaque fill plus `fill-opacity` | Native alpha | `Native-stable` | Generated values are finite unitless numbers from 0 to 1 | |
| 160 | | Linear gradient fill | Registered `<linearGradient>` in `<defs>` | Native `a:gradFill` | `Native-normalized` | Stops, coordinates, transforms, and references must follow the closed contract | |
| 161 | | Radial gradient fill | Registered `<radialGradient>` | Point-focused circular DrawingML gradient | `Approximate`; an in-circle effective focus round-trips while outer center/radius normalize | Effective focus must lie inside the canonical centered radius-0.5 circle; import centers an outside focus with a diagnostic; review radius- or outer-center-sensitive designs | |
| 162 | | Pattern fill | Annotated project pattern definition | Native `a:pattFill` | `Native-normalized` | Only registered PowerPoint preset patterns are supported | |
| 163 | | No outline | `stroke="none"` or the registered absence of a line | `a:noFill` under `a:ln` | `Native-stable` | Do not simulate absence with zero-width ambiguous CSS | |
| 164 | | Solid outline | Registered `stroke` and width | Native `a:ln` | `Native-stable` | Width and paint must use canonical units/grammar | |
| 165 | | Compound outline | No registered single-stroke SVG representation | Explicit geometry alternative or baked asset | `Bake-required` for the compound-line identity | Tolerant PPTX import omits the unsupported outline and reports it; strict import rejects non-`sng` `cmpd` | |
| 166 | | Inside-aligned outline | No registered ordinary SVG stroke representation | Explicit inset geometry or baked asset | `Bake-required` for exact outline alignment | Tolerant PPTX import omits the unsupported outline and reports it; strict import rejects non-`ctr` `algn` | |
| 167 | | Pattern, image, or group-derived outline paint | No registered line-paint SVG mapping | Explicit geometry alternative or baked asset | `Bake-required` | Tolerant PPTX import omits the unsupported outline and reports it; strict import rejects it instead of inventing a solid color | |
| 168 | | Outline scaling under transforms | Exact `vector-effect="none"` or `vector-effect="non-scaling-stroke"` | Choice resolved into native line width | `Native-normalized` | Other values are rejected; generated spelling is exact and lowercase | |
| 169 | | Dashed or dotted outline | Registered dash array | Preset or custom DrawingML dash | `Native-normalized` | Unsupported dash semantics are rejected | |
| 170 | | Line cap and join | Registered cap/join values | Native line cap/join properties | `Native-stable` within the fixed join contract | Import accepts one join; miter requires exact `lim="800000"` | |
| 171 | | Line arrowheads | Registered start/end markers | Native head/tail end properties | `Approximate` for marker size | Only triangle, stealth, arrow, diamond, and oval follow the conditional marker contract | |
| 172 | | Outer shadow | One supported shadow filter graph | Native outer shadow in `a:effectLst` | `Approximate`; one imported shape/connector/picture source `outerShdw` is reconstructed only when its non-zero offset is classifiable and its scale, skew, and rotation behavior are neutral or representable | Non-neutral `sx`/`sy`/`kx`/`ky`, rotate-with-shape behavior on a rotated target, zero offset, and unsupported attributes or graphs produce blocking diagnostics instead of silent simplification | |
| 173 | | Glow | One supported glow filter graph | Native glow in `a:effectLst` | `Approximate`; one imported shape/connector/picture source glow keeps the registered radius conversion | Review when the glow carries semantic emphasis | |
| 174 | | Imported text-run effect | Unchanged `metadata[data-pptx-part="txbody"]` on a logical shape; import-only blocking effect status for inherited Layout/Master list styles plus vertical, relationship-bearing, and table-cell fallback routes | Original slide-local native run effect inside `p:txBody` | `Native-stable` only while the raw slide-local payload remains usable; inherited effects, edits, or fallback routes that would drop a non-empty run `effectLst` / `effectDag` block | Not public authoring syntax; a table-cell run effect also disables the native Table replacement payload | |
| 175 | | Whole-object transparency | Atomic element `opacity` | Alpha distributed into supported native channels | `Native-normalized` | Prefer channel-specific alpha unless the whole atomic object fades | |
| 176 | | Group transparency | Compatible `<g opacity>` | Descendant-normalized approximation | `Approximate` with a warning | Generated SVG should prefer descendant alpha | |
| 177 | | Inner shadow, soft edge, reflection, blur, turbulence, blend mode, or arbitrary mask | No registered native mapping | Explicit geometry alternative or raster asset | `Bake-required`; PPTX import keeps the base object and emits blocking diagnostics for unsupported effects, effect DAGs, and picture/group lists outside the single registered effect | Handled object effects cannot be reclassified or omitted; text-run safety follows the unchanged-`txBody` row above | |
| 178 | |
| 179 | ## 7. PowerPoint tables |
| 180 | |
| 181 | | PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary | |
| 182 | |---|---|---|---|---| |
| 183 | | Visually drawn table | Ordinary SVG shapes, lines, and text | Independent editable PowerPoint shapes | Fidelity follows each component row | It is not a native table and has no PowerPoint table editing model | |
| 184 | | PowerPoint-native table | One `<g data-pptx-replace-with="table">` with child `<metadata type="application/json">` and a visible fallback | `p:graphicFrame` containing `a:tbl` when native Chart/Table replacement is enabled | Imported supported tables reconstruct a fallback plus replacement metadata | Metadata must form the registered rectangular schema; requires `--native-charts-and-tables` | |
| 185 | | Merged table cells | Canonical native-table merge metadata | Native horizontal/vertical merge semantics | `Native-stable` within the closed schema | Overlapping, ambiguous, or non-rectangular merges are rejected | |
| 186 | | Table cell formatting | Registered native-table cell formatting fields | Native cell fill, border, text, and alignment | `Native-normalized` | Fields outside the closed schema are not guessed; imported non-empty run effects block instead of normalizing into an effect-free cell | |
| 187 | | Unsupported native table feature | SVG fallback or direct source preservation | Visible fallback remains, or source OOXML stays on a direct route | Explicit fallback / `Direct preservation` | Do not extend JSON ad hoc | |
| 188 | |
| 189 | PowerPoint-native Chart/Table objects are opt-in. Default export keeps the SVG fallback as independently editable DrawingML shapes for visual stability; native export instead provides the object's data-source and table/chart-specific editing model, and may normalize appearance. |
| 190 | |
| 191 | Imported chart groups classify their visible fallback with `data-pptx-fallback-kind="source-preview|normalized|placeholder"`; `placeholder` alone denotes the reconstruction-only fallback. `data-pptx-replacement-status` instead records why a fallback-only chart or table import cannot make an active replacement claim. Imported groups in this contract use `data-pptx-import-source="pptx"` and active claims may carry `data-pptx-fallback-sha256` for stale-edit protection. Legacy `data-pptx-native*`, `data-pptx-visual-status`, and `data-pptx-route-status` spellings remain read-compatible but are not canonical authoring. |
| 192 | |
| 193 | ## 8. PowerPoint charts |
| 194 | |
| 195 | | PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary | |
| 196 | |---|---|---|---|---| |
| 197 | | Visually drawn chart | Ordinary SVG geometry and text | Independent editable PowerPoint shapes | Fidelity follows each component row | It has no “Edit Data” workbook | |
| 198 | | PowerPoint-native classic chart | One `<g data-pptx-replace-with="chart">` with registered JSON data in `<metadata type="application/json">` and a visible fallback | `p:graphicFrame`, classic chart part, and embedded workbook | Supported imports reconstruct a fallback plus replacement metadata | Chart type and data must match the closed schema; requires `--native-charts-and-tables` | |
| 199 | | Native ChartEx chart | Same marker interface with a supported ChartEx family | `cx:chart` part and embedded workbook | Supported families can reconstruct semantically | Only the registered family/field combinations are accepted | |
| 200 | | Chart title, legend, axes, labels, and series formatting | Registered native-chart metadata | Native chart properties | `Native-normalized` | Exact fields and supported families remain normative in `native-data-interface.md` | |
| 201 | | Chart caption, source, or footnote | Ordinary companion SVG text outside the replacement marker | Editable slide text boxes beside the chart | `Native-stable` as text | Do not hide slide prose inside chart JSON | |
| 202 | | Edited SVG fallback with stale replacement metadata | Updated visible SVG plus stale hash | Default export keeps the visible SVG; native replacement fails | Explicit safety behavior | The compiler never discards a newer visual edit silently | |
| 203 | | Unsupported 3D or deferred chart family | SVG-drawn chart, baked asset, or direct source preservation | No guessed native chart | Fallback / `Direct preservation` | Unsupported aliases must fail native validation | |
| 204 | |
| 205 | The exhaustive chart/table schemas and supported family list intentionally remain in the [Native Data Interface replacement contract](../skills/ppt-master/references/native-data-interface.md#2-powerpoint-native-chart--table-replacement-markers-opt-in). |
| 206 | |
| 207 | ## 9. PowerPoint playback and package features |
| 208 | |
| 209 | These capabilities belong to PPTX package semantics. Their absence from page SVG is deliberate. |
| 210 | |
| 211 | | PowerPoint feature | Owning project representation | PPTX result | Import and fidelity | Validation boundary | |
| 212 | |---|---|---|---|---| |
| 213 | | Speaker notes | `notes/<slide>.md` sidecar | Notes Slide part and relationship | `Sidecar/package` | Notes are not SVG text and do not affect page geometry | |
| 214 | | Slide transition | CLI options or `animations.json` | `p:transition` | `Sidecar/package` | Unknown effects or invalid durations fail; no silent `fade` fallback | |
| 215 | | Object animation (entrance / emphasis / motion path / exit) | `animations.json` targeting stable top-level SVG group IDs; `effects[]` may assign several rows to one anchor | Root `p:timing` animation tree | `Sidecar/package`; the group ID is only the shape-target anchor | Static structural layers and placeholders cannot be animated | |
| 216 | | Narration audio | `audio/` asset plus recorded-narration export option | Media relationship, audio carrier, and timing | `Sidecar/package` | Asset, slide association, and timing must validate | |
| 217 | | Automatic slide advance | Explicit transition timing or narration-derived duration | `advTm`/advance behavior | `Sidecar/package` | Click-driven animation is incompatible with recorded narration | |
| 218 | | Hyperlink or action | No main SVG compiler mapping | Not created by page SVG | `Direct preservation` where a native route retains source OOXML | An action-button preset supplies visual geometry only | |
| 219 | | Comment or review thread | No SVG or generation-side mapping | Not authored | `Direct preservation` only when explicitly owned by another route | Do not convert review metadata into visible slide content automatically | |
| 220 | | Relationship not owned by a mapped feature | No generic SVG escape hatch | Not generated | `Direct preservation` where applicable | Arbitrary relationship injection is unsupported | |
| 221 | |
| 222 | For one target group, the fully compatible legacy object represents one |
| 223 | effect row, while a non-empty `effects[]` represents several; the two forms are |
| 224 | mutually exclusive. Every row may set its own `trigger`, sequence `order`, |
| 225 | `delay`, `duration`, and `trigger_shape`, with the slide animation trigger used |
| 226 | only as an inherited Start value. `auto`, `mixed`, and `random` resolve generic |
| 227 | entrances only; explicit canonical effects cover entrance, emphasis, native |
| 228 | motion-path presets, and exit. This mapping does not infer paragraph/text-range |
| 229 | builds, custom freeform motion paths, native Chart/SmartArt build sequences, or |
| 230 | media playback commands. |
| 231 | |
| 232 | See [Animations & Transitions](./animations.md) (technical source: [`references/animations.md`](../skills/ppt-master/references/animations.md)) and [`audio-narration.md`](./audio-narration.md) for the sidecar workflows. |
| 233 | |
| 234 | ## 10. Other PowerPoint-native features |
| 235 | |
| 236 | | PowerPoint feature | Main-route status | Supported alternative | Boundary | |
| 237 | |---|---|---|---| |
| 238 | | SmartArt / DiagramML | No native SVG compiler mapping | Reconstruct meaning with shapes, or preserve through a native/template route | A screenshot or fallback must be explicit | |
| 239 | | OLE or embedded Office object | Unsupported in the SVG route | Direct preservation or a rendered preview | Do not manufacture package relationships from SVG metadata | |
| 240 | | Native equation / OMML | Unsupported in the SVG route | Render a formula asset or preserve native OOXML directly | A rendered formula is a picture, not an editable equation | |
| 241 | | Video | Unsupported as an SVG-authored media object | Direct preservation or an explicit poster/link workflow outside this contract | A `media` placeholder does not create video | |
| 242 | | 3D model | Unsupported | Direct preservation or baked preview | No browser-SVG approximation is treated as native 3D | |
| 243 | | Macro / VBA | Unsupported | Preserve only through a macro-aware direct workflow | The normal generated `.pptx` route does not synthesize VBA | |
| 244 | | Arbitrary Office extension XML | Unsupported | Direct preservation by an owning native workflow | The SVG compiler has no generic OOXML passthrough | |
| 245 | |
| 246 | ## 11. Reverse mapping: PPTX to project SVG |
| 247 | |
| 248 | The importer reconstructs supported PowerPoint semantics into the same project vocabulary used by export: |
| 249 | |
| 250 | | PowerPoint source object | Project SVG reconstruction | |
| 251 | |---|---| |
| 252 | | Preset shape | Expanded preset group with native carrier and visible preview evidence when supported | |
| 253 | | Custom geometry | `<path>` | |
| 254 | | Text body | `<text>` and `<tspan>` runs/paragraphs | |
| 255 | | Picture | `<image>`, or the registered nested crop representation | |
| 256 | | SVG picture with raster compatibility fallback | `<image>` sourced from the `asvg:svgBlip` relationship; the ordinary `a:blip` relationship is used only when the SVG relationship or media part is unavailable | |
| 257 | | Connector | Expanded line/path preview plus connector/frame/topology evidence | |
| 258 | | Group | `<g>` | |
| 259 | | Supported native table/chart | Visible fallback plus native-object metadata | |
| 260 | | Unsupported graphic frame or SmartArt | Explicit preview, placeholder, or unsupported status | |
| 261 | |
| 262 | This is semantic projection, not a syntax round trip. Preserving validated source-package Master/Layout facts is confined to Create Template mirror and always produces a new workspace; an ordinary visual import does not infer reusable topology from slide appearance. |
| 263 | |
| 264 | ### Import operating modes and error-recovery boundary |
| 265 | |
| 266 | `pptx_to_svg.py` defaults to tolerant import because its inputs are user-owned or third-party PPTX files. `--strict` is available for parser development, contract verification, and reproducing the first source violation. Strict generated-SVG validation and export remain unchanged. |
| 267 | |
| 268 | | Source condition | Default tolerant import | `--strict` | Diagnostic result | |
| 269 | |---|---|---|---| |
| 270 | | Recognized color semantics with unrelated source metadata | Canonicalize the recognized color and modifiers | Reject the noncanonical structure | Warning with part, slide, and shape context where available | |
| 271 | | Unsupported fill, outline, effect, image fill, text body, or style property | Keep the object and omit only the unsupported property or feature | Stop at the first violation | Warning names the omitted feature and fallback | |
| 272 | | Unsupported object that cannot be recovered property-by-property | Replace that object with a visible diagnostic placeholder; omit it only when it has no usable frame | Stop at the first violation | Warning identifies the source object | |
| 273 | | Unsupported slide or part background | Omit that background and continue the page/part | Stop at the first violation | Warning identifies the owning part | |
| 274 | | Corrupt package/XML or missing required package structure | Stop; no safe page-level recovery exists | Stop | Clean command error; no raw Python traceback | |
| 275 | |
| 276 | Every successful run writes `<output>/conversion-report.json`. The report records the mode, slide and warning counts, stable reason code, source message, chosen fallback, package part, and—when available—slide index plus shape id/name/kind. Tolerant import is therefore not silent: it maximizes usable output while making every contract recovery reviewable. |
| 277 | |
| 278 | ## 12. Validation ownership |
| 279 | |
| 280 | The four layers have deliberately different jobs: |
| 281 | |
| 282 | | Layer | Responsibility | |
| 283 | |---|---| |
| 284 | | Prompt, template, and examples | Generate only the canonical representation for each PowerPoint feature | |
| 285 | | `svg_quality_checker.py` | Reject invalid/unsupported mappings; warn but allow registered compatible spellings or fidelity risks | |
| 286 | | `svg_to_pptx.py` and package read-back | Normalize compatible input, compile DrawingML, and reject any result that would be ambiguous, structurally inconsistent, or invalid | |
| 287 | | `pptx_to_svg.py` | In default tolerant mode, preserve the usable deck and report source-owned degradation at the narrowest safe boundary; in `--strict` mode, stop at the first unsupported or malformed source construct | |
| 288 | |
| 289 | A generated-SVG warning is not permission to guess. It is reserved for a deterministic supported mapping whose spelling or fidelity deserves attention. Missing mappings, invalid units, malformed metadata, broken structure contracts, and potentially repair-triggering generated DrawingML remain errors. Import diagnostics describe explicit loss or normalization of source-owned content; they never authorize the importer to invent unsupported semantics. |
| 290 | |
| 291 | ## 13. Adding or changing a mapping |
| 292 | |
| 293 | Treat a mapping change as a compiler change, not as a permissive SVG parser tweak: |
| 294 | |
| 295 | 1. Name the PowerPoint capability and its intended editable DrawingML result. |
| 296 | 2. Define one canonical project-SVG or sidecar representation in the applicable authority module selected by [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md). |
| 297 | 3. State accepted compatible input separately from generated authoring. |
| 298 | 4. Implement export, and implement import only when semantic reconstruction is supported. |
| 299 | 5. Add checker classification: error for invalid/ambiguous input, warning only for deterministic compatible or approximate input. |
| 300 | 6. Perform focused regression verification on the generated SVG, PPTX package, PowerPoint rendering, and reverse import where applicable. |
| 301 | 7. Update the matching English and Chinese row in this guide. |
| 302 | |
| 303 | Implementation entry points: |
| 304 | |
| 305 | - Export: [`svg_to_pptx.py`](../skills/ppt-master/scripts/svg_to_pptx.py) and `scripts/svg_to_pptx/` |
| 306 | - Import: [`pptx_to_svg.py`](../skills/ppt-master/scripts/pptx_to_svg.py) and `scripts/pptx_to_svg/` |
| 307 | - Validation: [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py) |
| 308 | - Authority router: [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md) |
| 309 |