Charts are a language. Now AI speaks it.
plotagents is an open protocol between a model and the page. The model says what a chart means: the data, the finding, the unit. The library answers with a finished, accessible chart, or with the exact fix it needs.
Here’s our rollout plan. Where are we, and what could slip?
plot({ type: "gantt", title: "Go-live is June 15, and the ERP integration is the critical path", subtitle: "Rollout plan by phase, 2026. The filled part of each bar is progress", source: "illustrative data", data: /* 10 tasks: phase, task, start, end, progress, after */, task: "task", start: "start", end: "end", group: "phase", progress: "progress", dependsOn: "after", today: "2026-03-12", dashed: "tentative", dashedLabel: "To be confirmed", locale: "en",}){ ok: true, type: "gantt", svg: "<svg …>…</svg>", // 13.1 kB, with aria-label and <desc> description: "Gantt chart of 10 tasks in 4 phases, from Jan 5, 2026 to Jun 15, 2026. Longest: ERP integration (46 days). Milestones: Findings report (Feb 9),…", errors: [], warnings: [], suggestions: []}Install it once. Your AI charts with plotagents from then on.
The skill tells your assistant to use plotagents for every chart, map, table and dashboard. It carries the essentials of the protocol and checks npm for a newer release before it starts, so it never falls behind.
- Claude Code, Cursor, Codex… Run the command above in your terminal.
- Claude app Download the .zip and upload it in Settings → Capabilities → Skills.
- Any other AI Paste SKILL.md into its instructions.
One message each way. No pixels.
A model is good at knowing what the data says and bad at placing tick labels. So the protocol asks only for meaning, and keeps the craft on this side of the wire.
Say
The model describes the chart, not the drawing: rows of data, the role of each field, and a title that states the finding.
Check
safePlot never throws. It validates against the JSON Schema and the design rules before anything is drawn.
Repair
Every issue carries a fix written for a model to read. It applies the fix and calls again, usually once.
Show
An SVG comes back with its alt text in description, so the model can read what it drew before it answers.
First call
plot({
type: "donut",
data: /* 11 rows: city, stores */,
label: "city",
value: "store_count",
locale: "en",
})A wrong field name and an 11-slice donut: two classic mistakes.
plotagents answers
{
ok: false, svg: null,
errors: [
{ message: "The field \"store_count\" (value) does not exist.",
fix: "Available fields: city, stores" }
],
warnings: [
{ message: "11 slices: beyond 6 a donut cannot be read; the rest fold into \"Other\".",
fix: "Use `type: \"bar\"` or `type: \"treemap\"`." }
],
suggestions: [ ]
}Second call → chart
A small grammar for every chart.
Ten words carry most charts. Name a type, or leave it out and plotagents infers it from the data. seaborn names work too.
- title
- The finding, as a sentence with the number.
- subtitle
- How to read it: measure, unit, period.
- source
- Where the data comes from. Always.
- data
- Rows, as they come:
[{ region, sales }]. - x · y · series
- Which field plays which role.
- highlight
- The one thing the reader should see.
- dashed
- What is not a firm number yet.
- facet · time
- Small multiples; one period at a time.
- geo
- Chile, the US, the world, or your own GeoJSON.
- locale
"en"or"es", for numbers and dates.
bar/ line/ area/ scatter/ treemap/ sunburst/ donut/ pie/ heatmap/ sankey/ kpi/ hist/ kde/ ecdf/ regplot/ jointplot/ box/ violin/ strip/ swarm/ point/ radar/ network/ chord/ pyramid/ flowchart/ gantt/ wordcloud/ choropleth/ symbolmap/ pointmap/ table/ corr/ pairplot/ spark/ bump/ waffle/ dendrogram/ dotplot/ rail
Plus barplot, histplot, violinplot, lmplot… and plain words like timeline, map or roadmap. The full contract is one file: schema.json.
Drawn by the library, not guessed by the model.
Every chart here came from a spec of a few lines. Sorting, labeling, color, spacing and the mobile layout were decided on this side.
Bring your own geometry.
Chile, the United States and the world come built in. Anything else is one field away: comunas, school districts, sales territories, a campus, a floor plan.
- Any shape in
geo. A FeatureCollection, a Feature, a list of features, a TopoJSON, or a URL in the browser. - No key to configure. The property that matches your rows (
NOM_COM,GEOID,ADMIN) is found for you. - Layers on top.
markersby longitude and latitude,layersfor rivers, routes or borders. - Your framing.
fitTozooms to a few regions or a box; projections from Mercator to UTM metres. - Text values work. A party or a language colors by category, with a legend.
plot({
type: 'choropleth',
geo: myGeoJSON, // or TopoJSON, or a URL
data, key: 'country', value: 'language',
markers: { data: capitals, label: 'city' },
layers: [{ geo: tropic, dash: true }],
fitTo: ['Chile', 'Argentina'], // optional
})Rules the model can’t break.
Agents reach for dual axes, twelve-slice pies and titles that say nothing. Here, the good decision is the only one available.
The title states the finding
A full sentence with the key number. lint flags titles that only name the chart; describe writes the alt text.
One axis, always
No dual axes: they invent correlations. index: true rebases to 100, facet draws panels on a shared scale.
Labels where the eye is
Lines are labeled at their ends, values sit on the bars, colliding labels get leader lines. A legend only when it is needed.
Color follows the entity
Eight colorblind-safe colors in a fixed order. “Copper” keeps its color when you filter, drill down or move the slider.
Honest about uncertainty
Estimates and projections are hatched with dashed, never a new color, and the legend says what the hatching means.
Fast, accessible SVG
Zero dependencies, server-side rendering, an aria-label and a <desc> in every chart, and dense data batched into paths.
Hand it to any model.
The protocol ships as a JSON Schema and a ready-made tool definition, plus a one-page guide for the system prompt and an Agent Skill.
- The Agent Skill makes Claude, Cursor or Codex reach for plotagents on their own.
toolDefinition()turns the schema into a tool for Claude or OpenAI.safePlot(spec)returns the SVG or the errors, each with afix.describe(spec)writes alt text the model can check.- The guide for agents, also as AGENTS.md and llms.txt.
render()in the browser adds tooltips, drill-down, map zoom, and time controls when the spec asks for them.
import Anthropic from '@anthropic-ai/sdk';
import { safePlot, toolDefinition } from 'plotagents';
const client = new Anthropic();
const res = await client.messages.create({
model: process.env.ANTHROPIC_MODEL,
max_tokens: 4096,
tools: [toolDefinition()], // the whole protocol, as JSON Schema
messages: [{ role: 'user', content: 'Chart service times per clinic: …' }],
});
const call = res.content.find((b) => b.type === 'tool_use');
const { ok, svg, description, errors } = safePlot(call.input);
// Never throws. If !ok, return `errors` as the tool result:
// each one carries a `fix`, and the model calls again.import OpenAI from 'openai';
import { safePlot, toolDefinition } from 'plotagents';
const client = new OpenAI();
const res = await client.chat.completions.create({
model: process.env.OPENAI_MODEL,
tools: [toolDefinition({ flavor: 'openai' })],
messages: [{ role: 'user', content: 'Map unemployment by region: …' }],
});
const call = res.choices[0].message.tool_calls[0];
const result = safePlot(JSON.parse(call.function.arguments));<script src="https://unpkg.com/plotagents/dist/plotagents.js"></script>
<div id="chart"></div>
<script>
// Tooltips, time sliders, drill-down and map zoom included.
plotagents.render('#chart', {
type: 'choropleth',
geo: '/maps/comunas.topojson', // your own geometry, by URL
data, key: 'comuna', value: 'poverty',
title: 'Poverty is highest in the coal towns',
});
</script># One spec in, one SVG out. Works in any pipeline.
npx plotagents spec.json -o chart.svg
# Teach your AI assistant to chart with plotagents:
npx skills add carlosnavarreteliz/plotagents
# The guide an agent needs, in its system prompt:
curl https://carlosnavarrete.cl/plotagents/llms.txtAsk for a dashboard. Get a good one.
The same idea, one level up: the model lists KPIs, charts and filters; dashboard() lays them out the way an analyst would, and filters work across every panel.
- Numbers first. Up to five KPIs, computed from the data, with year-over-year change and a sparkline.
- Z-pattern. The trend goes full width; the rest fills balanced rows of a 12-column grid.
- One color per entity across every chart, one theme, one source line.
- Filters as buttons that move every chart and KPI at once.
- One HTML file. Works offline, prints, and turns into a PDF.
dashboard({
title: 'How are southern sales doing?',
data: sales,
kpis: [{ label: 'Sales 2025', field: 'sales', agg: 'sum',
compare: { field: 'year', current: 2025, previous: 2024 } }],
charts: [trend, map, byChannel, treemap],
filters: ['region', 'channel'],
})