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