Rendering
Zindex renders scenes to multiple output formats. The rendering pipeline normalizes the scene, computes layout, then compiles to the requested format.
Building an agent integration? The skill’s authoring guide covers writing scenes: element kinds, families, auto-layout, constraints, styles and icons. The Zindex skill covers the edit loop.
Render themes
Zindex supports 4 render themes that set colors, stroke width, corner radius and line style. A theme changes only the picture; the scene data stays as it is.
Themes don’t change text. Every theme draws text in the same fonts at the same sizes, the ones the layout engine measures, so a label wraps to the same lines and fits the same box under every theme. A node’s own style.fontSize still sets its size.
A preview of an unsaved scene takes one as theme:
POST /v1/diagrams/preview
{ "scene": { ... }, "theme": "dark" }
Saved versions take no theme. Their images use the default style (no theme: a white canvas, Inter text, the colors the scene sets), or the dark theme when the canvas background is dark; see Auto-detection from canvas background. The default style isn’t clean: clean has its own palette, stroke width and corner radius.
Available themes
| Theme | Background | Style | Font | Description |
|---|---|---|---|---|
clean | White (#ffffff) | Clean lines | Inter | Professional, crisp. |
dark | Dark (#1a1a22) | Clean lines | Inter | Dark mode with warm amber and green-cyan accents |
blueprint | Navy (#0d1b2a) | Clean lines | Inter | Technical/engineering aesthetic with cyan strokes |
sketch | Dark (#1a1a22) | Hand-drawn | Inter | Hand-drawn aesthetic with wobbly lines on dark background |
Theme resolution cascade
Styles resolve in priority order (highest wins):
- Element explicit style (inline object or named registry reference)
- Scene palette (scene-level
palettefield) - Theme defaults (palette colors, stroke width, corner radius; never a text size)
- Hardcoded fallback (white fill, dark stroke)
In a flowchart, a node that neither its style nor the palette gives a fill or stroke takes the flowchart tint, a light blue fill with a blue border, in the default style and clean. External systems, notes and nodes with an aws:* or gcp:* icon keep their own colors (Diagram families: Flowcharts).
Element-level styles always win. The scene palette overrides theme defaults for unstyled elements - useful when agents want a consistent color scheme without styling every element individually. In dark, blueprint and sketch previews, the colors a light design sets are then adapted (see Adaptive colors).
Auto-detection from canvas background
When no theme is given, as for every saved version, and scene.canvas.background parses as a dark color (perceived luminance < 102 on the 0-255 scale, e.g. #06080d, #1a1a22, rgba(6, 8, 13, 1)), the renderer auto-selects the dark theme so strokes and labels remain legible against the dark canvas. Without this, a clean-theme #333 stroke on a near-black canvas is nearly invisible.
Rules:
- An explicit
theme: "clean"on a preview always wins - the renderer respects an author who deliberately picks the clean theme on a dark canvas. - The parser reads every form listed in Color forms (
"midnightblue"is dark), and a CSS variable with a fallback, by its fallback. A translucent color counts as it shows over white, sorgba(0, 0, 0, 0.1)is light. Anything else, such as a variable with no fallback or a malformed value, falls through to the default style. scene.palette.backgrounddoesn’t pick the theme of a render without one: onlycanvas.backgrounddoes, so set that for the auto-theme behavior. It is the canvas the scene is designed on, though, and the canvas it paints: a darkpalette.backgroundmakes a dark design, which dark previews draw as written (see Adaptive colors).
{
"palette": {
"nodeFill": "#003366",
"nodeStroke": "#001a33",
"edgeStroke": "#004488",
"foreground": "#ffffff",
"background": "#f0f4f8"
}
}
Palette keys match the theme’s internal palette: background, foreground, nodeFill, nodeStroke, edgeStroke, containerFill, containerStroke, accentPrimary, accentSecondary, mutedForeground. All keys are optional - only the ones you set override the theme. accentPrimary colors the accent of every node whose style sets no accentColor (an ER table’s header and its PK badges, an org-chart card’s stripe, a UI-flow screen’s title bar); a node’s own accentColor wins over it. accentSecondary and mutedForeground in a scene’s palette change nothing: nothing draws a second accent, and an edge’s label takes its stroke color or its style’s textColor.
Adaptive colors
A preview in dark, blueprint or sketch adapts a scene’s own colors when the scene is designed on a light canvas (its palette.background if set, otherwise its canvas.background, is light or unset; a translucent one counts as it shows over white). Every color the scene sets, in element styles, named styles or palette, keeps its hue and flips its lightness against the theme: a white panel takes the canvas color, a pastel fill becomes a deep tinted surface, a dark fill a mid-tone one (fills stay dark, and among cards, and among containers, the most emphatic fill stays the most emphatic), and dark text and strokes turn light. Colors the scene leaves unset come from the theme. Adapting changes colors only; the layout is the same in every theme.
- Containers (frames, lanes, pools) take a band half as deep as cards: a container sits below a card of the same color, and a dark container becomes a deep surface, not the brightest panel on the page.
- An opaque fill keeps at least the contrast it had in the light design against what it sits on, up to 1.25:1, so a faint panel stays as visible as it was: a container’s against its parent container or the canvas, a node’s against the container it sits in or the canvas. A container also stays on its side of its parent, inverted: one darker than its parent in the light design is lighter than it in the preview, so nested tints step in order however deep they go. A node sits above what it is on, lighter in the preview, as a raised card does: a white card in a tinted frame stands a step above the frame instead of showing the canvas color through it.
- A stroke drawn in the same color as its shape’s fill or accent (a node’s or a frame’s) stays that color, moving with the fill and only as far as the shape needs to stand out from what it sits on.
- An org chart card’s accent stripe is adapted like a line, so it keeps its color against the card.
- An AWS or Google group’s border in its provider’s color counts as a color the scene sets where a fill the scene sets is inside or under it. It keeps the contrast it had there in the light design, up to 3:1. A Google Cloud boundary its author filled white keeps its outline.
- A frame’s accent border keeps the contrast it had in the light design, up to 3:1, as an authored
strokedoes. - Text and lines are then checked against what is under them (see Contrast).
What doesn’t adapt:
- Images (
kind: "image"), icons given as a URL or data URI, and AWS icons, the official files drawn as AWS ships them (an icon AWS ships for light and dark backgrounds is drawn in the variant that reads on what is under it, never recolored). Lucide icons are drawn in their node’s text color, so they follow it. - Google Cloud’s cards, icons and groups, drawn in Google’s colors on every canvas, and a card’s colors set in its node’s style (Google Cloud cards, Google Cloud groups), except a group’s border on a fill the scene sets (above).
- An edge’s own
strokewhere it runs on Google’s filled groups, in a diagram in Google Cloud’s style (Google Cloud edges). - A visual diff’s added, removed and changed colors, which pick their own shade for the canvas instead (see Visual diff rendering).
- Colors the renderer can’t read (see Color forms), such as
color-mix()or a CSS variable with no fallback: they are drawn as written. A CSS variable with a fallback,var(--brand, #333333), is read as its fallback: the fallback is adapted and checked inside thevar(), so a page that defines--branddraws its own color and any other viewer draws the adapted fallback. - A scene designed on a dark canvas: every dark theme draws its colors as written and fills in only what it leaves unset.
cleanadapts nothing: a dark design drawn incleankeeps its dark colors, on a white canvas unless itspalette.backgroundpaints its own. - Renders with no theme, as every saved version is drawn: the default style, or
darkpicked from a darkcanvas.background, draws the scene’s colors as written.
To pick colors, design for a light canvas: dark previews adapt them, and a dark palette.background, or a dark canvas.background with none, makes the scene a dark design, drawn as written.
Color forms
The renderer reads hex (3, 4, 6 or 8 digits), rgb(), rgba(), hsl(), hsla(), hwb(), lab(), lch(), oklch(), oklab(), color() in the predefined spaces (srgb, srgb-linear, display-p3, a98-rgb, prophoto-rgb, rec2020, xyz, xyz-d50, xyz-d65), the CSS named colors, and var(--x, <color>) by its fallback, however deeply nested, in every render and for every check. A none component counts as 0, as CSS reads it. Anything else is drawn as written: color-mix(), a relative color, a var() with no fallback, a typo, and a color a viewer rejects, such as a comma-separated rgb() mixing numbers and percentages (rgb(30, 50%, 255)), which every viewer draws black.
Every color the renderer reads is written in a form every viewer reads, browsers and the PNG export alike. Kept as written: hex, the named colors (all but rebeccapurple), and rgb(), rgba(), hsl() and hsla() whose rgb channels are all integers or all percentages, with an integer hue with no unit and an alpha as a plain number after a comma (spaces only with no alpha). Every other form, such as a percentage or slash alpha (rgb(0 128 0 / 0.5)), channels of mixed kinds (rgb(30 50% 255)), a decimal channel or hue, a hue with a unit, a none component, hwb(), lab(), lch(), oklch(), oklab(), color() or rebeccapurple, is written as hex, or rgba() when it is translucent, and a browser draws it the same. A color outside sRGB (a vivid oklch() or display-p3 color) is gamut-mapped as CSS Color 4 describes, keeping its lightness and hue; a browser that clips instead may draw the original a few levels differently. A var(--x, fallback) stays in the SVG, for a page that themes it, and a PNG draws its fallback (the innermost one, for nested variables).
Contrast
Text the renderer draws on a color it didn’t pair it with is checked against every color under it, in every render. A see-through color is read as it shows: a canvas over a white page (the page an image with a clear canvas usually sits on), a fill over what is under it; #00000000 is clear, not black.
- Node text on an authored fill: when a style (inline, a named style, or palette
nodeFill) sets an opaquefillbut nottextColor, the text is#ffffffor#1a1a1a, whichever has the higher WCAG contrast with the fill. When both come from the theme, the theme’s pairing stays. - Edge labels sit on a knockout, 90% opaque (95% under
sketch; opaque on a Google Cloud boundary’s blue, see Google Cloud edges), in the style’slabelBackgroundor else the color of each surface under it, so a label over a node or across a frame border keeps each one’s color. Where only its padding would reach a frame border its text doesn’t cross, the knockout stops half the border’s stroke and a pixel short of it, so the border is drawn whole. Over a translucent canvas the knockout takes the color the canvas shows; over a clear one it paints nothing. - A label with no clear place gets the same trim where only its padding reaches a node’s outline or another edge’s line and its text clears them: the knockout stops a pixel short (Layout engine: label placement).
- Labels outside their shape (BPMN events and gateways, UI flow entry and exit points, nodes with
fill: "none"or"transparent", as an AWS icon node is drawn by default) are checked against what is under the node, not its fill; one across two very different surfaces takes the color that reads best. An icon drawn in the text color follows. - Labels on a see-through fill (
"#33333320","rgba(30, 58, 138, 0.5)") are checked the same way, against the fill as it shows over what is under the node. - Text a family draws itself: ER rows, badges, types and headers, org card names and titles, UI flow title bars and bodies, lifeline headers and foot-bar labels, notes and pool titles, on the fill or band they are drawn on; the names under actors and the other figure heads, and fragment guards, on what they are drawn on.
- Frame titles sit on an opaque knockout in the frame’s fill as drawn. A title keeps its muted color when that reaches 4.5:1 there or the frame’s inline style sets
textColor, and otherwise turns#1a1a1aor#ffffff; in a preview that adapts the scene’s colors it moves lighter or darker at its own hue instead, as far as 4.5:1 needs, so a nested frame’s title stays as quiet as its parent’s. A Google Cloud group’s title keeps the color Google pairs with the group’s fill, such as a white title on the boundary’s blue, at 3.6:1 (Google Cloud groups). - A frame’s accent title. With
accentColorand notextColor, a frame’s title is the accent, moved lighter or darker at its hue until it reaches 4.5:1 (Element types: Frame color lists the titles that keep their own color). - A sequence fragment’s operator (
alt,opt,loop) is white on a tab of the fragment’s border color where that reads. A tab in the theme’s own border color that is a small step from reading (at most 0.06 in OKLab lightness) moves lighter or darker at its hue and keeps the white, the smaller change. Otherwise the operator is#1a1a1aor#ffffff, whichever reads better, and where neither reaches 4.5:1 the tab moves lighter or darker until it does. A tab that already reads is kept. - Marks a node draws on its fill in its stroke color (a BPMN gateway’s cross, plus, circle or pentagon, an event’s clock, error zigzag, envelope, inner ring or terminate dot, a subprocess’s plus, a weak entity’s inner border) reach 3:1 against the fill as it shows, in every render, since a gateway’s or event’s meaning depends on them. With the theme’s stroke, marks short of 3:1 are drawn
#1a1a1aor#ffffff, whichever reads better; with an authored stroke (even one the same color as the fill) they are drawn at its hue, lighter or darker as far as 3:1 needs. The outline keeps the stroke. - A note’s folded corner is its fill a step darker, at least as far as a light note’s fold (about 1.41:1) or the note’s own step in a light design, whichever is more, in every render: a very dark note can fold only as far as black. A translucent note’s fold keeps the note’s alpha, darkened as it shows over what is under the note.
- Under adaptive colors the renderer also checks node text inside its shape and text elements, and node, edge and frame strokes against what is around them (a node’s stroke against its own fill too, where its markers are drawn).
The targets:
- A color the theme gives, or the renderer picks, reaches 4.5:1 for text; when it falls short it becomes
#1a1a1aor#ffffff, whichever reads better. A muted one (a transition label’s guard and action, an org card’s title, an ER column’s type) instead moves lighter or darker at its own hue only as far as 4.5:1 needs, so it keeps its tint and stays quieter. - A color the scene sets keeps the contrast it has in the default render, up to 4.5:1 for text and 3:1 for lines. So a color the author made faint stays as faint.
- That contrast is measured where the color was designed:
- an edge label, on the canvas or on its own
labelBackgroundthere; - a label outside its shape, on its node’s fill (the canvas, for a node that fills nothing);
- other text, on what it is drawn on.
- an edge label, on the canvas or on its own
- An edge label’s color is the scene’s when the edge’s
textColororstroke, or paletteedgeStroke, sets it. A node’s text color is the scene’s when its style or paletteforegroundsets it. - In a preview that adapts the scene’s colors, the cap holds for lines only, and text reaches 4.5:1.
- On the Google Cloud boundary’s blue the cap doesn’t hold, in a default render too. An edge label reaches 4.5:1, and an edge’s line reaches 3:1. Google Cloud edges lists the exceptions.
- When a scene’s text color falls short, a color with a hue moves lighter or darker at that hue (and its own chroma) only as far as it has to, and a white, gray or black becomes
#1a1a1aor#fffffflike the theme’s. A line that falls short moves lighter or darker at its hue, toward the theme’s text color when that reaches the target. - Where one text color can’t reach its target on every part of a knockout (a label half on a light frame, half on a dark node), the parts it can’t read on take the color covering most of the knockout.
- Under adaptive colors, a theme line on a surface the scene didn’t color is left as the theme designed it; on one the scene colored, it keeps the contrast it has on the theme’s canvas, up to 3:1.
Sketch mode
The sketch theme uses a deterministic hand-drawn renderer with seeded randomness - the same scene always produces the same output. Shapes are rendered with wobbly lines and jittered control points instead of clean SVG primitives. Edges wobble too, a curved edge along its curve, but start and end exactly where the layout routed them, and don’t wobble where that would move an arrowhead or ER glyph: an edge’s end runs straight on its routed line under its own glyph, and straight past another edge’s glyph, so every glyph points along its edge and keeps the room the layout left it. Dashed strokes (dashed edge types, style.dash, sequence lifelines) are drawn once, in the same dash pattern as the other themes. A lifeline runs straight where a message meets it, so the message meets it where it does in every theme. Sketch mode uses seeded randomness (mulberry32 PRNG) - the same scene always produces the same hand-drawn output, ensuring deterministic rendering.
Supported formats by surface
| Format | HTTP API | MCP |
|---|---|---|
| SVG | yes | yes |
| PNG | yes | yes |
Formats
| Format | MIME Type | Output | Use case |
|---|---|---|---|
| SVG | image/svg+xml | SVG markup | Web display, embedding, vector editing |
| PNG | image/png | Binary image | Documentation, sharing, fixed-resolution |
SVG
The default format. Everything it draws is inside it, except an icon or image given as a URL (Icon rendering). The response body is the SVG itself, from a preview or from GET /v1/images/{id}@{revision}.svg. A saved version’s SVG names its version on the root element, in data-zindex-id, data-zindex-revision and data-zindex-hash.
The root names the diagram’s language in lang, for screen readers: the scene’s lang, else the language its Chinese, Japanese or Korean text shows. A diagram with neither has no lang.
Each element is named in the SVG. An image drawn from 7.1.0 puts each element’s markup in a <g data-zindex-element="<id>"> group, so a page or a script can find an element in the picture by its id (svg.querySelectorAll('[data-zindex-element="api"]')), as draw.io names its cells and Mermaid its nodes. An edge and its label are drawn in two passes, so a labeled edge has two groups with its id, the line and then the label; a sequence participant has two, its head and tail and then its foot (one with showLifelineFeet: false). An edge’s group holds its whole line unless it shares a stretch with edges drawn alike (the same color, width and dash): a fan-out’s stub, a joined trunk or a bus is drawn once, in one of their groups, so a shared line keeps a single line’s weight instead of darkening with each edge on it, and an arrowhead or ER glyph several edges draw alike at one point is drawn once too. A fork’s dot, and a joined trunk’s, is drawn in the group of the one edge that carries it in its junctions. A step badge is drawn in the group of the first edge it stands for, and each line of the step list in its own edge’s group. The layout’s computed paths keep every edge’s whole route. A frame’s group holds its border and title, not its members. A group element draws nothing: a titled one’s group holds only its title, as an SVG <title>, and an untitled one has none. Arrowheads are markers in the <defs>, shared by color (and, in a diff, size), so they’re in no group; nor are the background, the stamp and a diff’s legend, and an element that draws nothing has no group. In a diff (?from=), a removed element’s ghost carries its id, and a stretch of line two edges share is drawn once, in the group of the edge that draws it, so an edge’s group can hold only part of its line; a dot where a changed branch parts is drawn in that branch’s group. An ER table’s columns are drawn inside the table’s group, so a page can mark only the whole table. Previews and ?engine=current and ?from= images carry the groups, and so does a version’s kept image when its engine is 7.1.0 or later; a kept image drawn earlier never changes, so it has none, and ?engine=current draws that version with them. PNGs carry none. An element’s id is in the SVG, so don’t put in an id what you wouldn’t put in a label.
Text is drawn from glyphs. An image drawn from 8.41.0 defines each glyph’s outline once, in a <defs> at its top, and one drawn from 9.1.0 each emoji’s drawing in its colors too. An element’s group places its text’s glyphs with <use xlink:href> and holds the text itself in a <title>. Copy the <defs> with any group you take out of the image. A kept image drawn earlier has one <path> per line of text.
Rendering pipeline:
- Background rectangle from canvas configuration
- Elements in z order, each drawn whole: a frame’s border and title, a node’s shape (any of the shapes), icon and wrapped label, an edge’s routed line (straight, orthogonal, curved, polyline), a group’s
<title>(a group draws nothing), text, images and guides. In a sequence diagram, participants and activation bars come before every message, whatever theirzIndex, so messages paint over the lifelines and bars they cross, as Mermaid draws them; notes and every other element keep theirzIndexorder. A spanning frame paints right after the last other frame, so edges paint over it - Sequence lifelines’ foot bars
- Edge labels, step badges and the step list, on top of everything else
- The stamp, on a saved version
- Arrow markers (triangle, open triangle, diamond, circle, open circle, bar) in the
<defs>, one per kind and color
Styles applied: fill, stroke, strokeWidth, cornerRadius, fontSize, fontWeight, fontFamily (sans or mono), textColor, dash patterns, opacity, label backgrounds. opacity (0 to 1) fades the whole element as one, as CSS opacity does: a node’s shape, icon and label, or an edge’s line and its label.
accentColor draws:
- the header and PK badges of an
er.entityorer.weakEntitywithextensions.columns - the stripe of an
org.personororg.role - the title bar of a
uiflow.screenoruiflow.modal - the border and title of a frame, a Google Cloud zone apart (Frame color)
It draws nothing on any other element. A check, save or edit returns the warning ACCENT_COLOR_NOT_DRAWN, and its fix names what colors that element.
Dashes at a cross. A dashed line ending in a cross has a dash end at the X’s center, so the X stands on a dash. Past the center the pattern runs on to the node. The sketch theme’s wobbly lines keep their pattern as written, and a sequence.destroy message’s X is the destroy mark, not a cross, so its line keeps its pattern too.
Dashes at an open V. An open V (openTriangle) shows the line through it, so a dashed line that ends in one (a sequence reply, a BPMN message flow, a dashed edge in an AWS diagram) has its pattern stretched to a whole number of dashes over the length it draws, round its corners and along a curve, as a dashed frame’s border is fitted to its side: it starts on a dash at its source and its last dash ends at the V’s tip. Every other dashed line keeps its pattern as written, since a filled arrowhead covers the line’s end, and the sketch theme’s wobbly lines keep theirs. In a colored diff, a dashed line drawn in several pieces keeps one pattern along them.
Visual diff rendering
Render a color-coded comparison between two revisions of a diagram. Added elements appear in green, removed elements as red dashed ghosts, changed elements in amber, and unchanged elements are faded.
Add ?from=<revision> to a version’s image, with your API key:
GET /v1/images/{id}@3.svg?from=1
| Change type | Visual treatment | On a light canvas | On a dark canvas |
|---|---|---|---|
| Added | Green border or line, 3px; arrowheads and ER glyphs at their usual size; a frame keeps its own border and gets a green ring (below) | #15803d | #22c55e |
| Removed | Red ghost, 2px, dashed 2,3 (an edge type drawn dashed keeps its own dash), faded to 60% with the same floors as Unchanged; a frame’s ghost keeps its own border, faded the same way, and gets a red dashed ring (below) | #b91c1c | #f87171 |
| Changed | Amber border or line, 3px; arrowheads and ER glyphs at their usual size; a frame keeps its own border and gets an amber ring (below) | #b45309 | #f59e0b |
| Unchanged | Its own styling, faded to 50%, but no further than its text keeps 4.5:1 and its lines 3:1 against what they’re drawn on (not at all if it’s under that to begin with) |
Each color is the shade of its pair that contrasts more with the diagram’s canvas as it is drawn (a removed ghost at its 60%), so the marks stand out as lines on white and on dark canvases alike; on a mid-gray canvas the three can mix shades. A node that draws its AWS icon alone has no outline to color, so an added, removed or changed one is outlined round what it draws, its icon and the caption under it: edge labels keep clear of that, so none covers the outline. An edge’s label is drawn in its edge’s color; a label several fan-in edges share is drawn in the status of their shared trunk. Under its arrowheads and ER glyphs, a changed edge’s line is drawn at the width the version draws it, so each glyph looks as it does in the version; a curved edge and a sequence self-message keep the heavier line to the end.
A faded label, an unchanged edge’s or a removed ghost’s, keeps an opaque knockout in the colors of what lies under it, so the line it covers stays hidden. Only its text fades, and no further than 4.5:1 on the knockout.
A frame keeps its own border, whose color, width and dash say what kind of group it is, and its status is a ring 4 px clear outside that border. The ring is 3 px and solid in the added or changed color, or 2 px and dashed 2,3 in the removed color round a removed frame’s ghost, as on a step badge. A lane’s ring runs 4 px inside its border instead, since the lanes beside it share that border. A ring breaks round an icon on the border.
The comparison makes room for each ring, so it can differ a little from the plain image of the same version:
- An edge label keeps 6 px from a ring, as from a border, where its edge has a clear place. Without one, as between two close rings, it comes nearer, and its knockout stops short of the ring. Its text crosses a ring only where every place along its edge covers a node, a label or a ring.
- In a sequence diagram, the rows and fragments round a ringed fragment keep their usual gaps from its ring, so the fragment and the rows after it move down.
- The frames round a ringed spanning frame keep their padding outside its ring, and grow in place to keep it.
Lines still cross a ring, as they cross its frame’s border. Apart from a sequence diagram’s rows, the nodes a version placed keep their places.
A stretch of line two edges share, such as the stub a node’s edges leave by before they fork or a fan-in’s trunk, is drawn once, in the status of what is still there: unchanged when any edge on it is unchanged, and unchanged when an added and a removed edge share it, since the line was there and still is. So a new edge’s color starts where it leaves the shared stub. An arrowhead or ER glyph that several edges draw alike at one point is drawn once, the same way. A dot where branches part or join is drawn in the status of the changed branches that start there, when they agree, so a new branch off an unchanged line starts at a green dot and a removed one leaves from a red dot; a branch still drawn outranks a removed one’s ghost there. Any other dot takes the status of the lines drawn alike through it.
Removed elements are merged back from the “from” revision and rendered at their original positions: in a sequence diagram a removed message keeps its row and a removed lifeline its column. A sequence fragment is laid out with its rows, ghost rows included, so it stays around its own messages. A removed member’s ghost is drawn back inside the frame that held it. The legend in the bottom-left corner keys only the statuses the picture draws (Added, Removed, Changed, or No changes), in the same colors, its Removed key as faint as the ghosts, and names the version the picture compares with (Since version 1, or Compared with version 3 for a later one).
What is drawn amber, moved or not:
- A change to a label, type, shape, style, icon, edge end, cardinality or place in a sequence diagram’s order.
- A change to an ER table’s columns, which marks the whole table. The columns themselves aren’t marked.
- A change to a frame’s own fields or its members’ order, or a member joining or leaving it that the comparison doesn’t add or remove. The frame is ringed amber.
What isn’t, though the compare still lists it as changed:
- An element whose only change is its stored position or size (its
layout). An edit moves what lies past a row or column it grows, and a save stores the size a node is drawn at, with nothing a reader reads changed. - A frame whose only change is members the comparison adds or removes. Those members are drawn green or red, and the frame’s title, border and style didn’t change.
A step badge takes the status of the edges it stands for, and is drawn changed when they differ. Its ring is 3 px in the added or changed color, or 2 px dashed 2,3 on a removed ghost, faded as its edges are. A badge in the step list does the same for the edges whose stepText follows it, and each edge’s text fades with its edge. A removed edge’s text is struck through in the removed color, as HTML draws deleted text, faded as its ghost is but no further than 4.5:1 on the canvas.
A spanning frame is drawn round its targets in both versions, so a removed target’s ghost sits inside it, and its status is a ring round it, as any frame’s is. Its targets count as a frame’s members, so a target the comparison adds or removes doesn’t ring it amber.
Works for SVG and PNG. Zindex draws the comparison on request with the current engine and doesn’t keep it. from must be another revision of the same diagram; anything else is a 400. Links from GET /v1/diagrams/{id}/render and the MCP tool diagram_render draw the plain version. For a published diagram those links are version links, and a version link’s image takes from with no key, from another version the link shows (https://zindex.ai/d/{ref}@3.svg?from=2; What changed, through a version link). For a private diagram, an agent connected only over MCP gets changes as text from diagram_history with compare. The dashboard’s diagram page, a version link’s page, and presenting either, draw the same view with Color what changed.
Text and scripts
Text is drawn in Inter, the default fontFamily, sans. A style with fontFamily mono draws in a monospace font, for paths, endpoints and types. Any other fontFamily draws in Inter with the warning FONT_FAMILY_UNKNOWN. A fallback font draws each character the font doesn’t have. Together they draw digits, punctuation and:
- Latin, Cyrillic and Greek letters with their accents, and the phonetic alphabet. That covers English and the other European languages written in Latin letters, Russian, Ukrainian, Bulgarian, Serbian, Macedonian, Greek, Turkish and Vietnamese.
- Armenian and Georgian.
- Chinese, Japanese and Korean, with their punctuation and the fullwidth letters and digits typed with them (
A,1). - Arrows, among them
← ↑ → ↓ ↔ ↕ ↖ ↗ ↘ ↙ ↩ ↪ ↵ ↺ ↻ ↦ ⇄ ⇐ ⇒ ⇔ ⟵ ⟶ ⟷ ⟸ ⟹ ⟺ ➜. - Math, logic and set signs, among them
+ − × ÷ ± = ≠ ≈ ≤ ≥ ¬ ∞ √ ∑ ∏ ∫ ∂ ∆ ∅ ⊕ ⊗ ∧ ∨ ≡ ∀ ∃ ∈ ∉ ⊂ ⊆ ∪ ∩ ∇. - Currency signs, among them
$ ¢ £ ¥ € ₹ ₽ ₩ ₺ ₴ ₪ ₫ ₦ ₱ ₲ ₵ ₸ ₼ ₾ ฿ ₿. - Superscript and subscript digits (
⁰ ¹ ² ³ ⁴ ⁵ ⁶ ⁷ ⁸ ⁹and₀ ₁ ₂ ₃ ₄ ₅ ₆ ₇ ₈ ₉) and fractions, among them¼ ½ ¾ ⅓ ⅔ ⅛ ⅜ ⅝ ⅞. - Symbols, among them
✓ ✗ ★ ☆ ♥ ⚠ • ☐ ☑ ⚙ ⌘ ⏎, and box-drawing characters, among them─ │ ┌ ┐ └ ┘ ├ ┤ ┼. - Emoji, in color: every emoji of Unicode 18.0, among them
😀 ✅ ❌ 🚀 👍🏽 🇯🇵 1️⃣ 👨👩👧.
Text is shaped as browsers shape it, and letters are kerned. In sans, an arrow typed in ASCII, such as ->, <-, <->, => or -->, is drawn as one arrow, in code such as p->next too. In mono it stays as typed.
A Chinese character takes the forms of the scene’s language: Japanese, Korean, Simplified, Traditional or Hong Kong Chinese. A scene.lang that names Chinese, Japanese or Korean sets it. Otherwise the text decides, as that entry says.
Box-drawing characters line up as in a terminal, so a tree such as ├── src/ keeps its columns and its vertical lines join from line to line. Other columns aligned with spaces line up only in mono. A tab moves to the next tab stop, every eight spaces from the start of its line, in either family.
An emoji keeps its own colors in every image, whatever the theme or the text’s color, and is never bold or slanted. Skin tones, flags, keycaps and ZWJ sequences, such as 👩💻 or 👨👩👧, are each drawn as one emoji. A sign Unicode shows as text by default, such as ⚠, ✔, ❤ or ♥, is drawn as text in the text’s color. Followed by U+FE0F, the emoji selector (⚠️, ❤️), it is drawn as an emoji. U+FE0E asks for text, and an emoji no text font has is still drawn in color. An emoji is about a quarter wider than the font size, about two characters in mono.
A character no font has is drawn as an empty box (□). These are boxes:
- Other scripts, among them Arabic, Hebrew, Thai and the Indic scripts.
- Most rare Chinese characters, such as those in Unicode’s later extensions (Extension B onward), among them
𠀀. - A few rare signs.
- A character newer than Unicode 18.0, such as a new emoji. A new sequence of older emoji is drawn as those emoji.
Text is measured as it is drawn, with its emoji, boxes and arrows, so a node the engine sizes fits its label as drawn. When drawn text holds a box, a check, save or edit returns a CHARACTER_NOT_DRAWN warning. Where a label must be readable, write it in one of the scripts above.
A letter followed by a combining accent is drawn with the accent on the letter. A character no SVG can hold is left out of the picture, with no warning: a control character below U+0020 other than a tab or a line break, such as a NUL or a vertical tab, and U+FFFE and U+FFFF. The text is measured and drawn without it. The scene keeps the text as you sent it.
Icon rendering
Nodes with an icon field render a semantic icon inside the node shape, positioned above the label. A Google Cloud icon is drawn beside the label, on Google’s card (Google Cloud cards).
- Icons are referenced by key (
{family}:{id}, e.g.lucide:database), or given as adata:URI or a URL. A key no built-in icon has keeps the icon’s room and draws nothing, and the API returnsICON_NOT_FOUNDfor it - Three packs ship with the platform: about 52 Lucide icons (generic, ISC license), the official AWS Architecture Icons, about 780 (AWS icon keys), and Google Cloud’s product icons, about 250 keys (Google Cloud icon keys). AWS Architecture Icons, Release 24 (2026-07-31), © Amazon Web Services, Inc. or its affiliates. Drawn unmodified in architecture diagrams, as AWS allows: https://aws.amazon.com/architecture/icons/. Zindex is not affiliated with or endorsed by AWS.
- Google Cloud product icons (Updated May 2026), from https://cloud.google.com/icons. Google Cloud and Google’s product names and icons are trademarks of Google LLC. Zindex is not affiliated with or endorsed by Google. People, devices and places draw Google’s Material Symbols (Apache License 2.0, https://github.com/google/material-design-icons).
- A built-in icon’s SVG is base64-encoded and embedded, so the image is self-contained: a Lucide icon as an
<image>, an AWS or Google Cloud icon’s file once per image as a<symbol>in<defs>, drawn with<use>wherever the icon appears. An icon given as a URL stays a link in the SVG: images Zindex serves don’t load it, nor do most viewers, and PNG output leaves it out. A check or save returns the warningASSET_URI_POLICY_VIOLATIONfor it. An icon given as adata:URI is drawn wherever the image is - Icon color:
currentColorin the source SVG (the Lucide icons) is replaced with the node’s resolvedtextColor, so icons automatically match the active theme. AWS icons are AWS’s files byte for byte, never recolored, cropped or stripped of their tile; where AWS ships a light and a dark variant (Users, Client, the AWS Cloud logo), the one whose ink contrasts more with what is under the icon is drawn. Google Cloud icons are Google’s files byte for byte, never recolored, cropped, flipped or rotated; the Material Symbols for people, devices and places are filled in the near-black Google draws people in - Icon size: a Lucide icon scales with the node, at most 32 px and 40% of its width and height (decorative role). An AWS icon is drawn at AWS’s predefined size for its kind, scaled to the 14 px label, whatever the node’s box (AWS: use icons at their predefined size): a service icon 70 px, a resource or general icon 42 px, a group icon 35 px. Its label wraps at 160 px, balanced, below the icon, and the measurer sizes the node to hold both. A Google Cloud icon’s size is on its card (Google Cloud cards)
- When both icon and label are present, they stack vertically, wrapped or not: icon on top, label below, 4 px apart. A label’s
textStyle.verticalAlignplaces the whole stack, andtextStyle.align"left"or"right"puts the icon on that side, the padding in from the edge, whether or not the label wraps. The measurer reserves enough vertical room for the stack automatically,layout.autoSize: "content"counts the icon, and agents who explicitly undersize a node get aTEXT_OVERFLOWdiagnostic with the required height. A Google Cloud card places its own text (Google Cloud cards)
AWS icons render icon-only by default
Nodes with an icon prefixed aws: render without their shape by default - just the icon and the label below - whatever the node’s shape says: a database node’s cylinder or an objectStorage node’s bucket isn’t drawn under an AWS icon, and its label and icon aren’t inset for it. Its edges end on the icon’s art, not on the invisible box around it, and an edge into or out of its bottom ends under the label, never through it. An end on a round icon (a gateway, a load balancer, an endpoint or another icon whose art is a circle) meets the circle, not the square round it, as Graphviz and yFiles clip an edge at a node’s shape. Ends on one face of the icon keep 16 px apart where the face holds them, and an arrowhead coming from below meets a side of the icon rather than the label under it when a route one bend longer gets there (Layout Engine: AWS architecture diagrams). A diagram with a node that has an aws:* icon, with or without AWS groups, ends its edges in AWS’s open arrow, an open V, unless an edge’s type has its own arrowhead or the edge sets endArrow, as AWS’s Architecture Icons deck and its networking conventions draw arrows (Element types: Edge types). An externalSystem node is the exception: it keeps its gray dashed box, which marks it outside the trust boundary, with the icon inside, and its edges end on the box. A non-white fill draws the shape too (below). This matches the official AWS Architecture Icons guidance and the AWS shapes of draw.io, Lucidchart and Cloudcraft: AWS’s service icons identify themselves, so a box adds noise. An icon-only node also composites cleanly over a colored container fill, where a white knockout under each service would block the container’s color. AWS’s own groups have no fill (AWS groups).
Default-equivalent fill: an explicit fill: "#ffffff" (white in any form the renderer reads, such as #fff, white, rgb(255, 255, 255), oklch(1 0 0) or var(--x, #fff), opaque or fully transparent) on a cloud-icon node is treated the same as “fill not set” and triggers the icon-only override anyway. Translucent intermediate alpha values (rgba(255, 255, 255, 0.85) and similar) are PRESERVED as deliberate “card-style” tinting - the agent picked a specific alpha for a reason and overriding it would strip a deliberate card-on-container look. This catches defensive default styling from agents (Python codegen, LLM-generated JSON) that emit fill: "#ffffff" on every node without thinking about the AWS convention - the white knockout would override the platform’s intended icon-only render. The whole defensive-default style block (fill + stroke + strokeWidth) is treated as a unit: when fill is default-equivalent, stroke is also dropped so the icon renders cleanly.
Opting back into a bounded look: set fill to any non-white color. A tinted fill (e.g. #ffeeaa, #dde9fb, the platform’s near-white #fefefe) restores the node’s shape (its rect, cylinder or bucket) with the chosen color, the icon drawn in it. To get a bordered icon with a transparent interior (line outline, no fill knockout), set fill: "transparent" or fill: "none" together with the stroke you want - explicitly opting out of “fill is just defensive” semantics.
Generic non-cloud icons (lucide:* and others) keep the bounded-box default - they’re used in mixed contexts where a visible boundary matters. A Google Cloud icon draws a card instead (below).
Google Cloud cards
A node with a gcp:* icon is drawn as Google’s product card, as Google’s Architecture Center diagrams draw every product, whatever the node’s shape:
- The card is white, with a 1 px near-black border and 6 px corners. It fills the node’s box, and edges end on its border as on any box. A stacked card shares the box with its copy (below).
- The icon is 44 px, at the card’s left and centered top to bottom. A person, device or place is 28 px in the same place.
- The text sits beside the icon: the node’s label in 14 px bold, then Google’s name for the product in 14 px regular, both near-black, 18 px apart and centered top to bottom.
- The product line is left out when the label is the product’s name (ignoring case and spacing), for a person, device or place, and for a key Google’s set doesn’t have. A node without a label shows the product’s name in bold.
- The type stays 14 px, bold over regular: a style’s
fontSizeandfontWeightand the node’stextStyledon’t change it, and itsfontFamilydoes.
How a card grows:
- The card widens with its text, up to 230 px of text.
- A longer label wraps to two lines of even length, never inside a word, and so does a longer product name. Lines you break with
\nstay as written, and a word wider than 230 px widens the card. - A card is 70 px tall with one or two lines, 80 with three and 98 with four, and 18 px taller for each line after that.
- The engine sizes a node it places to its card, and a node whose
layoutis smaller than its card grows to fit it. A largerlayoutkeeps its size, the card filling it.
A card keeps its colors on every canvas and in every theme, and dark previews don’t adapt it, so it reads as a light panel on a dark canvas. The scene’s palette doesn’t change it, and in a flowchart it keeps its colors instead of the flowchart tint. The node’s own style does:
fillcolors the card, as Google draws a standby resource on gray (#DADCE0). On a fill too dark for the near-black text, the text turns white or near-black, whichever reads better.stroke,strokeWidth,cornerRadiusandtextColorchange the border, the corners and the text.multiple: truedraws the card as a stack (below).
Two kinds of node don’t draw a card. An externalSystem node keeps its gray dashed box, which marks it outside the trust boundary, with the icon above its label inside; and BPMN, sequence, ER, org chart and UI flow node types draw as their family does.
Stacked cards. Set style.multiple: true on a node that stands for several instances of one product, such as a set of buckets or one zone’s pool of VMs. A named style can carry it, and multiple: false is the same as leaving the key out. The card is drawn as a stack, as Google’s diagrams draw one:
- The copy. One gray copy (
#BDC1C6) sits behind the card, 4 px to the right and 4 px down, with the card’s border and corners. It keeps its gray on every canvas. - The box. The node’s box holds the card and the copy, so it is 4 px wider and 4 px taller than the card alone. Edges end on the box: on the card at its top and left, and on the copy at its right and bottom.
- The card. The icon and the text stay on the card.
fillcolors the card only, so a stacked standby is#DADCE0over the gray copy.stroke,strokeWidthandcornerRadiusapply to both. - On a zone’s strip, the copy stands on the strip, and the strip is as wide as the box. An edge into the bottom meets the strip, as on any zoned card.
What a stack doesn’t do:
- It shows no count. One copy is drawn however many instances there are. Write the number in the label when it matters, such as “Web servers (3)”.
- It doesn’t span zones. A stack is one node, so instances spread over zones stay one card per zone, each on its zone’s strip.
- Only a card draws it. A node that draws no card ignores
multipleand draws as it does without it: one with another icon or none, and the two kinds above. In an AWS diagram, use AWS’s icons for several instances, such asaws:ec2-instancesandaws:ebs-multiple-volumes.
Module / group frames inside colored containers
The default-equivalent rule extends to frames: a frame whose fill is default-equivalent (white in any form, opaque or fully transparent) AND that sits inside a colored ancestor frame gets its fill overridden to "none". Translucent intermediate alphas (e.g. rgba(255, 255, 255, 0.85)) are PRESERVED - a card-on-container look where each module reads as a slight tint over its colored container. Module frames are dashed boundaries that let the parent container’s color show through. AWS’s own groups have no fill: use the presets below.
The override only fires when there’s a colored ancestor in the chain - top-level frames or frames inside transparent ancestors keep their fill (a near-white frame on a white canvas is invisible anyway). The frame’s stroke (typically dashed, marking the module boundary) is preserved - only the fill is overridden, since the stroke is the boundary marker the agent legitimately set.
Recommended alpha for the card-on-container aesthetic: rgba(255, 255, 255, 0.5). This produces a visible-but-subtle white card that lets the parent container’s color show through clearly. Higher alphas (0.7-0.85) look mostly opaque and obscure the parent color; lower alphas (0.2-0.3) look almost transparent and lose the card grouping. 0.5 is the sweet spot. Use a different alpha only if you have a specific aesthetic reason - the platform preserves whatever you set.
AWS groups
A frame whose containerType is one of AWS’s groups is drawn as AWS draws it (AWS Architecture Icons): AWS’s color and line, no fill, AWS’s group icon flush in the top-left corner with the title beside it, and the title in the node label’s size (14 px) and the text color. AWS draws the same group colors on light and dark canvases, and a dark preview leaves them alone, except a border on a fill the scene sets (Adaptive colors). A frame’s own style overrides the preset (a stroke, a dash, a fill), and its icon replaces the preset’s.
| containerType | Border | Line | Icon | Title |
|---|---|---|---|---|
aws.cloud | text color | solid | AWS logo (its dark variant on dark) | beside the icon |
aws.region | #00A4A6 | dashed 4.5,1.5 | Region flag | beside the icon |
aws.az | #00A4A6 | dashed 6,4.5 | none | top center |
aws.vpc | #8C4FFF | solid | VPC | beside the icon |
aws.subnet.public | #7AA116 | solid | lock | beside the icon |
aws.subnet.private | #00A4A6 | solid | lock | beside the icon |
aws.securityGroup | #DD344C | solid | none | top left |
aws.autoScalingGroup | #ED7100 | dashed 6,4.5 | centered on the top edge | centered under the icon |
aws.account | #E7157B | solid | account | beside the icon |
aws.corporateDataCenter | #7D8998 | solid | building | beside the icon |
Lines are 1.5 px. A group icon is 35 px, and the members of a group sit below it. An Auto Scaling group’s icon sits half above its top edge. A frame the engine fits around one keeps that half inside it, clear of its own header.
A frame with an aws:* service icon and no preset is AWS’s custom group: the icon in the corner and the border in the icon’s category color, solid. A stroke or an accentColor in its style replaces that color, and a dash makes the border dashed. Its title keeps its own color, as an AWS group’s does, whatever accentColor says.
Any other icon (a Lucide key or a URL) draws 16 px before a frame’s title, in the title’s color. AWS’s other groups (server contents, EC2 instance contents, Spot Fleet and IoT Greengrass) are a generic frame with a stroke and an icon such as aws:group-server-contents.
A gateway docked on a VPC’s border (an internet gateway, virtual private gateway, VPC endpoint or transit gateway attachment the VPC lists directly) is drawn with its icon centered on the border’s line, on whichever side the layout docks it (Layout Engine: AWS architecture diagrams), and the border breaks under the icon, as it breaks where an edge crosses it, so the gateway reads as sitting on the line. On the left or right side its label is centered under the icon, straddling the border, as AWS’s Site-to-Site VPN figure draws it, and the border breaks under the label too, so the text reads clear of the line. On the top the label lies inside the VPC, and on the bottom outside it, clear of the border.
In an architecture diagram, or one without a family, the AWS Cloud, Region, VPC, Availability Zone and subnet presets also place their members as AWS’s reference diagrams do (Availability Zones as columns, subnets as rows across them), and each group is fitted to its members: Layout Engine: AWS architecture diagrams has the arrangement and what it doesn’t do. In other families, and for the other presets, a frame is laid out as any frame is.
Nest presets as AWS does (AWS Cloud, Region, VPC, Availability Zone, subnet). Three warnings name a frame:
AWS_GROUP_NESTING: a preset inside a preset AWS doesn’t nest it in.AWS_GROUP_UNTYPED: a generic frame that holds AWS icons and is titled with an AWS group’s own name (VPC,Private subnet 2). It names the preset to set, or says the frame can stay generic.AWS_FRAME_HIDES_GROUPS: a generic frame between presets that the layout can’t read through. It names the groups it hides.
A group across Availability Zones, such as an Auto Scaling group over two, is a frame written with spans instead of children, drawn round what it spans (Step badges and spanning frames).
Anchor to the frame when the connection is semantically about the group as a whole (e.g. ‘depends on Regional Services’); anchor to a specific child node when the connection targets a known member.
Layers
A layer draws like a generic frame, except that its border is solid unless its style sets a dash, even when the engine doesn’t arrange it. The plain frames inside it stay dashed, so they read as nested.
Google Cloud groups
A frame whose containerType is one of Google Cloud’s groups is drawn as Google’s Architecture Center diagrams draw it: Google’s fill and line, 6 px corners and no icon. Google draws the same colors on light and dark canvases, and a dark preview leaves them alone, except a border on a fill the scene sets (Adaptive colors). A frame’s own style overrides the preset (a fill, a stroke, a dash), except on a zone (below), and its icon draws 16 px before its title, as on any frame.
| containerType | Fill | Border | Title |
|---|---|---|---|
gcp.cloud | #4285F4 | solid | the wordmark (below); another title white, 22 px |
gcp.project | #F1F3F4 | none | top center, or top left where the layout moves it (below) |
gcp.region | #E8EAED | solid | top left |
gcp.vpc | none | 2 px, dashed 8,8 | 17 px bold |
gcp.subnet | none | dashed 4,4 | top left |
gcp.zone | a strip under each node | solid | in each strip |
gcp.tier | white | solid | facing the next Region |
gcp.instanceGroup | white | solid | facing the next Region, its kind opposite |
gcp.onPremises | #EFEBE9 | solid | top left |
Borders are 1 px and near-black unless the table says otherwise. Titles are 14 px and near-black unless it says otherwise, and sit at the top left unless it gives another place. The VPC’s title is white where it sits on the boundary’s blue, and near-black elsewhere.
A project’s title. It stands at the top center. The layout moves it to the top left, project by project, where a line from above would otherwise run down beside it (when it moves). A project with an icon draws its title after the icon at the left, as any frame does.
The boundary’s wordmark. A gcp.cloud with no title, or titled “Google Cloud” in any case, draws Google’s white “Google Cloud” wordmark in its top-left corner, 24 px high.
- The SVG keeps “Google Cloud” as the wordmark’s text for screen readers.
- Any other title, such as “Google Cloud: production”, is drawn as written in white text, with no wordmark. To name a project or an environment, put a
gcp.projectframe inside the boundary. - A boundary with an
iconof its own draws the icon before its title, as any frame does, and no wordmark. - The wordmark is never recolored. It is Google’s near-black version on a light
fillfrom the frame’sstyle, or with a darktextColor, and white otherwise.
Zones. gcp.zone is a spanning frame, written with spans listing the nodes in one zone of one Region. It draws no box. Under each node it spans it draws a 30 px strip, the node’s width, with the zone’s title centered in it.
- A strip’s color is the zone’s place among its Region’s zones, in the order the scene lists them: green (
#CEEAD6), blue (#D2E3FC), yellow (#FEEFC3), then again. So the first zone of every Region has one color. - Each node a zone spans is 30 px taller, its box holding the card and the strip below it. An edge into its side meets the card, or a stack’s copy on its right, and one into its bottom meets the strip.
- A node two zones span takes the first one’s strip. The strips keep Google’s colors whatever the zone’s
stylesays.
Tier titles. A tier’s or instance group’s title faces the next Region, as Google mirrors it: top right in every Region but the last, and top left in the last or only one.
Instance groups. gcp.instanceGroup writes its kind in the top corner its title doesn’t take, from the zones that span the nodes it holds: “Regional MIG” for two or more zones, “Zonal MIG” for one, and nothing when no zone spans them.
VPC networks. gcp.vpc is a spanning frame too, written with spans listing its subnets, and drawn round them across their Regions (Step badges and spanning frames). In Google’s arrangement it is one straight band across those Regions, its title before the first. Spanning frames, zones among them, are drawn in architecture diagrams and diagrams without a family.
In an architecture diagram, or one without a family, the boundary, Region and subnet presets also arrange their members, zones as columns and tiers as rows, and each group is fitted to its members (Layout Engine: Google Cloud architecture diagrams). In other families, a frame is laid out as any frame is.
GKE clusters, node pools, folders and custom groups have no preset (Element types: Container types). Three warnings name a frame (Validation rules):
GCP_GROUP_NESTING: a preset nested where Google doesn’t nest it.GCP_GROUP_UNTYPED: a generic frame that holdsgcp:*icons and is titled with a Google group’s own name (VPC network,Region: us-east1). It names the preset to set, or says the frame can stay generic.GCP_FRAME_HIDES_GROUPS: a generic frame in a Region round its subnets, or in a subnet round its tiers. It names the groups it hides.
Google Cloud edges
A diagram drawn in Google Cloud’s style, one with Google’s groups or gcp:* icons and no other cloud’s, draws every edge as Google’s connectors are drawn:
- a 2 px near-black line (
#202124), its bends rounded at 6 px; - labels at 14 px;
- the open arrow, its default arrowhead (Element types: Edge types), as Google’s small chevron.
The chevron is 11.6 px across at Google’s 2 px line. Where the engine spreads ends along a face, it places two arrowheads at least 13.6 px apart (other diagrams use 12 px), which leaves 2 px between their wings. Ends that share a point, and a side too short for its ends, are the exceptions (Where an edge enters its target).
Where the near-black line reads below 3:1 on the canvas, such as a dark one, an edge takes the palette’s edgeStroke, or else the theme’s line color, off Google’s filled groups. On them it stays near-black.
An edge whose style sets stroke keeps that color, except on the boundary’s blue and in a dark preview (both below). Its strokeWidth and dash apply as on any edge. A diagram that mixes AWS and Google Cloud keeps the theme’s edges, with the open V.
The router keeps lines off the boundary’s blue when any route does (Layout Engine: Google Cloud architecture diagrams). An edge’s line is drawn darker where it runs on the boundary’s blue and reads below 3:1 there: the same hue, as far as 3:1 needs. A color that already has 3:1 on the blue, as Google’s near-black does, is kept. An arrowhead or junction dot on the blue is drawn the same way.
The blue is the part of gcp.cloud outside the filled groups it holds. Off the blue this rule changes nothing, on Google’s gray and white groups too. A diagram that mixes AWS and Google Cloud follows the same rule.
On the blue the line is not darkened when:
- the boundary’s own
stylesets itsfill; - the image is a visual diff (Visual diff rendering).
In a dark preview of a diagram in Google Cloud’s style, an edge whose style sets stroke takes its adapted color on the canvas around Google’s filled groups. On those groups it is drawn as in the default render: as written, and darker on the blue.
A label goes on the boundary’s blue only where its line has no clear place off it (Layout Engine: label placement). There its text reaches 4.5:1, even in a color the scene sets, so a dark orange is drawn darker. A label on the boundary’s blue with its own line under its text has an opaque knockout, so the line doesn’t show through the text. A label with its own labelBackground is checked on that background instead, like any color the scene sets (Contrast).
Workflow rendering
When nodeType uses workflow family types, the renderer produces BPMN-inspired shapes:
| nodeType | Rendering | Label position |
|---|---|---|
workflow.start | Filled circle (BPMN start event) | External: below the circle, or above it in some vertical flows |
workflow.end | Bold-stroke circle (BPMN end event, stroke-width >= 3) | External: below the circle, or above it in some vertical flows |
workflow.gateway | Diamond with x marker (exclusive gateway) | External: below the diamond, or above it in some vertical flows |
workflow.gatewayParallel | Diamond with + marker (parallel gateway) | External: below the diamond, or above it in some vertical flows |
workflow.gatewayInclusive | Diamond with circle marker (inclusive gateway) | External: below the diamond, or above it in some vertical flows |
workflow.timer | Circle with clock-hand lines (timer event) | External: below the circle, or above it in some vertical flows |
workflow.error | Circle with zigzag path (error event) | External: below the circle, or above it in some vertical flows |
workflow.task | Falls through to generic shape (roundedRect) | Inside the shape |
workflow.subprocess | Falls through to generic shape (roundedRect) | Inside the shape |
workflow.decision | Diamond, sized to inscribe the label | Inside the diamond |
The four workflow.gateway* types use the BPMN external-label convention because their diamond interiors carry a marker glyph (x, +, circle, pentagon) and there is no room for prose. workflow.decision is the marker-less alternative, sized so the label fits inside the diamond’s inscribed rectangle - matching the broader flowchart convention used by Mermaid, draw.io, Lucidchart, yEd, and PlantUML.
An external label (events, gateways, and uiflow.entry and uiflow.exit) goes below the shape, unless the flow would run through it. In a top-to-bottom (TB) flow, a node whose edges all leave from its bottom, such as a start event, has its label above the shape. In a bottom-to-top (BT) flow, a node whose edges all arrive at its bottom, such as an end event, does too. The engine picks the side from the node’s edges and the flow direction; there is nothing to set. Edges connect to the shape, not to the label’s space, and an edge into a gateway ends on its diamond.
The shape stays where the node’s layout puts it. On a box no taller than the shape (a 40 x 40 event drawn at 50, a 50 x 50 gateway drawn at 70) the shape is centered on the box, and the box grows round it for the label; a taller box, as the engine writes one, holds the shape at its top with the label below, or at its bottom with the label above. A label pushes nothing, except a node or frame it would come within 8 px of, which it pushes to 8 px, or to the gap it had if that was smaller. Frames with their own layout grow round a label, and so do pools and lanes, whatever their layout.
Where the label side stops:
- A node with edges at both ends of a
TBorBTflow (an intermediate event, a gateway with a flow straight through it) keeps its label below, and the edge leaving its bottom crosses the label. - In
LRandRLflows every external label stays below. An edge’s end keeps off the face of the shape its label covers while another face gives it a clean route, as bpmn-js leaves an event by its side for a flow to the lane below; when none does, an edge that reaches the shape’s bottom from a lower row crosses the label. - In every flow direction, a route otherwise keeps out of its own nodes’ labels but for the segment that docks, as ELK keeps edges out of a node’s label margins: a flow leaving a gateway’s side tip runs past the gateway’s label before it turns. A route the engine has no clean choice for (an edge through the planner’s waypoints, a bundle, or the last resort) can still cross one.
Workflow edge rendering:
| edgeType | Line style | End arrowhead | Start arrowhead |
|---|---|---|---|
workflow.sequenceFlow | Solid line | Filled triangle | None |
workflow.messageFlow | Dashed line (6,3, fitted to end on a dash at the arrowhead) | Open triangle | Open circle |
default (no family override) | Solid line | Filled triangle | None |
For workflow diagrams, prefer workflow.sequenceFlow over plain default for sequential edges: it says the edge is BPMN sequence flow. Both draw a filled triangle at the target, so a reader can follow the flow without reading every label.
ER diagram rendering
Entity-Relationship diagrams get specialized rendering when using ER family types:
ER node rendering
| nodeType | Rendering |
|---|---|
er.entity | Standard rect (generic shape) |
er.weakEntity | Double-border rect (outer + inner rect with 4px inset) |
er.attribute | Ellipse (generic shape) |
er.relationship | Diamond (generic shape) |
Crow’s-foot cardinality markers
When edge endpoints include a cardinality field, the renderer produces crow’s-foot notation markers instead of standard arrows:
| Cardinality | Marker | Notation |
|---|---|---|
one | | | Single vertical line |
many | < | Crow’s foot: three prongs that touch the entity and meet on the line |
zero-or-one | ○| | Circle + vertical line |
zero-or-many | ○< | Circle + crow’s foot |
one-or-many | |< | Vertical line + crow’s foot |
Relationship lines are solid for er.relationship and er.identifying, as Mermaid and Information Engineering draw an identifying relationship. Add style.dash (for example [6, 4]) to draw a non-identifying relationship dashed.
Cardinality markers are specified per-endpoint, so from: { cardinality: "one" } and to: { cardinality: "many" } produces a one-to-many relationship.
Relationships into one row from one side, drawn alike (the same line and the same glyph at the row), share one riser into the row, with one glyph at it and a dot where each joins, as ELK draws edges that share a port. One drawn differently keeps its own line, and so do all of them when an edge also leaves by that row, when one runs straight in from another table’s row (a dot on a line between two tables would read as a reference to either), or when the join would add a crossing or run through a table (Joined entries).
A relationship whose route crosses another route is routed once more with every other route in place, as libavoid and yFiles can route crossing edges again. It goes round the other side of a table instead when that way leaves and enters by the same sides, takes no more bends, stays inside the drawing, runs no closer to a table and leaves the finished diagram with fewer crossings, so its line can run longer. Where no such way exists (two rows whose keys lie the other way round, with no table to go round, or a way that would need more bends or run past the drawing’s edge), the crossing stays, drawn plain.
Only relationships that end on a table’s row and are routed orthogonally take part. In a diagram with many crossings only the relationships that cross most are tried, eight at most. A diagram of more than 250 edges is left as routed, so the pass adds nothing to a large schema’s drawing time. In flowchart, workflow, UI-flow and architecture diagrams and diagrams without a family (not an AWS diagram the cloud layout arranges), long edges are routed again by a looser rule, which lets them change sides and take up to two more bends (Edge routing).
When cardinality is omitted on an endpoint and the endpoint resolves to a known column (via endpoint.column or the PK fallback for entities with a single primary key), the engine infers the cardinality from the column’s pk / fk / unique / nullable flags each time it draws the diagram, so the glyph follows the column. Author-set values are always preserved. See Crow’s Foot cardinality (auto-inference) for the full rule.
Self-loops skip glyph rendering. When an edge’s source and target are the same entity (e.g. a parent_id-style self-FK), the renderer omits Crow’s Foot glyphs on both endpoints. The U-bracket geometry that draws self-loops is too tight to fit two readable markers; the column-row position inside the entity already conveys the relationship’s direction.
Another relationship that ends at the loop’s row shares the loop’s last leg and parts from it at the loop’s corner. A dot marks the fork when the two lines are drawn alike (Forks).
Sequence diagram rendering
When diagramFamily is "sequence", the layout engine positions lifelines horizontally and orders messages vertically by their position in the elements array (definition order = visual order). An edit puts a new lifeline, message or note between two others, or moves one, with after or before (Operations: Order in a sequence diagram).
Lifeline rendering
| nodeType | Rendering |
|---|---|
sequence.lifeline | A box, the label in it |
sequence.actor | A stick figure, the label under it |
sequence.boundary | A circle joined by a short line to a bar standing at its left, the label under it |
sequence.control | A circle with a small arrowhead on its top, the label under it |
sequence.entity | A circle standing on a line, the label under it |
sequence.database | An upright cylinder, the label under it |
sequence.collections | Two rectangles, one behind the other and up to its right, the label in the front one |
sequence.queue | A cylinder lying on its side, the label on it |
sequence.note | Rect with a folded top-right corner; soft yellow fill (dark olive under dark and sketch, navy under blueprint) and a gold border, unless the note’s style or the palette sets fill or stroke; over its lifeline, across several, or beside one (below) |
Figure heads and box heads. The eight participant types differ only in the head and foot they draw. Each has the same dashed tail, and the rest of this section applies to all of them.
- Figure heads (actor, boundary, control, entity, database): an icon on the lifeline, the label under it on whatever is behind the head. The icons are UML’s, as Mermaid and PlantUML draw them.
- Box heads (lifeline, collections, queue): the label inside.
A participant’s style sets the fill, stroke and textColor of either.
Lifeline head and foot. Each lifeline renders both a head bar at the top and a matching foot bar at the bottom of the diagram by default - UML convention also followed by PlantUML, Mermaid, and yEd. The dashed lifeline tail ends on the foot: a box foot’s top, a figure foot’s icon. To suppress foot bars (e.g. when the author has their own bottom row of shapes), set showLifelineFeet: false in the document’s top-level extensions.
Created and destroyed lifelines. A lifeline whose first row is a sequence.create message arriving at it has its head on that row, as UML and PlantUML draw a created participant. A box head is centered on the arrow, which ends at the box’s side. A figure head has its icon on the arrow, however many lines its name takes. The arrow ends at the side of the icon it reaches, such as a database’s wall.
A lifeline that a sequence.destroy message arrives at ends at that arrow’s X, with no foot bar. A bar on such a lifeline starts below its head and stops at the destroy row.
- Only a message’s target is created or destroyed, by the first such message, and a message from a lifeline to itself does neither. To end a lifeline that sends, add a destroy message to it.
- A lifeline that a message or note uses above its create message, or below its destroy message, is drawn full height on that side, with the warning
FAMILY_SEQ_USED_BEFORE_CREATEorFAMILY_SEQ_USED_AFTER_DESTROY.
Notes beside a lifeline. A note with extensions.side and one lifeline’s ID as its anchor sits beside that lifeline, its near edge 25 px from it, as Mermaid and PlantUML place note left of and note right of. The gap beside it widens to hold it, and one beside the first or last lifeline widens the drawing (Element types has the fields).
Notes with no anchor. A note with no extensions.anchor is drawn over the lifelines of the message above it, or beside one of them with side (Element types has the cases).
Header auto-sizing and content-aware pitch. A head is as wide as its label and padding need, and at least 100 px. A collections head is 5 px wider and a queue head 12 px wider, to hold their drawing. A box head is 40 px tall and grows to fit a multi-line label (e.g. "Compute Endpoint\n(Metadata)"). All box heads on a diagram are as tall as the tallest of them, so their dashed tails start level, and a box foot is as tall as its head. A figure’s name doesn’t change a box head’s height.
The first row. Rows start below the tallest head at the top, so a first message’s label never sits on a figure’s name. A figure head is 70 px tall, and 16 px more for each extra line of its name. A figure’s dashed line starts below the name’s last line, and its foot is as tall as its head. A created participant’s head is on its own row and doesn’t count.
Lane pitch. The pitch is computed per pair: each adjacent lifeline pair gets the larger of the equal-share floor, the header crowding guard (16 px gutter past auto-sized headers), and the self-message arc clearance - so a single wide self-message on one lifeline doesn’t push every other gap wider too. The canvas auto-extends if total content exceeds the declared canvas width.
Message rows. Each message’s label sits above its own arrow, as PlantUML, Mermaid and draw.io place it, centered over it unless something is in the way: on a message that passes over other lifelines, their columns can push it toward one end. A self-message’s label sits above its loop’s top arm, or beside the loop when the row above is taken. Each row keeps its label’s height clear above its arrow: below the message before it, the lifeline header band (an obstacle to every label), a note, a fragment’s header, an operand’s guard and the end of a fragment. So a label goes below its arrow only when nothing above or beside it is clear for some other reason, and onto its arrow only when nothing below is clear either.
Activation bars. A bar (sequence.activation) runs from the arrow of the message named by its extensions.startsAt to the arrow of extensions.endsAt, on the lifeline startsAt arrives at, or one row tall without endsAt (PlantUML’s activate and deactivate, Mermaid’s + and -). A message to or from the lifeline in those rows ends at the bar’s side that faces its other end, and a self-message leaves and returns on the bar’s right side, so every arrowhead shows. An endsAt that comes before startsAt is ignored, and the bar is one row tall (FAMILY_SEQ_ACTIVATION_ENDS_BEFORE_START). A bar with a box and no startsAt is drawn over the messages the box covers on the nearest lifeline.
Stacked bars. A bar that starts while another is open on its lifeline is drawn 8 px to the right of it, a level for each open bar, as Mermaid stacks them, so no bar hides another. A message meets the outermost bar face on the side toward its other end. A nested bar that a self-call opens starts where the call comes back. A bar that opens on the row another ends on isn’t stacked; it is drawn in line with that one.
Message rendering
| edgeType | Rendering |
|---|---|
sequence.message | Solid line with filled arrowhead (synchronous call) |
sequence.async | Solid line with open arrowhead (asynchronous message) |
sequence.reply | Dashed line with open arrowhead (return value) |
sequence.create | Dashed line with filled arrowhead, ending at the side of the head of the lifeline it creates |
sequence.destroy | Solid line with filled arrowhead and an X where it ends, the lifeline it destroys ending there; with endArrow: "cross", only the destroy X, with no arrowhead |
style.dash overrides a dashed type’s 6,3 (Element types: Edge types). endpoints change a message’s arrowheads, a cross included (Element types: Endpoints). A numbered message has a badge at its arrow’s start (Layout Engine: Numbered messages).
A message whose type is left out. In a diagram whose diagramFamily is sequence, an edge between two participants with no sequence.* type is a message, as in Mermaid, PlantUML and UML. That is an edge whose edgeType is absent, default or another family’s. Its line says which kind, by the rule the Mermaid import uses:
- A line with
style.dashset to a pattern is asequence.reply, whatever its arrowheads. - A solid line with
endArrow: "openTriangle"and nostartArrowis asequence.async. - Any other solid line is a
sequence.message.
Only style.dash and endpoints count. An edgeType from another family adds no dash or arrowhead, so a uiflow.back edge here draws solid.
A message of this kind keeps its place in elements, its endpoints and its style. It takes a row, counts in autonumber, can start or end an activation bar and is written to Mermaid as a message. The saved scene keeps default; the kind is worked out each time the diagram is drawn. Set a sequence.* type to choose the kind yourself: only that makes a create or a destroy.
An edge with an end that isn’t a participant isn’t a message. It is drawn outside the message rows, with the warning FAMILY_SEQ_ORPHAN_MESSAGE: join it to two participants, or remove it.
A message label wider than 200 px wraps above its arrow, and its row grows to hold the lines (each row keeps its label’s height: Message rows). The lifelines don’t move apart for a message’s label, except in two gaps: a self-message’s loop, and the gap to a lifeline the message creates. A wrapped label wider than the gap between its lifelines is drawn over the lifelines it reaches, and its backdrop hides a stretch of each. To keep a label off them, shorten it or break it with \n.
Self-messages (from and to referencing the same lifeline) render as U-shaped loops with rounded interior corners (PlantUML / Lucidchart convention). The loop’s arc width auto-sizes to fit the message label centered above the top arm with clearance from the source lifeline body - agents don’t need to estimate label width or shorten labels to fit a fixed loop. Every self-message on one lifeline gets the same width, the widest label’s, so the loops line up.
Combined fragments
A fragment frame (containerType: "fragment") holds messages and notes, and other fragments, in its children. The engine lays it out with its rows, as Mermaid and PlantUML do:
- Its rows. It runs from its first message or note to its last, in document order, with a header row above for its operator and guard and 12 px below its last row. Rows added before, inside or after it move it with them. Its own
layoutis ignored. - Its width. It is as wide as its rows: their arrows, the activation bars they meet, their labels and notes, and its nested fragments, plus 16 px each side, so a nested fragment sits 16 px inside its parent. It is at least as wide as its header and each guard in its column, widened about its center. A guard moved past a bar grows its right edge only (below).
- Its left edge. It reaches at least 5 px past the heads of the lifelines its messages start or end on, as PlantUML draws a group, so its operator’s tab sits beside the first lifeline, not over it. Where the tab would cover a lifeline or an activation bar, the fragment reaches further left, until the tab ends 4 px before them. Fragments of one depth whose tabs sit beside the same lifeline reach as far as the widest tab among them needs, so they share a left edge; fragments at another depth are not counted.
- Its operands.
extensions.operandslists the operands after the first, each{ "startsAt": "<id>", "guard": "..." }: the message or note it starts at, in the fragment and after its first row. Each gets a dashed divider above that row, with[guard]in a row of its own under it, for every operator (alt,parand the rest). The first operand’s guard is the frame’stitle. The renderer adds the brackets round an operand’sguard, so write it without them ("guard": "card declined"), and draws thetitleas written, so write its brackets ("title": "[card approved]"). - Its chrome. The operator’s tab sits beside the first lifeline and its bar (above). The guard after it, the dividers and the operand guards are drawn over the lifelines and arrows, each guard on a knockout of what is under it, so no lifeline runs through its text. The box itself is drawn under them.
- Where a guard starts. Every guard starts after the tab, at least 38 px inside the fragment’s edge. A guard whose text would meet an activation bar open in its row starts 6 px past that bar’s right face, and past any further bar it would then meet, so its knockout never cuts a bar. The guards share one column when that furthest start is clear in every guard row; otherwise each keeps its own. The fragment’s left edge and tab stay put, and its right edge grows to a moved guard’s end plus 16 px, so a long guard can carry the fragment across lifelines its messages don’t touch, as PlantUML and Mermaid widen a group for its text.
- Edits. A message added
beforean operand’s first row becomes its first. Deleting or moving an operand’s first row starts the operand at its next row; an operand left with no rows is removed, with the info codeFRAGMENT_OPERAND_REMOVED.
Boundaries:
- Fragments nest or follow each other; they can’t cross. Each row is in one fragment’s
children(an element in two frames is refused,MULTIPLE_FRAME_MEMBERSHIP), and a nested fragment is in its parent’s. - Operators are drawn as written. The tab shows
extensions.operatoras it is (alt,opt,loop,par,break,critical,refand so on); the engine gives none of them a meaning of its own. - A fragment holds its rows, and only its rows. One that holds no message or note (a
reflisting the lifelines it covers, say) has nowhere to be and isn’t drawn (FAMILY_SEQ_EMPTY_FRAGMENT); arefneeds at least one row in it. One whosechildrenskip a row between its first and its last draws that row inside it (FAMILY_SEQ_FRAGMENT_SPLIT). - Outside a sequence diagram a fragment is an ordinary frame with a tab: it keeps its
layout. There are no rows to start an operand at, so its operands draw no dividers, except one stored with aybefore 8.0.0.
Participant boxes and highlight bands
In a sequence diagram, a frame that isn’t a fragment is drawn by what its children hold. One that holds participants is a participant box round them (Mermaid’s and PlantUML’s box). One that holds messages, notes, fragments or other bands is a highlight band behind those rows (Mermaid’s rect). Neither needs a containerType, and the engine ignores the frame’s own layout.
[
{ "id": "box_core", "kind": "frame", "title": "Order platform",
"children": ["orders", "worker"], "style": { "fill": "#E0F2FE" } },
{ "id": "band_payment", "kind": "frame", "title": "Payment",
"children": ["m_charge", "m_charged"], "style": { "fill": "#FEF3C7" } }
]
A participant box:
- Its extent. It runs from its first lifeline to its last, 12 px outside their heads, and from above the heads to 12 px below the foot bars, or below the lifelines’ ends when
showLifelineFeetis false. At its two ends it also holds a self-message’s loop and a note beside the end lifeline. Every box shares one top and one bottom. - Its title. The
titleis centered at the top, above the heads. A titled box moves every head in the diagram down 28 px; untitled boxes move them 12 px. A box is widened to hold a title wider than its lifelines, and round one lifeline it grows evenly on both sides. - Its look. It has a solid 1 px border and no fill unless its style, a named style or the palette gives one. It is drawn under everything else, so arrows that leave it cross its border.
- Its room. A box makes the diagram wider by 12 px at each of its ends.
A highlight band:
- Its extent. It opens 8 px below the row above it and closes 8 px below its last row. It is as wide as a fragment round the same rows (Combined fragments). A band with a
titlegets one more row at its top, with the title at the top-left, and widens about its center to hold it. - Its look. It is a filled rectangle with no border unless its style sets
stroke. Without a fill of its own or from the palette, it takes a 6% tint of near-black on a light canvas, or of white on a dark one. It is drawn over the boxes and under fragments, lifelines and messages, and moves no lifeline. - Nesting. A band can hold fragments and other bands, and a fragment can hold bands.
Boundaries:
- One frame, one role. A frame that holds both lifelines and rows isn’t drawn (
FAMILY_SEQ_FRAME_MIXED); use two frames. One that holds neither isn’t drawn (FAMILY_SEQ_EMPTY_FRAGMENT). - Boxes don’t nest or overlap. Where two boxes share a lifeline, the outer one is drawn, or the first in
elementsorder when neither holds the other. The other isn’t drawn (FAMILY_SEQ_BOX_NESTED). - A box holds every lifeline between its ends. A lifeline that stands between two members without being in
childrenis drawn inside the box (FAMILY_SEQ_BOX_SPLIT). Add it withupdateNodeandframe, or move it out withupdateNodeandafterorbefore. - A band holds every row between its ends. A row its
childrenskip is drawn inside it (FAMILY_SEQ_FRAGMENT_SPLIT). - Neither has an operator, a tab or operands. Those are a fragment’s (Combined fragments).
- A long label can still cross a box’s border. A message’s label moves along its arrow to keep off a border, and one too wide for any clear place there is drawn across it.
- Outside a sequence diagram both are ordinary frames.
Edits treat a band as they treat a fragment, and a box doesn’t take a lifeline by its place (Operations: Order in a sequence diagram).
Lane and pool rendering
Pools and lanes are drawn as the BPMN 2.0.2 specification draws them, as bpmn-js does:
| containerType | Rendering |
|---|---|
pool | Solid border; 30 px header strip with a dividing line |
lane | Solid border; 30 px header strip, no dividing line |
generic (default) | Dashed border (4,4, or the frame’s style.dash: [] draws it solid), title at the top left |
- Header strips. In a horizontal pool (lanes stacked top to bottom,
laneDirection: "vertical"), the strips run down the left side, in anRLflow too, and titles read bottom to top. In a vertical pool (lanes side by side,laneDirection: "horizontal"), they run along the top and titles read left to right. A lane’s strip comes after its pool’s, and each level of nested lanes adds a strip. A line divides a pool’s strip from its lanes, as the BPMN specification requires; a lane’s strip has none, except a lane that holds lanes. Nothing is drawn across the top of a horizontal pool, and a lane’s title sits only in its strip. - Titles are centered in their strips. A pool’s title is 14 px, in the theme’s text color. A lane’s takes the lane’s text color where that reads on the lane’s fill (WCAG AA), as a frame title does, and otherwise a shade that reads there.
- Lane borders are continuous. The BPMN specification lets sequence flows cross lanes, so a flow crossing a lane’s border doesn’t break it.
- Nodes outside lanes. The nodes a pool, or a lane that holds lanes, lists beside its lanes are drawn in an untitled band after the last lane (
POOL_NODE_OUTSIDE_LANE), and a lane that no pool lists is drawn as a pool of one lane (LANE_OUTSIDE_POOL).
The engine sizes and places pools and lanes, members included: Layout Engine: Pools and lanes covers lane order and depth, direction, several pools, edits, and what they don’t do.
Step badges and spanning frames
Step badges. An edge’s step is drawn as the numbered callout of AWS’s Architecture Icons: a 25 px circle filled in the theme’s text color, its number in 13 px bold in the canvas color. It inverts on a dark canvas, whether the scene is designed dark or the dark theme adapts it, so the number reads at 4.5:1 or more. Where the theme’s text color doesn’t read on the canvas at 4.5:1, the circle is near-black or white, whichever reads better. The sketch theme draws a rough circle.
A sequence message’s number is the same badge, centered on the start of its arrow or on the axis of the activation bar the arrow leaves (Layout Engine: Numbered messages). A number of three or more digits is drawn smaller to fit inside it.
The step list. Each entry is its step’s badge, then the stepText of its edges in the node label’s size (14 px), with a dot before each edge’s line when the step has several. Layout Engine: Numbered steps says where the badges and the list go and what steps don’t do.
Spanning frames. A frame written with spans is drawn as its containerType draws a frame, with no fill whatever its style says, round the targets it spans. Its border breaks where a line crosses it and runs through no arrowhead, and its header sits where the layout placed it, 16 px off the lines. Layout Engine: Spanning frames covers its box, the room kept for it and the families that draw it. A Google Cloud zone draws a strip under each node it spans instead, and a gcp.vpc in Google’s arrangement is one band across its Regions (Google Cloud groups).
PNG
Zindex converts the SVG to PNG on its servers.
Send "format": "png" to a preview, or ask for GET /v1/images/{id}@{revision}.png. The response body is the PNG itself. It has the SVG’s width and height in pixels; there is no option for a larger scale, so use the SVG when you need a sharp image at a bigger size.
Rendering via API
Preview an unsaved scene (no key)
POST /v1/diagrams/preview draws a scene, or Mermaid text sent as mermaid, without saving it:
curl -s -o preview.svg https://api.zindex.ai/v1/diagrams/preview \
-H "Content-Type: application/json" \
-d '{
"scene": {
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"scene": { "title": "Demo", "canvas": { "width": 800, "height": 400 } },
"elements": [
{ "id": "n1", "kind": "node", "nodeType": "service", "shape": "roundedRect",
"label": "API", "layout": { "mode": "absolute", "x": 50, "y": 50, "width": 200, "height": 80 } }
]
},
"theme": "dark"
}'
The response is the image. format is svg, the default, or png, and theme is clean, dark, blueprint or sketch; dark, blueprint and sketch adapt a light design’s colors (Adaptive colors). A preview has no address line, and nothing is saved.
A saved version (API key)
Zindex draws each version’s image when the version is saved and keeps it, in the default theme and with its address, zindex.ai/d/{id}@{revision}, and date in the bottom-right corner:
curl -s -o my-diagram.svg "https://api.zindex.ai/v1/images/my-diagram@3.svg" \
-H "Authorization: Bearer $ZINDEX_API_KEY"
Use .png for a PNG. ?engine=current draws the version with today’s engine instead of returning the kept image, and ?from=1 colors what changed since revision 1; see Visual diff rendering.
For links that work without a key, such as for a person to open, GET /v1/diagrams/{id}/render returns SVG and PNG links to one version: for a private diagram, signed links valid for 7 days, as below; for a published one, its version links, which don’t expire but stop if the diagram is made private or deleted, with url for the version’s page and no expires. revision or asOf picks the version; the default is the latest:
curl -s https://api.zindex.ai/v1/diagrams/my-diagram/render \
-H "Authorization: Bearer $ZINDEX_API_KEY"
{
"id": "dgm_7Q2kD9a1B2c3",
"revision": 3,
"hash": "sha256:231332…",
"chain": "sha256:92f0fe…",
"engine": "3.1.0+build.1220",
"svg": "https://api.zindex.ai/v1/images/dgm_7Q2kD9a1B2c3@3.svg?e=1791849625&s=AkwA637RDSUzJG4jEerAsgfErY706lGd",
"png": "https://api.zindex.ai/v1/images/dgm_7Q2kD9a1B2c3@3.png?e=1791849625&s=6CxFaaWmxNlDFPy9ArhRqxcaYhOmAXgt",
"expires": "2026-10-13T00:00:25.000Z"
}
engine is the build that drew the kept image.
MCP render
diagram_render returns the same links for a version, not the image. In apps that show MCP Apps views, such as ChatGPT and Claude on the web, the person also sees the picture in the chat (MCP Tools). With preview: true the result includes the PNG, so the agent can look at it:
{ "id": "my-diagram", "preview": true }
With scene or mermaid instead of id, it draws an unsaved document as a PNG and saves nothing. It returns no warnings. diagram_validate, diagram_create and diagram_edit return them, including what drawing notices; see Render diagnostics and MCP Tools.
Render diagnostics
Laying out and drawing a scene can notice problems that don’t stop the image from being drawn, such as text that doesn’t fit its node. Each has a code, and each code is either warning level or info level.
Warning-level codes come back in warnings when you validate, save or edit a diagram: POST /v1/diagrams/validate, POST /v1/diagrams and POST /v1/diagrams/{id}/revisions, and the MCP tools diagram_validate, diagram_create and diagram_edit. Each warning has the code, the element it concerns when there is one, and a one-line fix with the figures you need:
{
"ok": true,
"errors": [],
"warnings": [
{ "code": "TEXT_OVERFLOW", "element": "n1", "fix": "Its text needs about 152px of height and has 30px: make it taller or wider, or wrap the text." }
]
}
The warning-level codes are TEXT_OVERFLOW, ICON_NOT_FOUND, CHARACTER_NOT_DRAWN, NODE_OVERLAP_DETECTED, NODE_OUTSIDE_FRAME, FRAME_OVERLAP_DETECTED, NODE_IN_WRONG_FRAME, LABEL_DUPLICATION_DETECTED, EDGE_COLUMN_NOT_FOUND, EDGE_CROSSES_NODE, EDGE_OFFSET_ON_GROWN_NODE, POOL_FLOW_DIRECTION, SPAN_COVERS_NODE and DRAW_TIMEOUT. Warnings never block a save. A response lists at most 10, always including CHARACTER_NOT_DRAWN and DRAW_TIMEOUT when they apply.
Info-level codes describe something the engine already handled, such as growing a canvas that was too small, and usually need no fix. The API doesn’t return them; their sections below explain what each one does to the picture. Images, previews and render links carry no diagnostics.
Validation rules covers the errors and warnings that checking the scene itself produces.
TEXT_OVERFLOW
Emitted when text runs past the element that holds it: a wrapped label too long for its node’s height at the current font size (an icon above it counts), or the title of a frame with its own layout that is narrower than the title.
Warning level. The API returns it in warnings, with the element whose text overflowed as element and a fix that gives the height the text needs and the height it has. For a node whose label wraps, both are the node’s heights, and the height the text needs includes the node’s icon and the padding above and below: the height layout.autoSize: "content" gives the node on every layout.
For a frame, the title runs past the frame’s right border, and the fix gives the width the title needs (the title and 8 px on each side) and the width the frame has. Make the frame that wide with resizeElement, or shorten the title with updateFrame. When you write the scene, you can instead leave layout off the frame, so the engine fits it to its members and widens it to its title. Pools, lanes and sequence fragments aren’t checked.
ICON_NOT_FOUND
Emitted when a node’s or a frame’s icon is a family:id key that no built-in icon or alias has:
- a Lucide name outside the built-in set (
lucide:file-lock); - an
aws:*orgcp:*key outside the built-in sets; - a family Zindex doesn’t ship (
azure:*).
The node keeps the icon’s room, drawn empty: an aws:* node draws its label alone, a gcp:* node its card, and any other node its box. A frame draws no icon in its header (an AWS group keeps none of its preset’s). A data: URI is drawn as given and a URL stays a link; a key that isn’t a family:id gets ICON_KEY_INVALID_FORMAT from validation instead.
Warning level. The API returns it in warnings, with the node or frame as element. The fix names up to three keys of the same family spelled like the one sent; when none is spelled close, up to three whose name or keywords hold its words (aws:queue names aws:sqs); the families there are when the family doesn’t exist; or says to pick a key from the icon list, AWS icon keys or Google Cloud icon keys. An image given as a data: URI works in every case.
CHARACTER_NOT_DRAWN
Emitted when text drawn in the image holds a character no font has: a letter of a script the images don’t draw, a rare Chinese character, a rare sign, or a character newer than Unicode 18.0. Each is drawn as an empty box (□). Text and scripts lists what is drawn and what is a box. The scene’s title and description aren’t drawn, nor is a hidden element, so none of them warns.
Warning level. The API returns one for the whole diagram in warnings, without an element. Its fix counts the different characters drawn as boxes, lists up to five of them, and names up to three of the elements whose text holds one.
{ "code": "CHARACTER_NOT_DRAWN", "fix": "2 characters can't be drawn and appear as boxes (ש, ם), in 'orders': write the text in Latin, Cyrillic, Greek, Armenian, Georgian or common Chinese, Japanese or Korean characters, or keep the text and accept the boxes." }
A character that shows nothing alone, such as a combining mark, is listed by its code point (U+0E31). When there are more than five characters or three elements, the fix says how many more. Fix the elements it names, and the next write’s warning names the rest.
An element’s text is everything drawn for it. Change it where it is drawn:
- A node’s or an edge’s label, or a text element’s text:
setText. - A frame’s title:
updateFrame. - An ER table’s columns:
updateNodewith the completeextensions.columns. - An edge’s
stepText:updateEdge. - A fragment’s operand guards: delete the fragment and create it again in one edit.
Or keep the text and accept the boxes; the diagram is saved as written.
CANVAS_AUTO_EXTENDED
Emitted by the layout engine when the final canvas is larger than the declared scene.canvas, or none was declared. Declared canvas dimensions are a minimum, not a hard cap; the engine auto-extends scene.canvas.{width,height} to fit everything it draws: nodes, frames, edges and edge labels. The margin past content that outgrew the canvas matches the drawing’s margin on the opposite side, between 40 px (60 px at the bottom) and 20% of the content’s size. Content past the left or top edge, such as a label above the top row, moves the whole drawing right or down to leave that margin, and the canvas grows by the same amount; node positions in the diagram stay as they are. A frame written without a layout counts as past an edge it comes within 20 px of, so a frame fitted round nodes placed near the edge never touches it. The SVG always renders against the auto-extended canvas - content is never silently clipped.
Info level. The API doesn’t return it.
If you want the declared size to remain authoritative for downstream consumers (e.g. clients that read scene.canvas to size their own viewport), persist the auto-extended dimensions back to your scene via updateScene so the next read returns them as the declared values. Growth past the left or top edge comes back on every layout, so persist only what the canvas grew on the right and at the bottom.
CANVAS_AUTO_TIGHTENED
Emitted when the engine reduced the declared scene.canvas below the value the agent declared on either axis. This is the only path where the engine does that. It trips when all three hold:
- The engine placed every node in this layout.
- No text, image or frame has an absolute
layout(Layout engine: Text, images and a frame you place yourself). - The declared dimension on the named axis exceeds the comfortable centered-content size by more than 30%.
The engine places every node on a new diagram whose nodes have no positions, on autoLayout without elements, and after updateScene changes or removes layoutStrategy or diagramFamily. In those cases the members of a frame that keeps its own layout (a pool, lane or fragment, or any frame in an org chart or network) keep their positions. The engine caps that axis at content x 1.4 to avoid rendering with excessive slack. This is common when an agent declares a generous canvas height for an auto-layout pass and the content turns out shorter than expected.
The engine tightens each axis on its own, so a scene that over-declares both width and height can be tightened on both. A tightened canvas still grows for anything drawn past it, such as a long edge label; the diagnostic gives the final size, and isn’t emitted once that size is back at or above the declared one.
Info level. The API doesn’t return it.
Zindex saves the tightened size with the diagram, so reads return it. Once the nodes have positions, the engine never tightens the canvas again. For a larger canvas on that axis, set it with updateScene. The engine keeps it as a minimum and the nodes keep their positions, so the extra room ends up on the right or at the bottom.
CANVAS_CONTENT_OFFSET
Emitted by the layout engine when the bounding-box center of the laid-out content deviates from the canvas center by more than 10% of the canvas dimension on either axis. It fires only where the engine’s centering pass did not run:
- at least one node already has a position, given by an agent or kept from an earlier save;
- a text, an image or a frame has its own absolute
layout(Layout engine: Text, images and a frame you place yourself); - a pool’s own
layoutkeeps the drawing at that pool’s corner (Layout Engine: Pools and lanes).
Any other layout in which the engine places every node never trips this diagnostic: it passes through the centering pass that balances content within the declared canvas before this check.
Typical trigger: an agent hand-codes absolute coordinates for every element and the resulting layout leaves a large empty margin on one side of the canvas. For example, content bounded x=50..940 in a 1400 px wide canvas leaves 460 px of empty space on the right vs 50 px on the left.
Info level. The API doesn’t return it.
Recovery options in preference order:
- Send
autoLayoutwithoutelements. The engine places every node again, centered and spread to fill the canvas. Skip this when a text or an image has an absolutelayout: it stays where it is written, and nothing is centered around it. A frame with its ownlayoutis no obstacle whereautoLayoutdrops thatlayout(Layout engine: Laying out again). Two more limits:- It doesn’t spread when frames are laid out with their members.
- A frame that keeps its own
layout(a pool, lane or fragment, or any frame in an org chart or network) keeps its members’ positions. The engine places only the other nodes, around them, and recenters nothing.
- Shrink
scene.canvasviaupdateSceneto match the actual content bounds. - Recenter the absolute coordinates by adding
(canvasDim - contentDim) / 2 - contentMinto each axis on every element.
EDGE_LABEL_SUPPRESSED_REDUNDANT
Emitted when the engine draws edges whose FK-named labels it promoted to column-row anchors. An edge whose label exactly matches the name of a column declared in either endpoint’s extensions.columns is automatically promoted: the edge anchors at the named column row inside the entity on the matching side(s) (the dbdiagram.io / DBeaver convention), and the label isn’t drawn, because the column position now carries the FK identity. The edge keeps its label as written, and the engine promotes it again each time it draws the diagram.
Info level. The API doesn’t return it.
To keep the label drawn on a specific edge, set style.forceLabel: true on the edge, with the label or in a later edit. The edge still anchors at the named column, and this diagnostic doesn’t list it. Authors writing new scenes can also set endpoint.column directly and skip the label-matching step entirely.
EDGE_COLUMN_NOT_FOUND
Emitted when an edge’s endpoint.column references a column that does not exist in the endpoint entity’s extensions.columns. The renderer docks that end as it docks any edge (at the side’s center, or straight across where the nodes line up; Where an edge enters its target), so the diagram still renders, but the agent’s intent (anchor at the named column) was not honored.
Warning level. The API returns it in warnings, with the edge as element and a fix that lists the entity’s columns first, then the advice: Edge '{edge}' {side} column '{column}' isn't on '{element}': use one of {columns}, or remove column. An entity with no extensions.columns gets ..., which has no extensions.columns: add the column there, or remove column.
The fix lists the columns the entity declares, so you can pick a real one. Common causes: typo in the column name, the entity uses the alternate columns shape ({key: "FK", name}) and the agent referenced the wrong field, or the column was renamed but a stale edge still points at the old name.
EDGE_CROSSES_NODE
Emitted for a straight or curved edge whose line or curve runs through a node it doesn’t join, inside that node’s outline. Such an edge keeps the shape you set and isn’t routed round nodes (Edge routing), so the engine reports it instead of moving it: one warning per edge, naming the node in its fix. A line that only passes through a node’s bounding box, beside a round or slanted outline, isn’t reported.
Warning level. The fix: set router: "orthogonal" with updateEdge, or leave router off, and the engine routes the edge round nodes; or move the node off its line with updateNode.
EDGE_OFFSET_ON_GROWN_NODE
Emitted for a node drawn bigger than its layout gave it, to fit its label or icon, when an edge end pins an anchor offset on a side that grew: top or bottom when the width grew, left or right when the height did. An offset is a fraction of the side as drawn, so a line placed from the size you wrote lands off its mark. One warning per node; its fix names the drawn size and the edges.
A save stores the drawn size in the node’s layout (Element types: Node size and wrapped text), so the next draw has nothing to report. A node whose edges dock on a smaller box than it draws, listed there, is left out. Its offsets are fractions of that smaller box: the shape, the icon, or the card without the strip a zone adds.
Warning level. The fix: restate the offset against the drawn size with updateEdge, or give the end’s anchor the side alone and let the engine place it.
EDGE_LABEL_SUPPRESSED_FANIN
Emitted when 2+ edges share an exact label string AND a target endpoint AND come from the same conceptual source unit. The visual symptom WITHOUT this rule would be a stack of identical labels at the converging node where the source nodes are themselves the same conceptual unit - same source, same parent frame (with full coverage), or a common single-step predecessor. The platform handles this by rendering the label once on the lowest-id edge per group, dropping it from the others, AND joining the members that enter one side of the target onto a single trunk into that side’s center, with a dot where they meet, so the convergence reads as one labeled flow (Where an edge enters its target). A straight or curved member stays out of the trunk: it keeps its own line and arrowhead, and the label is still drawn once.
A group is recognized as a single conceptual source unit when ANY of:
- All sources are the same node (the same upstream emits N self-loops or N edges to one target).
- All sources share a single parent frame whose
childrenlist contains exactly those sources (the frame IS the source unit). - The sources have exactly one common single-step predecessor (a gateway or fan-out node).
When the group fails the source-unity check (sources are structurally distinct), every edge keeps its own line, label and arrowhead, and nothing is reported.
This is structurally distinct from EDGE_LABEL_SUPPRESSED_REDUNDANT: there’s no underlying column or other carrier - the convergence itself is the redundancy. The rule applies in workflow, entity-relationship, network, org chart and UI flow diagrams. It skips sequence diagrams, where same-label messages between the same actors are temporally distinct events (request/reply round-trips, retries) that must remain visible. It also skips architecture diagrams, diagrams without a family and flowcharts, where every edge keeps its own line, label and arrowhead: in architecture each edge is a dependency of its own, and in a flowchart each exit carries its own answer.
Info level. The API doesn’t return it.
To keep a label visible on a specific edge, set style.forceLabel: true on that edge - it never participates in the group at all (so it neither suppresses nor is suppressed). To break the convergence, distinguish the labels via updateEdge (e.g. REFUND_FIRED [orderRefund] vs REFUND_FIRED [subscriptionRefund]).
EDGE_OBSTACLE_GRAZED
Emitted when the router finds no route that keeps its distance and draws one that doesn’t. The line then:
- comes within 16 px of, or crosses, a node other than its own ends;
- runs over 24 px within 8 px along the side of a node it ends on;
- runs within 16 px along the border of a frame that holds neither end; or
- crosses a frame’s title on the route round every node, which the router takes when no other route keeps off the nodes and the titles.
These aren’t reported:
- An edge into, out of or inside a frame, an edge to a frame, and a flow across the lanes of its pool. An edge may pass through any frame and cross the border of a frame that holds one of its ends, that it ends on, or any lane of a pool that holds one.
- A line in the middle of a gap between two nodes less than 32 px apart, since no line keeps 16 px from both.
- Crossing a frame’s title, except on the route round every node (above). The router otherwise crosses one only when every other way costs more than two bends.
- Crossing the border of a frame that holds neither end straight across, whether or not a way round exists. A line between layers, or between frames drawn as stacked tiers with a tier between them, crosses every border between its ends, and the router still takes a way round when there is one. Only a run along such a border is reported.
- Sequence messages, which cross the lifelines between their ends by design.
A straight or curved edge through a node gets EDGE_CROSSES_NODE instead. The geometry is still drawn (a graze beats no edge), but the line may clip a third-party node or run along an unrelated frame’s border.
The 16 px clearance value matches the convention used by yFiles’ OrthogonalEdgeRouter (minimumDistanceToNode recommended 16), libavoid (Inkscape, dia, Dunnart - 12-16 px), Graphviz splines=ortho (~18 px nodesep margin), and mxGraph/draw.io (~12 px). It is the smallest pixel distance at which a routed edge reads as “clearly distinct from the obstacle’s stroke at 1× zoom.”
Typical triggers:
- Dense source fan-out into a narrow escape corridor. A node with N edges leaving the same face into a corridor < N × 16 px wide can’t fit every track at full clearance. The bundler/channel-router packs them as tightly as the corridor allows; tracks that overshoot the clearance band are flagged.
- Notes or service nodes positioned in a lane that edges need to cross. The router can route around the obstacle. If no clean detour exists (e.g. canvas edges block the leftward escape), it draws the nearest route round the nodes, which can pass within 16 px of one. It crosses a node only where no route round the nodes exists.
- Tightly-packed playground / showcase fixtures where the visual density is intentional.
Info level. The API returns no note for it, so check the image.
Recovery, in preference order:
- Widen the canvas. Shrinking the obstacle’s effective neighborhood gives the router more room to find a clean detour. Often a 100-200 px increase on one axis is enough.
- Move the obstacle node or frame out of the routing corridor. For notes specifically: notes are typically annotative; placing them adjacent to the relevant elements (not in the middle of an active routing channel) avoids forcing edges to detour around them.
- Distinguish or merge the affected edges. If multiple parallel edges all converge on the same target, consider whether one labeled trunk would carry the same meaning. The fan-in label suppression rule (
EDGE_LABEL_SUPPRESSED_FANIN) handles convergence cleanly when the source nodes form one conceptual unit. - Set
style.forceLabel: trueon a specific edge if the close routing is intentional - this signals “I know this edge is tight; render it anyway” and helps any downstream review tooling distinguish “agent oversight” from “deliberate density.”
The engine still draws the edge. Act on it when an edge visibly clips a node in the image, or accept the close routing when the diagram’s density is fixed.
FRAME_OVERLAP_DETECTED
Emitted when two frames overlap by more than 2 px and neither holds the other. The region they share reads as part of both, and a node in it reads as a member of both. A frame written without a layout is fitted to its nodes. When the engine lays out every node (a new diagram, autoLayout without elements, or a changed layoutStrategy or diagramFamily) of an architecture, flowchart, workflow, UI flow or entity-relationship diagram, or one without a family, it lays such frames out with their nodes and keeps them apart. Network and org chart layouts place nodes without regard to frames, and nodes with positions keep them, so a fitted frame can grow over another frame when their nodes sit between each other’s. Two frames with their own layout overlap when their boxes do.
Scope:
- Containment exempt. A frame and the frames inside it, at any depth and through groups, are not reported, nor is a pool and its lanes. Lanes that share a border don’t overlap.
- Auto-bands exempt. The tinted bands
autoGroupdraws are not frames. - Sequence diagrams exempt. Fragments and highlight bands are laid out with their rows, and participant boxes with their lifelines (Combined fragments, Participant boxes and highlight bands). Their own
layoutis ignored. - Rounding. Overlaps of 2 px or less are not reported.
- Capped. The first 20 pairs are reported.
Recovery:
- Let the engine place one frame’s nodes. Send
{ "op": "autoLayout", "elements": [...] }naming the nodes of one of the two frames. The engine places them again clear of the other frame, without moving the rest. - Move them. Call
updateNodewith new positions for one frame’s nodes. A frame with its ownlayoutkeeps its box: move it withmoveElementor change its size withresizeElement, and move its nodes with it. - Lay the whole diagram out again. In an architecture, flowchart, workflow, UI flow or entity-relationship diagram, or one without a family,
{ "op": "autoLayout" }lays every frame out with its nodes and keeps the frames apart. It also drops thelayoutof every frame but a pool, a lane or a fragment, so frames you gave a box lose it, and places every node again, except the members of a pool, lane or fragment that keeps itslayout. Pools don’t need it: the engine keeps every two pools that share columns at least 40 px apart, whatever theirlayoutsays (Layout Engine: Pools and lanes).
Warning level. The API returns it in warnings, with one frame as element and a fix that names the other.
LABEL_DUPLICATION_DETECTED
Emitted when 2+ edges share identical label text AND converge on a shared source node. Sequence diagrams don’t get it: there, messages that repeat a label are separate moments (a retry, a second round trip). The visual symptom is a stack of identical labels emitted from one node (e.g. an api_gateway emitting three edges all labeled route to different downstream services). The engine renders all labels faithfully because the edges are real and distinct, but the result reads as duplication rather than as N distinct routes. Whether to merge the edges, distinguish the labels, or accept the duplication is a semantic call only the diagram author can make, so the engine reports it as a warning and lets the agent decide.
Shared-target convergence does NOT trigger this diagnostic: when the sources form one unit, EDGE_LABEL_SUPPRESSED_FANIN reports it, and otherwise every edge and label is drawn.
Warning level. The API returns it in warnings, with a fix that names the edges and the label they share.
Self-loops with duplicate labels are intentionally included; they almost always indicate an authoring mistake. Detection is case-sensitive - “Read” and “read” are treated as distinct.
The recommended remediation is to distinguish the labels via updateEdge (e.g. “route to users” vs “route to orders”) so the diagram is unambiguous. Alternatively, if the edges represent the same flow, merge them; if both labels are intentional and clarity is acceptable, ignore the warning.
MISSING_DIAGRAM_FAMILY
Emitted when the scene omits the top-level diagramFamily field (or sets it to an empty string). The field is technically optional in the JSON schema, but it is effectively load-bearing: it gates family-specific behavior the engine and downstream tooling rely on. Concrete examples of behavior that depends on diagramFamily:
- Same-label fan-in collapse. Edges with one label into one target from one source are drawn as one labeled flow in workflow, entity-relationship, network, org chart and UI flow diagrams, and never in sequence, architecture or flowchart diagrams, or diagrams without a family (EDGE_LABEL_SUPPRESSED_FANIN).
- Flowchart conventions. Top-to-bottom layout, yes straight on and no to the side, and the flowchart tint are gated on
diagramFamily === "flowchart"(Diagram families: Flowcharts). - Column-row anchors from labels. An edge label matching a column declared in either endpoint’s
extensions.columnsanchors the edge at that column’s row. Columns are the ER signal, so this doesn’t depend ondiagramFamily. - Workflow-family BPMN conventions. Gateway external labels and terminate / subprocess marker rendering are gated on
diagramFamily === "workflow". Arrowhead defaults follow each edge’sedgeTypein any family, AWS’s and Google Cloud’s open arrow included (Element types: Edge types). - Family-namespaced node types (e.g.
workflow.task,er.entity,sequence.lifeline) are accepted in any family, but a family’s rules and conventions apply only when the scene declares it: aworkflow.taskin an architecture diagram gets no workflow warnings.
Without diagramFamily, the engine draws the scene as an architecture diagram, applies no family’s rules, and downstream tooling cannot segment by diagram type. The fix is to declare it on every scene at creation time (diagram_create) or via the updateScene operation on an existing scene.
Info level. The API doesn’t return it.
NODE_IN_WRONG_FRAME
Emitted when a node’s center lies inside a frame that doesn’t list it in children, directly or through a frame or group inside it. The node reads as one of that frame’s members. When the engine lays out every node (a new diagram, autoLayout without elements, or a changed layoutStrategy or diagramFamily) of an architecture, flowchart, workflow, UI flow or entity-relationship diagram, or one without a family, it keeps other nodes out of frames written without a layout. Network and org chart layouts place nodes without regard to frames, and nodes with positions keep them, so a frame written without a layout can grow around a node that sits between its members. A node given coordinates inside another frame is drawn there.
Scope:
- Members at any depth exempt. A node in a frame nested in the frame, or in a group among its children, is a member.
- Innermost frame named. When frames are nested, the warning names the smallest frame around the node that it isn’t a member of.
- Auto-bands and sequence diagrams exempt.
- Capped. The first 20 nodes are reported.
Recovery:
- Let the engine place it. Send
{ "op": "autoLayout", "elements": ["<node>"] }. The engine places it again outside the frames it isn’t a member of, without moving the rest. When the node’s own frame overlaps the other one,FRAME_OVERLAP_DETECTEDcomes too, and its fix moves the whole frame’s nodes. - Move it. Call
updateNodewith alayoutoutside the frame’s box. - Lay the whole diagram out again. In the families above,
{ "op": "autoLayout" }keeps other nodes out of every frame but a fragment, pools and lanes included. It also drops thelayoutof every frame but a pool, a lane or a fragment, and places every node again, except the members of a pool, lane or fragment that keeps itslayout.
Warning level. The API returns it in warnings, with the node as element and a fix that names the frame.
NODE_OUTSIDE_FRAME
Emitted when a node sits outside the frame that lists it in children, and that frame keeps a fixed size. A frame with its own layout keeps the box the layout gives it, except that it grows where a member that grew or was pushed would cross its border (Making room). Only a frame written without a layout grows to fit all its children, and so do pools and lanes, whose layout is a minimum (Layout Engine: Pools and lanes). A member ends up outside when it was given coordinates outside the frame, when it had none on a new diagram (laying out a new diagram doesn’t keep nodes inside a fixed frame), or when autoLayout with elements placed it again and found no room inside. The renderer draws the node where it is, outside the box that claims it.
Laying out every node again (autoLayout without elements, or a new layoutStrategy or diagramFamily) never takes a member out. In an architecture, flowchart, workflow, UI flow or entity-relationship diagram, or one without a family, it drops the layout of every frame but a pool, a lane or a fragment and fits the frame round its members. A pool, lane or fragment with its own layout, and any frame with its own layout in an org chart or network, keeps its box (for a pool or lane, as a minimum), and its members stay where they are.
Scope:
- The frame’s own nodes. The nodes in its
children, and the nodes of groups among them. A frame inside the frame is checked on its own. - Fitted frames, pools and lanes exempt. A frame written without a
layout, and every pool and lane, grow to fit their children, so they are never reported. - Sequence diagrams exempt. Fragments and highlight bands are laid out with their rows, and participant boxes with their lifelines (Combined fragments, Participant boxes and highlight bands). Their own
layoutis ignored. - Rounding. Half a pixel past an edge is not reported.
Recovery:
- Move the node inside. Call
updateNodewith alayoutinside the frame’s box. Read the frame’slayoutwithview=dsp. - Make room. Enlarge the frame with
resizeElement, which keeps its top-left corner, or withanchorthe side you name. Moving a frame moves its members with it, so it doesn’t bring a node inside.
Warning level. The API returns it in warnings, with the node as element and a fix that names the frame.
NODE_OVERLAP_DETECTED
Emitted when two leaf-node bounding boxes overlap by more than 2 px after every layout pass completes. The renderer paints each rect in z-order so the lower one is obscured by the upper - this usually surfaces as labels reading through other shapes, edges terminating inside a covered node, or text content visually overlapping a neighboring rect. The diagnostic catches a class of authoring error that previously could only be discovered by visually inspecting the rendered output.
Two nodes’ positions collide where the engine can’t make room. A node’s layout size is a minimum: a node grows to fit its content (a database’s cylinder needs room for its caps above and below the label), and the engine pushes the nodes its growth runs into (Layout Engine: Making room). The overlaps left are coordinates an agent wrote (a node put on another one stays there), overlaps already in the document, and a node with a relative layout in the way. When an overlapping node is drawn bigger than its layout says, the fix names it and both sizes. The engine never places a node on top of another. The renderer paints the scene as it is, so this is a positioning issue, not a render bug.
Scope:
- Leaf nodes only. Frames and groups are excluded because containment is legitimate (a frame is supposed to enclose its children).
- Containment exempt. A node inside a frame parent is not flagged - that’s containment, not overlap.
- Sequence-family participants exempt. They span the canvas height by convention; their overlap with sequence messages, notes, and activations is part of the diagram family geometry, not authoring error. So are bars stacked on one lifeline, and a note over a lifeline whose bar is open. A note over another lifeline, or beside one, that covers a bar is still flagged.
- Sub-pixel tolerance. Overlaps of 2 px or less are treated as rounding noise from canvas-sizing’s
Math.ceilcalls and line-height multipliers; they are not flagged. - Capped. When
Nnodes mutually overlap (e.g. ten stacked at the same coordinates), there areN * (N-1) / 2pairs. The detector reports the first 20, and a response gives each node’s first overlap, at most 10 warnings in all. Fix those, then read the next write’swarnings.
Recovery in preference order:
- Let the engine place it. Send
{ "op": "autoLayout", "elements": ["<one of the two nodes>"] }. The engine places that node again next to its neighbors, clear of other nodes, without moving the rest. - Reposition one node. Call
updateNodeon either of the named nodes with newlayout.x/layout.ythat places it outside the overlap region. - Increase the offending node’s gap intent. If the overlap is small and the layout intent is “side-by-side with margin”, move one of the rects to start at the other’s right edge + a margin (e.g. 24 px).
Warning level. The API returns it in warnings, with one of the two nodes as element and a fix that names the other.
POOL_FLOW_DIRECTION
Emitted by the layout engine for a pool whose laneDirection turned the flow. Lanes always run along the flow and stack across it, as BPMN draws them, so a pool’s laneDirection sets the flow: "vertical" (lanes stacked top to bottom) a left-to-right one, "horizontal" (lanes side by side) a top-to-bottom one. When layoutStrategy.direction runs along the lanes’ stacking, such as "horizontal" with LR, the first pool in document order with a laneDirection wins, and the diagram flows across its lanes instead. A later pool whose laneDirection disagrees with that flow gets it too, and its lanes run across the flow anyway. A pool without laneDirection never gets it: its lanes stack across the scene’s direction (Layout Engine: Pools and lanes).
Warning level. The API returns it in warnings, with the pool as element and a fix that names the laneDirection that gives the flow layoutStrategy.direction asks for.
To have the flow run the way layoutStrategy.direction says, set every pool’s laneDirection to stack the lanes across it ("vertical" for LR or RL, "horizontal" for TB or BT), or leave laneDirection out. Lanes along the flow, such as phases, aren’t supported.
SPAN_COVERS_NODE
Emitted when a spanning frame’s box covers a node it doesn’t span and that isn’t inside one of its targets. The box is one rectangle round its targets, so such a node reads as spanned. It comes when the targets don’t sit together, such as two nodes with another between them, and from positions a saved diagram keeps (Layout Engine: Spanning frames).
Warning level. The API returns it in warnings, with the spanning frame as element and a fix that names up to three of the nodes it covers.
Add the covered nodes to the frame’s spans with updateFrame when they belong in it, or span only targets that sit together. autoLayout places every node again with a margin round each target, which clears a node pressed against one but not one between two. In an AWS diagram the room it keeps is for the header, in a VPC’s rows.
DRAW_TIMEOUT
Emitted when you validate a scene and laying it out and drawing it took longer than the drawing budget, or needed more memory than a drawing worker has, so the drawing’s own warnings weren’t checked. A save or edit past its budget saves nothing and answers 422 DRAW_TIMEOUT instead; Limits gives the budgets.
Warning level. The API returns it in warnings, with a fix that says which budget the drawing passed and what to change.
Fields nested in scene.scene
layoutStrategy, diagramFamily and palette belong at the document root, alongside schemaVersion, scene and elements. Sent inside scene.scene instead, they are moved to the root before the scene is checked, for create, validate and preview alike, and stored there; a field set in both places keeps the root’s value. No warning is returned.
AUTOGROUP_FAMILY_MISMATCH
Emitted when the document’s extensions.autoGroup is set and its diagramFamily is set to a family other than "architecture". The extension (subtle background bands grouping nodes by nodeType) applies to architecture diagrams and diagrams without a family; other families, flowchart among them, get no bands and the extension is ignored.
Recovery: either remove extensions.autoGroup from the scene, or change diagramFamily to "architecture" if the scene genuinely is architecture.
Info level. The API doesn’t return it.
AUTOGROUP_SUPPRESSED_TRIVIAL
Emitted when the document’s extensions.autoGroup: "byNodeType" is set but the scene has fewer than 2 nodeType groups with 2+ members each. A single band is pointless visual chrome - the engine suppresses it entirely.
Recovery: either remove extensions.autoGroup, or add more diverse node types so at least 2 buckets reach the 2-member threshold (e.g. add a database cylinder alongside the existing service nodes).
Info level. The API doesn’t return it.
AUTOGROUP_SKIPPED_SCATTERED
Emitted when the document’s extensions.autoGroup: "byNodeType" is set but the nodes of a type are scattered: two of them share a column (a row in top-to-bottom layouts) with a node of another type between them, so a band around them would wrap that node too, or a band around them would overlap a frame the scene draws or another band. The engine decides on the final positions, whether it placed the nodes or the scene gives their coordinates. When it places every node, it lays each band out as a region, apart from the others, as it does a frame without a layout, so overlapping bands come only from positions the nodes keep, such as a saved diagram’s or a node an edit added; the message names the band they would overlap.
Recovery: place nodes of the same type next to each other; have the planner place them, which keeps each type together, by leaving layout off the nodes of a new diagram or sending autoLayout without elements on a saved one; or remove extensions.autoGroup.
Info level. The API doesn’t return it.
Using diagnostics for automated correction
Warnings let an agent find and fix layout problems without looking at the image. After each validate, save or edit, read warnings, make the change each fix describes to the element it names, and check the next write’s warnings:
TEXT_OVERFLOW: make the element as tall as the fix says or wider, or wrap its text. For a frame’s title, make the frame as wide as the fix says withresizeElement, or shorten the title withupdateFrame.ICON_NOT_FOUND: set the node’siconwithupdateNodeto a key the fix names or one from the icon list, or to an image as adata:URI, or remove it withicon: null.CHARACTER_NOT_DRAWN: it has noelement; its fix names the elements. Rewrite their text in Latin, Cyrillic, Greek, Armenian, Georgian or common Chinese, Japanese or Korean characters, or keep the text and accept the boxes.NODE_OVERLAP_DETECTED: sendautoLayoutwithelementsnaming one of the two nodes so the engine places it again in free space, or move one of them withupdateNode.NODE_OUTSIDE_FRAME: move the node inside its frame withupdateNode, or enlarge the frame withresizeElement.POOL_FLOW_DIRECTION: set the pool’slaneDirectionto the value the fix names, which stacks its lanes across the flow you asked for, or leavelaneDirectionout.FRAME_OVERLAP_DETECTED: sendautoLayoutwithelementsnaming the nodes of one of the two frames so the engine places them again clear of the other, or move them withupdateNode(and a frame with its ownlayoutwithmoveElement).NODE_IN_WRONG_FRAME: sendautoLayoutwithelementsnaming the node so the engine places it again outside the frame, or move it withupdateNode.LABEL_DUPLICATION_DETECTED: give one of the named edges a more specific label withupdateEdge, such as “route to users” instead of “route”, or merge the edges.EDGE_COLUMN_NOT_FOUND: set the edge’scolumnto one the fix lists, or remove it withupdateEdge; without it the edge docks on the entity’s side as any edge does (its center, or straight across).EDGE_CROSSES_NODE: set the edge’srouterto"orthogonal"withupdateEdge, or remove it, so the engine routes it round nodes; or move the node the fix names off its line.EDGE_OFFSET_ON_GROWN_NODE: restate the offset against the size the fix names withupdateEdge, or give the end’sanchorthe side alone.SPAN_COVERS_NODE: add the covered nodes to the spanning frame’sspanswithupdateFramewhen they belong in it, or span only targets that sit together.
Info-level codes usually need no fix, and the API doesn’t return them. When an image looks wrong, their sections above say what the engine did and what to change: style.forceLabel: true keeps a label the engine dropped, autoLayout has the engine place nodes again, and updateScene moves misplaced root fields or sets diagramFamily.
Edge label typography
An edge’s label is drawn in the edge’s stroke color, so whatever sets the stroke (the edge’s style, a named style, the palette’s edgeStroke or the theme) colors its label too. To color the label on its own, set textColor in the edge’s style, inline or through a named style. The palette’s foreground and mutedForeground don’t change edge labels.
Label width
An edge label wider than 200 px wraps (Element types: Label wrapping). A line of text is at most 192 px, since the 4 px of padding on each side count toward the 200. The lines are centered on the label’s place, and its backdrop covers all of them. The 250 px of a node’s label doesn’t apply to an edge. A label with no clean place can also wrap narrower, and its lines are drawn at that width (Element types: Label wrapping).
State-machine convention: EVENT [guard] / action
When an edge label matches the UML / SCXML / BPMN convention EVENT [guard] / action, the renderer splits it, on one line, into three styled <tspan> runs inside one <text>:
- The event name, in the standard 12px edge fill.
- The bracketed guard, in 10px.
- The action segment, in 10px italic.
The guard and the action are drawn in the theme’s muted color. Under dark and sketch they take a gray quieter than the event’s instead. In every theme they reach 4.5:1 on what is under the label (Contrast). The convention is shared by PlantUML, Stateflow, XState, Camunda Modeler, and the wider state-machine tooling ecosystem.
In a flowchart, workflow, UI flow or sequence diagram, an edge label with a balanced [...] or a / (a slash with a space each side) is split this way. In every other diagram, one with no diagramFamily included, an edge label is plain text: there a slash usually means “or” (reads / writes), and brackets hold a note. In those four families, a label with neither is plain text too. A label with a line break (\n) skips the convention and is drawn line by line.
A convention label too wide for one line (over 200 px) breaks between its parts:
- The event takes a line.
- The guard and the action share the next line when they fit together, and each takes its own line when they don’t. A line of two runs is centered as one block.
- A part still too wide wraps by itself, in its own type. An event or guard that is one long identifier stays whole, unless
wrapis"character", which breaks it between its characters.
textStyle.wrap: "none" keeps all three on one line.
The width measurer sums per-segment widths at the matching font sizes plus a 6px inter-segment gap, so layout reservation matches what gets drawn - no surprise overflow into adjacent edges.
To opt out for a specific edge (e.g. when an author wants uniform typography on a label that happens to match the convention), insert a newline so the parser falls through to the multi-line path.
Edge routing
Four routing algorithms determine how edges connect elements:
| Router | Description |
|---|---|
straight | One line between the two nodes’ centers, ending where it crosses each node’s outline |
orthogonal | Right-angle path with horizontal and vertical segments |
curved | One bowed arc between the two nodes, ending on each node’s outline |
polyline | Drawn as orthogonal |
straight and curved edges keep the shape you set, and the engine doesn’t route them round nodes.
straightis the line between its nodes’ centers, ending where it crosses each node’s outline (an ellipse, a diamond, a cylinder’s lid, a cloud’s lobe), as Graphviz, draw.io, Mermaid and yFiles end it. Where the nodes line up, so a center’s coordinate lies in both facing sides’ ranges, it runs exactly horizontal or vertical. An end that would meet a box’s side at less than 26.6 degrees, the arrowhead’s half-angle, moves round the corner onto the next side, 8 px in, so the arrowhead stays whole. Two or more straight edges between one pair of nodes run as parallel lines 12 px apart, so a pair running both ways is two lines.curvedis one quadratic Bezier between its nodes, ending on each outline, as Graphviz’ssplines=curvedand tldraw draw it. The engine picks the side it bows to and how far: away from other nodes, inside the frames that hold both its ends, off other routes and steep at each end where it can, and otherwise away from the diagram’s center. Curved edges between one pair of nodes bow to either side instead, so a pair running both ways forms a lens; they keep that spread even across a node, and the middle one of an odd number runs straight. A curved self-loop is rounded. The computed path’scontrolis the curve’s control point (M points[0] Q control points[1]).- Scope. A line or curve that can’t clear a node crosses it, with the warning EDGE_CROSSES_NODE. For an edge that should go round nodes, use
orthogonalor leaverouteroff. Sequence messages ignorerouter: the engine draws them from lifeline to lifeline.
An edge with orthogonal, polyline or no router gets right-angle segments that the engine routes itself. Its waypoints are kept but not drawn through. The engine may replace a long detour with a U-hook below the diagram (see Long-haul back-edge U-hook below), and never turns such an edge into a curve.
Three kinds of edge that cross another route are routed once more, at most eight per layout, in a diagram of up to 250 edges. No other edge is routed again to remove a crossing. A self-loop, a straight edge and a curved edge never are.
- An ER relationship that ends on a table’s row goes round a table when that crosses less without more bends (ER diagram rendering).
- An edge that runs with the flow across two or more ranks may leave or enter by another free side and take up to two more bends, one for each route it no longer crosses. This applies in flowchart, workflow, UI-flow and architecture diagrams and diagrams without a family. It doesn’t apply in an AWS diagram the cloud layout arranges, which has no ranks.
- An orthogonal edge in a Google Cloud diagram the cloud layout arranges that crosses another is routed again the same way. As in any route, it prefers a face that points toward the other end.
The new route is kept only when the finished diagram has fewer crossings and is no worse by any other measure, such as a label on another edge’s line.
Where an edge enters its target
An orthogonal edge enters the side of its target that faces the source, never the far side while a route to a facing side is clear: an edge from above a node enters its top. It leaves its source straight out from the side it leaves by, never running along that side first. Where on that side:
- The center, by default.
- Straight across, at the source’s coordinate, when the source’s center lies inside that side’s range, so the route is one straight line; outside that range the edge enters the center. This keeps an edge into a large frame from running along the frame’s border before it enters (
efs_shared → file_systemsin a cloud diagram). The range leaves out:- 8 px at each of the side’s corners, more past a rounded corner (below). On a cloud-icon node drawn as its icon alone, these are the corners of the icon’s art, the bottom of its sides included.
- A
uiflow.screenoruiflow.modalcard’s title bar. - 4 px either side of a cylinder’s or bucket’s lid seams.
- Past a rounded corner. On a
roundedRect, apillor a Google Cloud card, an end that draws an arrowhead or glyph keeps 6 px past the corner’s curve. The arrowhead’s wing then stays beside the straight side. An anchored end keeps it too.- A
roundedRectkeeps the end at least 14 px from each corner, or itscornerRadiusplus 6 px when the radius is over 8. - A
pillkeeps it half the pill’s height plus 6 px from the corners along its top and bottom. Its rounded ends take an end only at their middle. - A Google Cloud card keeps it 12 px from each corner, or its
cornerRadiusplus 6 px when its style sets one. A stacked card keeps it 4 px further than a single card does (16 px at the default radius). - A straight line that would land on the curve enters the side’s center with a bend instead.
- On a side too short for its ends 12 px apart past the curves, they keep 12 px and their order first, as close as 8 px to the corners.
- A cloud-icon node drawn as its icon alone keeps the corner distance in Straight across, above.
- A
- Beside a node in the way. When a node between the two lies on that straight line or within 16 px of it, the edge runs straight at the nearest place 16 px clear of it, inside both sides’ ranges and 12 px off the other edges into or out of either node, instead of detouring round to another side. An end whose
anchorhas anoffset, an ER row’s end and a pair running both ways keep their routes (an end that names only a side takes the line on the side it names); a BPMN sequence flow or UI-flow transition takes the line only less than 16 px off its target side’s center. - BPMN sequence flows and UI-flow transitions (
workflow.sequenceFlow,uiflow.navigate,uiflow.back,uiflow.action) into a node enter the center of the side unless the source is less than 16 px off it; otherwise the route takes one step between the two nodes, as the Camunda Modeler (bpmn.io) draws sequence flows. A node in the way can still give a route a smaller step to keep clear of it. An edge with an edge back between the same two nodes keeps the straight entry, so the pair runs as two straight lines, unless the two nodes line up within 12 px, where one of the pair can take a U. Message flows, edges into frames and groups, untyped (default) edges and every other family keep the straight entry above. - Through the overlap. When the source’s center lies outside the target side’s range but the two boxes’ facing sides overlap, the edge runs straight through the middle of the overlap, both ends off their centers, as Graphviz’s orthogonal router draws them, when that line is clear of other nodes, frame borders and titles. A BPMN sequence flow or UI-flow transition takes the overlap’s point nearest the target side’s center, and only when its source is less than 16 px off that center. One of a pair running both ways between two nodes (a pair of message flows, say) takes the overlap’s third on its side, so the two stay at least 12 px apart; an overlap too narrow for that keeps the pair’s ordinary routes. Without an overlap, the edge takes a bend.
- Past a title in the overlap. Where the middle of the overlap would cross the title of a frame the line enters, the edge runs straight at the nearest place along the overlap that clears the title, as it does for an edge with no anchor: 5 px clear of it, or 16 px clear in a Google Cloud diagram. Where no place in the overlap clears it, the router crosses the title only when every other way costs more than two bends. An end that names only a side offers just that side to the straight line.
- Shared sides. When several ends meet one side, the engine spreads them at least 12 px apart (13.6 px for arrowheads in a Google Cloud diagram) where the side has room. They keep the order of the directions they arrive from, so converging edges don’t cross where they turn into it, and an end can sit off the center. Two parallel edges that run straight between the same two nodes are two lines, even beside a fan-out’s shared trunk. Where the side has too little room for that spacing:
- In a family that draws fork dots, ends going the same way share a point and join (below) when they match at that end. That takes the same
edgeTypeandstyle, and the same glyph at that end. An end that doesn’t match, such as an arrow beside a line with no arrowheads, keeps a point of its own, even closer than 12 px apart. - In flowchart, workflow, UI-flow, org chart and sequence diagrams each end keeps a point and an arrowhead of its own, even closer than 12 px apart, as bpmn-js draws each sequence flow. Entries into one side of a plain decision (any decision diamond but the
workflow.*types ander.relationship, in any family), and the members of a group whose shared label is drawn once, still join with a dot (below).
- In a family that draws fork dots, ends going the same way share a point and join (below) when they match at that end. That takes the same
- Ends left too close. The spread leaves some ends in place: a fan-out’s shared trunk, and an end whose face its layout fixes. A cloud layout and an org chart fix faces. When two ends that can’t share a point are left closer than 12 px, one of them slides along the side:
- It slides to 12 px apart, or to the side’s even spacing where the side is too short for 12 px.
- Ends closer than 4 px may slide to as little as 4 px where 12 px would add a crossing.
- Ends already 4 px or more apart move only where that adds no crossing.
- Ends that never slide.
- An ER row’s end, an
anchorwith anoffset, astraightorcurvededge and a self-loop. - A line that runs straight between two nodes, and a fan-out’s shared trunk where one of its lines does.
- Both ends of a pair where neither can move, or no place keeps the line 8 px clear of other nodes and borders (below).
- The ends on a cloud-icon node drawn as its icon alone, which keep their own spacing (Layout engine: AWS architecture diagrams).
- An ER row’s end, an
- Clear of other nodes and borders. The engine moves an end along its side by spreading, by sliding apart (above) and by nesting (below). Each keeps the end’s line 8 px or more from other nodes, and from a frame’s border the line runs beside for 16 px or more. A line already nearer than that gets no nearer. A line can still cross a border.
- A spread end whose place is refused this way goes as far toward it as keeps the line 16 px clear, or stays where no such place exists. The other ends spread around it.
- An end on a cloud-icon node drawn as its icon alone is exempt from these moves: it keeps its own spacing (Layout engine: AWS architecture diagrams). The end-leg nudge in a cloud layout still keeps its line 8 px clear.
- Lines from one direction nest. Two lines that run along a side from the same direction nest, whether they turn into it or leave it: the outer line takes the outer end, so neither crosses the other. Where their routes cross, one run moves a track over. The move is kept only when it leaves fewer crossings and runs through no node and onto no other line; otherwise the two can cross. Nesting moves no end whose place is fixed: an
anchorwith anoffset, an ER row’s end or a fan-out’s shared trunk.- Two lines that leave one side and enter faces that point the same way, each running out and back like a bracket, nest the other way round: the line to the farther node takes the outer end and the deeper run. Two lines between the same two nodes, one each way, nest as in the rule above.
- Joined entries. Entries that must share one point join one trunk into it, with one arrowhead and a dot at every point where their lines meet, as ELK marks the branch points of edges that share a port: two or more entries into one side of a plain decision (below), entries a side has no room to keep apart (only where forks are dotted, above), the members of a group whose shared label is drawn once (EDGE_LABEL_SUPPRESSED_FANIN), at that side’s center, and the relationships into one ER table row from one side, which share one riser into the row and one cardinality glyph at it. Each keeps its own line until the junction, which sits on the trunk at least 24 px out from the side, or where the nearest of them runs along it; a row’s riser keeps 8 px from other lines beside it. An edge that leaves by that side (for an ER row, by that row), an entry with an
anchor(with or without an offset), an entry drawn differently from the others (dashed among solid lines, which takes a vertex of its own on a decision, below; another glyph at an ER row), astraightorcurvededge, and a join that would add a crossing or run through a node stay apart. - Forks. In an architecture, entity-relationship or network diagram, or one without a family, a dot marks every point where edges drawn alike (the same color, width, dash and opacity; their labels and end glyphs don’t matter) with an end at one point fork, whichever their ends there (one leaving a table’s row where others end at it forks from them too, and so does a line that ends where a self-loop does): where one of them leaves the line the others share and three or more ways of line meet, a T or a four-way fork. A node’s fan-out runs its bus 24 px from the faces it feeds, or midway between the node and them where the gap is narrower than 48 px, so each dot sits out in the channel, not on a target’s outline. Branches of one fork keep 9 px apart where the space between the nodes has room, so their dots keep 3 px clear of each other; where placed nodes leave too little room, the crowded dots are drawn smaller (down to 3 px across), still 3 px apart, as schematic tools never let two junction dots touch. Where lines only cross, there is no dot, so a fork can’t be read as a crossing (as ELK marks a hyperedge’s junction points and schematic diagrams mark a connection). Flowchart, workflow, UI-flow, org chart and sequence diagrams draw a dot only at the joins above and at a plain decision’s split (below): BPMN tools draw a gateway’s flows without one, and an org chart’s tree has a branch at every T. A line drawn differently (dashed off a solid bus) forks with no dot. In an AWS or Google Cloud diagram the cloud layout arranges, it takes a port of its own instead, with the exceptions listed in Layout engine: AWS architecture diagrams. Crossings are always plain: no hops.
- Diamonds. An end on a diamond (a gateway, a decision, an
er.relationshipor anyshape: "diamond") lies on its outline: at a vertex, or on an edge of the outline within the middle half of the box side it enters. Where the outline’s edges lie within 40 degrees of the line (a wide decision entered from beside it) the end goes to the vertex only, where the arrowhead stays whole, and the other end slides along its own side so the line stays straight; if no straight line is clear, the edge takes a step to the vertex. A diamond’s exits (a decision’s or a BPMN gateway’s, not aner.relationship’s) leave by different vertices while one is free, so no two share a line out until the vertices run out: the branch whose target lies along the flow nearest the diamond’s center line leaves by the vertex facing the flow (the bottom in a top-to-bottom diagram), and each other branch by the side vertex facing its target, as flowchart guides draw yes and no from the bottom and side points and Camunda keeps the main path straight. In a flowchart the labels decide first. The yes leaves by the vertex facing the flow, unless another exit’s target spans the diamond’s line. A no whose target sits on the line leaves by the right vertex, the bottom in a left-to-right flow (Diagram families: Flowcharts). A branch past the free vertices (the fourth, or the fifth with no flow direction) shares the vertex that faces its target with the branch already there: the vertex facing the flow when its target lies beyond the diamond along the flow, else the side vertex on its target’s side. The two leave as one line, at least 24 px long, that splits toward their targets in their order, so each enters its target’s facing side; a plain decision draws a dot at the split, and aworkflow.*diamond doesn’t, as bpmn-js draws a gateway’s flows. Only branches drawn alike share a vertex: one drawn differently, or a vertex a gateway’s label covers, ananchoror a loop back holds, leaves the branch on a side with room, spread along it. An anchored exit keeps its anchor, and the vertex a gateway’s external label covers takes no exit. Two or more entries into one side of a plain decision (any diamond but theworkflow.*types ander.relationship) join at its vertex, since one flow line enters a decision. Entries drawn differently can’t share a line, so when a decision’s entries are drawn two or more ways, each set drawn alike takes a free vertex facing its sources, the sets placed to face them best overall; with too few free vertices they enter as they would otherwise. BPMN gateways andworkflow.decisionkeep an arrowhead per sequence flow, as bpmn-js draws them. straightandcurvededges end where their line or curve crosses the target’s outline, not at a side’s center, and each stays one line or one curve from its source to its target.- Their ends keep the same corner distance as any end: 8 px, more past a rounded corner (above).
- Ends that meet one side closer than 24 px spread at least 12 px apart, moving only that end and never into a glancing angle.
- Where such an end sits within 12 px of an orthogonal edge’s end going the other way, it gives way rather than the orthogonal edge moving to another side. A curve’s end slides along the outline at least 24 px off and the curve bows again from there; a straight line moves sideways 12 px at a time. So a flow into a gateway’s vertex keeps it where a curved loop back leaves beside it. The orthogonal edge still moves when that saves it a bend, or when the line has no room.
- An end whose
anchorhas anoffsetis fixed, and the other end points at it.
- Anchors. An endpoint’s
anchorplaces that end.{ "side": "left" }fixes the side, and the rules above choose where on it;{ "side": "left", "offset": 0.25 }fixes the place too, 0 to 1 from the side’s top (left and right sides) or its left (top and bottom sides), with the same corner distance as any end (8 px, more past a rounded corner), below auiflow.screenoruiflow.modalcard’s title bar and off a cylinder’s or bucket’s lid seams; on a curved outline the end lies on it. An anchored edge joins no shared trunk, and two ends anchored at one place are kept 12 px apart where the side has room (spread evenly over it where it hasn’t). An anchor wins over the centered dock of a BPMN sequence flow or UI-flow transition and over an org chart’s fixed sides. Use anchors to separate edges that leave one side of a node. A sequence message, a self-loop and an end with acolumnignore their anchor (EDGE_ANCHOR_IGNORED).
The engine doesn’t move a node to make an edge straight, nor for an anchor: an anchor on the side facing away from the other node routes round the node. For a straight, centered edge, give the two nodes the same center on that axis (moveElement), or have the engine place them again (autoLayout with those nodes in elements).
Multi-bend obstacle-aware routing (corridor-graph A*)
Simple L-paths and 2-bend step paths can’t always navigate dense layouts. When every L-path candidate AND every step-path candidate from rankedAnchorCandidates crosses one or more obstacles, the router falls through to a corridor-graph A* search before accepting an obstacle-crossing fallback.
The algorithm - the same one used by libavoid (Inkscape, draw.io, dia, yEd) and Graphviz neato/circo - builds a visibility graph from obstacle corners (expanded outward by the 16 px routing clearance), connects every vertex pair sharing an axis with a clear segment, then A*-searches with a manhattan heuristic and a 20-px bend penalty. The result is a multi-bend orthogonal polyline through clear space.
Triggers only when needed (clean simple paths still win in the common case), so for typical scenes the additional cost is zero. Each search stops after 5,000 A* expansions. When no search finds a clear route, the router falls back as EDGE_OBSTACLE_GRAZED describes. It keeps a path that crosses a node only where no route round the nodes exists. A whole drawing is bounded by the drawing budget, not by this cap.
The router keeps a line off node sides:
- A stretch over 24 px that runs within 16 px of a node’s side moves off it: to the middle of the gap between two nodes less than 32 px apart, else 16 px off the side.
- The same holds along the sides of the nodes a line ends on, where the route has room. The line’s first and last segments, straight out of its source’s face and into its target’s, aren’t stretches along a side. A fan-out’s branches aren’t moved.
- A line that can’t keep off a side is reported as EDGE_OBSTACLE_GRAZED. For a node the line ends on, that means a stretch left within 8 px of its side. The API doesn’t return the code, so check the image.
- A stretch moves, and its end slides along the face with it, only where nothing else places that end. These stay where they are: an end that an
anchorwith anoffset, an ER row, the diagram family or a cloud layout places, a BPMN sequence flow’s or UI-flow transition’s centered end, and everystraightandcurvededge.
Long-haul back-edge U-hook
Even with corridor-graph A*, the orthogonal router can find a path so much longer than the straight-line manhattan distance that the result reads as visual noise rather than as routing - typically because the dense middle of the canvas was blocked and the only legal corridor ran along the canvas top or bottom. The classic case is a state-machine “back-edge” (e.g. REVIEW_REJECTED → GENERATING for a retry transition), which sweeps from one end of the canvas to the other.
When the chosen path is at least 1.5 times the manhattan distance between its endpoints and has at least 4 corners, the engine replaces it with a U-hook: the edge drops from the bottom of its source to a corridor 30px below every node, runs along it to below the target, and rises into the bottom of the target. Where another node sits directly below the source or above the target, the drop or the rise shifts sideways to clear it, and if no clear U-hook exists the original path stays. The U-hook keeps right angles, and it applies to edges with orthogonal, polyline or no router. It never takes an edge whose target lies wholly below its source, where it would enter the side turned away from the source, nor an edge with an end placed for it: an end with an anchor, an ER relationship’s end on its column’s row, and each exit of a diamond with two or more exits, which leaves by its own vertex. To keep an edge out of it, set router: "curved": one arc, bowing round the nodes between its ends where it can. A straight edge would run through them. Camunda Modeler, Bizagi, Signavio, PlantUML state diagrams and Mermaid draw retry and loop-back edges the same way.