Block diagrams

TL;DR

Ask your agent

Say what the blocks are, which ones sit together in a row, and which ones hold others. The agent writes the grid.

Use Plotwork to draw our smart camera as a block diagram with four columns. The lens, the image sensor, and the image processor are on the first row, the processor two columns wide. Below them, the system on chip holds the CPU, the neural engine, and the GPU, with the LPDDR5 memory as a cylinder under all three. On the last row put Wi-Fi, USB-C, and a round status light. Link the sensor to the processor with RAW, and the processor to the chip with frames.

Use Plotwork to draw the memory map of our microcontroller as a block diagram with eight columns: peripherals across the top, then SRAM and core-coupled RAM, then the bootloader, the application, and the one-time programmable area. Write each address range under its name.

Use Plotwork to draw how a request moves through our stack as a block diagram: client, edge, API, and the orders database on one row with block arrows between them, and an arrow down from the API to the event queue.

Example

This is the smart camera from the first prompt. It shows a box two columns wide, a group with its own grid of three columns, a cylinder that spans that grid, a gap, a circle, and links with labels that never cross a box.

PictureSourceOutline

A memory map

A memory map is a grid read by its widths: each region is as wide as its share of the address space, and a gap keeps a range free. Tones group the kinds of memory. No link is needed, because the position is the meaning.

PictureSourceOutline

A request pipeline with block arrows

Block arrows draw a flow the grid already shows, so the stages need no lines between them. dir=both points both ways, dir=down points at the cell below, and row ends a row early. The gaps put the queue under the API.

PictureSourceOutline

The language

A line is one statement. A # starts a comment. Ids are words such as cpu, ram-1 or _x, labels are in double quotes, and options are written key=value. The first line is the header.

The header

block "Smart camera" columns=4 desc="The blocks of a camera board."

There is no direction=. The author places every cell, so the picture reads as it was written.

Statements

tone= takes neutral, blue, violet, aqua, orange, green, amber, or red, and icon= takes a name from the closed list of icons, such as lucide:cpu or simple:raspberrypi. A diagram cannot set a colour: the theme chooses every colour, in light and dark.

The grid

Cells fill the grid from the left, in the order written, and wrap at the last column. span= makes a cell as wide as that many columns, and a span that does not fit what is left of the row starts the next row. A span wider than the grid is drawn as wide as the grid, with warning W202.

1block "Grid" columns=32box a "One"3box b "Two columns" span=24gap5box c "After a gap"6row7box d "A row of its own"

The columns are even, so the grid reads as one, unless one wide box would make every column much wider; then each column is as wide as what it holds. A row is as tall as its tallest cell, and the boxes in it grow to match.

Groups

A group is a grid inside a frame, with its name and icon in the corner. Its cells follow on the lines after the {, and it takes span= columns of the grid around it. columns= sets its own grid, and with none it takes as many columns as its first row holds. Groups nest up to three deep, and each level is a shade stronger than the one around it.

1block "Camera" columns=42group soc "System on chip" columns=3 span=4 tone=violet icon=lucide:layers {3  box cpu "CPU" sub="4 cores"4  box npu "Neural engine"5  box gpu "GPU"6}

A link may name a group, and then it ends at the group's frame.

Shapes and block arrows

Every shape but the circle and the diamond fills its cell, and those two keep their size, centred, so a circle is never stretched into an ellipse. Text wraps inside the shape and never touches its edge.

A block arrow that points at an empty cell or past the edge of the grid is warning W201.

Links

A link runs through the gutters between cells with square bends and never crosses a box. Two neighbours in a row or a column meet with one straight line, and the gutter between two neighbours whose link has a label widens to hold the label. Lines that share a gutter keep apart. A label wider than 200px is cut with an ellipsis and warning W203.

Limits and warnings

The limits are checked from the text alone, so a diagram that is too big is refused at once with a hint on how to split it. The layout is plain arithmetic over the grid, so a diagram of 40 boxes is laid out in a few milliseconds.

From Mermaid

Mermaid block-beta and block convert to a Plotwork block diagram that keeps the grid: the columns, the widths, the spaces, and the composite blocks. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full.

1block-beta2  columns 33  a["Frontend"] b["Backend"]:24  block:data:35    columns 26    db[("Orders")] cache(("Cache"))7  end8  a --> b9  b -- "SQL" --> db

See also