The Visual Layer: Layout, Themes, and Configuration
Mermaid’s semantic model tells the runtime what relationships exist, but it does not yet decide whether those relationships will be easy to read. This chapter examines the visual layer: how Mermaid measures content, computes geometry, applies themes, resolves configuration, and manages reproducibility. The practical judgment is whether a visual choice changes meaning, presentation, or the reliability of the generated artifact—and which trade-offs follow from that distinction.
A diagram is not readable merely because it has been parsed. Text has width, groups need room for their contents, edge labels need space, and the final SVG has to fit the host that displays it. Mermaid treats those concerns as a geometry and policy problem between semantic state and painted output.
Meaning is not geometry
A layout algorithm decides where nodes sit and how edges travel between them. It does not decide whether a flowchart should contain a particular relationship; that information already belongs to the parsed model. Its job is to translate the model into positions and paths that a renderer can draw.
That separation begins with measurement. Labels have dimensions, and those dimensions affect whether two nodes can fit beside each other, whether an edge label collides with a shape, and how much space a group needs to contain its members. Mermaid’s common layout structure measures leaf elements in a browser, passes their sizes to the layout stage, and lets the algorithm write positions, group extents, edge points, and label anchors. The renderer then draws shapes, strokes, markers, text, and the surrounding viewBox from those numbers.
Measurement is the one part of this process that depends directly on the browser’s rendering environment. Fonts, text wrapping, and the dimensions reported by the page affect the inputs to geometry. Mermaid’s layout guidance keeps the algorithmic core free of the DOM so that the same core can run in tests with captured browser dimensions. That design gives a useful boundary: browser code measures; the layout core calculates; the renderer paints.
The separation also makes failure easier to name. A node whose label spills outside its shape may have been measured incorrectly or given unsuitable styling. Two nodes that occupy the same space point to a layout constraint. An edge that crosses an unrelated node or ends away from its target points to routing or endpoint geometry. A label placed on top of another edge indicates that space was not reserved before positions were chosen. These are different problems even though the user sees all of them as “the diagram looks wrong.”
Groups make the geometry problem more demanding. A group or subgraph is both a container and an object in the layout. Its frame has to enclose its members, leave room for a title, and remain an obstacle for edges that should not pass through it. Nested groups multiply those relationships. An edge can terminate at a group boundary, enter a member inside a group, or cross several levels of containment.