Flow and arrangement

Flow one way

Rule. A diagram has one main direction, down or right, and most connectors point along it. Items sit in ranks across that direction, and a connector joins items in later ranks wherever possible.

Why. A single direction lets the reader follow cause to effect without turning the page. Purchase et al. ranked information flow third among UML layout preferences.

diagram component "One direction"
direction right

component Parser
component Checker
component Emitter
Parser --> Checker : AST
Checker --> Emitter : typed AST

Source. Purchase et al. 2002; Sugiyama et al. 1981 and Gansner et al. 1993 (layered drawing).

Status: enforced. Ranking assigns ranks. Component diagrams flow right by default, and package and state diagrams flow down, because their long labels then sit beside vertical lines. direction changes it.

Keep connected items close

Rule. Connected items sit in neighbouring ranks where the graph allows. A source pulls next to the first thing it feeds.

Why. Short edges need fewer dummies, fewer bends and less searching.

Source. Gansner et al. 1993 (minimising weighted edge length).

Status: partial. Longest-path ranking with sources pulled next to their targets. The optimal network-simplex ranking of the research report (recommendation 4) is not implemented.

Order ranks to avoid crossings

Rule. Within each rank, items are ordered so that edges between ranks cross as little as possible. Hints and notes are part of the ordering, not applied afterwards.

Why. Most crossings are decided by the order, before any line is routed.

Source. Gansner et al. 1993 (weighted median, transpose); research report recommendation 2.

Status: enforced within a container (Crossing reduction).

Order across containers too

Rule. The order of items inside a container should take the lines that leave the container into account.

Why. A container laid out on its own can put a child on the wrong side of its outside partners. The Order Platform diagram has its one crossing for this reason, and the Compiler pipeline has a jog between its two containers.

Source. Sander 1996; Forster 2002 (via the research report); Layout levers.

Status: planned. Not scheduled. It needs a global layering across the hierarchy, which is a rewrite of arrange.

Keep long edges straight

Rule. An edge that spans several ranks runs as one straight line, where both ends can take it. Where only one end can, it bends once, near the other end.

Why. Long edges that wander become spaghetti (Gansner et al.), and continuity helps path tracing (Ware et al.).

Source. Gansner et al. 1993; Ware, Purchase, Colpoys and McGill 2002.

Status: enforced, by the straightening step of Placement.

Align a pendant with what it hangs from

Rule. An item joined to the rest by a single chain, such as an initial state, a final state or a note-like leaf, sits in line with the item it hangs from, so the chain is straight.

Why. A short spur that jogs looks careless, and it is the easiest jog to remove.

diagram state "Pendants in line"

[*] --> Ready
Ready --> Done : finish
Done --> [*]

Source. Drafting practice.

Status: enforced, by the pendant step of Placement.

Centre and balance

Rule. An item with several neighbours in the next rank sits centred over them. A rank is balanced around the items it connects to, and the layout is symmetric where the graph is.

Why. Symmetry has a measurable but smaller effect than crossings and bends (Purchase 1997), and it is what makes a tree look like a tree.

Source. Purchase 1997; Gansner et al. 1993; Brandes and Köpf 2001.

Status: partial. An order-preserving median solve aligns connected items. It is a heuristic: an item can sit off the line of what it connects to. Network simplex or Brandes-Köpf coordinates are not implemented (research report recommendation 4).

Group what belongs together

Rule. Containers hold their contents. Notes sit beside what they annotate. Unconnected siblings fold into a compact block instead of one long row. Orthogonal regions tile across the flow.

Why. Proximity groups things before any line is read.

Source. Gestalt proximity (via the research report); UML 2.5.1, 14.2.4 (regions).

Status: enforced: Compound layout, the Beside and Adjacent constraints for notes, wrap_constraints for package siblings, and region tiling in the state layout.

Honour hints over heuristics

Rule. A layout hint (left-of, above, align and the others) always wins over what the heuristics would choose.

Why. The author knows what the diagram is for. A hint is the one way to say so without coordinates.

Source. DECISIONS.md, “Format, look and layout control”; Layout hints.

Status: enforced. Constraints apply inside every ordering sweep and win over edges.

Draw the same input the same way

Rule. The same source always gives the same drawing, byte for byte, on every machine.

Why. A diagram in version control should change only when its source does, and readers should not have to find their way around a drawing again after an unrelated edit.

Source. PLAN.md rules; the D2 TALA author’s caution about seed-dependent layouts (via the research report).

Status: enforced. There is no randomness, no HashMap order in the output, and text is measured with embedded metrics. The golden tests check it.