| 1 | # Chart Visualization Templates |
| 2 | |
| 3 | This directory contains 33 canonical value-driven references. A chart belongs here |
| 4 | when source values, categories, time, weights, or durations determine visual |
| 5 | mark position, length, area, angle, font size, or connection width. |
| 6 | |
| 7 | Qualitative page topology is built as a page-specific Structure by Executor. |
| 8 | Cell-grid semantics belong in [`tables/`](../tables/). Reusable PowerPoint |
| 9 | Master/Layout, page-type, slot, and placeholder contracts belong in |
| 10 | [`layouts/`](../layouts/). |
| 11 | |
| 12 | ## Planning vocabulary and source of truth |
| 13 | |
| 14 | [`charts_index.json`](./charts_index.json) is the sole chart registry. Its |
| 15 | `charts` object maps each canonical key to one selection-rule `summary` in the |
| 16 | form `Pick for ... Skip if ...`. The key matches `<key>.svg`; `meta.total` |
| 17 | matches the canonical SVG roster. |
| 18 | |
| 19 | [`chart-vocabulary.md`](./chart-vocabulary.md) is the complete planning |
| 20 | projection. It lists all 33 exact `chart/<key>` references by information |
| 21 | relationship and states only what each encoding represents. It contains no |
| 22 | chart-authoring instructions and does not prescribe selection. |
| 23 | |
| 24 | Default Strategist and Quick read the vocabulary together with the Table |
| 25 | registry before planning, choose through their own judgment, then use |
| 26 | [`visualization_recall.py`](../../scripts/visualization_recall.py) `validate` |
| 27 | to resolve selected canonical references. Its `recall` mode remains an |
| 28 | optional diagnostic helper over the machine registry, not the runtime |
| 29 | capability gate. Default writes `chart/<key>` to `page_visualizations`; Quick |
| 30 | keeps the selected reference in active context. Executor then reads only the |
| 31 | selected SVG and execution references. [`chart_recall.py`](../../scripts/chart_recall.py) |
| 32 | and bare keys remain legacy compatibility only. |
| 33 | |
| 34 | ## Authoring contract |
| 35 | |
| 36 | [`VISUALIZATION_TEMPLATE_AUTHORING.md`](../VISUALIZATION_TEMPLATE_AUTHORING.md) |
| 37 | owns the shared standalone-SVG, neutral-preview, root-boundary, Shape-first, |
| 38 | family, and catalog rules. Chart-specific requirements are: |
| 39 | |
| 40 | - Preserve the exact value-to-mark mapping, labels, units, categories, series, |
| 41 | ordering, and source notes required by the information. |
| 42 | - Keep calculator-supported `chart-plot-area` markers accurate. |
| 43 | - Default output remains independently editable DrawingML shapes. |
| 44 | - Add native Chart replacement metadata only for a supported independent data |
| 45 | object. The visible fallback and metadata describe the same data. |
| 46 | - Do not classify a named quadrant, process, hierarchy, or relationship diagram |
| 47 | as a chart unless values actually determine its marks. |
| 48 | |
| 49 | `matrix_2x2` is a chart: each item's x/y coordinates encode two values and its |
| 50 | radius encodes a third metric. A fixed 2×2 set of titled text regions is a |
| 51 | page-specific Structure. A schedule whose dates or durations determine task-bar |
| 52 | position and length is `chart/gantt_chart`; a qualitative stage/lane plan is a |
| 53 | Structure built from those relationships. |
| 54 | |
| 55 | ## Runtime boundary |
| 56 | |
| 57 | One selected SVG is a flexible reference for one mapped page. Design Spec §IX |
| 58 | or the Quick active-context decision plus source data owns final semantics. |
| 59 | Project palette, typography, chrome, grouping, capacity, and geometry remain |
| 60 | adaptable. Selecting a chart reference does not itself select native output; |
| 61 | §IX/Quick names independent objects separately and decides |
| 62 | `<object-key>=yes|no`, while explicit `--native-charts-and-tables` export is a |
| 63 | second opt-in. |
| 64 |