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 `` 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

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

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 `` 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.