Skip to content
Docs menu

Blocks and charts

Every block a page or slide can hold, with a spec for each text, table, chart and diagram block, and how Venom checks a spec.

View .md

A block is a small JSON object, { "type": "...", ...fields }. Where a list of blocks is expected, a plain string is shorthand for a text block. An agent does not need this page: studio_catalog_get lists the blocks and studio_component_get returns the exact schema and a working example of any of them.

Text and media

Type What it is
heading text, level 1 to 4
text md: markdown with bold, italic, code, links, bullet and numbered lists
bullets items (up to 40), ordered, title
image src (an https address or a small data:image/png, jpeg, gif or webp), alt (required), caption, fit
quote text, by
callout text, title, tone of info, success, warn or danger
code code, lang, title (monospace, no highlighting)
divider a thin rule

Markdown is the small subset above. Raw HTML is never passed through: it is shown as text.

Data

stats is a row of KPI tiles, each [label, value, change?, note?, good?]:

{ "type": "stats", "items": [["ARR", "$4.2M", "+12%"], ["Churn", "1.8%", "-0.3%", null, "down"], ["NPS", 54]] }

Tiles are laid out by their count, so six make two rows of three rather than a row of five and one left over. Each tile shows its label small above the value and the change as a coloured pill: a change starting with + is green and one starting with - is red. Where a fall is good news (latency, churn, incidents, cost) say so with good: "down", either on the whole block ({ "type": "stats", "good": "down", ... }) or as one tile's fifth item ("down"; "up" is the default, so stored artifacts look the same). A fall is then green and a rise red. The big_number layout takes the same good slot, and a sparkline takes good for the colour of its last point.

table takes columns and rows (up to 12 columns and 300 rows), and optionally formats, align, totals, highlight and zebra (Charts, tables and KPI components). comparison sets options against features with yes, no, partial or text cells. Numbers are printed in full (1,240,000, not 1.24M) and a column that is mostly numbers is right-aligned, header included, so its digits line up. columns is a two-column layout block with left and right lists of blocks and a ratio of 1:1, 2:1 or 1:2; a column cannot hold another columns block. Each side's charts are drawn for its width, so a chart in a narrow column keeps labels as readable as one across the page. On a phone the page does not scroll sideways: each chart and diagram on a page is drawn a second time for a narrow screen (fewer ticks, thinned labels, a flowchart stacked top to bottom) and the stylesheet shows that one, so text stays at least 11 px. A table scrolls inside its own frame. A timeline's height follows its content (the labels above and below the line and how they wrap), so a short one leaves no empty space.

On a page, charts and diagrams sit in cards; on a slide they sit on the slide itself.

Charts

A chart is a block whose type is the chart, with its data as rows. Common options: title, caption, format, series, labels, legend, xTitle, yTitle, and the source line's source, asOf, unit, note and unverified (the data contract). format is one of num, compact, pct, usd, eur, gbp, int, dec1, dec2.

Type Data Extras
bar [["Q1", 10, 8], ["Q2", 12, 9]] one value per series stacked, horizontal
line [["Jan", 3], ["Feb", 5]], null leaves a gap
area like line stacked
pie, donut [["EU", 60], ["US", 40]]
waterfall [["Revenue", 120], ["COGS", -45]]; ["Subtotal", null, "total"] draws the running total total adds a final bar
scatter [[1, 2], [2, 4.5, "group", "label"]]
funnel [["Visits", 1000], ["Signups", 120]], widest first
combo rows like bar lines (which series are lines), y2, y2format
sparkline [3, 5, 4, 8] area, good ("down" when a fall is good news)
histogram raw values [12, 15, 18, 22] (binned for you) or binned rows [["0-10", 4]] bins
heatmap [["Mon", 3, 5], ["Tue", 8, 2]] columns names the value columns
gauge no data: value, min (0), max (100), target
progress [["Design", 80], ["Build", 45, 50]]: label, value, max (default 100) max
{ "type": "waterfall", "format": "usd", "total": "Net", "data": [["Revenue", 120], ["COGS", -45], ["Opex", -30]] }

Charts are drawn as SVG with the theme's colours, so they are readable in light and dark. They take empty, negative, flat and very large data without breaking: empty data draws a "No data" panel. Each chart has a title, a text description and a table of its values for screen readers.

Diagrams

Type Compact form
sequence steps: [["Browser", "API", "POST /login"], ["API", "Browser", "200", "dashed"]], or text: lines like A->B: hello and B-->A: ok
flowchart text: A[Start] --> B{Valid?} then B -->|yes| C(Done); [] box, () round, {} decision, ([]) pill. Or nodes and edges. direction: LR or TD. Up to 40 nodes
timeline items: [["Q1", "Beta", "Invite only"], ["Q2", "Launch"]]
gantt tasks: [["Design", "2026-01-05", "2026-01-30", "Phase 1"], ["Build", "2026-02-02", "6w"]]; an end is a date or a length (14d, 3w, 2m)
tree root: { "name": "CEO", "children": [...] } up to 6 levels and 80 nodes, or text as an outline indented two spaces per level

How a spec is checked

Venom checks the whole spec before it saves anything and answers with every problem, each with its path, what is wrong and what is allowed, so one retry fixes it:

- blocks[0].colour: unknown field "colour" Allowed: data, stacked, horizontal, title, caption, format, series, labels, legend, xTitle, yTitle.
- blocks[0].data[0][1]: must be a number or null, got "x".
- blocks[1].type: unknown block type "waterfal", did you mean "waterfall"? Types: heading, text, ...

Unknown fields are refused with the nearest name, and a block that fails ends with a working example of its type. The shapes models often send instead (Chart.js data, rows of objects, numbers as text, bar_chart) are read as what they mean (Shapes Venom also reads). studio_artifact_validate runs the same check without saving.