Frames, tones, lines, and symbols

TL;DR

Every picture on this page is drawn by the renderer from the source beside it, so the page cannot disagree with the renderer. Each picture follows the theme of the page, light or dark.

1. Frame styles

A group draws a frame with a corner tab that holds its icon and its name. The frame style tells a reader what kind of boundary it is. A group type sets the style, and no option changes it, so pick the type that says what the group is.

Picture	Frame	Types	Reads as
	Dashed	region, zone, network, identity-boundary, trust-boundary	A boundary: what is inside is isolated or checked differently
	Solid	cloud, account, subnet, public-subnet, private-subnet, management-subnet, isolated-subnet, resource-group, cluster, scale-group, service-plan, web-tier, app-tier, data-tier, storage-account, messaging, edge, security, observability, ci-cd, environment	A logical container: things that belong together
	Dotted	cloud-boundary, on-premises, client-side, external-systems	A side of a line: outside the system you are drawing, or the cloud side of a cloud boundary

2. Tones

A tone is a color family. Each tone has a fill and an outline for a group, a chip color for the corner tab, and an ink color for text and icons, tuned for light and for dark. The picture shows an untyped group of that tone. The last column lists the group types that take the tone by default.

Every picture is drawn from this source, with the tone replaced:

1flow "Blue tone" direction=down2group g "Blue" tone=blue {3  node n step "Resource"4}

Picture	Tone	The default of
	tone=neutral	cloud, account, region, zone, subnet, resource-group, trust-boundary, on-premises, client-side, external-systems
	tone=blue	network, web-tier, edge, cloud-boundary
	tone=violet	private-subnet, cluster, service-plan, app-tier, identity-boundary, ci-cd
	tone=aqua	scale-group, data-tier, observability
	tone=orange	messaging
	tone=green	public-subnet
	tone=amber	management-subnet, storage-account, environment
	tone=red	isolated-subnet, security

3. Nesting depth

A group nested in another is shaded one step stronger than the one around it, in light and in dark, up to four levels. An account, a region, a network, and a subnet read as four levels, and a neutral group deepens toward the ink color in the same way. Depth is automatic; there is nothing to write.

PictureSourceOutline

4. Edge styles and arrowheads

An edge joins two nodes. The token sets the line style and where the arrowheads go. Use -> for a call that waits, --> for a response or a looser dependency, and ..> for a call that is not waited for, such as a webhook, an event, a pull, or a push.

Every picture is drawn from this source, with the last line replaced by the statement in the table:

1flow "Edge" direction=right2node a step "A"3node b step "B"4a -> b

Picture	Source	Line	Arrowheads	Use it for
	a -> b	solid	at the end	A call or a flow of data.
	a --> b	dashed	at the end	A reply, a read, or a link that is optional or indirect.
	a ..> b	dotted	at the end	An asynchronous call: a webhook, an event, a pull, or a push that is not waited for.
	a -- b	solid	none	An association with no direction.
	a <-> b	solid	at both ends	A two-way call or sync.
	a <--> b	dashed	at both ends	A two-way link that is optional or indirect.

Labels and icons on an edge

Picture	Source	What it does
	a -> b : "HTTPS"	A label sits on the line. Keep it to a few words.
	a ..> b : "event"	A dotted line with a label is an event or a webhook.
	a -> b : "yes"	The labels yes, no, true, and false get a status icon without being asked: here status:yes, a green tick.
	a -> b : "no"	The label no gets status:no, a red cross.
	a -> b : "retry" icon=status:retry	An explicit icon= on the edge wins. It needs a label.
	a -> b : "yes" icon=none	icon=none removes the automatic icon.

An edge between two nodes that sit side by side, such as a primary and a replica database, is drawn straight across, so the two columns stay level. Give it ..> and a label such as "replication". Keep to one such pair in a diagram.

PictureSourceOutline

5. Marks and second lines

A node card and a group tab hold more than a name. These options add to them, and the card or tab grows to hold them without ever covering the icon or the text.

On a node

Picture	Source	What it does
	node a service "Orders API"	A node has a type, which sets its tone and icon, and a label.
	node a service "Orders API" sub="Validates credentials"	sub= adds a second line under the label.
	node a storage "Web app" icon=azure:blob-storage stack=simple:angular,simple:typescript	stack= adds up to three small technology marks under the text. The card grows to hold them.
	node a external "Partner API"	The type external has a dashed outline: a system you call but do not run.
	node a service "Orders API" tone=violet	tone= overrides the tone the type sets.
	node a database "orders-db" icon=aws:rds change=update	change= marks a planned change with a corner badge and a coloured outline: create, update, replace, or destroy.
	node a service "Orders API" icon=none	icon=none removes the icon.

On a group

Every picture is drawn from this source, with the first group line replaced by the statement in the table:

1flow "Group" direction=down2group g "Web tier" type=web-tier {3  node n step "Resource"4}

Picture	Source	What it does
	group g "Web tier" type=web-tier {	The type sets the icon in the tab, the tone, and the frame style.
	group g "Web tier" type=web-tier sub="10.0.1.0/24" {	sub= adds a second line to the tab, such as an address range or a plan.
	group g "Plan" type=service-plan stack=simple:dotnet {	stack= adds up to three small marks to the tab, written like the marks of a node.
	group g "Network" type=network provider=azure {	provider= makes the type draw that provider's own icon where it has one.
	group g "Web tier" type=web-tier icon=lucide:rocket {	icon= replaces the icon in the tab.
	group g "Web tier" type=web-tier icon=none {	icon=none removes the icon.
	group g "Web tier" type=web-tier tone=amber {	tone= overrides the tone the type sets. Prefer the type that says what the group is.

An overlay

An overlay is a dashed frame drawn around nodes or groups that it does not own, wherever layout put them. It is one line after the members. Here two machines in two zones form one scaling group, and the frame crosses the zone frames on purpose.

PictureSourceOutline

See also