| 1 | --- |
| 2 | name: oh-my-ppt-chart |
| 3 | description: Must be read before adding or modifying Oh My PPT slide charts. Defines chart-selection rules, product-safe Chart.js usage, canvas layout constraints, axis label rules, and retry fixes. |
| 4 | --- |
| 5 | |
| 6 | # Oh My PPT Chart |
| 7 | |
| 8 | For deeper examples (chart selection, frame height guide, category axis patterns, layout integration tips), read `references/chart.md`. |
| 9 | |
| 10 | ## When to use |
| 11 | |
| 12 | - Adding a chart to a new or existing slide |
| 13 | - Modifying chart type, data, or options |
| 14 | - Repairing a blank or broken chart canvas |
| 15 | |
| 16 | ## When not to use |
| 17 | |
| 18 | - Pure visual micro-edits that don't change chart structure (e.g. adjusting a single color value). These still follow chart skill hard rules, but don't require reading the full reference. |
| 19 | - A page without a source-grounded quantitative relationship. Course maps, agendas, processes, equal-status topic groups, hierarchies, and qualitative comparisons are page-native diagrams, not Chart.js charts. |
| 20 | |
| 21 | ## 30-second decision checklist |
| 22 | |
| 23 | Before deciding to write chart HTML, answer these in order: |
| 24 | |
| 25 | 1. **Chart gate**: does the source provide a real numeric, temporal, compositional, profile, or correlation relationship? If not, use a page-native diagram and stop. |
| 26 | 2. **Visual question**: is the message comparison, trend, composition, profile, or correlation? Choose the chart form for that question; never create numbers or proportions just to use a chart. |
| 27 | 3. **Content slot**: how much vertical space remains for the chart zone after title, outer padding, gaps, notes, and reserve? |
| 28 | 4. **Support budget**: if metric cards, insight rails, legends, or footnotes share that zone, subtract their height first. Start with a small support set (often 0-2 items) around a main chart; add more when the reading path, hierarchy, and chart budget remain clear. |
| 29 | 5. **Final chart height**: hero / standard / compact? Pick one final px height for the chart frame. The `h-[Npx]` class must equal this final number. |
| 30 | 6. **Data semantics**: one value axis = one unit/meaning. Do not mix counts, percentages, money, or "new role" labels in one numeric dataset. |
| 31 | 7. **Takeaway**: what should the audience conclude from the chart? Write one visible interpretation sentence or a compact annotation rail; the chart cannot be the whole argument by itself. |
| 32 | 8. **Data shape**: labels + datasets. Are there enough data points for the chosen type? |
| 33 | 9. **Script event**: DOMContentLoaded only — the runtime loads Chart.js before this event fires. |
| 34 | |
| 35 | ## Chart selection |
| 36 | |
| 37 | Use Chart.js only for a real source-grounded relationship: |
| 38 | |
| 39 | - **Category comparison or ranking**: use a bar chart; use horizontal bars for long labels. |
| 40 | - **Ordered time or continuous change**: use a line chart; use an area only when cumulative magnitude is the message. |
| 41 | - **Verified, mutually exclusive parts of one stated whole**: use a doughnut or pie with 4-6 slices. Values must add to the displayed total or 100%; a list of topics or an invented time split is not a whole. |
| 42 | - **Same-scale scores across shared dimensions**: use a radar chart sparingly; every axis must share a meaningful scale. |
| 43 | - **Two or three numeric variables**: use scatter or bubble for correlation/distribution. |
| 44 | - **No data chart**: use a page-native route, four-part map, process, hierarchy, relationship diagram, or comparison layout for agendas, course maps, stages, concepts, or unquantified topic groups. |
| 45 | |
| 46 | ## How to create a chart |
| 47 | |
| 48 | Every chart needs exactly two parts: an HTML frame with explicit height, and a script block using DOMContentLoaded + PPT.createChart. |
| 49 | |
| 50 | ### 1. HTML — chart frame with explicit height |
| 51 | |
| 52 | Before writing the chart frame, you MUST calculate the chart slot and then choose the actual chart frame height. Write the calculation as an HTML comment immediately before the chart frame, include the dedicated marker `@ppt-chart-height=N`, and make the marker, the **final chart height**, and the `h-[Npx]` value all use the same number. Never put `@ppt-chart-height=...` as visible text inside `.ppt-chart-frame`. Do NOT write a comment that ends with one number and a frame height that uses another number. Two terms: **content slot** = current canvas height − padding − title − gaps − reserve (the area for the chart plus its support modules); **chart slot** = content slot − support modules. The final `h-[Npx]` MUST equal the chart slot, never the content slot. |
| 53 | |
| 54 | ```html |
| 55 | <!-- height calc @ppt-chart-height=560: default 900 canvas example; content slot = 900 - 48(p-6) - 68(title) - 24(gap-6) - 28(h3) - 8(gap-2) - 32(reserve) = 692 (chart + support area); support rail = 132; chart slot = 692 - 132 = 560 -> h-[560px] --> |
| 56 | <div class="ppt-chart-frame relative h-[560px] w-full overflow-hidden"> |
| 57 | <canvas id="my-chart" class="h-full w-full"></canvas> |
| 58 | </div> |
| 59 | ``` |
| 60 | |
| 61 | The final number in the comment and `h-[Npx]` MUST match. If the comment ends with `chart height = 420`, the div MUST say `h-[420px]`; never write `chart height = 420` and then use `h-[240px]`. |
| 62 | |
| 63 | Use this exact comment structure for generated charts: |
| 64 | |
| 65 | ```html |
| 66 | <!-- height calc @ppt-chart-height=[final]: content slot = [current canvas height - ... - reserve] = [content slot]; support = [support height]; chart slot = [content slot - support] = [chart slot]; chart height = [role decision] = [final] --> |
| 67 | <!-- Example after replacing placeholders: height calc @ppt-chart-height=560: chart slot = 560; chart height = hero/main = 560 --> |
| 68 | <div class="ppt-chart-frame relative h-[560px] w-full overflow-hidden"> |
| 69 | ``` |
| 70 | |
| 71 | Calculation steps: |
| 72 | 1. Start from the current canvas height stated by the layout/canvas prompt (runtime page root has no default padding) |
| 73 | 2. Subtract outer padding (p-6=48, p-8=64) |
| 74 | 3. Subtract all modules above the chart: title, subtitle, metrics row, legends |
| 75 | 4. Subtract all gaps between modules |
| 76 | 5. If chart is inside a card: subtract card padding and card title |
| 77 | 6. Subtract a 24-40px safety reserve (use 40px on dense data slides) |
| 78 | 7. This gives the **content slot** for the chart zone. |
| 79 | 8. Subtract only sibling modules stacked above/below the chart inside the same column or vertical zone. Side-by-side modules in other columns share width, not height; do **not** divide the content slot by column count, and do not subtract a left metric rail from a right-column chart height. |
| 80 | 9. Choose the chart frame height from the chart slot (do not stop short and leave an empty band): |
| 81 | - Hero/main chart (dominant zone): 380–560px only when the chart is the primary evidence |
| 82 | - Standard chart beside/under a compact support set: 280–360px, with an actual nonzero gap around independent support modules |
| 83 | - Compact supporting chart (one small module in a dense layout): 220–280px, with other modules kept concise |
| 84 | - If the computed chart slot is 600px+ and the chart is the primary evidence, use the top of the hero/main range (usually 520–560px). Do not calculate a 600+ slot and then choose 340px for the primary chart. |
| 85 | 10. If the chart slot is below the space needed for its labels, axes, and intended reading distance (often around 220px on a 1600×900 canvas), redesign the chart/support relationship and run the layout width/height self-check again. |
| 86 | |
| 87 | Column budget rule: columns share width, not height. If the page uses `grid-cols-2`, the chart column still receives the full post-title vertical content slot. A bad calc is `content slot = 732; left metrics = 732/2; right side = 366`; the correct calc is `right column content slot = 732`, then subtract only the right-column heading, insight card, gaps, padding, and reserve. |
| 88 | |
| 89 | Avoid a two-row bottom card grid when it competes with a standard/tall chart. If the slide has 4-6 additional facts, choose in-chart annotations, an evidence rail, a compact table, a grouped list, or a compact aligned data mosaic with an explicit budget. A main chart usually starts with 0-2 support items; a larger set is valid when the chart remains dominant and the reading path stays clear. |
| 90 | |
| 91 | Axis-heavy charts need extra space. For horizontal bars with 6+ categories, long labels, negative+positive ranges, or wide tick labels such as percentages, reserve 40-60px inside the chart options for the x-axis/tick area (`layout.padding.bottom`, tick padding, and a modest `maxTicksLimit`). If that would push support modules into a second row, redesign the support area as a side rail, annotation band, compact table, or in-chart callouts instead of shrinking the plot. |
| 92 | |
| 93 | Only the `.ppt-chart-frame` owns chart size. The `<canvas>` uses `class="h-full w-full"` and must not have `width`, `height`, or inline `style` size attributes in generated HTML. |
| 94 | |
| 95 | ### Data semantics — one axis, one meaning |
| 96 | |
| 97 | Do not mix units or meanings in a single Chart.js dataset or value axis. A bar chart whose x-axis is "变化率 %" must contain only percentages; do not put headcount values such as `850` or `1400` into that same dataset. If the source has both absolute counts and percent changes, choose one expression: |
| 98 | |
| 99 | - **Counts story**: grouped bars for 2022 vs 2026 headcount; put percent change in tooltips, labels, or a compact insight rail. |
| 100 | - **Change-rate story**: bars for comparable percentage changes only; represent "new role / 0 → 850" as an annotation or separate card, not as `850` on the percent axis. |
| 101 | |
| 102 | Chart.js category labels are plain text. Do not put HTML such as `<br>`, `<span>`, or inline styles inside `data.labels`; Chart.js will draw that HTML literally or mis-measure it. For multi-line category labels, use string-array labels (e.g. `['AI调校师', '约80→1,400']`) or keep details in tooltip callbacks / nearby annotations. |
| 103 | |
| 104 | ### Chart slides need interpretation |
| 105 | |
| 106 | A chart-only slide is usually under-explained even if the chart is large. Pair the main chart with one visible takeaway sentence and, when useful, concise annotations, an insight rail, or a source/note line. These support modules explain how to read the chart; they must not repeat every bar/table row as equal-weight cards. If the source has rich context, use the support area for "so what", caveat, baseline, or implication rather than more labels. |
| 107 | |
| 108 | Bad patterns to avoid: |
| 109 | |
| 110 | ```html |
| 111 | <!-- height calc: current canvas height - 48(...) = available content slot --> |
| 112 | <div class="ppt-chart-frame relative h-[400px]">...</div> |
| 113 | |
| 114 | <div class="ppt-chart-frame relative h-64">...</div> |
| 115 | |
| 116 | <canvas id="chart" width="320" height="380" style="height: 240px"></canvas> |
| 117 | |
| 118 | <!-- Mixed units on one percentage axis: 850 people, 1650%, and 17.9% are not comparable --> |
| 119 | data: { labels: ['AI叙事设计师', 'AI调校师', '原画师'], datasets: [{ label: '变化率', data: [850, 1650, 17.9] }] } |
| 120 | |
| 121 | <!-- Chart.js labels are not HTML --> |
| 122 | labels: ['AI调校师<br><span>约80→1,400</span>'] |
| 123 | ``` |
| 124 | |
| 125 | ### 2. JavaScript — always use DOMContentLoaded + PPT.createChart |
| 126 | |
| 127 | ```html |
| 128 | <script> |
| 129 | document.addEventListener('DOMContentLoaded', function() { |
| 130 | PPT.createChart(document.getElementById('my-chart'), { |
| 131 | type: 'bar', |
| 132 | data: { |
| 133 | labels: ['A', 'B', 'C'], |
| 134 | datasets: [{ |
| 135 | label: 'Revenue', |
| 136 | data: [10, 20, 30], |
| 137 | backgroundColor: ['#3B82F6', '#10B981', '#F59E0B'] |
| 138 | }] |
| 139 | }, |
| 140 | options: { |
| 141 | responsive: true, |
| 142 | maintainAspectRatio: false, |
| 143 | plugins: { |
| 144 | legend: { position: 'bottom' } |
| 145 | }, |
| 146 | scales: { |
| 147 | y: { beginAtZero: true } |
| 148 | } |
| 149 | } |
| 150 | }); |
| 151 | }); |
| 152 | </script> |
| 153 | ``` |
| 154 | |
| 155 | This is the only correct event and the only correct API. The runtime loads Chart.js before `DOMContentLoaded` fires, so the helper is always available inside this callback. |
| 156 | |
| 157 | ### Complete working example |
| 158 | |
| 159 | ```html |
| 160 | <div class="grid grid-cols-2 gap-4"> |
| 161 | <div class="flex flex-col gap-2"> |
| 162 | <h3 class="text-2xl font-bold">Quarterly Revenue</h3> |
| 163 | <p class="text-lg text-gray-500">Growth trend across regions</p> |
| 164 | </div> |
| 165 | <!-- height calc @ppt-chart-height=560: default 900 canvas example; page content slot = 900 - 48(p-6) - 68(title/subtitle) - 24(gap-6) - 32(reserve) = 728; two columns share width, not height; right-column heading/support = 168; chart slot = 728 - 168 = 560; chart height = hero/main side chart = 560 --> |
| 166 | <div class="ppt-chart-frame relative h-[560px] w-full overflow-hidden"> |
| 167 | <canvas id="revenue-chart" class="h-full w-full"></canvas> |
| 168 | </div> |
| 169 | </div> |
| 170 | <script> |
| 171 | document.addEventListener('DOMContentLoaded', function() { |
| 172 | PPT.createChart(document.getElementById('revenue-chart'), { |
| 173 | type: 'bar', |
| 174 | data: { |
| 175 | labels: ['Q1', 'Q2', 'Q3', 'Q4'], |
| 176 | datasets: [{ |
| 177 | label: 'Revenue (M)', |
| 178 | data: [12, 19, 15, 22], |
| 179 | backgroundColor: '#3B82F6' |
| 180 | }] |
| 181 | }, |
| 182 | options: { |
| 183 | responsive: true, |
| 184 | maintainAspectRatio: false, |
| 185 | plugins: { legend: { display: false } }, |
| 186 | scales: { y: { beginAtZero: true } } |
| 187 | } |
| 188 | }); |
| 189 | }); |
| 190 | </script> |
| 191 | ``` |
| 192 | |
| 193 | ## Hard rules |
| 194 | |
| 195 | - Use `PPT.createChart(canvasElement, config)` — pass the canvas DOM element, not a 2D context. |
| 196 | - Wrap every `PPT.createChart` call inside `document.addEventListener('DOMContentLoaded', function() { ... })`. |
| 197 | - Put category labels in `data.labels` as plain strings or string arrays. If a category-axis `ticks.callback` is needed, return `this.getLabelForValue(value)`. |
| 198 | - Derive chart frame height from the layout budget (current canvas height minus all other modules and a 24-40px safety reserve), then choose a height that fits the chart role. Do not blindly use all leftover height. |
| 199 | - Every generated `.ppt-chart-frame` needs the height calc comment immediately before it. |
| 200 | - Do not add padding to the `.ppt-chart-frame` div — it wastes height budget without visual benefit. Padding belongs on the parent card/container, not on the chart frame itself. |
| 201 | - Do not put `width`, `height`, or inline `style` size attributes on `<canvas>`; the chart frame controls the size. |
| 202 | - Keep chart code local and deterministic. |
| 203 | |
| 204 | ## Failure repair strategy |
| 205 | |
| 206 | When a chart is blank or broken: |
| 207 | |
| 208 | 1. **Check the event**: the script must use `DOMContentLoaded`. Any other event name (ppt-ready, ppt-rendered, ppt-page-ready, load, etc.) will not fire or fire too early. |
| 209 | 2. **Check the canvas id**: the `getElementById` string must match the canvas `id` attribute exactly. |
| 210 | 3. **Check the height**: the chart frame `h-[Npx]` must be a positive number. A missing or zero height produces an invisible canvas. |
| 211 | 4. **Check the data format**: labels must be an array of plain strings/string arrays (no HTML), datasets an array of objects with a `data` array of numbers using one unit/meaning per value axis. |
| 212 | 5. **Remove duplicate scripts**: if editing a page that already has a chart, merge scripts rather than adding a second `DOMContentLoaded` listener for the same canvas. |
| 213 | |
| 214 | ## Chart animation boundary |
| 215 | |
| 216 | Two levels of chart animation, each handled by a different system: |
| 217 | |
| 218 | - **Chart container entrance** (the whole chart block fading/sliding in): add `data-anim` on the `.ppt-chart-frame` div. This is a standard layout animation — see animation skill. |
| 219 | - **Chart internal drawing** (bars growing, lines drawing, pie slices rotating): controlled by Chart.js `options.animation`. The runtime defaults handle this; you rarely need to customize it. |
| 220 | - **Do not** write custom JS timelines that animate individual chart elements. Use `data-anim` for the container, and Chart.js options for the internals. |
| 221 | |
| 222 | ## Cross-skill references |
| 223 | |
| 224 | - Budget chart height from the current slide height (see layout skill). Title + modules + gaps + chart frame + 24-40px reserve <= current canvas height. |
| 225 | - Chart container entrance animation uses `data-anim` on the chart frame div (see animation skill). |
| 226 |