---
title: Blocks and charts
description: 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.
section: studio
order: 20
audience: [user, builder, agent]
sources: [services/nodejs-cloud/lib/studio/blocks.ts, services/nodejs-cloud/lib/studio/charts.ts, services/nodejs-cloud/lib/studio/diagrams.ts]
features: []
---

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?]`:

```json
{ "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](/docs/studio/components.md#tables)). `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](/docs/studio/components.md#one-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` |

```json
{ "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:

```text
- 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](/docs/studio/components.md#shapes-venom-also-reads)). `studio_artifact_validate` runs the same check without saving.
