New Bring your own storage. Keep your diagrams in your own private GitHub repository, on Pro and Team.Bring your own storage on GitHub, for Pro and Team. Learn more about bring your own storage

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

ThemeBackgroundStyleFontDescription
cleanWhite (#ffffff)Clean linesInterProfessional, crisp.
darkDark (#1a1a22)Clean linesInterDark mode with warm amber and green-cyan accents
blueprintNavy (#0d1b2a)Clean linesInterTechnical/engineering aesthetic with cyan strokes
sketchDark (#1a1a22)Hand-drawnInterHand-drawn aesthetic with wobbly lines on dark background

Theme resolution cascade

Styles resolve in priority order (highest wins):

  1. Element explicit style (inline object or named registry reference)
  2. Scene palette (scene-level palette field)
  3. Theme defaults (palette colors, stroke width, corner radius; never a text size)
  4. 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:

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

What doesn’t adapt:

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.

The targets:

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

FormatHTTP APIMCP
SVGyesyes
PNGyesyes

Formats

FormatMIME TypeOutputUse case
SVGimage/svg+xmlSVG markupWeb display, embedding, vector editing
PNGimage/pngBinary imageDocumentation, 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:

  1. Background rectangle from canvas configuration
  2. 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 their zIndex, so messages paint over the lifelines and bars they cross, as Mermaid draws them; notes and every other element keep their zIndex order. A spanning frame paints right after the last other frame, so edges paint over it
  3. Sequence lifelines’ foot bars
  4. Edge labels, step badges and the step list, on top of everything else
  5. The stamp, on a saved version
  6. 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:

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 typeVisual treatmentOn a light canvasOn a dark canvas
AddedGreen 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
RemovedRed 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
ChangedAmber 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
UnchangedIts 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:

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:

What isn’t, though the compare still lists it as changed:

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:

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:

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

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:

How a card grows:

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:

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:

What a stack doesn’t do:

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.

containerTypeBorderLineIconTitle
aws.cloudtext colorsolidAWS logo (its dark variant on dark)beside the icon
aws.region#00A4A6dashed 4.5,1.5Region flagbeside the icon
aws.az#00A4A6dashed 6,4.5nonetop center
aws.vpc#8C4FFFsolidVPCbeside the icon
aws.subnet.public#7AA116solidlockbeside the icon
aws.subnet.private#00A4A6solidlockbeside the icon
aws.securityGroup#DD344Csolidnonetop left
aws.autoScalingGroup#ED7100dashed 6,4.5centered on the top edgecentered under the icon
aws.account#E7157Bsolidaccountbeside the icon
aws.corporateDataCenter#7D8998solidbuildingbeside 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:

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.

containerTypeFillBorderTitle
gcp.cloud#4285F4solidthe wordmark (below); another title white, 22 px
gcp.project#F1F3F4nonetop center, or top left where the layout moves it (below)
gcp.region#E8EAEDsolidtop left
gcp.vpcnone2 px, dashed 8,817 px bold
gcp.subnetnonedashed 4,4top left
gcp.zonea strip under each nodesolidin each strip
gcp.tierwhitesolidfacing the next Region
gcp.instanceGroupwhitesolidfacing the next Region, its kind opposite
gcp.onPremises#EFEBE9solidtop 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.

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.

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):

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:

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:

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:

nodeTypeRenderingLabel position
workflow.startFilled circle (BPMN start event)External: below the circle, or above it in some vertical flows
workflow.endBold-stroke circle (BPMN end event, stroke-width >= 3)External: below the circle, or above it in some vertical flows
workflow.gatewayDiamond with x marker (exclusive gateway)External: below the diamond, or above it in some vertical flows
workflow.gatewayParallelDiamond with + marker (parallel gateway)External: below the diamond, or above it in some vertical flows
workflow.gatewayInclusiveDiamond with circle marker (inclusive gateway)External: below the diamond, or above it in some vertical flows
workflow.timerCircle with clock-hand lines (timer event)External: below the circle, or above it in some vertical flows
workflow.errorCircle with zigzag path (error event)External: below the circle, or above it in some vertical flows
workflow.taskFalls through to generic shape (roundedRect)Inside the shape
workflow.subprocessFalls through to generic shape (roundedRect)Inside the shape
workflow.decisionDiamond, sized to inscribe the labelInside 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:

Workflow edge rendering:

edgeTypeLine styleEnd arrowheadStart arrowhead
workflow.sequenceFlowSolid lineFilled triangleNone
workflow.messageFlowDashed line (6,3, fitted to end on a dash at the arrowhead)Open triangleOpen circle
default (no family override)Solid lineFilled triangleNone

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

nodeTypeRendering
er.entityStandard rect (generic shape)
er.weakEntityDouble-border rect (outer + inner rect with 4px inset)
er.attributeEllipse (generic shape)
er.relationshipDiamond (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:

CardinalityMarkerNotation
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

nodeTypeRendering
sequence.lifelineA box, the label in it
sequence.actorA stick figure, the label under it
sequence.boundaryA circle joined by a short line to a bar standing at its left, the label under it
sequence.controlA circle with a small arrowhead on its top, the label under it
sequence.entityA circle standing on a line, the label under it
sequence.databaseAn upright cylinder, the label under it
sequence.collectionsTwo rectangles, one behind the other and up to its right, the label in the front one
sequence.queueA cylinder lying on its side, the label on it
sequence.noteRect 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.

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.

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

edgeTypeRendering
sequence.messageSolid line with filled arrowhead (synchronous call)
sequence.asyncSolid line with open arrowhead (asynchronous message)
sequence.replyDashed line with open arrowhead (return value)
sequence.createDashed line with filled arrowhead, ending at the side of the head of the lifeline it creates
sequence.destroySolid 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:

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:

Boundaries:

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:

A highlight band:

Boundaries:

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:

containerTypeRendering
poolSolid border; 30 px header strip with a dividing line
laneSolid 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

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:

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:

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

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:

  1. Send autoLayout without elements. The engine places every node again, centered and spread to fill the canvas. Skip this when a text or an image has an absolute layout: it stays where it is written, and nothing is centered around it. A frame with its own layout is no obstacle where autoLayout drops that layout (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.
  2. Shrink scene.canvas via updateScene to match the actual content bounds.
  3. Recenter the absolute coordinates by adding (canvasDim - contentDim) / 2 - contentMin to 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:

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:

These aren’t reported:

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:

Info level. The API returns no note for it, so check the image.

Recovery, in preference order:

  1. 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.
  2. 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.
  3. 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.
  4. Set style.forceLabel: true on 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:

Recovery:

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:

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:

Recovery:

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:

Recovery:

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:

Recovery in preference order:

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:

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

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:

RouterDescription
straightOne line between the two nodes’ centers, ending where it crosses each node’s outline
orthogonalRight-angle path with horizontal and vertical segments
curvedOne bowed arc between the two nodes, ending on each node’s outline
polylineDrawn as orthogonal

straight and curved edges keep the shape you set, and the engine doesn’t route them round nodes.

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.

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

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.