# Hive.chart Creation Foundations

Required reading whenever any chart_* tool is available.

- Repository: https://github.com/aden-hive/hive (11131 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aden-hive/hive --skill hive.chart-creation-foundations -g -a claude-code -y`
Codex: `npx skills add aden-hive/hive --skill hive.chart-creation-foundations -g -a codex -y`
Cursor: `npx skills add aden-hive/hive --skill hive.chart-creation-foundations -g -a cursor -y`
Gemini CLI: `npx skills add aden-hive/hive --skill hive.chart-creation-foundations -g -a gemini-cli -y`

## Description

Required reading whenever any chart_* tool is available. Teaches the one-tool embedding contract (call chart_render → live chart appears in chat AND a downloadable PNG lands in the queen session dir), the ECharts (data viz) vs Mermaid (structural diagrams) decision, the BI/financial-grade aesthetic baseline (no chartjunk, restrained palette, proper typography, single message per chart), and the canonical spec patterns for the 12 most-common chart types. Skipping this leads to 1990s-Excel charts, missing downloads, and the agent writing markdown image links by hand instead of letting chart_render drive the UI.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Chart creation foundations

These tools render BI/financial-analyst-grade charts and diagrams that show up live in the chat AND save as high-DPI PNGs in the user's queen session dir.

## The embedding contract, one rule

> **To put a chart in chat, call `chart_render`. The chat reads `result.spec` and renders the chart live in the message bubble. The download link is `result.file_url`. Do not write `![chart](...)` image markdown by hand, the tool's result drives the UI.**

That's it. One tool call, one chart in chat, one file on disk. No two-step "remember to also save it" pattern. The chat's chart-rendering UI is fed by the tool result envelope automatically.

## When to chart at all

Chart when the data is **visual at heart**: trends over time, distributions, comparisons across categories, hierarchies, flows, geo. Skip the chart when:

- The point is one number → just say it. ("Revenue was $4.2M, up 12% YoY.")
- The point is a ranking of 5 things → use a markdown table with bold and emoji indicators.
- The data is so noisy a chart would mislead → describe the takeaway in prose.

A chart costs the user attention. It must repay that cost with a takeaway they couldn't get from prose.

## ECharts vs Mermaid, the picking rule

| Use ECharts (`kind: "echarts"`) when... | Use Mermaid (`kind: "mermaid"`) when... |
|---|---|
| You're plotting **numbers over categories or time** | You're showing **structure, not data** |
| Bar / line / area / scatter / candlestick / heatmap / treemap / sankey / parallel coordinates / calendar / gauge / pie / sunburst / geo map | Flowchart / sequence / gantt / ERD / state diagram / mindmap / class diagram / C4 architecture |
| The viewer's question is "how much / how many / what's the trend" | The viewer's question is "what calls what / what depends on what / what happens after what" |

If both fit (rare), prefer ECharts, its rasterized output is a proper data chart for slides; Mermaid's diagrams are for technical docs.

The rest: https://github.com/aden-hive/hive/blob/HEAD/core/framework/skills/_preset_skills/chart-creation-foundations/SKILL.md