Skip to content
Docs menu

Charts, tables and KPI components

The data components an agent fills with numbers instead of drawing anything, the one data contract they share, the shapes Venom also reads, and how to place them in a page, a deck slide or an html page.

View .md

Studio's components are data. An agent sends the numbers and Venom draws the chart: an SVG in the artifact's theme, readable in light and dark, with a layout of its own on a phone, a table of every value for screen readers, and the same picture in print and in PowerPoint. Nobody writes SVG, chart code or CSS for them.

To see every component drawn in your organisation's theme, open /studio/gallery while signed in (add ?scheme=dark or ?scheme=light). Each one is shown with the JSON that drew it, which is the example an agent gets from studio_catalog_get.

The components

Type What it shows Its own fields (besides the shared ones below)
bar bars, vertical or horizontal, grouped or stacked data, series, stacked, horizontal
line one line per series data, series
area filled lines, optionally stacked data, series, stacked
combo bars plus lines, optionally on a second axis data, series, lines, y2, y2format
waterfall how steps add up from a starting level: gains green, losses red, the start and totals in the accent data, total
pie, donut shares of a whole (the donut prints the total) data
scatter points on two number axes, coloured by group data, series
histogram how values are distributed data (raw values or binned rows), bins
heatmap a grid shaded by value; two hues when values cross zero data, columns
funnel stages that narrow, with the conversion between them data
gauge one reading on a scale, with a target mark value, min, max, target
progress bars toward a goal data ([label, value, max?]), max
sparkline a small trend with its last value data, area, good
stats KPI tiles: a big number, its change and a note items, good
table a data table columns, rows, formats, align, totals, highlight, zebra
comparison options across, features down: yes, no, partial or text columns, rows, highlight
timeline, callout, quote milestones, a highlighted note, a pull quote see Blocks and charts

One data contract

  • Rows. Category charts take rows: a label, then one number per series: [["Q1", 120, 150], ["Q2", 135, 170]], with the series named in series. null leaves a gap.
  • Formats. format is one of num, compact, pct, usd, eur, gbp, int, dec1, dec2, for the values and the axis. A table takes formats, one per column, and shows numbers in full ($1,200,000, not $1.2M).
  • Axes. xTitle and yTitle; labels prints each value on its mark; legend shows or hides the legend.
  • Where the numbers come from. Every chart, table, comparison and set of tiles takes source (a name, or a markdown link), asOf (the date of the figures), unit, note and unverified. They print in one line under the component. unverified: true adds an Unverified badge and "estimate" an Estimate badge: use them for any figure that does not come from a checked source.
{"type":"bar","title":"Revenue by quarter","series":["2025","2026"],"format":"usd",
 "data":[["Q1",120,150],["Q2",135,170],["Q3",160,190]],
 "source":"Finance ledger","asOf":"2026-09-30","unit":"USD thousands"}

Tables

A table's numbers align right and text left unless align says otherwise. totals: true (or a label such as "Total 2026") adds a row that sums each numeric column; a percentage column is left blank, because shares and rates do not add up. highlight takes row numbers (0 is the first) or the text of a row's first cell. zebra shades every other row. A table holds up to 12 columns and 300 rows; printed, it breaks across pages with its header repeated on each one.

Comparison

{"type":"comparison","columns":["Venom","Vendor A"],"highlight":"Venom",
 "rows":[["Self-hosted",true,false],["SSO",true,"partial"],["Price per seat","$12","$20"]]}

true, false and "partial" are drawn as a tick, a cross and a half circle, with the words for screen readers. highlight marks the recommended option; it is stored as the column's number, so renaming the option keeps it.

Shapes Venom also reads

Models on every gear guess. Venom rewrites the guesses that have one plain meaning into the form above before it checks a block, and stores the rewritten form:

  • rows of objects: [{"quarter":"Q1","revenue":10,"cost":8}] (the series are named after the keys);
  • Chart.js: {"labels":["Jan","Feb"],"datasets":[{"label":"Web","data":[3,5]}]};
  • labels or categories beside a list of numbers, or series as [{"name","data"}];
  • an object of label to value: {"EU":60,"US":40};
  • numbers as text: "1,234", "$4.2M", "12%", "(45)";
  • type names such as bar_chart, kpi, doughnut, horizontal_bar, or {"type":"chart","chartType":"pie"};
  • field names such as as_of, sources, x_label, number_format: "percent", "true" for true;
  • a block wrapped in another key: {"type":"chart","chart":{"type":"line",...}} (a slide's chart slot copied into a page) or {"type":"table","table":{...}};
  • a comparison whose columns start with a header for the feature column, and a list of lines where one text goes;
  • a waterfall total written as ["Q3", null, 4800000] or with "subtotal", and legend given as the series' names.

Anything else is refused with the path of what is wrong, what was expected, and a working example of that component, so the next attempt is right.

Placing them

  • Page: a block in the page's blocks.
  • Deck: the chart slot of the chart layout, the table slot of the table layout, or a two_column side.
  • html page: a script with the block as JSON, where the component goes:
<script type="application/venom+json">
{"type":"line","title":"Weekly users","data":[["W1",1200],["W2",1350],["W3",1500]],"source":"Product analytics"}
</script>

The script may hold one block, a list, or {"blocks":[...]}. When the page is served, Venom checks it like a page's block and draws it in place in the org theme; no script runs and nothing is fetched. A block that does not check is reported when the page is saved (the tool's answer names the path and the fix) and drawn as a visible error.

PowerPoint

Charts, including the histogram, heatmap, gauge and progress bars, export as grouped native shapes and text you can restyle. Tables and comparisons export as native PowerPoint tables (a comparison writes "✓ Yes", "✗ No" and "◐ Partial"); the source line goes under each one. None of them are PowerPoint chart objects with a datasheet.

For agents

studio_catalog_get with group components lists every component with its fields and one example, and says the shared fields once. studio_component_get gives one component's full JSON Schema.