graphic-chart
Generates data visualization charts as PNG. Renders HTML with Apache ECharts v6 in headless Chromium via Playwright → screenshots at 2× retina quality.
CDN: https://cdn.jsdelivr.net/npm/echarts@6.0.0/dist/echarts.min.js
Critical Rules (read before every generation)
area type → type: 'line' + areaStyle: {} — ECharts has no type: 'area'.doughnut → type: 'pie' + radius: ['40%', '70%'] — ECharts has no type: 'doughnut'.- Readiness signal: register
chart.on('finished', fn) BEFORE chart.setOption() — ECharts bug #14101/#17500: if listener is registered after setOption, it silently never fires. Always register both finished and rendered events before setOption.
xAxis.type: 'category' must be explicit — ECharts does not infer it from the data. Forgetting this produces a blank chart.- Category labels go in
xAxis.data, not in a data.labels array. ECharts structure is flat: { xAxis, yAxis, series, grid, title, legend } — not nested under data or options.
- Data labels are fully built-in — use
label: { show: true } on any series. No plugin needed.
- Highlight a specific bar/point via per-item
itemStyle — put { value: N, itemStyle: { color: '#...' } } directly in the data array. Do NOT use Chart.js-style backgroundColor arrays.
- ECharts init uses a
<div> container, not <canvas> — echarts.init(document.getElementById('chart')). The container div needs explicit dimensions.
animation: false in option — disables animation for instant render. Still register finished + rendered events before setOption for the readiness signal.- Never dump HTML in chat. Save to file, show summary only.
- Title states the insight, not the subject. "Revenue grew 3× in 12 months" not "Monthly Revenue".
- Pie/doughnut: use body
padding: 64px 80px and .chart-container { max-height: 860px } — prevents edge-to-edge fill when no title.
Step 1: Intake
Required: chart_type, data
Optional parameters and defaults:
| Parameter |
Default |
Description |
| chart_type |
— |
bar / line / area / pie / doughnut / scatter / radar / treemap |
| data |
— |
JSON array or CSV — required |
| title |
— |
States the insight, ≤10 words |
| subtitle |
— |
1-sentence context line |
| style |
clean-slate |
clean-slate / midnight-editorial / matt-gray / electric-burst / brutalist |
| dimensions |
1080x1080 |
WxH pixels (output PNG = 2× via deviceScaleFactor) |
| x_label |
— |
X-axis label text |
| y_label |
— |
Y-axis label text |
| source |
— |
Data source shown in footer |
| highlight |
— |
Data label to highlight (e.g. "Q4", "Dec", index 3) |
If chart_type or data is missing, ask exactly:
"To create the chart, I need:
- Chart type — bar / line / area / pie / doughnut / scatter / radar / treemap
- Data — provide as JSON array or CSV (e.g.
[12, 18, 22, 25, 31] with labels ['Q1','Q2','Q3','Q4','Q5'])
Optional: title, style (default: clean-slate), dimensions (default: 1080×1080), highlight a specific data point"
If both present → skip to Step 2.
Step 2: Internal Architecture (never shown to user)
1. Normalize chart type:
area → line + areaStyle: {} on seriesdoughnut → pie + radius: ['40%', '70%'] on serieshorizontal bar → bar + swap xAxis/yAxis (category axis on y)- All others: use as-is
2. Read references/chart-library.md — load full config spec for this chart type.
3. Read references/style-presets.md — load CSS tokens + data palette for chosen style.
4. Commit to design direction:
| Decision |
Derive from |
| Tone |
Professional / editorial / bold / technical — match the data's audience |
| Data story |
Single insight this chart proves (becomes the title) |
| Highlight strategy |
Which data point needs visual emphasis and why? |
| Background |
Light (clean-slate, matt-gray) or dark (midnight-editorial, electric-burst, brutalist) |
5. Parse data:
- Simple array
[12, 18, 22] → series.data, labels provided separately
- Object array
[{x: 'Jan', y: 12}] → xAxis.data from x keys, series.data from y values
- CSV: parse header row as xAxis.data, value row as series.data
- Multi-series: multiple
series entries each with type, name, data
- Scatter:
series.data: [[x1,y1], [x2,y2], ...] format
6. Parse dimensions: "1080x1080" → W=1080, H=1080. Body = WxH. Output PNG = 2W × 2H.
Step 3: HTML Generation
Read ALL before generating:
references/chart-library.md for this chart type's full ECharts config specreferences/style-presets.md for the chosen style's CSS tokens + palette
Required HTML structure:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
[font CDN link from style preset]
<style>
:root {
[all CSS tokens from style preset]
}
*, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
html, body {
width: [W]px; height: [H]px;
overflow: hidden;
background: var(--bg);
font-family: var(--font-body);
}
body {
display: flex;
flex-direction: column;
padding: 40px 48px 32px; /* pie/doughnut: use 64px 80px */
}
/* ECharts container must have explicit size */
.chart-container {
flex: 1;
min-height: 0;
/* pie/doughnut only: max-height: 860px; */
}
.chart-header { margin-bottom: 24px; }
.chart-title {
font-family: var(--font-display);
font-size: clamp(1.1rem, 2.5vw, 1.6rem);
font-weight: 700;
color: var(--text);
line-height: 1.2;
}
.chart-subtitle {
font-family: var(--font-body);
font-size: clamp(0.75rem, 1.2vw, 0.9rem);
color: var(--text-muted);
margin-top: 6px;
line-height: 1.5;
}
.chart-footer {
margin-top: 14px;
font-family: var(--font-body);
font-size: 10px;
color: var(--text-muted);
opacity: 0.65;
}
</style>
</head>
<body>
[if title or subtitle: <div class="chart-header"><div class="chart-title">...</div>...</div>]
<div id="chart" class="chart-container"></div>
[if source: <div class="chart-footer">Source: [source]</div>]
<script src="https://cdn.jsdelivr.net/npm/echarts@6.0.0/dist/echarts.min.js"></script>
<script>
window.__chartReady = false;
document.fonts.ready.then(() => {
const container = document.getElementById('chart');
const chart = echarts.init(container, null, { renderer: 'canvas' });
// CRITICAL: register events BEFORE setOption — ECharts bug #14101/#17500
// 'finished' may silently not fire if registered after setOption with animation:false
chart.on('finished', () => {
window.__chartReady = true;
});
// Belt-and-suspenders fallback via 'rendered'
chart.on('rendered', () => {
clearTimeout(window.__renderDebounce);
window.__renderDebounce = setTimeout(() => { window.__chartReady = true; }, 100);
});
const palette = [palette from style preset];
const option = {
animation: false, // instant render for screenshot
backgroundColor: 'transparent', // body CSS handles bg color
textStyle: {
fontFamily: '[--font-body value]',
color: '[--text-muted value]',
},
[title config if title param provided],
[legend config per chart type],
[grid config per chart type],
[xAxis config per chart type],
[yAxis config per chart type],
series: [{
[full series config from chart-library.md for this type]
[palette colors applied per chart type]
[if highlight: per-item itemStyle on the highlighted data point]
}]
};
chart.setOption(option); // setOption ALWAYS comes after event registration
});
</script>
</body>
</html>
Design quality rules:
- Title font:
fontWeight: 'bold', fontSize: 20–24 — no thin titles
- Grid lines: low opacity (0.06–0.10) — subordinate to data
- Bars:
barMaxWidth: 60, rounded via itemStyle.borderRadius: [4,4,0,0]
- Lines:
smooth: true for natural curves, symbolSize: 8 for points
- Pie/doughnut:
label.formatter: '{b}\n{d}%' for built-in on-slice labels
- Dark presets: grid
rgba(255,255,255,0.07), axis line/tick color rgba(255,255,255,0.15)
- Tooltip:
show: false — static PNG, no hover interaction
- When no title provided: skip
.chart-header, omit title from ECharts option
Step 4: Self-QA (fix every failure before Step 5)
Structure:
Type-specific:
Design:
Step 5: Export
Determine slug from title or chart type + data context (kebab-case, ≤30 chars):
mkdir -p chart/[slug]
Save HTML: chart/[slug]/chart.html
Quick browser check:
open chart/[slug]/chart.html
Run export (replace [skill-root] with actual path to this skill's directory):
bash [skill-root]/scripts/export-chart.sh \
chart/[slug]/chart.html \
chart/[slug]/chart.png \
--width [W] \
--height [H]
The script installs Playwright on first run (~200MB Chromium download), then captures the chart at deviceScaleFactor: 2.
Step 6: Output Summary
## Chart: [title]
Date: [YYYY-MM-DD] | Type: [chart_type] | Style: [style]
Dimensions: [W×H]px → PNG: [2W×2H]px @2× retina
Files
Source: chart/[slug]/chart.html
Output: chart/[slug]/chart.png
Size: [X] KB
Checklist
- [ ] Title states the insight clearly
- [ ] Data labels legible at display size
- [ ] Highlight visible on correct data point
- [ ] Source attribution present in footer
Prompt Tips (show when user asks for guidance)
"Provide structured data — JSON or CSV, not prose descriptions."
"Name the chart type explicitly. 'bar chart comparing Q1–Q4' not 'a chart showing quarters'."
"Specify the data story. 'highlight Q4 which outperformed all others' gives the annotation context."
✅ Good: "Create a line chart. Title: 'From $12k to $95k ARR in 12 Months'. Data: [12, 18, 22, 25, 31, 38, 44, 52, 61, 68, 78, 95] (Jan–Dec 2024). Highlight December. Source: Internal CRM. Style: electric-burst."
❌ Bad: "make a chart about our company growth"
1---2name: graphic-chart3description: Generates data visualization charts (bar, line, area, pie, doughnut, scatter, radar, treemap) as PNG using Apache ECharts v6. 1080×1080px default, 5 style presets, highlight annotations. Trigger when user says "create a chart", "visualize data", "make a bar chart", "line graph", "pie chart", "data visualization", "chart this data", "plot", "graph", or "visualize these numbers".4---5
6# graphic-chart
7
8Generates data visualization charts as PNG. Renders HTML with Apache ECharts v6 in headless Chromium via Playwright → screenshots at 2× retina quality.
9
10CDN: `https://cdn.jsdelivr.net/npm/echarts@6.0.0/dist/echarts.min.js`
11
12---
13
14## Critical Rules (read before every generation)
15
161. **`area` type → `type: 'line'` + `areaStyle: {}`** — ECharts has no `type: 'area'`.
172. **`doughnut` → `type: 'pie'` + `radius: ['40%', '70%']`** — ECharts has no `type: 'doughnut'`.
183. **Readiness signal: register `chart.on('finished', fn)` BEFORE `chart.setOption()`** — ECharts bug #14101/#17500: if listener is registered after setOption, it silently never fires. Always register both `finished` and `rendered` events before setOption.
194. **`xAxis.type: 'category'` must be explicit** — ECharts does not infer it from the data. Forgetting this produces a blank chart.
205. **Category labels go in `xAxis.data`**, not in a `data.labels` array. ECharts structure is flat: `{ xAxis, yAxis, series, grid, title, legend }` — not nested under `data` or `options`.
216. **Data labels are fully built-in** — use `label: { show: true }` on any series. No plugin needed.
227. **Highlight a specific bar/point via per-item `itemStyle`** — put `{ value: N, itemStyle: { color: '#...' } }` directly in the `data` array. Do NOT use Chart.js-style `backgroundColor` arrays.
238. **ECharts init uses a `<div>` container, not `<canvas>`** — `echarts.init(document.getElementById('chart'))`. The container div needs explicit dimensions.
249. **`animation: false` in option** — disables animation for instant render. Still register `finished` + `rendered` events before setOption for the readiness signal.
2510. **Never dump HTML in chat.** Save to file, show summary only.
2611. **Title states the insight, not the subject.** "Revenue grew 3× in 12 months" not "Monthly Revenue".
2712. **Pie/doughnut: use body `padding: 64px 80px` and `.chart-container { max-height: 860px }`** — prevents edge-to-edge fill when no title.
28
29---
30
31## Step 1: Intake
32
33**Required:** `chart_type`, `data`
34
35**Optional parameters and defaults:**
36
37| Parameter | Default | Description |
38|---|---|---|
39| chart_type | — | bar / line / area / pie / doughnut / scatter / radar / treemap |
40| data | — | JSON array or CSV — required |
41| title | — | States the insight, ≤10 words |
42| subtitle | — | 1-sentence context line |
43| style | clean-slate | clean-slate / midnight-editorial / matt-gray / electric-burst / brutalist |
44| dimensions | 1080x1080 | WxH pixels (output PNG = 2× via deviceScaleFactor) |
45| x_label | — | X-axis label text |
46| y_label | — | Y-axis label text |
47| source | — | Data source shown in footer |
48| highlight | — | Data label to highlight (e.g. "Q4", "Dec", index 3) |
49
50**If `chart_type` or `data` is missing, ask exactly:**
51
52> "To create the chart, I need:
53> 1. **Chart type** — bar / line / area / pie / doughnut / scatter / radar / treemap
54> 2. **Data** — provide as JSON array or CSV (e.g. `[12, 18, 22, 25, 31]` with labels `['Q1','Q2','Q3','Q4','Q5']`)
55>
56> Optional: title, style (default: clean-slate), dimensions (default: 1080×1080), highlight a specific data point"
57
58If both present → skip to Step 2.
59
60---
61
62## Step 2: Internal Architecture (never shown to user)
63
64**1. Normalize chart type:**
65- `area` → `line` + `areaStyle: {}` on series
66- `doughnut` → `pie` + `radius: ['40%', '70%']` on series
67- `horizontal bar` → `bar` + swap xAxis/yAxis (category axis on y)
68- All others: use as-is
69
70**2. Read `references/chart-library.md`** — load full config spec for this chart type.
71
72**3. Read `references/style-presets.md`** — load CSS tokens + data palette for chosen style.
73
74**4. Commit to design direction:**
75
76| Decision | Derive from |
77|---|---|
78| Tone | Professional / editorial / bold / technical — match the data's audience |
79| Data story | Single insight this chart proves (becomes the title) |
80| Highlight strategy | Which data point needs visual emphasis and why? |
81| Background | Light (clean-slate, matt-gray) or dark (midnight-editorial, electric-burst, brutalist) |
82
83**5. Parse data:**
84- Simple array `[12, 18, 22]` → series.data, labels provided separately
85- Object array `[{x: 'Jan', y: 12}]` → xAxis.data from x keys, series.data from y values
86- CSV: parse header row as xAxis.data, value row as series.data
87- Multi-series: multiple `series` entries each with `type`, `name`, `data`
88- Scatter: `series.data: [[x1,y1], [x2,y2], ...]` format
89
90**6. Parse dimensions:** `"1080x1080"` → W=1080, H=1080. Body = WxH. Output PNG = 2W × 2H.
91
92---
93
94## Step 3: HTML Generation
95
96Read ALL before generating:
97- `references/chart-library.md` for this chart type's full ECharts config spec
98- `references/style-presets.md` for the chosen style's CSS tokens + palette
99
100**Required HTML structure:**
101
102```html
103<!DOCTYPE html>
104<html lang="en">
105<head>
106<meta charset="UTF-8">
107[font CDN link from style preset]
108<style>
109:root {
110 [all CSS tokens from style preset]
111}
112
113*, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
114html, body {
115 width: [W]px; height: [H]px;
116 overflow: hidden;
117 background: var(--bg);
118 font-family: var(--font-body);
119}
120body {
121 display: flex;
122 flex-direction: column;
123 padding: 40px 48px 32px; /* pie/doughnut: use 64px 80px */
124}
125
126/* ECharts container must have explicit size */
127.chart-container {
128 flex: 1;
129 min-height: 0;
130 /* pie/doughnut only: max-height: 860px; */
131}
132
133.chart-header { margin-bottom: 24px; }
134.chart-title {
135 font-family: var(--font-display);
136 font-size: clamp(1.1rem, 2.5vw, 1.6rem);
137 font-weight: 700;
138 color: var(--text);
139 line-height: 1.2;
140}
141.chart-subtitle {
142 font-family: var(--font-body);
143 font-size: clamp(0.75rem, 1.2vw, 0.9rem);
144 color: var(--text-muted);
145 margin-top: 6px;
146 line-height: 1.5;
147}
148.chart-footer {
149 margin-top: 14px;
150 font-family: var(--font-body);
151 font-size: 10px;
152 color: var(--text-muted);
153 opacity: 0.65;
154}
155</style>
156</head>
157<body>
158
159[if title or subtitle: <div class="chart-header"><div class="chart-title">...</div>...</div>]
160
161<div id="chart" class="chart-container"></div>
162
163[if source: <div class="chart-footer">Source: [source]</div>]
164
165<script src="https://cdn.jsdelivr.net/npm/echarts@6.0.0/dist/echarts.min.js"></script>
166
167<script>
168window.__chartReady = false;
169
170document.fonts.ready.then(() => {
171 const container = document.getElementById('chart');
172 const chart = echarts.init(container, null, { renderer: 'canvas' });
173
174 // CRITICAL: register events BEFORE setOption — ECharts bug #14101/#17500
175 // 'finished' may silently not fire if registered after setOption with animation:false
176 chart.on('finished', () => {
177 window.__chartReady = true;
178 });
179 // Belt-and-suspenders fallback via 'rendered'
180 chart.on('rendered', () => {
181 clearTimeout(window.__renderDebounce);
182 window.__renderDebounce = setTimeout(() => { window.__chartReady = true; }, 100);
183 });
184
185 const palette = [palette from style preset];
186
187 const option = {
188 animation: false, // instant render for screenshot
189
190 backgroundColor: 'transparent', // body CSS handles bg color
191
192 textStyle: {
193 fontFamily: '[--font-body value]',
194 color: '[--text-muted value]',
195 },
196
197 [title config if title param provided],
198 [legend config per chart type],
199 [grid config per chart type],
200 [xAxis config per chart type],
201 [yAxis config per chart type],
202
203 series: [{
204 [full series config from chart-library.md for this type]
205 [palette colors applied per chart type]
206 [if highlight: per-item itemStyle on the highlighted data point]
207 }]
208 };
209
210 chart.setOption(option); // setOption ALWAYS comes after event registration
211});
212</script>
213</body>
214</html>
215```
216
217**Design quality rules:**
218- Title font: `fontWeight: 'bold'`, `fontSize: 20–24` — no thin titles
219- Grid lines: low opacity (0.06–0.10) — subordinate to data
220- Bars: `barMaxWidth: 60`, rounded via `itemStyle.borderRadius: [4,4,0,0]`
221- Lines: `smooth: true` for natural curves, `symbolSize: 8` for points
222- Pie/doughnut: `label.formatter: '{b}\n{d}%'` for built-in on-slice labels
223- Dark presets: grid `rgba(255,255,255,0.07)`, axis line/tick color `rgba(255,255,255,0.15)`
224- Tooltip: `show: false` — static PNG, no hover interaction
225- When no title provided: skip `.chart-header`, omit title from ECharts option
226
227---
228
229## Step 4: Self-QA (fix every failure before Step 5)
230
231**Structure:**
232- [ ] Container is a `<div>`, not `<canvas>`
233- [ ] `window.__chartReady = false` declared before `document.fonts.ready`
234- [ ] `chart.on('finished', ...)` registered BEFORE `chart.setOption()`
235- [ ] `chart.on('rendered', ...)` debounce fallback registered BEFORE `chart.setOption()`
236- [ ] `animation: false` in option object
237- [ ] `chart.setOption(option)` is the LAST call in the init block
238
239**Type-specific:**
240- [ ] Area: `type: 'line'` + `areaStyle: {}` — no `type: 'area'`
241- [ ] Doughnut: `type: 'pie'` + `radius: ['40%', '70%']` — no `type: 'doughnut'`
242- [ ] Bar: `xAxis.type: 'category'` explicitly set
243- [ ] Category data in `xAxis.data` (not `data.labels`)
244- [ ] Pie/doughnut: body `padding: 64px 80px` + `.chart-container { max-height: 860px }`
245- [ ] Highlight: per-item `{ value: N, itemStyle: { color } }` in data array
246
247**Design:**
248- [ ] All palette colors from `references/style-presets.md`
249- [ ] Title states insight (not just subject)
250- [ ] `tooltip: { show: false }` or omitted (no hover on static PNG)
251- [ ] Dark preset: grid/axis colors use `rgba(255,255,255,...)`
252- [ ] Source in footer if `source` param provided
253- [ ] Data labels visible (built-in `label: { show: true }` on series)
254
255---
256
257## Step 5: Export
258
259Determine slug from title or chart type + data context (kebab-case, ≤30 chars):
260```bash
261mkdir -p chart/[slug]
262```
263
264Save HTML: `chart/[slug]/chart.html`
265
266Quick browser check:
267```bash
268open chart/[slug]/chart.html
269```
270
271Run export (replace `[skill-root]` with actual path to this skill's directory):
272```bash
273bash [skill-root]/scripts/export-chart.sh \
274 chart/[slug]/chart.html \
275 chart/[slug]/chart.png \
276 --width [W] \
277 --height [H]
278```
279
280The script installs Playwright on first run (~200MB Chromium download), then captures the chart at `deviceScaleFactor: 2`.
281
282---
283
284## Step 6: Output Summary
285
286```
287## Chart: [title]
288Date: [YYYY-MM-DD] | Type: [chart_type] | Style: [style]
289Dimensions: [W×H]px → PNG: [2W×2H]px @2× retina
290
291Files
292 Source: chart/[slug]/chart.html
293 Output: chart/[slug]/chart.png
294 Size: [X] KB
295
296Checklist
297- [ ] Title states the insight clearly
298- [ ] Data labels legible at display size
299- [ ] Highlight visible on correct data point
300- [ ] Source attribution present in footer
301```
302
303---
304
305## Prompt Tips (show when user asks for guidance)
306
307> "Provide structured data — JSON or CSV, not prose descriptions."
308>
309> "Name the chart type explicitly. 'bar chart comparing Q1–Q4' not 'a chart showing quarters'."
310>
311> "Specify the data story. 'highlight Q4 which outperformed all others' gives the annotation context."
312>
313> ✅ Good: "Create a line chart. Title: 'From $12k to $95k ARR in 12 Months'. Data: [12, 18, 22, 25, 31, 38, 44, 52, 61, 68, 78, 95] (Jan–Dec 2024). Highlight December. Source: Internal CRM. Style: electric-burst."
314>
315> ❌ Bad: "make a chart about our company growth"
Varnan-Tech