Labels

Labels here are the text on lines: connector labels, keywords such as «import», transition triggers and guards, message names. Names of boxes and containers are in Names and titles.

Keep a label beside its own line

Rule. A label sits next to a straight run of its own line, 6 to 8px from it, and close to the middle of that run.

Why. Closeness is what ties a label to its line (Gestalt proximity). A label far from its line has to be matched by searching.

diagram state "Labels beside their lines"

[*] --> Idle
Idle --> Busy : start [ready] / log()
Busy --> Idle : done

Source. Gestalt proximity (via the research report); Kakoulis and Tollis 1997.

Status: enforced. A reserved state label sits 8px from its anchor (Placement), and a state label placed after routing sits with its ink 8px from its own segment. labels::Placer tries five positions along each segment, 6px off it, and prefers the middle and longer runs. The quality test counts labels more than 12px from their own line: 4 state labels in the golden files: two-line labels above a line in a rightward flow, whose upper line is 14px away, and a self-transition label in the staircase under its loop.

Never leave a label between two lines

Rule. No other line may be as near to a label as its own line. A label that sits between two parallel lines must move, or one of the lines must.

Why. A label equally near two lines belongs to neither, and a reader guesses. This is the unambiguous reading rule, second only to notation in When rules conflict.

Bad: retry could belong to either line.

Source. Kakoulis and Tollis 1997 (a label must be associated with exactly one edge); drafting practice.

Status: partial. The quality test counts every connector label with another line at least as near as its own: 1 of 118 state labels, 1 of 27 package labels and none of 69 component labels in the golden files. A state label placed after routing must be 12px nearer its own line than any other, or it keeps its reserved spot. Component and package labels are placed by fewest collisions and are not checked for this when placed.

Never let a label touch other ink

Rule. A label does not overlap a box, a name, another label or any line.

Why. Text over ink is hard to read, and a label on a line seems to belong to it.

Source. Purchase et al. 2002 (text legibility); Castelló, Mili and Tollis 2000.

Status: partial. Reserved state labels are obstacles for every line, so no line crosses them, and a state label placed after routing must clear every line, outline, arrowhead, shape and label. The placer used for component and package labels takes the position with the fewest collisions, but cannot make room when every position collides. The quality test counts labels within 2px of a line or an outline, or on a shape or label: 1 in the golden files (a package label).

Write labels horizontally

Rule. All text runs left to right, horizontally, including labels on vertical lines.

Why. 86% of subjects preferred horizontal labels in UML diagrams.

Source. Purchase, Allder and Carrington 2002.

Status: enforced. No text is rotated.

Put labels on a consistent side

Rule. In a diagram that flows down, a label sits right of its vertical line. In one that flows right, it sits above its horizontal line. A reverse pair between two items keeps both labels on the outside, so the two lines run close together.

Why. A consistent side lets the eye find each label without searching, and keeps lines and labels from interleaving.

Source. Drafting practice; DECISIONS.md, “State machine diagrams (stage 4)”.

Status: enforced for state diagrams (label_side, order_label_sides). Component labels go right of vertical runs and above horizontal runs. Package labels may also take the left of a vertical run, to avoid a collision.

Reserve room for labels

Rule. The layout makes room for long labels before lines are routed, instead of hoping that a spot will be free afterwards.

Why. A placer that chooses among positions cannot make space, and fails on dense diagrams. Label dummies that take part in the layout guarantee room (dot, KLay).

Source. Gansner et al. 1993; Schulze, Wechselberg and von Hanxleden 2018; Castelló et al. 2000 (all via the research report).

Status: partial. State transition labels are dummies in the layered layout (Placement). Component and package diagrams flowing right widen the rank gap by the label’s width. Elsewhere labels are placed after routing.

Never let a label force a bend

Rule. A label follows its line, not the reverse. A line should run as straight as it would without its label, and the label then takes a free spot beside it. When no spot is free, the label keeps its reserved place, and the line goes through it.

Why. Labels serve lines. Today a state transition is routed through its label’s anchor, and every label is an obstacle for every line, so a short transition jogs just to pass its anchor. In Elevator controller, near target floor, speed zero, levelled at floor and fully open all do this.

Source. Purchase et al. 2002 (bends); Layout levers.

Status: partial, for state diagrams (Labels after routing). The layout still reserves every label’s room. Each line that bends is routed again without its waypoint, and its label placed beside the new line, on the segment and side that read best. A label keeps its reserved spot when no place is clear, near (12px) and unambiguous, when its line gains no straightness, or when its line gains a crossing. A diagram keeps the fully reserved drawing unless the result has fewer bends and no more crossings, overlaps, merged ends or label flaws. The study measured 26 bends for this before box growth; after box growth and L over Z it saves 7, because most short jogs past an anchor are already gone. The labels freed in the golden files are motor overcurrent / cut power (Elevator), close / send FIN (TCP) and wait(event) / block() (Process lifecycle). near target floor keeps its spot: right of its straightened line it would lie on next call, and left of it on the region border.