| 1 | # SVG Visualization Template Library |
| 2 | |
| 3 | This directory contains the standardized SVG visualization templates used by PPT Master — charts, infographics, process diagrams, relationship diagrams, and strategic frameworks. The directory name `charts/` is kept for backward compatibility; the library scope is broader than charts. |
| 4 | |
| 5 | ## Source of truth |
| 6 | |
| 7 | [`charts_index.json`](./charts_index.json) is the single source of truth for the library: total count + one selection-rule `summary` per template (format: `"Pick for X. Skip if Y (use other_key)."`). [`chart_recall.py`](../../scripts/chart_recall.py) can recall a bounded candidate set from this live registry without maintaining a second category or keyword index. |
| 8 | |
| 9 | For one page, provide 3-8 English semantic content-shape tags, then inspect the positive-scoring summaries plus the explicit `no-template-match` option. The requested limit is a cap, not a padding target, and lexical confidence never expands the output automatically. At `high` / `medium`, retain `no-template-match` when no bounded candidate fits. At `low` / `none`, a fitting candidate needs no expansion, but rerun the same query once with `--semantic-fallback` before keeping `no-template-match`. In Default Generate, a selected result creates one `Page | Template | Usage` row in §VII and one matching `page_charts` entry; its path is derived from the key, while Usage is concise page-local intent and detailed adaptation remains in §IX. Quick Generate keeps the selected key/purpose only in active context and writes no mapping artifact. A negative result creates no row in either profile. See [`chart-recall.md`](../../scripts/docs/chart-recall.md). The Generate workflow remains the authority for when the active profile uses this helper; maintainers may still open the registry directly when editing or auditing the catalog. |
| 10 | |
| 11 | ## Authoring contract |
| 12 | |
| 13 | [`CHART_STYLE_GUIDE.md`](./CHART_STYLE_GUIDE.md) owns readable standalone SVG, semantic and structural fidelity, root-group bounds, data encoding, and neutral previews. Default Design Spec §IX or the Quick active-context page decision plus source data own the generated page's semantics; Default `spec_lock.md` owns stable project anchors. A selected SVG is a page-local structural reference, while its type, styling, frames, grouping, item count, capacity, and geometry remain adaptable. |
| 14 | |
| 15 | ## Visualization output model |
| 16 | |
| 17 | This library is **Shape-first**. Infographics, process diagrams, architecture |
| 18 | diagrams, frameworks, and the default rendering of data charts export as |
| 19 | independently editable PowerPoint shapes: |
| 20 | |
| 21 | - Use ordinary SVG primitives for basic nodes, containers, and straight |
| 22 | relationships; they export as editable PowerPoint shapes. A straight |
| 23 | directional relationship uses `<line>` with a registered arrow marker. |
| 24 | - When a bent or curved relationship exactly matches a stock Connector contour, |
| 25 | prefer a compact authored `bentConnector*` / `curvedConnector*` preset. It is |
| 26 | an unconnected native Connector shape and does not create node attachment or |
| 27 | automatic routing. |
| 28 | - Use a stock PowerPoint preset for a solid block arrow, chevron, or standard |
| 29 | flowchart node when it exactly expresses the intended object. A template may |
| 30 | retain the complete compact atomic `<g>` generated by `preset_shape_svg.py`, |
| 31 | so direct export preserves the native preset identity. The group owns the |
| 32 | metadata and base paint once; its direct visible paths are registry-derived |
| 33 | layers with only necessary per-layer paint overrides. It has no hidden |
| 34 | carrier, preview wrapper, or stored fingerprint. If preset, frame, |
| 35 | adjustments, or paint changes, regenerate the whole group instead of editing |
| 36 | metadata or paths. PPTX import and `mirror` retain their separate expanded |
| 37 | lossless representation; do not copy that transport form into new templates. |
| 38 | - When no single preset suffices but closed operands can express the object, |
| 39 | materialize the Union / Combine / Fragment / Intersect / Subtract result with |
| 40 | `shape_boolean_svg.py` before considering a hand-authored contour. |
| 41 | - Keep a hand-authored `<path>` / `<polygon>` only for branded, data-defined, |
| 42 | locked organic / hand-drawn, or other contours that primitives, an exact |
| 43 | preset, and Boolean materialization cannot faithfully express. They still |
| 44 | export as editable DrawingML shapes. |
| 45 | - Authored Connector metadata comes only from `preset_shape_svg.py`; never |
| 46 | hand-write endpoint attachment metadata. Existing attached Connector topology |
| 47 | imported from a source PPTX belongs to the preserve/mirror round-trip |
| 48 | contract, not chart-template authoring. |
| 49 | |
| 50 | Data-backed charts retain the separate opt-in replacement route described |
| 51 | below. Conceptual diagrams and frameworks are never labeled as native charts. |
| 52 | |
| 53 | ## Native Chart/Table replacement markers |
| 54 | |
| 55 | Supported data chart templates include a `<g data-pptx-replace-with="chart">` marker by default, and pure text-grid table templates include the table form. These are capability examples, not project decisions: Default keeps and rewrites the marker only when its Design Spec §IX page block says `Native-ready: yes` (legacy §VII fallback only); Quick makes the same independent-object decision in active context before drawing. Otherwise omit it. The default SVG export path remains shape-based DrawingML. With `--native-charts-and-tables`, prepared groups become native PowerPoint Chart/Table objects from their JSON metadata. The legacy `--native-objects` spelling remains a compatibility alias. |
| 56 | |
| 57 | `--native-charts-and-tables` is an explicit native-object opt-in and may be lossy or visually normalized. Replacement-local value labels, center KPIs, callouts, quadrant notes, fixed axis ranges, and custom binning/splits may not survive native replacement unless represented by the payload. ChartEx palette entries do survive when supplied through valid payload colors, but this does not preserve every ChartEx style detail. Detectable information-loss risks should be reported as warnings, not handled by disabling an otherwise supported replacement marker. Review those warnings and compare the native-object export with the default shape-based export before delivery. |
| 58 | |
| 59 | Native replacement authoring remains active for all 23 currently supported data-chart templates: |
| 60 | |
| 61 | | Family | Active replacement templates | Native output | |
| 62 | |---|---|---| |
| 63 | | Category comparison | `column_chart`, `horizontal_bar_chart`, `grouped_bar_chart`, `stacked_bar_chart` | Classic category charts | |
| 64 | | Time trend | `line_chart`, `area_chart`, `stacked_area_chart`, `dual_axis_line_chart` | Classic line/area/combo charts | |
| 65 | | Part-to-whole | `pie_chart`, `donut_chart`, `pie_of_pie_chart`, `bar_of_pie_chart`, `treemap_chart`, `sunburst_chart` | Classic pie-family or ChartEx hierarchy charts | |
| 66 | | Distribution and relationship | `scatter_chart`, `bubble_chart`, `histogram_chart`, `pareto_chart`, `box_plot_chart` | Classic XY or ChartEx distribution charts | |
| 67 | | Specialty business charts | `waterfall_chart`, `funnel_chart`, `stock_chart`, `radar_chart` | ChartEx or classic specialty charts | |
| 68 | | Text-grid tables | `basic_table`, `financial_statement_table` | Native DrawingML tables | |
| 69 | |
| 70 | Replacement payloads must include explicit `name`, `x`, `y`, `width`, and `height` fields so the native frame aligns with the fallback drawing. Keep legends, explanatory cards, source notes, center KPIs, and custom callouts outside the marked group when they must remain separate shapes; otherwise accept and review the native-object export warning. Canonical rectangular merged text cells may use anchor-only `row_span` / `col_span` metadata with blank covered cells; nonrectangular merges and graphical cells (harvey balls, rating dots, avatars) stay unmarked on the SVG fallback route. Per-side borders, plain multi-paragraph cells, and the closed run-rich paragraph schema use the contracts in [`native-data-interface.md`](../../references/native-data-interface.md#2-powerpoint-native-chart--table-replacement-markers-opt-in). Relationship-bearing text, structural line breaks, fields, tabs, bullets, and arbitrary rich-text OOXML stay on the SVG fallback route. |
| 71 | |
| 72 | ## Usage |
| 73 | |
| 74 | Execution loads only selected keys under [`executor-chart.md`](../../references/executor-chart.md) §1 and reuses an unchanged file within the active context. Files are named after the `key` field in `charts_index.json` (e.g. `column_chart.svg`, `quadrant_bubble_scatter.svg`). Templates are named by visual structure, not by business-model name — terms like SWOT, BCG, PEST, OKR, Porter's Five Forces, and Value Chain are translated into semantic content-shape tags before candidate recall. |
| 75 |