name: dot-quality description: Use when enforcing quality standards on DOT diagrams — checking completeness, structure, and visual clarity before sharing or committing

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