hive.chart-creation-foundations

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 aesthetic baseline (non-negotiable)

These are the rules that turn an Excel-default chart into a Tableau-grade one. Every chart you produce must follow them.

1. Theme & background

• chart_render has no theme parameter. The renderer reads the user's UI theme from the desktop env (HIVE_DESKTOP_THEME) so the saved PNG matches what the user is actually looking at. You don't pick; the system does.
• Title goes in option.title.text, NOT in the message body. The chart is self-contained.

2. Palette discipline — DO NOT set color on series

The OpenHive ECharts theme is auto-applied to every chart_render call. It defines:

• An 8-hue categorical palette for multi-series charts (honey orange, slate blue, sage, terracotta, bronze, indigo, olive, rust)
• Cozy spacing (grid.top: 90, grid.bottom: 56, etc.)
• Brand typography (Inter Tight)
• Tasteful axis lines + dashed gridlines

Do not set option.color, option.title.textStyle, option.grid, or option.itemStyle.color on series. The theme covers it. If you do override, you'll fight the brand palette and the chart will look generic.

When you need data-encoded color (NOT category color):

• Sequential (magnitude): use visualMap with inRange.color: ['#fff7e0', '#db6f02'] (light-to-honey)
• Diverging (positive/negative): use visualMap with inRange.color: ['#a8453d', '#f5f5f5', '#3d7a4a'] (terracotta/neutral/sage)
• Semantic up/down (candlestick is auto-themed): for explicit gain/loss bars use #3d7a4a (gain) and #a8453d (loss), NOT #27ae60 / #e74c3c.

3. Typography

The default font (-apple-system, "Inter Tight", system-ui) is already wired in the renderer — don't override unless the user asked. Set option.textStyle.fontSize: 13 for body labels, 16 for axis names, 18 bold for the title.

4. No chartjunk

• No 3D. Ever. 3D pie charts and 3D bar charts are visual lies.
• No drop shadows on bars or lines. The default flat ECharts look is correct.
• No gradient fills unless the gradient encodes data (e.g. heatmap fill).
• No neon colors. Saturation belongs on highlighted bars, not on every series.
• No more than 5 stacked colors in a stacked bar — past that the eye can't separate them.

5. Axis hygiene

• X-axis labels rotate 45° only when they overflow. Otherwise horizontal.
• Y-axis starts at 0 for bar/area charts (truncating misleads). Line charts can start at min - 5%.
• Use option.yAxis.axisLabel.formatter: '{value} M' to add units, NOT a separate "USD millions" subtitle.
• Date axes: pass ISO strings ("2024-01-15") and ECharts handles the layout. Use xAxis.type: "time".

6. One message per chart

Every chart goes in its own assistant message (or its own chart_render call). Do not pile 4 charts into one wall of tool calls — the user can't focus and the chat gets noisy.

Calling chart_render — the canonical pattern

chart_render(
  kind="echarts",
  spec={
    "title": {"text": "Q4 revenue by region", "left": "center"},
    "tooltip": {"trigger": "axis"},
    "xAxis": {"type": "category", "data": ["NA", "EU", "APAC", "LATAM"]},
    "yAxis": {"type": "value", "axisLabel": {"formatter": "${value}M"}},
    "series": [{"type": "bar", "data": [12.4, 8.7, 5.3, 2.1], "itemStyle": {"color": "#db6f02"}}]
  },
  title="q4-revenue-by-region",
  width=1600, height=900, dpi=300
)

Returns:

{
  "kind": "echarts",
  "spec": {...echoed...},
  "file_path": "/.../charts/2026-04-30T...q4-revenue-by-region.png",
  "file_url": "file:///.../q4-revenue-by-region.png",
  "width": 1600, "height": 900, "dpi": 300, "bytes": 142318,
  "title": "q4-revenue-by-region", "runtime_ms": 287
}

The chat panel reads result.spec and mounts ECharts in the message bubble. The user sees the chart immediately. The PNG is on disk and the chat shows a download link from result.file_url. You don't write that link — it appears automatically.

The 12 chart types you'll use 95% of the time

| When | ECharts type | Notes |

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

| Trend over time | series.type: "line" | Smooth = smooth: true only when data is noisy |

| Multi-metric trend | Two line series with yAxis: [{}, {}] | Separate scales when units differ |

| Category comparison | series.type: "bar" | Sort by value descending, not alphabetically |

| Stacked composition | bar with stack: "total" | Cap at 5 categories |

| Distribution | series.type: "boxplot" or bar of bins | Boxplot for ≥3 groups; histogram for one |

| Two-variable correlation | series.type: "scatter" | Add regression markline if relevant |

| Candlestick / OHLC | series.type: "candlestick" | Date axis + dataZoom range slider |

| Geo distribution | series.type: "map" | Bundled world and country GeoJSONs |

| Hierarchy / share | series.type: "treemap" or sunburst | Use treemap for >12 leaves; pie only for 2-5 |

| Flow | series.type: "sankey" | Names matter — keep them short |

| Calendar density | series.type: "heatmap" + calendar | Daily metrics over a year |

| KPI scorecard | series.type: "gauge" | Set min, max, threshold band |

Worked specs for each are in references/ — paste, modify, render.

Mermaid quick rules

chart_render(
  kind="mermaid",
  spec="""
flowchart LR
  A[Customer signs up] --> B{Onboarded?}
  B -- yes --> C[Activate trial]
  B -- no --> D[Email reminder]
""",
  title="signup-flow"
)

• One diagram per chart_render call.
• Keep node labels short (≤20 chars).
• Use flowchart LR for left-to-right; TD for top-down. LR reads better in a chat bubble.
• For sequence diagrams, indicate async with ->> (open arrow) and sync return with -->> (dashed).
• Don't try to encode data in mermaid (no widths, no quantities) — that's an ECharts job.

Common mistakes the agent makes

1. Writing ![chart](file://...) markdown by hand. Don't. The chat renders from the tool result automatically. Manual image markdown will display nothing (file:// is blocked from arbitrary chat content).
2. Calling chart_render twice for the same chart "to embed and to save". Only one call. The single call does both.
3. Overriding fonts to fancy display faces. Stay with the default; the agent's job is data, not typography.
4. Pie charts with 12 slices. Use a horizontal bar chart sorted by value. Pie is only for 2-5 mutually-exclusive shares.
5. Forgetting axisLabel.formatter for currency / percentage. A y-axis showing "12000000" is unreadable; "12M" is correct.
6. Putting a chart's title in the message body. Set option.title.text instead so the title is part of the saved PNG.