DOT Quality Standards

Overview

Every DOT diagram makes structural claims. Those claims must be verifiable, complete, and unambiguous. Quality enforcement ensures diagrams communicate correctly — not just render correctly.

Core principle: A diagram that renders without errors can still be wrong. Structural claims require titles, color requires legends, and shapes must match their semantic meaning.

The Iron Law

NO DIAGRAM WITHOUT A TITLE, NO COLOR WITHOUT A LEGEND

These are not suggestions. A diagram without a title is anonymous — reviewers cannot reference it. A diagram with unexplained color is ambiguous — different readers draw different conclusions.

Quality Checklist

Must Have — FAIL if missing

• Graph has a label= attribute set to a meaningful title
• labelloc=t is set (title appears at top, not bottom)
• Every node has either a meaningful ID or an explicit label=
• All edges convey accurate relationships (not aspirational or assumed)

Should Have — WARN if missing

• rankdir is set explicitly (LR, TB, BT, or RL) — don't rely on defaults
• Default node and edge attributes are declared at the top with node [...] and edge [...]
• Shape vocabulary is consistent with the shape-meaning table below
• If any color is used, a cluster_legend subgraph documents all colors used
• Error and exception paths are drawn (not just the happy path)
• External dependencies are shown, even if simplified

Nice to Have — INFO

• fontname is set consistently (Helvetica or similar sans-serif)
• nodesep and ranksep are tuned for readability
• Cluster fill colors are distinct from node fill colors
• A // comment explains any non-obvious structural choice

Line Count Targets

Diagrams that exceed WARN thresholds should be split into overview + detail files.

Anti-Pattern Red Flags

Shape Vocabulary Compliance

Shapes carry semantic meaning. Using the wrong shape creates ambiguity:

The Quality Gate

Run this 7-step check before every diagram is shared, committed, or embedded in documentation:

1. Render check — dot -Tsvg diagram.dot > /dev/null — zero errors
2. Title check — grep 'label=' diagram.dot shows a non-empty title
3. Color check — if any fillcolor or color attribute is set, cluster_legend exists
4. Shape check — review each node shape against the Shape Vocabulary table
5. Float check — every node has at least one edge (incoming or outgoing)
6. Path check — error/failure paths are present, not just the happy path
7. Size check — line count is within target range for the diagram type