Skip to content

aden-hive/hive / core/framework/skills/_preset_skills/chart-creation-foundations

hive.chart-creation-foundations

Verified

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.

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 timeYou're showing structure, not data
Bar / line / area / scatter / candlestick / heatmap / treemap / sankey / parallel coordinates / calendar / gauge / pie / sunburst / geo mapFlowchart / 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.

7. Notes and caveats live outside the plot

The theme fixes the grid, so there is no free space inside the chart for extra text. Text you add there lands on top of the axis name or the tick labels.

  • One short qualifier (under ~90 characters) can go in option.title.subtext. Never a second subtext line.
  • Do not add graphic text elements for footnotes, sources or exclusions. Put those in the message that carries the chart.
  • To flag a qualified data point, mark its category label ("Supabase*") and explain the asterisk in the message.
  • Show a missing value as a gap with (N/A) in its category label, not as a zero-length bar.

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

WhenECharts typeNotes
Trend over timeseries.type: "line"Smooth = smooth: true only when data is noisy
Multi-metric trendTwo line series with yAxis: [{}, {}]Separate scales when units differ
Category comparisonseries.type: "bar"Sort by value descending, not alphabetically
Stacked compositionbar with stack: "total"Cap at 5 categories
Distributionseries.type: "boxplot" or bar of binsBoxplot for ≥3 groups; histogram for one
Two-variable correlationseries.type: "scatter"Add regression markline if relevant
Candlestick / OHLCseries.type: "candlestick"Date axis + dataZoom range slider
Geo distributionseries.type: "map"Bundled world and country GeoJSONs
Hierarchy / shareseries.type: "treemap" or sunburstUse treemap for >12 leaves; pie only for 2-5
Flowseries.type: "sankey"Names matter — keep them short
Calendar densityseries.type: "heatmap" + calendarDaily metrics over a year
KPI scorecardseries.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.
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall