# SVG Visualization Template Library

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.

## Source of truth

[`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.

For one planned page, provide 3-8 English semantic content-shape tags, then inspect the positive-scoring returned summaries plus the explicit `no-template-match` option. The requested 3-8 limit is a cap: the tool never pads a weak result with zero-score keys, and zero positive matches returns only the fallback. See [`chart-recall.md`](../../scripts/docs/chart-recall.md). The Generate workflow remains the authority for when Strategist uses this helper; maintainers may still open the registry directly when editing or auditing the catalog.

## Authoring contract

[`CHART_STYLE_GUIDE.md`](./CHART_STYLE_GUIDE.md) owns readable standalone SVG, semantic and structural fidelity, root-group bounds, data encoding, and neutral previews. The active Design Spec and `spec_lock.md` own final palette, typography, containers, effects, and chrome. Preview styling is adaptable, but visible content and frames that express real grouping, hierarchy, or capacity remain authoritative until the template is fully migrated and reviewed.

## Visualization output model

This library is **Shape-first**. Infographics, process diagrams, architecture
diagrams, frameworks, and the default rendering of data charts export as
independently editable PowerPoint shapes:

- Use ordinary SVG primitives for basic nodes and containers. Thin directional
  relationships use `<line>` / supported open `<path>` geometry with registered
  arrow markers; they remain static editable shapes and do not create node
  attachment or automatic routing.
- Use a stock PowerPoint preset for a solid block arrow, chevron, or standard
  flowchart node when it exactly expresses the intended object. A template may
  retain the complete compact atomic `<g>` generated by `preset_shape_svg.py`,
  so direct export preserves the native preset identity. The group owns the
  metadata and base paint once; its direct visible paths are registry-derived
  layers with only necessary per-layer paint overrides. It has no hidden
  carrier, preview wrapper, or stored fingerprint. If preset, frame,
  adjustments, or paint changes, regenerate the whole group instead of editing
  metadata or paths. PPTX import and `mirror` retain their separate expanded
  lossless representation; do not copy that transport form into new templates.
- Keep custom contours, branded geometry, and data-driven marks as ordinary
  `<path>` / `<polygon>` geometry. They still export as editable DrawingML
  shapes; native preset identity is not required for editability.
- Do not put authored Connector metadata or endpoint attachment metadata in
  this template library. Existing Connector topology imported from a source
  PPTX belongs to the preserve/mirror round-trip contract, not chart-template
  authoring.

Data-backed charts retain the separate opt-in replacement route described
below. Conceptual diagrams and frameworks are never labeled as native charts.

## Native Chart/Table replacement markers

Supported data chart templates include a `<g data-pptx-replace-with="chart">` marker by default, and pure text-grid table templates include a `<g data-pptx-replace-with="table">` marker the same way. The default SVG export path is unchanged: the fallback vector artwork is exported as shape-based DrawingML exactly as drawn. When `svg_to_pptx.py --native-charts-and-tables` is enabled, that fallback group is replaced with a native PowerPoint Chart or Table object using the JSON metadata inside its child `<metadata type="application/json">` node. The legacy `--native-objects` spelling remains a compatibility alias.

`--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.

Native replacement authoring remains active for all 23 currently supported data-chart templates:

| Family | Active replacement templates | Native output |
|---|---|---|
| Category comparison | `column_chart`, `horizontal_bar_chart`, `grouped_bar_chart`, `stacked_bar_chart` | Classic category charts |
| Time trend | `line_chart`, `area_chart`, `stacked_area_chart`, `dual_axis_line_chart` | Classic line/area/combo charts |
| 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 |
| Distribution and relationship | `scatter_chart`, `bubble_chart`, `histogram_chart`, `pareto_chart`, `box_plot_chart` | Classic XY or ChartEx distribution charts |
| Specialty business charts | `waterfall_chart`, `funnel_chart`, `stock_chart`, `radar_chart` | ChartEx or classic specialty charts |
| Text-grid tables | `basic_table`, `financial_statement_table` | Native DrawingML tables |

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.

## Usage

Execution loads only selected keys under [`executor-chart.md`](../../references/executor-chart.md) §1 and reuses unchanged path + SHA. 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.
