Diagram families
Declare diagramFamily on every scene: architecture, flowchart, workflow, entityRelationship, sequence, network, orgchart or uiflow. It selects the family’s node types, rules, layout and drawing. Without it the diagram is drawn as an architecture diagram, and nothing warns you.
Family selection guidance
Default to architecture for system-component diagrams: services, databases, queues and infrastructure. Its decisions follow no yes and no convention: each branch leaves toward wherever its target lands. Switch family when the structure matches one of these patterns:
- Steps with yes/no decisions and loops ->
flowchart, such as a deploy pipeline, a retry policy or a request handler’s checks. Label each decision’s exits with their answers, and the engine runs the flow top to bottom, keeps the yes path straight and turns each no to the right (Flowcharts). It has no BPMN events, gateway markers or message flows: useworkflowfor those. - Parallel processing paths or perimeter actors ->
workflow+pool/laneframes. If the diagram has 2+ horizontal or vertical bands of activity (frontend/backend/async, or actor-system-database), pool/lane frames make the parallelism visible. Reach for this when you’d otherwise stack badges or decorators around one large central node. - BPMN processes with events, gateways and joins ->
workflow. Diamond gateways and event-based intermediate nodes communicate process logic clearly. UseedgeType: "workflow.sequenceFlow"between sequential steps (auto-applies triangle arrowheads); useworkflow.decisionfor plain decision diamonds (label renders inside) and the fourworkflow.gateway*types for marker-bearing BPMN gateways (label renders outside the diamond, below it, or above it in some vertical flows: Rendering). - Data model with relationships ->
entityRelationshipwithextensions.columnsfor PK/FK badges. Crow’s Foot cardinality glyphs are auto-inferred from each column’spk/fk/unique/nullableflags; setcardinalityon an endpoint only to override. Setendpoint.columnto anchor an FK edge at a specific column row; the PK side can omitcolumnand falls back to the entity’s sole PK row automatically. Self-FK loops (parent_id-style) render as a U-bracket between the FK row and the PK row inside the same entity. - Time-ordered messages between actors ->
sequence. Auto-positions lifelines and orders messages by definition order. Lifeline headers auto-size to fit their labels and render a foot bar mirror at the bottom by default - do not author duplicate bottom-row shapes (the document’s top-levelextensions.showLifelineFeet: falsesuppresses them). For annotations between messages, usesequence.notewithextensions.anchor(single lifeline id or array for span). - States and transitions (labels such as
submit [valid] / save) ->flowchart, orworkflow. Other families, and a diagram with no family, draw a transition’s guard and action as plain text. - Reporting hierarchy ->
orgchart. - Screen navigation ->
uiflow.
A scene with badges or decorators stacked around a slab-shaped central node almost always wants workflow + pool / lane instead. Splitting the work into bands renders cleaner than fanning many edges out of one oversized central node.
The per-family minimal scenes below show the full element shape for each family.
Capability matrix
| Diagram type | Fit | Notes |
|---|---|---|
| Architecture diagrams | Excellent | Nodes, edges, groups, frames, constraints - full protocol support |
| Flowcharts | Excellent | Top to bottom, yes straight on and no to the right, loops round the side that crosses least, document and subroutine shapes, warnings for decisions with too few or unlabeled exits |
| Service / system topology | Excellent | Multiple node types, edge routers, container grouping |
| Data flow diagrams | Excellent | Directional edges with labels, orthogonal routing |
| Workflow / process diagrams | Excellent | Full BPMN via workflow family - see BPMN row below for details |
| Agent workflows | Excellent | Step-by-step flows with typed nodes and labeled edges |
| Dependency graphs | Excellent | Nodes + directed edges, layout constraints |
| Org charts | Excellent | Structured person cards (name bold + title muted + department accent stripe + icon), automatic top-to-bottom tree layout, solid/dashed reporting lines |
| Entity-Relationship diagrams | Excellent | Compartmented entity boxes (header + attribute rows with PK/FK badges + types), crow’s-foot cardinality (5 markers), weak entity double-border, solid identifying and dashed non-identifying relationships |
| UI / navigation flows | Excellent | Screen/modal nodes with title bar rendering, entry/exit circles, navigate/back/action edges, orphan screen validation |
| Class diagrams | Acceptable | Class boxes as labeled nodes, inheritance/association as edges - no compartments or stereotypes |
| State graphs | Acceptable | States as nodes (ellipse/roundedRect), transitions as labeled edges - no formal statechart notation |
| BPMN | Excellent | Full BPMN coverage: 11 event types (start, end, timer, error, intermediate catch/throw, terminate, message start/end), 4 gateway types (exclusive, parallel, inclusive, event-based), subprocess with [+] collapse marker, BPMN-correct sequence/message flow arrows, swimlanes |
| UML sequence diagrams | Excellent | Activation bars (stacked when nested), sync/async/reply/create/destroy messages, created and destroyed lifelines, self-messages, numbered messages, notes over or beside lifelines, combined fragments (alt/opt/loop/par with pentagon labels and guard conditions), participant boxes, highlight bands, time-ordered layout, Mermaid sequenceDiagram both ways |
| UML state/activity notation | Not yet first-class | No fork/join bars, nested states, or formal UML notation |
| Swimlane enterprise workflows | Acceptable | Pools and lanes laid out as BPMN tools do: lanes across the flow in your order, each fitted to its tasks, columns shared across lanes and pools; no phases along the flow |
| Mind maps | Not yet first-class | No radial layout |
| Freeform sketching | Not supported | Zindex is a structured protocol, not a freeform canvas |
| Infographic / presentation layouts | Not supported | No rich text formatting, image composition, or decorative layout |
Excellent fit
Architecture diagrams
The core use case. Services, databases, queues and external systems as typed nodes. Connections via edges with orthogonal or straight routing. Frames and groups for logical containment. Constraints for alignment and distribution.
Maps to: node (all shapes and types), edge (all routers), frame, group, constraint
Minimal scene. The hierarchical planner walks the edge graph, assigns nodes to ranks, minimizes crossings, and routes edges orthogonally - no layout on any element.
{
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"layoutStrategy": { "direction": "LR" },
"scene": {
"id": "service-arch",
"title": "Service Architecture",
"canvas": { "width": 900, "height": 360 }
},
"elements": [
{ "id": "client", "kind": "node", "nodeType": "actor", "shape": "roundedRect", "label": "Client" },
{ "id": "api", "kind": "node", "nodeType": "service", "shape": "roundedRect", "label": "API Gateway" },
{ "id": "cache", "kind": "node", "nodeType": "storage", "shape": "roundedRect", "label": "Redis Cache" },
{ "id": "db", "kind": "node", "nodeType": "database", "shape": "cylinder", "label": "PostgreSQL" },
{ "id": "worker", "kind": "node", "nodeType": "service", "shape": "roundedRect", "label": "Worker" },
{ "id": "e1", "kind": "edge", "from": { "elementId": "client" }, "to": { "elementId": "api" } },
{ "id": "e2", "kind": "edge", "from": { "elementId": "api" }, "to": { "elementId": "cache" }, "label": "read/write" },
{ "id": "e3", "kind": "edge", "from": { "elementId": "api" }, "to": { "elementId": "db" }, "label": "queries" },
{ "id": "e4", "kind": "edge", "from": { "elementId": "db" }, "to": { "elementId": "worker" }, "label": "events" }
]
}
Recommended for blob-of-services architectures: extensions.autoGroup: "byNodeType". When the scene has no explicit frame containers, the rendered diagram is a flat cloud of floating shapes. Adding "extensions": { "autoGroup": "byNodeType" } at the scene-document root makes the engine synthesize subtle background bands grouping nodes by their nodeType (“Services”, “Databases”, “External Systems”, etc.), lifting the diagram into a layered architecture that reads in one glance. Architecture diagrams and diagrams without a family only, and opt-in: without it, there are no bands. Each band is a region: when the engine places every node (a new diagram, or autoLayout without elements), it lays each band’s nodes out together, apart from the other bands, as it does a frame’s. Skipped when the scene already authors frames containing the candidate nodes (no double-wrap), when all nodes share a single nodeType (single band is pointless), or when the nodes of a type are scattered (a node of another type sits between two of them in a column) or placed so that their band would overlap a frame or another band, as positions a saved diagram keeps can. The API doesn’t say when banding was skipped or why, so check the drawing.
Layers: a stack of rows. To draw an architecture as layers (edge, services, data), write each layer as a frame with containerType: "layer" and list the layers top to bottom; the engine stacks them in that order, each card in its layer’s row, and you write no layout. It arranges the first stack only, and not inside a pool, lane or cloud group (Layout engine: Layers).
AWS architectures: the aws.* presets. For a system on AWS with VPCs, Availability Zones and subnets, write AWS’s groups as frames with their containerType presets, nested as AWS nests them (aws.cloud > aws.region > aws.vpc > aws.az > aws.subnet.public and aws.subnet.private), and the services as nodes with aws:* icons, each listed in the frame it runs in, with no layout. The engine draws each group as AWS does, with the official AWS Architecture Icons, and arranges the diagram as AWS’s reference architectures are drawn instead of by the layered layout: Availability Zones as columns, subnets as rows across them, gateways on the side of the VPC they face (on the top when they serve several AZs or the load balancer between two), regional services in a column beside the VPCs, global services in a row above the Regions, users outside AWS Cloud.
It doesn’t:
- Guess groups from frame titles.
AWS_GROUP_UNTYPEDwarns when a frame’s title is a group’s own name, and names the preset to set or says the frame can stay generic. - Reorder Availability Zones.
- Arrange presets inside another frame placed between a Region and its VPC, a VPC and its Availability Zones, or a zone and its subnets. It reads through a frame round all of a VPC’s zones, round whole VPCs or round subnets next to each other in one zone, and
AWS_FRAME_HIDES_GROUPSnames the rest. - Arrange Azure groups (Google Cloud’s have an arrangement of their own, below).
- Draw
autoGroupbands in these diagrams.
A group across Availability Zones, such as an Auto Scaling group, is a frame with spans instead of children, drawn round what it spans. Layout Engine: AWS architecture diagrams has the whole behavior and an example scene.
Google Cloud architectures: the gcp.* presets. For a system on Google Cloud, write Google’s groups as frames with their containerType presets, and the services as nodes with gcp:* icons, each listed in the frame it runs in. Nest the groups as Google does: gcp.cloud > gcp.project (optional) > gcp.region > gcp.subnet > gcp.tier and gcp.instanceGroup, with gcp.onPremises outside gcp.cloud. Draw the VPC network round its subnets, and each zone round its nodes, as spanning frames with spans. The engine draws each node as Google’s product card and each group as Google’s Architecture Center diagrams do (Rendering: Google Cloud groups).
In an architecture diagram, or one without a family, the engine also arranges the groups as Google’s reference diagrams are drawn, instead of by the layered layout:
- Zones are columns through every tier of a Region.
- A subnet’s tiers are rows, in the order their edges run.
- Regions stand side by side, their matching rows level.
- The VPC is one band across its Regions.
- Global and regional items form rows above or below, by their edges.
- Users stand outside the boundary.
Leave layout off the frames and their nodes.
It doesn’t guess groups from frame titles (GCP_GROUP_UNTYPED warns when a title is a group’s own name, and names the preset to set or says the frame can stay generic), reorder Regions or zones, put cards a tier doesn’t hold in zone columns, or draw autoGroup bands. A GKE cluster, node pool or folder has no preset: draw it as a generic frame, and its cards stand in no zone column. It doesn’t arrange groups inside a frame between them, other than a project or a generic frame round whole Regions; GCP_FRAME_HIDES_GROUPS names a generic frame round subnets or tiers. Layout Engine: Google Cloud architecture diagrams has the whole behavior and an example scene.
Flowcharts
Use the generic node types: process for a step, decision for a question, document for a report or file (a wavy bottom) and database. For the start and each end, use a generic node with shape: "pill" or "ellipse". A decision is any node drawn as a diamond: a decision, or another node with shape: "diamond". Label each exit of a decision with the answer it stands for.
The engine draws a flowchart the way its readers expect:
- Top to bottom, unless
layoutStrategy.directionsays otherwise. - Yes runs straight on, no turns aside. An exit labeled with an affirmative answer (
yes,y,true,ok,pass,passed,successorvalid) continues straight along the flow. One labeled with a negative answer (no,n,false,fail,failed,failure,errororinvalid) leaves to the right, or below when the flow runs left to right or right to left. Of two exits where one is a no, the other runs straight on. - Whole labels only. Labels match ignoring case and trailing punctuation (
Yes.is yes), but “No errors” andyes, retryaren’t answers. - Loop tests. When a decision has two exits and one loops back to an earlier step, the other runs straight on, whatever its label. “More items?” sends its yes back to “Load next item”, and its no runs straight on to “Ship order”.
- The main path runs straight: from the start, through each step’s one exit and the exit each decision sends straight on, in one line.
- Edits keep the lines. A node an edit inserts between two placed nodes goes on the line of the one before it, and what lies past it moves along the flow to make room. A new no branch goes to the right of its decision, or below when the flow runs left to right or right to left (Layout Engine: Positions are kept).
- Loops back across two or more ranks run round the left (above when the flow runs left to right or right to left), away from the no branches, unless the other side crosses fewer nodes or lines.
- An arrowhead on every entry. Lines into a step each keep their own end and arrowhead. Only lines into one side of a decision join, at its point, since one flow line enters a decision. Edges with the same label each keep their label.
- One tint. In the default style, every node draws light blue with a blue border, except external systems, notes and nodes with an
aws:*orgcp:*icon. A node whosestyleor the scene’spalettesets its fill or stroke keeps that color, with the plain white fill or gray border for the other. Thedark,blueprintandsketchthemes, and a saved version on a dark canvas, keep their own colors.
Where it stops:
- Other labels. Apart from loop tests, these decisions keep the general decision rules: one whose exits carry other labels (
approved,rejected), one with two yes exits, and one with three or more exits and no single yes. The branch nearest the decision’s line goes straight on, and the others leave by the side facing their targets (Rendering: Where an edge enters its target). - Three or more exits with a yes that loops back. Such a decision keeps the general decision rules too, so its no isn’t turned to the right.
- An else-if ladder, several decisions whose yes leads to the same node, draws as a column of checks: each no runs straight down to the next check, and each yes leaves to the side.
- Frames. In a flowchart with a frame that has no
layout, the main path isn’t lined up and no branches aren’t moved to the right, so a decision’s exits leave toward wherever their targets land, and a node an edit inserts is placed by the general rules. Loops still run round the left, or above when the flow runs left to right or right to left.
Validation warns, and the diagram still saves:
FAMILY_FLOWCHART_DECISION_FEW_EXITS: a decision has fewer than two exits. Add an exit for each answer, or make the node aprocess.FAMILY_FLOWCHART_EXIT_UNLABELED: an exit of a decision with two or more exits has no label. Set itslabelto the answer withupdateEdge.
Maps to: the generic node types (process, decision, document, database, generic), the pill, ellipse, diamond, parallelogram (input and output), document and subroutine (a predefined process) shapes, labeled edges
Minimal scene. No layout and no direction: the flow runs top to bottom. Each decision’s yes goes straight down and its no to the right. “Ask for another card” stands beside the main path, so its loop back to “Charge card” runs on the right, where it crosses nothing.
{
"schemaVersion": "0.1",
"diagramFamily": "flowchart",
"scene": {
"id": "order-checkout",
"title": "Order Checkout"
},
"elements": [
{ "id": "placed", "kind": "node", "nodeType": "generic", "shape": "pill", "label": "Order placed" },
{ "id": "stock", "kind": "node", "nodeType": "decision", "label": "In stock?" },
{ "id": "charge", "kind": "node", "nodeType": "process", "label": "Charge card" },
{ "id": "paid", "kind": "node", "nodeType": "decision", "label": "Payment OK?" },
{ "id": "retry", "kind": "node", "nodeType": "process", "label": "Ask for another card" },
{ "id": "backorder", "kind": "node", "nodeType": "process", "label": "Backorder items" },
{ "id": "receipt", "kind": "node", "nodeType": "document", "label": "Email receipt" },
{ "id": "done", "kind": "node", "nodeType": "generic", "shape": "pill", "label": "Order complete" },
{ "id": "e1", "kind": "edge", "from": { "elementId": "placed" }, "to": { "elementId": "stock" } },
{ "id": "e2", "kind": "edge", "from": { "elementId": "stock" }, "to": { "elementId": "charge" }, "label": "yes" },
{ "id": "e3", "kind": "edge", "from": { "elementId": "stock" }, "to": { "elementId": "backorder" }, "label": "no" },
{ "id": "e4", "kind": "edge", "from": { "elementId": "charge" }, "to": { "elementId": "paid" } },
{ "id": "e5", "kind": "edge", "from": { "elementId": "paid" }, "to": { "elementId": "receipt" }, "label": "yes" },
{ "id": "e6", "kind": "edge", "from": { "elementId": "paid" }, "to": { "elementId": "retry" }, "label": "no" },
{ "id": "e7", "kind": "edge", "from": { "elementId": "retry" }, "to": { "elementId": "charge" } },
{ "id": "e8", "kind": "edge", "from": { "elementId": "receipt" }, "to": { "elementId": "done" } }
]
}
A Mermaid flowchart or graph imports as a flowchart (Mermaid scope).
Org charts
Use org.person or org.role nodes for structured person cards. Cards render with a bold name, muted title, left accent stripe (department color via accentColor), and optional icon (e.g. lucide:user). Leave layout off the nodes for an automatic top-to-bottom tree; the tree doesn’t read layoutStrategy. Solid edges for direct reports (org.directReport), dashed edges for matrix/dotted-line relationships (org.dottedLine).
Maps to: org.person, org.role, org.department node types, org.directReport / org.dottedLine edge types, accentColor style, icons
Minimal scene. The tidy-tree planner gives balanced TB layouts for reporting hierarchies. style.accentColor paints the left department stripe.
{
"schemaVersion": "0.1",
"diagramFamily": "orgchart",
"scene": {
"id": "team-org",
"title": "Engineering Team",
"canvas": { "width": 900, "height": 420 }
},
"elements": [
{ "id": "cto", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Jordan Lee\nCTO", "style": { "accentColor": "#d4a843" } },
{ "id": "vp-eng", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Alex Chen\nVP Engineering", "style": { "accentColor": "#4db89a" } },
{ "id": "vp-design", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Sam Rivera\nHead of Design", "style": { "accentColor": "#4db89a" } },
{ "id": "dev1", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Pat Kim\nSenior Developer" },
{ "id": "dev2", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Taylor Ng\nSRE" },
{ "id": "r1", "kind": "edge", "edgeType": "org.directReport", "from": { "elementId": "cto" }, "to": { "elementId": "vp-eng" } },
{ "id": "r2", "kind": "edge", "edgeType": "org.directReport", "from": { "elementId": "cto" }, "to": { "elementId": "vp-design" } },
{ "id": "r3", "kind": "edge", "edgeType": "org.directReport", "from": { "elementId": "vp-eng" }, "to": { "elementId": "dev1" } },
{ "id": "r4", "kind": "edge", "edgeType": "org.directReport", "from": { "elementId": "vp-eng" }, "to": { "elementId": "dev2" } }
]
}
Entity-Relationship diagrams
Use er.entity or er.weakEntity nodes with extensions.columns for compartmented table-like boxes. Each column has a name, and optionally a type, pk/fk/unique/nullable flags and a comment. The renderer produces a colored header bar (via accentColor), separator line, and attribute rows with PK/FK badges and right-aligned types. Weak entities render with double-border. Crow’s-foot cardinality markers on edges (one, many, zero-or-one, zero-or-many, one-or-many). Relationship lines are solid (er.relationship, er.identifying), as Mermaid and Information Engineering draw identifying relationships; add style.dash for a non-identifying one.
Maps to: er.entity, er.weakEntity node types, extensions.columns, accentColor style, er.relationship / er.identifying edge types, cardinality on endpoints
Minimal scene. extensions.columns turns each entity into a compartmented box with header, separator, and PK/FK badges. The second edge omits cardinality and anchors at item.order_id, so the engine infers one at the order’s key and many at the foreign key. Author-set values are always preserved.
{
"schemaVersion": "0.1",
"diagramFamily": "entityRelationship",
"layoutStrategy": { "direction": "LR" },
"scene": {
"id": "er-orders",
"title": "Order Schema",
"canvas": { "width": 900, "height": 360 }
},
"elements": [
{
"id": "customer",
"kind": "node",
"nodeType": "er.entity",
"shape": "rect",
"label": "Customer",
"extensions": {
"columns": [
{ "name": "id", "type": "uuid", "pk": true },
{ "name": "email", "type": "text" },
{ "name": "created_at", "type": "timestamp" }
]
}
},
{
"id": "order",
"kind": "node",
"nodeType": "er.entity",
"shape": "rect",
"label": "Order",
"extensions": {
"columns": [
{ "name": "id", "type": "uuid", "pk": true },
{ "name": "customer_id", "type": "uuid", "fk": true },
{ "name": "total", "type": "numeric" }
]
}
},
{
"id": "item",
"kind": "node",
"nodeType": "er.entity",
"shape": "rect",
"label": "OrderItem",
"extensions": {
"columns": [
{ "name": "id", "type": "uuid", "pk": true },
{ "name": "order_id", "type": "uuid", "fk": true },
{ "name": "product_id", "type": "uuid", "fk": true },
{ "name": "qty", "type": "int" }
]
}
},
{ "id": "e1", "kind": "edge", "edgeType": "er.relationship", "from": { "elementId": "customer", "cardinality": "one" }, "to": { "elementId": "order", "cardinality": "many" }, "label": "places" },
{ "id": "e2", "kind": "edge", "edgeType": "er.relationship", "from": { "elementId": "order" }, "to": { "elementId": "item", "column": "order_id" }, "label": "contains" }
]
}
UI / navigation flows
Use uiflow.screen and uiflow.modal nodes for screen-level navigation diagrams. Screens render with a title bar strip at the top (using accentColor), with the first label line as the title and subsequent lines as body description. Modals add a drop shadow behind the card. Use uiflow.entry for app entry points (filled circle) and uiflow.exit for logout/close (bold circle). Three edge types: uiflow.navigate (solid), uiflow.back (dashed), uiflow.action (solid). Validation warns on missing screens, missing entry points, and orphan screens with no edges.
Maps to: uiflow.screen, uiflow.modal, uiflow.entry, uiflow.exit node types, uiflow.navigate / uiflow.back / uiflow.action edge types, accentColor style
BPMN
Full BPMN coverage via the workflow diagram family. Available BPMN primitives:
- Events: start (filled circle), end (bold circle), timer (circle + clock), error (circle + zigzag), intermediateTimer (double circle + clock), intermediateMessage (double circle + envelope), intermediateError (double circle + zigzag), intermediateThrowMessage (double circle + filled envelope), terminate (filled inner circle), messageStart (circle + envelope), messageEnd (bold circle + envelope)
- Gateways: exclusive (diamond + x), parallel (diamond + +), inclusive (diamond + circle), event-based (diamond + pentagon)
- Activities: task (roundedRect), subprocess (roundedRect with [+] collapse marker)
- Flows: sequenceFlow (solid, triangle arrowhead), messageFlow (dashed, open circle source, open arrowhead target)
- Swimlanes: pools and lanes laid out by the engine, with BPMN header strips (Swimlane enterprise workflows)
Maps to: workflow.start, workflow.end, workflow.timer, workflow.error, workflow.intermediateTimer, workflow.intermediateMessage, workflow.intermediateError, workflow.intermediateThrowMessage, workflow.terminate, workflow.messageStart, workflow.messageEnd node types, workflow.gateway, workflow.gatewayParallel, workflow.gatewayInclusive, workflow.gatewayEvent node types, workflow.task, workflow.subprocess node types, workflow.sequenceFlow / workflow.messageFlow edge types, pool / lane container types
Minimal scene. Setting diagramFamily: "workflow" activates BPMN-correct rendering: workflow.start as a circle, workflow.gateway as a diamond with an x marker, workflow.end as a bold-stroke circle, and workflow.sequenceFlow edges with triangle arrowheads. For a marker-less decision diamond, use workflow.decision (label inside) instead.
{
"schemaVersion": "0.1",
"diagramFamily": "workflow",
"layoutStrategy": { "direction": "LR" },
"scene": {
"id": "approval-flow",
"title": "Approval Flow",
"canvas": { "width": 900, "height": 240 }
},
"elements": [
{ "id": "start", "kind": "node", "nodeType": "workflow.start", "shape": "ellipse", "label": "Submitted" },
{ "id": "review", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Review" },
{ "id": "gate", "kind": "node", "nodeType": "workflow.gateway", "shape": "diamond", "label": "OK?" },
{ "id": "approve", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Notify Approver" },
{ "id": "reject", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Notify Rejection" },
{ "id": "done", "kind": "node", "nodeType": "workflow.end", "shape": "ellipse", "label": "Done" },
{ "id": "e1", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "start" }, "to": { "elementId": "review" } },
{ "id": "e2", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "review" }, "to": { "elementId": "gate" } },
{ "id": "e3", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "gate" }, "to": { "elementId": "approve" }, "label": "yes" },
{ "id": "e4", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "gate" }, "to": { "elementId": "reject" }, "label": "no" },
{ "id": "e5", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "approve" }, "to": { "elementId": "done" } },
{ "id": "e6", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "reject" }, "to": { "elementId": "done" } }
]
}
UML sequence diagrams
Full UML sequence diagram support via the sequence diagram family. Lifelines (sequence.lifeline) render with header boxes and dashed tails terminating at a matching foot bar at the bottom of the diagram (the UML convention; opt out with showLifelineFeet: false in the document’s top-level extensions). Headers auto-size to fit their labels - the 100 px width is a floor, not a cap, so multi-word participant names like "Compute Endpoint\n(Metadata)" fit. Actors (sequence.actor) render as stick figures with the same head + foot mirror. Activation bars (sequence.activation) render as thin filled rectangles on lifelines, from the message named by extensions.startsAt to the one named by extensions.endsAt, and messages to or from them end at the bar’s side. Five message types: synchronous (sequence.message, filled arrowhead), asynchronous (sequence.async, open arrowhead), reply (sequence.reply, dashed with open arrowhead), create (sequence.create, dashed with filled arrowhead), and destroy (sequence.destroy, filled arrowhead with X terminator). Self-messages render as U-shaped loops. Combined fragments (alt, opt, loop, par and the rest) render as dashed-border frames with pentagon operator labels and guard conditions, laid out with the messages they hold, nested ones inside, and a divider above the row each further operand starts at (extensions.operands[].startsAt).
UML notes / annotations between messages (sequence.note) render as a rectangle with a folded top-right corner. Anchor each note via extensions.anchor: a single string centers the note OVER the named lifeline; a string array spans the note across the named lifelines (also centered-over semantics). Matches UML 2.5 §17.4. Notes interleave vertically with messages by their position in the elements array. A note with one anchor and extensions.side ("left" or "right") sits beside its lifeline instead (Rendering: Lifeline rendering).
Participant types. Six more node types head a column and say what the participant is, such as sequence.database and sequence.queue. They work as a lifeline does and differ only in the head and foot drawn (Element types).
Lifelines that start and end. A sequence.create message that is a lifeline’s first row puts the lifeline’s head on that row, and a sequence.destroy message ends the lifeline it arrives at, with no foot bar (Rendering: Lifeline rendering).
Numbered messages. extensions.autonumber at the document’s top level numbers every message, top to bottom, as Mermaid numbers them, with a badge at its arrow’s start (Layout engine: Numbered messages). A message’s own step restarts the count, and edits renumber the messages after the one they change.
Participant boxes and highlight bands. A frame that isn’t a fragment is drawn by its children, and needs no containerType. Participants draw a box round them, and messages and notes draw a filled band behind those rows. Boxes don’t nest or overlap, and one frame can’t be both (Rendering: Participant boxes and highlight bands).
Mermaid. A Mermaid sequenceDiagram imports as a sequence diagram, reads back as one and takes edits in that form (Mermaid scope: Sequence diagrams).
Maps to: sequence.lifeline, sequence.actor, sequence.boundary, sequence.control, sequence.entity, sequence.database, sequence.collections, sequence.queue, sequence.activation, sequence.note node types, sequence.message / sequence.async / sequence.reply / sequence.create / sequence.destroy edge types, fragment container type with extensions.operator and extensions.operands, plain frames for participant boxes and highlight bands
Minimal scene. No layoutStrategy and no layout on any element - the sequence family resolver auto-positions lifelines left-to-right in definition order and stacks messages vertically by their position in elements. The first message edge is topmost. sequence.reply renders as a dashed arrow. An edit puts a new lifeline, message or note between two others with after or before (Operations: Order in a sequence diagram).
{
"schemaVersion": "0.1",
"diagramFamily": "sequence",
"scene": {
"id": "auth-sequence",
"title": "Authentication",
"canvas": { "width": 640, "height": 360 }
},
"elements": [
{ "id": "client", "kind": "node", "nodeType": "sequence.actor", "shape": "rect", "label": "Client" },
{ "id": "server", "kind": "node", "nodeType": "sequence.lifeline", "shape": "rect", "label": "Auth Server" },
{ "id": "db", "kind": "node", "nodeType": "sequence.lifeline", "shape": "rect", "label": "User DB" },
{ "id": "m1", "kind": "edge", "edgeType": "sequence.message", "from": { "elementId": "client" }, "to": { "elementId": "server" }, "label": "POST /login" },
{ "id": "m2", "kind": "edge", "edgeType": "sequence.message", "from": { "elementId": "server" }, "to": { "elementId": "db" }, "label": "find user" },
{ "id": "m3", "kind": "edge", "edgeType": "sequence.reply", "from": { "elementId": "db" }, "to": { "elementId": "server" }, "label": "user record" },
{ "id": "m4", "kind": "edge", "edgeType": "sequence.reply", "from": { "elementId": "server" }, "to": { "elementId": "client" }, "label": "session token" }
]
}
Acceptable with generic primitives
These work with generic shapes and edges, without the specialized notation.
Class diagrams
Classes as labeled nodes, inheritance and association as edges. No compartmentalized class boxes, stereotypes, or interface notation.
Limitation: No multi-compartment shapes or formal UML stereotypes.
State graphs
States as ellipse or roundedRect nodes, transitions as labeled edges, in a flowchart or workflow diagram. No formal statechart notation (fork bars, nested states, history nodes).
A transition label written as EVENT [guard] / action draws its guard and action smaller and muted, so the eye finds the event first (Rendering: edge label typography). A label wider than 200 px wraps, between its parts first (Element types: Label wrapping). Architecture, network, entity-relationship and org chart diagrams, and a diagram with no family, draw every edge label as plain text.
Limitation: No hierarchical state nesting.
Network diagrams
Use network.* node types (network.server, network.router, network.switch, network.firewall, network.cloud, network.client) with network.dataFlow and network.controlFlow edge types. Typed semantics are available but nodes render as their declared shape without family-specific visual treatment.
Limitation: No family-specific rendering (device icons, interface markers).
Swimlane enterprise workflows
Use a frame with containerType: "pool" whose children are frames with containerType: "lane", and list each node in its lane’s children. The engine lays them out as BPMN tools do: lanes run along the flow and stack across it in the order the pool lists them, every node a lane lists lands inside it, each lane is as deep as its contents need (at least 60 px, or its title’s length plus 16 px), and columns are shared across lanes and pools, so the flow reads as time. Pools and lanes are drawn with BPMN header strips: a 30 px strip with the title, rotated in a horizontal pool (Rendering). A pool’s or lane’s layout is a minimum, not a fixed size: the pool grows to hold its lanes and members. Add a task to a lane later with createNode’s frame, and move one to another lane with updateNode’s frame.
Limitations: Lanes always run across the flow: there are no phases or milestones along it. The engine keeps lanes in the order the pool lists them and pools in document order, without reordering them to reduce crossings. A frame inside a lane, such as a subprocess, is fitted round its members rather than laid out with them. Edges can still run through a gateway’s or event’s external label in some layouts. Layout Engine: Pools and lanes has the details.
Minimal scene. No positions anywhere: set laneDirection on the pool, list the lanes as the pool’s children, and list the nodes in each lane as that lane’s children. The engine places the nodes and sizes the pool and lanes.
{
"schemaVersion": "0.1",
"diagramFamily": "workflow",
"layoutStrategy": { "direction": "LR" },
"scene": {
"id": "approval-lanes",
"title": "Approval with Lanes",
"canvas": { "width": 900, "height": 420 }
},
"elements": [
{ "id": "pool", "kind": "frame", "title": "Approval Process", "containerType": "pool", "laneDirection": "vertical", "children": ["lane-req", "lane-rev"] },
{ "id": "lane-req", "kind": "frame", "title": "Requester", "containerType": "lane", "children": ["start", "submit"] },
{ "id": "lane-rev", "kind": "frame", "title": "Reviewer", "containerType": "lane", "children": ["review", "gate", "notify", "end"] },
{ "id": "start", "kind": "node", "nodeType": "workflow.start", "shape": "ellipse", "label": "Submitted" },
{ "id": "submit", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Submit" },
{ "id": "review", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Review" },
{ "id": "gate", "kind": "node", "nodeType": "workflow.gateway", "shape": "diamond", "label": "OK?" },
{ "id": "notify", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Notify" },
{ "id": "end", "kind": "node", "nodeType": "workflow.end", "shape": "ellipse", "label": "Done" },
{ "id": "e0", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "start" }, "to": { "elementId": "submit" } },
{ "id": "e1", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "submit" }, "to": { "elementId": "review" } },
{ "id": "e2", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "review" }, "to": { "elementId": "gate" } },
{ "id": "e3", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "gate" }, "to": { "elementId": "notify" }, "label": "yes" },
{ "id": "e4", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "gate" }, "to": { "elementId": "end" }, "label": "no" },
{ "id": "e5", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "notify" }, "to": { "elementId": "end" } }
]
}
laneDirection: "vertical" stacks the lanes top to bottom, which BPMN calls a horizontal pool, and the flow runs left to right; "horizontal" puts them side by side, a vertical pool, and the flow runs top to bottom. Lanes always run across the flow: when layoutStrategy.direction runs along the lanes’ stacking, laneDirection wins. Pools, lanes and their nodes all omit layout.
Not yet first-class
These need notation or layout DSP doesn’t have.
UML state/activity notation
Requires fork/join bars, nested composite states, history pseudo-states, and activity partitions. Generic nodes can approximate simple cases but not the full notation.
Mind maps
Hierarchical auto-layout (layoutStrategy: { "direction": "TB" }) can approximate a top-down tree structure, but there is no radial/circular layout algorithm for true mind-map branching from a central topic.
Not supported
Freeform sketching
Zindex is a structured diagram protocol, not a freeform drawing canvas. There are no pen strokes, freehand shapes, or pixel-level drawing primitives.
Infographic / presentation layouts
Zindex focuses on structured diagrams, not rich visual compositions with decorative typography, image grids, or complex text formatting.
Cross-cutting capabilities
- Auto-layout - leave
layoutoff nodes and the layout engine places them by the diagram’s family. Architecture, flowchart, workflow, entityRelationship, uiflow and no-family scenes get a layered layout in the directionlayoutStrategy.directiongives (TB, LR, BT or RL), flowcharts top to bottom and the rest left to right without one. AWS and Google Cloud groups are placed by what they are, org charts as a tree, network diagrams by force and sequence diagrams by message order. A scene can fix some nodes and leave the rest to the engine.autoLayoutlays out again. Nodes keep their positions after the first save, unless:- a node that grows needs the room
- a new node’s edge label needs more room than the column it joins
- a new task in a pool needs room in its lane or a column of its own
- a node an edit inserts in a flowchart needs room along the flow
- a node an edit adds to a frame without a
layouthas no room there - an AWS diagram’s row or column grows for a node or a spanning frame’s header an edit adds, or for the room round a tier frame
- an edit moves an AWS diagram’s Region’s column right to keep a labeled line into the column clear
- a Google Cloud diagram’s row, zone column, Region or project’s box grows, a gap between two Regions, two projects or two zone columns opens, or a line crosses an item in a row, for what an edit adds
- a layer in a stack of layers grows for a card an edit adds to it or moves into it, or an edit adds a layer, and what lies after it moves along by the growth (the card stands in that layer’s row)
- an edit moves them to another lane
- a frame added or deleted around them would leave frames overlapping or a frame holding a node that isn’t its member
- an
orderconstraint you add finds its two nodes the wrong way around
- Numbered steps -
stepon an edge draws a numbered badge at the start of its line, andstepTextlists the step in a list beside the drawing, in every family; a sequence diagram can also number every message withextensions.autonumber(Layout engine: Numbered steps). - Spanning frames - a frame with
spansinstead ofchildrenis drawn round elements that keep their own frames, such as an Auto Scaling group across Availability Zones, in architecture diagrams and diagrams without a family (Layout engine: Spanning frames). - Themes -
POST /v1/diagrams/previewtakes atheme(clean,dark,blueprintorsketch, hand-drawn) to draw a scene in another style without changing it.dark,blueprintandsketchadapt the colors of a scene designed on a light canvas; images, icons given as a URL or data URI, AWS icons, and Google Cloud’s cards and groups keep theirs. Saved versions are drawn in the default style, or thedarktheme whenscene.canvas.backgroundis a dark color; otherwise their colors come from the scene’s own styles andpalette. - Edge routers - straight, orthogonal, curved, polyline.
- Constraint types - align, distribute, sameSize, stack, centerIn, contain, grid, minGap, noOverlap, order.
- Inline or registry styles - control fill, stroke, text color, font size and weight, opacity per element or via named style tokens.