Guide for AI agents
A short guide meant to be pasted into an agent's system prompt. The same text is published as plain Markdown at AGENTS.md and llms.txt. To have your AI follow it on its own, install the Agent Skill.
One function, one JSON object. No design decisions: the library makes them.
import { plot, safePlot } from 'plotagents';
const svg = plot({ type, data, x, y, series, title, subtitle, source });Rules for a good chart
title,subtitleandsourceare optional. Leave them out when the page around the chart already says it. When you set atitle, make it the finding, a full sentence with the key number: "Biobío accounts for 30% of sales", not "Sales by region".subtitlesays how to read it (measure, unit, period);sourcesays where the data comes from.- Choose a
datashape that fits the table. Rows ([{ region: "Biobío", sales: 1240 }]) are fine for a few rows. For many rows, write the field names once: header + rows[["region", "sales"], ["Biobío", 1240], ["Ñuble", 830]], columns{ region: ["Biobío", "Ñuble"], sales: [1240, 830] }, or CSV text"region,sales\nBiobío,1240". For a wide table, passy: ["revenue", "costs"]. In a dashboard, passdataonce at the top. paddingis 8 px top and bottom and 0 at the sides by default; set a number,[vertical, horizontal]or{ top, right, bottom, left }to change it.- Call
safePlot(spec)as your tool: it never throws and returnserrors,warningsandsuggestions, each with afix. Ifokisfalse, fix the spec and call again. - Set
locale: "en"for English number formats (default is Spanish:1.234,5); also"pt","fr","de", or"auto"to recognize it from the text. Tables recognize it on their own.
Which type
| To show | type | Key fields |
|---|---|---|
| Compare categories | bar | x, y, series?, stack? (true / "percent"), top? |
| Count rows per category | countplot | x |
| Mean per category with a CI | barplot or point | x, y, hue? |
| Change over time | line | x date ("2024-03") or year, y, series?; ci: true with several observations per x |
| A project plan or schedule | gantt | task, start, end (or duration), group?, progress?, dependsOn?, today?, collapsed? |
| Volume over time | area | like line; stacks with series |
| The shape of a series in a table cell | spark | x, y, width/height any size (e.g. 108×26), fill?, series? |
| One row of a distribution in a table cell | rail | value, min, max, band?: [lo, hi], median?, refs?: [{ field | value, label }], clip? / domain? (past an end → chevron); 160×18 by default |
| Who passed whom over time | bump (slope for first vs last) | x period, y value (or rank), series, top?, ends?: "first-last" |
| Measures on different scales | line + index: true, or facet | there is no dual axis |
| Exponential growth | line + yScale: "log" | |
| Relationship between two measures | regplot (fit + CI) / scatter / bubble | x, y, hue?, size?, label? |
| Relationship + marginals | jointplot | x, y |
| Which measures move together | corr (correlation) | vars? (default: every numeric field), method? ("spearman"), alpha?: 0.05; cluster: true or type: "clustermap" groups them with a dendrogram |
| Every pair of measures at once | pairplot (splom) | vars (3–6), hue?, corner?, kind?: "reg" |
| Distribution of one measure | hist (kde: true), kde, ecdf | x, hue? |
| Distribution by category | box, violin, strip, swarm | x category, y measure, hue? |
| Distribution where each thing stays one thing | dotplot | x, bin?, label?, series?, highlight?, ticks?: [[value, label]] |
| Multi-dimensional profile | radar | axis, value, series (≤ 4 series) |
| Hierarchical part-to-whole | treemap or sunburst | path: [level1, level2, …], value |
| Part-to-whole, ≤ 6 parts | donut / pie | label, value; half: true for a semicircle |
| Magnitude on a grid | heatmap | x, y, value |
| A count as a number of things | waffle | series, value? (or one square per row), columns?, unit? |
| How things group, and at what height | dendrogram | rows id, parent, heightField? or linkage + labels; cut?, clusters? |
| A value per region, state or country | choropleth (symbolmap for totals) | geo: "chile" | "usa" | "world" or any GeoJSON/TopoJSON object, key, value (text → one color per category) |
| Dots at real places on a street map | pointmap | lon, lat (auto-detected), size?, hue?, value?, label?; tiles: "osm" (default) / "esri-gray" / "esri-dark", or carto-* / mapbox-* with tilesKey |
| Who is connected to whom | network | edges from, to, value?; nodes? with group; layout? |
| Exchanges between a few groups | chord | from, to, value |
| Age structure | pyramid | age, sex, value |
| A process with decisions | flowchart | nodes (type, lane), edges (label) |
| Flows between stages | sankey | from, to, value |
| One or more numbers | kpi | items: [{ label, value, delta, period, trend, target, good }] |
| Exact values to look up | table | columns?: [field | { field, type, label, format, good, target }], sortBy?, total?, group?; types bar, delta, heat, sparkline, progress, badge, check are inferred when omitted |
| What comes up most in text | wordcloud | text (field or raw text), value?, series?; prefer bar + top to compare exactly |
seaborn names work (histplot, kdeplot, boxplot, violinplot, lmplot, stripplot, swarmplot, pointplot), and hue is an alias of series. Leave type out to infer it from the data.
Most useful options
highlight: "Ñuble": emphasize one category or series and mute the rest.exclude: ["Maule"]drops entries and recomputes the chart; colors stay put.legend: "top" | "bottom" | "left" | "right" | false: where the legend goes (top by default).colorScale: "viridis": any matplotlib colormap for heatmaps, maps and treemaps by change ("RdBu"diverges around 0;_rreverses; or a list of colors).palette: "tab10"for categories.palette: "nordico": a minimal palette family (arcilla,nordico,tinta: five muted colors, the 6th series on goes gray;cdiais the default): validated colors plus matching ramps, with a dark variant undertheme: "noche".palettes: ["cdia", "arcilla", "nordico", "tinta"](ortrue) bakes the alternatives into one SVG;data-palette="nordico"on any ancestor switches, andtoHTMLadds the buttons.dashedfor what is not a firm number (estimates, projections, provisional figures): a name, a list, or a data field (dashed: "provisional"). Shapes keep their color, with a hatched fill and a dashed outline. On a time axis,dashedFrom: 2025dashes lines, areas and columns from that year on. Always setdashedLabel("Projection", "Preliminary") so readers know what the hatching means.facet: "region"(+columns): one panel per value, on a shared scale.time: "year": one period at a time (the latest) with % change vs the previous one. Time controls are off by default: addslider: trueonly when the person asks to move through periods (buttons for ≤ 8 periods, a minimal slider otherwise;"buttons"/"slider"force one,play: falsehides play). Treemaps can be colored by change withcolorBy: "change".refLines: [{ y: 600, label: "Target" }]andannotations: [{ x: "2024-01", label: "New branch" }].format: "percent" | "currency" | "compact" | "integer"or{ prefix, suffix, decimals }.xScale/yScale: "log".table: give a title that states the finding like any chart. More than 15 rows paginate in tens (pageSize), phones get one card per row, and the browser adds sort, search and paging. Usegood: "down"on costs so ▲ turns red,progresswithtarget: "budget"for spent vs budget, andtotal: truefor a totals row. Keep 4–7 columns.theme: "noche"or a JSON object ({ extends, categorical, type, marks, font });palette: [...]for your own colors.font: "Poppins"andtextScale: 1.5(presentation mode);configure({ font, textScale })sets them for every chart.network+focus: "node id": center a node and highlight its neighbors.- Your own map:
geo: <GeoJSON or TopoJSON>; the matching property is found for you (featureKeyto force it). Addmarkers: [{ lon, lat, label }],layers: [{ geo, label }]for rivers or routes, andfitTo: ["Biobío"]or a[lonMin, latMin, lonMax, latMax]box to zoom. - Maps for a static site:
geo: { paths: { id: "M…Z" } }takes outlines already projected (no projection runs);views: [{ id, label, value }, …]bakes several readings of one geometry into one SVG (switch withdata-view,plotagents/views);pathPrecision: 1, simplify: 0.5shrink the paths;fitTo: "mainland"drops far islands;microstates: truedraws Singapore or Malta as dots; world countries match by ISO-2 too. gantt: dayenddates are inclusive; a row withoutendis a milestone. Always settodayon a live plan.collapsed: ["Phase 2"](ortrue) folds phases into one summary bar; in the browser a click on a phase toggles it.network+layout: "force" | "circular" | "radial" | "concentric" | "clusters" | "tree" | "grid"picks the placement;curveness: 0straightens edges.pointmapdraws on OpenStreetMap tiles by default (tiles: "esri-gray","mapbox-light"+tilesKey, or your own{ url, attribution }). Tiles load only when the SVG is inline or intoHTML, not inside<img>.- Your own look for every chart:
registerTheme("acme", { background, text, grid: { color, dash }, categorical: "tab10", font })thenconfigure({ theme: "acme" }). geo: "usa": states match by postal code ("TX"), English or Spanish name, or FIPS ("48"). Alaska and Hawaii are insets; Puerto Rico appears only when your data has it. In the browser, maps zoom on click, Ctrl/⌘ + scroll or pinch.
Mistakes the library already handles
- More than 8 series → the 9th onward turn gray;
lintsuggestshighlightorfacet. - Colliding line labels → spread apart with leader lines.
- Donut with more than 6 parts → folds into "Other".
- Long category labels → switches to horizontal.
- Hard-to-tell custom palette →
lintnames the offending pair. - Numbers as text ("1.234,5", "12%", "$ 3.000") → parsed automatically.
- Tens of thousands of points → drawn as batched paths, still fast.
- Empty categories (
null,"") → grouped as "(no data)" / "(sin dato)", never a "null" label.
Dashboards
When someone asks for a dashboard, call safeDashboard({ title, subtitle, source, data, kpis, charts, filters }) (tool: toolDefinition({ kind: 'dashboard' })). Layout, widths, shared colors and filters are decided for you:
titleis the question the dashboard answers; a chart title, when you set one, states its finding.- At most 5 KPIs, computed from
datawhen possible:{ label, field, agg: "sum", compare: { field: "year", current: 2025, previous: 2024 }, trendBy: "month" }. - 4–6 charts. The first time series (or the one with
primary: true) goes full width; the rest fill balanced rows. filters: ["region", "channel"]become buttons that filter every chart and KPI.- No more than one donut; one
sourcefor the page.
Outputs
plot(spec)→ SVG string. Drop it into HTML, Markdown, an.svgfile or a PDF.toHTML([spec1, spec2])→ self-contained page with tooltips, sliders and drill-down.describe(spec)→ alt text for the chart.schema/toolDefinition()→ JSON Schema and tool definition (Anthropic or OpenAI).- CLI:
npx plotagents spec.json -o chart.svg.