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.
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.