chart-spec

name

chart-spec

description

Render a small INTERACTIVE chart inline in the chat conversation (hover tooltips, legend, light/dark aware) by emitting a fenced ```chart block containing a JSON spec — no code execution, no image file. Use for a quick line/bar/area/scatter/pie of small tabular data (a few series, up to ~1000 rows) that you already have in the conversation and want the reader to hover and read. For publication-quality, complex, or scientific figures, or anything needing computation, use plots-and-diagrams (matplotlib, static image via code execution) instead.

Chart spec (interactive in-chat chart)

Emit a JSON chart spec in a fenced ```chart block. The frontend validates it and draws it with the app's own chart components (recharts + the brand --chart-* palette), so it matches the UI, gets hover tooltips and a legend, and recolors correctly in light and dark. No code runs — the block is data only.

When to use this vs a matplotlib figure

• This (chart-spec): you already have the numbers in the conversation, the dataset is small, and interactivity (hover to read exact values) helps. Fast, no sandbox, theme-aware, native look.
• plots-and-diagrams (matplotlib): you need to compute the data, the figure is complex/scientific/publication-grade, you want a downloadable 300-DPI image, or you need a chart type beyond line/bar/area/scatter/pie. That path renders a static image via code execution.

The block

Put ONLY the JSON inside the fence — no prose, no trailing comments:

```chart
{
  "type": "line",
  "title": "Weekly runs",
  "x": "week",
  "series": [
    { "key": "runs", "label": "Total runs" },
    { "key": "useful", "label": "Useful runs", "colorIndex": 2 }
  ],
  "data": [
    { "week": "W1", "runs": 120, "useful": 88 },
    { "week": "W2", "runs": 143, "useful": 101 },
    { "week": "W3", "runs": 138, "useful": 110 }
  ]
}
```

Schema

• type (required): one of line, bar, area, scatter, pie.
• x (required): the data key for the category / x-axis (for pie, the slice name). Must be an identifier (letters, digits, _, -; starts with a letter/underscore) and must appear in every data row.
• series (required): 1–8 entries, each { "key", "label"?, "colorIndex"? }.
  • key: identifier, present in the data rows, distinct from x.
  • label: display name (free text; optional, defaults to key).
  • colorIndex: brand palette slot 1–8 (optional; defaults to the series position). You cannot set a raw color — color always comes from the brand tokens, which keeps charts on-brand and theme-correct.
• data (required): 1–1000 row objects; values are numbers or short strings. Use null/omit for gaps.
• stacked (optional): true to stack bar/area series.
• title (optional): short caption shown above the chart.

Keep it calm

• 1–4 series is the norm; the palette starts monochrome and the first slots are the most distinct. Don't pack 8 series into one chart — split or aggregate.
• Let the data carry the color; don't set colorIndex unless you're encoding a specific meaning (e.g. reusing slot 1 for the primary series across charts).
• For scatter, series automatically get distinct marker shapes (a colorblind secondary encoding) — no action needed.
• One series needs no legend; the title names it.

If it doesn't render

An invalid or incomplete spec shows as a plain JSON code block instead of a chart (never an error). Common fixes: x/series[].key must be identifiers and present in the data; keep to the five type values; ≤ 8 series, ≤ 1000 rows.