Design guidelines for creating well-laid-out block diagrams and state charts. Use when building or reviewing model files.
Follow these rules when creating or editing model files, placing blocks programmatically, or building state charts. Based on 80+ sources including MAAB v5/v6, NASA Orion, Michael Burke (MathWorks), UML/Agile Modeling, ELK, yFiles, and graph drawing literature.
spacing.edgeNode default: 10 from edge center, yFiles minimumNodeToEdgeDistance default: 10, LabVIEW "do not wire under objects", Gestalt proximity principle)spacing.edgeEdge default: 10, yFiles minimumEdgeDistance)portY = block.y + block.height * (portIndex + 1) / (portCount + 1). Match source and destination portY values exactly, then snap the block position to the nearest grid point that achieves this.When a line cannot maintain 20px clearance from an unrelated block without creating an awkward route:
For a typical 3-block model (Source -> Processing -> Sink):
Source block: x=80, y=120, w=80, h=60
Processing block: x=280, y=100, w=140, h=100
Sink block: x=520, y=110, w=60, h=60
Key formulas:
nextBlock.x >= prevBlock.x + prevBlock.width + 80block.y + block.height * (portIndex + 1) / (portCount + 1)For branch lines (one source to two destinations), use waypoints:
"waypoints": [
{"x": branchX, "y": srcPortY},
{"x": branchX, "y": dstPortY},
{"x": dstBlockX, "y": dstPortY}
]
Where branchX is a convenient midpoint X between the source and destination blocks.
col = i % 3, row = floor(i / 3)labelOffset: {dx, dy} in the model file to adjust:
dy: -15 for above, dy: 15 for belowdx: 15 for right, dx: -15 for leftmidpointOffset so the two transitions don't overlap:
midpointOffset: {dx: -20, dy: 0} or {dx: 0, dy: -20}midpointOffset: {dx: 20, dy: 0} or {dx: 0, dy: 20}For the Smart Thermostat pattern (1 junction + 4 states):
Junction: x=80, y=60 (top-left, entry point)
State 1: x=80, y=220 (center-left, default/idle)
State 2: x=340, y=80 (upper-right)
State 3: x=340, y=370 (lower-right)
State 4: x=600, y=80 (far-right, extension of state 2)
State sizes: 180x110 (uniform) Gap between states: 60-80px minimum
Before finalizing any model:
Key references (80+ total):