Write Mermaid Diagrams That Explain a System Instead of Decorating It

A useful diagram makes a relationship easier to understand than prose. Mermaid lowers the cost of keeping diagrams beside technical discussion, but it also makes it easy to produce a dense graph that is technically correct and practically unreadable.

Choose the diagram type from the question. Use a flowchart for branching behavior, a sequence diagram for messages over time, a state diagram for valid transitions, and an entity relationship diagram for data structure. Do not force every architecture discussion into a left-to-right box map.

Keep labels short and move explanation into surrounding prose. A node named “Validate signed request and reject expired timestamp” is trying to be both diagram and paragraph. Name it “Validate request,” then explain expiration rules below the diagram.

sequenceDiagram
  participant B as Browser
  participant A as API
  participant D as Database
  B->>A: Publish work
  A->>A: Validate and rate-limit
  A->>D: Insert pending work
  D-->>A: Share identifier
  A-->>B: Share URL

Use consistent direction and vocabulary. If the code calls something a “work,” do not alternate between snippet, document, paste, and artifact in adjacent nodes. Highlight only the path under discussion; excessive colors and shapes create a legend the reader must learn before understanding the system.

Test the rendered result at the width where readers will see it. Long labels may produce a diagram wider than a phone. Break a complicated model into two diagrams when the reader would otherwise have to pan across unrelated branches.

Finally, keep the source editable and include one sentence describing the diagram's claim. That sentence is a valuable review test: if the diagram does not make the claim clearer, it probably needs a different structure rather than more decoration.

Start with the question the diagram answers

A useful diagram has a reading task: trace a request, compare ownership, understand a state change, or find a dependency. Write that task in one sentence before choosing a Mermaid diagram type. Flowcharts work for branching processes, sequence diagrams for ordered interactions, state diagrams for lifecycle rules, and class or entity diagrams for stable relationships. Choosing by appearance usually produces a picture that contains facts but does not help a reader reason.

Limit the first version to the actors and transitions needed for that question. Group secondary details in prose or a second diagram. A dense graph is not automatically more authoritative; it often forces readers to hunt through crossed edges and abbreviations.

Make source stable and reviewable

Use predictable identifiers that survive label edits. Quote labels containing punctuation, keep direction explicit, and use subgraphs only when their boundary has meaning. Put one relationship per source line so diffs reveal what changed. Avoid relying on theme-specific colors to communicate state because the diagram may be rendered in dark mode, printed, or viewed with forced colors.

Store the Mermaid source near the explanation and validate it with the same Mermaid version used by the destination. Features and parsing rules evolve. If the diagram will be embedded in several systems, test the oldest supported renderer or restrict the syntax to a known-compatible subset.

Handle untrusted diagram text safely

Mermaid source is data, but renderers can support links, HTML labels, or interaction callbacks. Use a strict security level for user-provided diagrams, disable features you do not need, and render into an isolated container. Do not concatenate arbitrary user text into directives or configuration blocks. Apply length and complexity limits so an intentionally huge graph cannot monopolize the main thread.

Treat external links as untrusted navigation and make their behavior visible. If your product permits links, validate allowed protocols and add safe target attributes. Explain these restrictions in the demo so the production team does not unknowingly replace them with a permissive default.

Test comprehension, not only syntax

Ask a reviewer unfamiliar with the source to answer the original reading question. If they follow the wrong edge or cannot find the starting point, revise labels and layout before adding decoration. Check the diagram at narrow widths, high zoom, light and dark themes, and with long translated labels. Provide a text description or adjacent ordered steps for readers who cannot use the visual.

Export tests matter too. SVG should preserve readable text and a meaningful viewBox; raster exports should have enough resolution for their destination. Confirm that copying the source recreates the same diagram without private assets. End the shared artifact with the Mermaid version, security mode, intended reading order, and any omitted branches. That context turns a diagram from a screenshot into maintainable technical documentation.

Keep one small regression diagram for each syntax feature you depend on, so renderer upgrades can be checked before they alter published documentation.