v3.0.0 to v3.0.1

---

name: chart

description: Interactive web-based charts for data analysis and business intelligence. Project-based output in output/chart-html/<project>/ with HTML + script + data + screenshot.

metadata:

starchild:

emoji: "📊"

skillKey: chart

user-invocable: true

disable-model-invocation: false

---

# Chart — Project-Based Interactive Charting

Generate interactive chart pages with Apache ECharts. Each chart lives in a dedicated project folder under `output/chart-html/`, making it easy to reuse and iterate.

## When to Use

Any time the user wants a visual chart: price charts, comparisons, dashboards, business analytics, etc.

## Architecture

- **ECharts** (CDN) for rendering

- **ECharts native export (`getDataURL`) + canvas merge** for reliable PNG output

- **Project-based storage**: one folder per chart project

- **No gallery mode**: all artifacts stay in the project folder

## Project Structure (Required)

Each chart project should follow:

```

output/chart-html/

<project-name>/

index.html # chart page

generate.py # generation script (for reproducibility)

README.md # title / description / data source notes

data.json # data snapshot

screenshot.png # saved image

```

Example folder name: `btc-90d-20260401`

## Workflow

### Step 1: Pick template or custom layout

Available templates:

| Template | Best for |

|---|---|

| `line.html` | Time-series trends, multi-series comparisons |

| `bar.html` | Category comparisons, rankings |

| `pie.html` | Composition / share breakdown |

| `candlestick.html` | OHLCV price charts |

| `scatter.html` | Correlation, distribution |

| `dashboard.html` | KPI cards + 2×2 multi-chart grid |

| `radar.html` | Multi-dimension scoring |

| `heatmap.html` | Matrix / calendar intensity |

| `dual-axis.html` | Two series with very different scales (e.g. market cap vs stablecoin supply) — left and right Y axes, each with its own label color |

| `multi-panel.html` | Stacked panels sharing one X axis (e.g. price + volume + RSI) — single ECharts instance, tooltip/zoom synced across all panels |

| `waterfall.html` | Incremental contribution breakdown (e.g. P&L attribution, budget variance) — positive/negative bars stacked on a floating base |

### Step 2: Create project folder

Use `create_project(name, description, data_sources)` from `scripts/build_chart.py`.

### Step 3: Build and save chart page

Use either:

- `build_chart(template_name, ...)`

- `build_chart_custom(...)`

Then save as `index.html` in the project folder:

- `save_chart(html, project_dir=project_dir)`

### Step 4: Save reproducible assets

Also save:

- `save_generate_script(script_content, project_dir)` → `generate.py`

- `save_data(data, project_dir)` → `data.json`

- project README is created by `create_project(...)`

### Step 5: Serve preview

Use project-root serving (recommended):

```python

preview_serve(

title="Chart Preview",

dir="skills/chart/scripts",

command="python3 chart_server.py /data/workspace/output/chart-html 7860",

port=7860

)

```

Then open: `/preview/<id>/<project-name>/index.html`

### Step 6: Export image

Two modes:

1. **User wants web page + image**: click "💾 Save Image" in page toolbar, saves to current project as `screenshot.png`

2. **User wants image only**: call `screenshot_chart(project_dir)` (Playwright) and send `screenshot.png` directly

## Toolbar Requirements

Every chart page must include these buttons:

```html

<div class="actions">

<button onclick="downloadPNG(this)">📥 Download PNG</button>

<button onclick="copyToClipboard(this)">📋 Copy Image</button>

<button onclick="saveToProject(this)">💾 Save Image</button>

</div>

```

Do not include gallery entry.

## Key Files

| File | Purpose |

|------|---------|

| `skills/chart/scripts/base-styles.css` | Base dark theme CSS |

| `skills/chart/scripts/base-export.js` | Export helpers: download/copy/save-to-project |

| `skills/chart/scripts/build_chart.py` | Project creation, HTML build, data/script save, screenshot |

| `skills/chart/scripts/chart_server.py` | Static server + `/save-chart` API |

| `skills/chart/templates/*.html` | Reusable chart templates |

| `output/chart-html/<project>/*` | All generated chart artifacts |

## Notes

- Embed data directly in HTML (`const DATA = ...`) to avoid iframe CORS issues.

- For multi-chart pages, register all chart instances in `window.CHART_INSTANCES`.

- Use meaningful project names (`topic-range-date`) for easy lookup.