Varnan-Tech/opendirectory

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/[email protected]/dist/echarts.min.js

---

Critical Rules (read before every generation)

1. area type → type: 'line' + areaStyle: {} — ECharts has no type: 'area'.
2. doughnut → type: 'pie' + radius: ['40%', '70%'] — ECharts has no type: 'doughnut'.
3. 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.
4. xAxis.type: 'category' must be explicit — ECharts does not infer it from the data. Forgetting this produces a blank chart.
5. 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.
6. Data labels are fully built-in — use label: { show: true } on any series. No plugin needed.
7. 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.
8. ECharts init uses a <div> container, not <canvas> — echarts.init(document.getElementById('chart')). The container div needs explicit dimensions.
9. animation: false in option — disables animation for instant render. Still register finished + rendered events before setOption for the readiness signal.
10. Never dump HTML in chat. Save to file, show summary only.
11. Title states the insight, not the subject. "Revenue grew 3× in 12 months" not "Monthly Revenue".
12. 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:

1. Chart type — bar / line / area / pie / doughnut / scatter / radar / treemap
2. 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 series
• doughnut → pie + radius: ['40%', '70%'] on series
• horizontal 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 spec
• references/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/[email protected]/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:

• Container is a <div>, not <canvas>
• window.__chartReady = false declared before document.fonts.ready
• chart.on('finished', ...) registered BEFORE chart.setOption()
• chart.on('rendered', ...) debounce fallback registered BEFORE chart.setOption()
• animation: false in option object
• chart.setOption(option) is the LAST call in the init block

Type-specific:

• Area: type: 'line' + areaStyle: {} — no type: 'area'
• Doughnut: type: 'pie' + radius: ['40%', '70%'] — no type: 'doughnut'
• Bar: xAxis.type: 'category' explicitly set
• Category data in xAxis.data (not data.labels)
• Pie/doughnut: body padding: 64px 80px + .chart-container { max-height: 860px }
• Highlight: per-item { value: N, itemStyle: { color } } in data array

Design:

• All palette colors from references/style-presets.md
• Title states insight (not just subject)
• tooltip: { show: false } or omitted (no hover on static PNG)
• Dark preset: grid/axis colors use rgba(255,255,255,...)
• Source in footer if source param provided
• Data labels visible (built-in label: { show: true } on series)

---

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"