| 1 | > Default Generate also loads [`executor-base.md`](./executor-base.md); a selected chart-family SVG is adapted through [`executor-visualization.md`](./executor-visualization.md), while independent native readiness and metadata remain exclusively in [`native-data-interface.md`](./native-data-interface.md). |
| 2 | |
| 3 | # Executor Chart Branch |
| 4 | |
| 5 | Conditional Executor authority for value-driven SVG geometry, plot-area markers, and the [`verify-charts`](../workflows/stages/verify-charts.md) handoff. |
| 6 | |
| 7 | **Trigger**: load whenever source values determine visible geometry, including bar length/height, point position, arc angle, polygon vertex, connector or flow width/path, bubble center/radius, duration position, area, or another quantitative visual variable. Mini charts, sparklines, insets, and small multiples count even without a catalog reference. |
| 8 | |
| 9 | **Boundary**: |
| 10 | |
| 11 | | Information model | Route | |
| 12 | |---|---| |
| 13 | | Values, dates, or durations determine geometry or another visual variable | This branch | |
| 14 | | Qualitative order, grouping, containment, causality, or named zones determine topology | [`executor-structure.md`](./executor-structure.md) | |
| 15 | | A row header and column header jointly address each body fact | [`executor-table.md`](./executor-table.md) | |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## 1. Value-driven Geometry |
| 20 | |
| 21 | **Hard rule — data owns the marks**: derive every quantitative mark from the authoritative values and one explicit scale/encoding. Do not eyeball positions, preserve sample values from a catalog preview, or alter data to improve composition. |
| 22 | |
| 23 | Construct the chart in this order: |
| 24 | |
| 25 | 1. Resolve the data domain, categories, units, baseline, scale, and any radius/color/bin mapping. |
| 26 | 2. Establish the plot frame, axes/grid or radial frame, and legend needed to decode those mappings. |
| 27 | 3. Calculate marks from the values, including cumulative, derived, or hierarchical geometry where the chosen chart requires it. |
| 28 | 4. Add data labels, axis/category labels, annotations, units, source notes, and visible exceptions from the active page contract. |
| 29 | 5. Apply project typography, palette, effects, and container treatment without changing the encoding. |
| 30 | |
| 31 | **Perceptual reading**: choose the least ambiguous presentation of the same |
| 32 | authoritative data. Preserve source or semantic order when it carries meaning; |
| 33 | otherwise sort categories for the page's comparison task. Prefer direct series |
| 34 | labels when they remain legible, and keep legends, grid lines, ticks, and other |
| 35 | decoding aids only when they materially reduce lookup or comparison effort. |
| 36 | Comparable panels and small multiples use the same domain, scale, and category |
| 37 | order unless a visibly disclosed difference is itself the message. Bars and |
| 38 | columns whose length compares magnitude start from zero; schedule spans and |
| 39 | other true interval marks retain their authoritative domain. Any non-zero |
| 40 | baseline or axis break must be explicit and must not exaggerate the comparison. |
| 41 | A dual-axis chart is valid only when both series share the exact time/category |
| 42 | domain and the units and visual identities stay unambiguous; otherwise separate |
| 43 | the views. |
| 44 | |
| 45 | **Per-object completeness**: preserve every authoritative series, category, point, label, unit, qualifier, source, and scale cue needed to read the chart. When the source cannot determine a required scale or derived value, return the ambiguity upstream in Default or resolve it from explicit source facts in Quick; never fabricate it at draw time. |
| 46 | |
| 47 | **Hard rule — schedule geometry**: A schedule is a Gantt chart when dates or |
| 48 | durations determine each task bar's `x` and `width`, even if the source was a |
| 49 | PowerPoint table object. A qualitative stage × lane placement without that |
| 50 | mapping belongs to [`executor-structure.md`](./executor-structure.md). |
| 51 | |
| 52 | **Selected reference**: when the page has a `chart/<key>` primary reference, [`executor-visualization.md`](./executor-visualization.md) owns its resolution and flexible adaptation. This branch still owns the actual value-to-geometry calculation. A chart authored from scratch follows the same geometry contract without loading a catalog SVG. |
| 53 | |
| 54 | **Incidental microvisual**: draw a small value-driven trend or indicator accurately. It enters §2 and the verification handoff only when Default §IX or the Quick active-context decision promotes it to a coordinate-verified data object; do not infer that promotion from its appearance after drawing. |
| 55 | |
| 56 | --- |
| 57 | |
| 58 | ## 2. Plot-area Marker |
| 59 | |
| 60 | ### 2.1 Chart Plot-Area Marker (Mandatory per verified chart object) |
| 61 | |
| 62 | > [`verify-charts`](../workflows/stages/verify-charts.md) enumerates Default pages from Design Spec §IX and Quick pages from the still-active authoring decisions. A missing marker invokes that stage's declared fallback and adds avoidable derivation work. |
| 63 | |
| 64 | **Hard rule — object-scoped marker**: every Default chart object given a |
| 65 | semantic key in §IX `Visualization`, and every Quick chart object promoted for |
| 66 | coordinate verification, has one page-local `kebab-case` object key. Wrap that |
| 67 | object in `<g id="<object-key>">`; put exactly one marker inside its plot-area |
| 68 | group after the axes and before the first data mark. Use |
| 69 | `id="<object-key>-chartArea"` so several charts can coexist without duplicate |
| 70 | IDs. New pages prefix the marker payload with `object=<object-key> |`. A legacy |
| 71 | unscoped marker and `<g id="chartArea">` are accepted only when the page has |
| 72 | exactly one verified chart object. |
| 73 | |
| 74 | **Rectangular plot area**: |
| 75 | |
| 76 | ```xml |
| 77 | <g id="revenue-trend"> |
| 78 | <g id="revenue-trend-chartArea"> |
| 79 | <!-- axes --> |
| 80 | <!-- chart-plot-area: object=revenue-trend | x_min,y_min,x_max,y_max --> |
| 81 | <!-- data marks --> |
| 82 | </g> |
| 83 | </g> |
| 84 | ``` |
| 85 | |
| 86 | **Radial plot area**: |
| 87 | |
| 88 | ```xml |
| 89 | <!-- chart-plot-area: object=share-pie | pie | center: cx,cy | radius: r --> |
| 90 | <!-- chart-plot-area: object=share-donut | donut | center: cx,cy | outer-radius: r1 | inner-radius: r2 --> |
| 91 | <!-- chart-plot-area: object=capability-radar | radar | center: cx,cy | radius: r --> |
| 92 | ``` |
| 93 | |
| 94 | | Value | Derivation | |
| 95 | |---|---| |
| 96 | | `x_min` | X coordinate of the Y-axis line or leftmost data boundary | |
| 97 | | `y_min` | Y coordinate of the topmost grid line or data boundary | |
| 98 | | `x_max` | X coordinate of the rightmost axis endpoint or data boundary | |
| 99 | | `y_max` | Y coordinate of the X-axis baseline or bottom data boundary | |
| 100 | | `cx, cy` | Absolute center after accounting for containing translate transforms | |
| 101 | | `r`, `r1`, `r2` | Visible outer/inner radii used by the authored radial geometry | |
| 102 | |
| 103 | Calculator-supported SVGs in `templates/charts/` carry the same comment, and |
| 104 | single-object previews may retain the legacy unscoped payload and |
| 105 | `id="chartArea"`. A qualitative structure or cell-grid table does not gain a |
| 106 | marker merely because it contains numbers. |
| 107 | |
| 108 | ### 2.2 Authoring-time Check |
| 109 | |
| 110 | After writing each page containing verified charts, confirm marker count and |
| 111 | object ownership before continuing: |
| 112 | |
| 113 | ```bash |
| 114 | rg -n "chart-plot-area" <project_path>/svg_output/<current_page>.svg |
| 115 | ``` |
| 116 | |
| 117 | The number of markers must equal the number of promoted chart objects, and each |
| 118 | marker must sit under its matching object wrapper. One marker somewhere on a |
| 119 | multi-chart page is insufficient. |
| 120 | |
| 121 | **Native layout handoff**: for a native-ready classic chart whose authored plot |
| 122 | rectangle must remain fixed, copy that final absolute slide rectangle into |
| 123 | metadata `plot_area`; omit it only for PowerPoint automatic layout. The marker |
| 124 | comment alone does not affect export; the closed schema stays in |
| 125 | [`native-data-interface.md`](./native-data-interface.md) §2. |
| 126 | |
| 127 | Technical SVG/PPT constraints remain in [`shared-standards-core.md`](./shared-standards-core.md). |
| 128 | |
| 129 | --- |
| 130 | |
| 131 | ## 3. Verification Handoff |
| 132 | |
| 133 | Coordinate calibration is a conditional post-generation stage, not part of the page-authoring loop. After all SVG pages exist, run [`verify-charts`](../workflows/stages/verify-charts.md) whenever the active profile declares at least one page with value-driven chart geometry. |
| 134 | |
| 135 | | Active profile | Verification page list | |
| 136 | |---|---| |
| 137 | | Default Generate | Design Spec §IX, with the stage's explicit legacy §VII fallback | |
| 138 | | Quick Generate | Still-active page decisions cross-checked one-for-one against plot-area markers | |
| 139 | |
| 140 | Do not run `svg_position_calculator.py` during the initial draft. The stage calibrates completed SVG geometry against the declared plot area, handles direct/decomposable/formula/manual modes, repairs genuine coordinate mismatches, and then returns to the active profile's checker order. |
| 141 |