microsoft/dot-quality

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

| Diagram Type | Target | WARN at | FAIL at | |-------------|--------|---------|---------| | Overview / context | 30–80 | 120 | 200 | | Architecture (detail) | 80–150 | 250 | 400 | | Inline (single concept) | 10–30 | 50 | 80 | | Quick sketch | 5–20 | 35 | 60 |

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

---

Anti-Pattern Red Flags

| Flag | Problem | Fix | |------|---------|-----| | Floating node | Node with no edges — forgotten or placeholder | Connect it or remove it | | Mystery color | Color used without legend entry | Add to legend or remove color | | label="" | Empty label — invisible node | Set a meaningful label | | Duplicate node IDs | Same ID used for different concepts | Rename to make IDs unique | | All nodes same shape | Shape vocabulary not being used | Apply shape-meaning table | | Edges without direction meaning | Arrow direction doesn't match data/control flow | Reverse or relabel edges | | No title | Anonymous diagram — cannot be referenced | Add label= and labelloc=t |

---

Shape Vocabulary Compliance

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

| Shape | Meaning | Misuse to Avoid | |-------|---------|-----------------| | box / rectangle | Service, process, component | Don't use for data stores | | cylinder | Database, file store, queue | Don't use for services | | diamond | Decision point, branch | Don't use for processes | | ellipse | Start / end state, terminal | Don't use for services | | doublecircle | Final/accepted state (FSM) | Reserve for state machines | | parallelogram | External system, I/O | Don't use for internal services | | note | Annotation, documentation node | Don't use for primary components | | component | Fan-out / fan-in coordinator | Don't use for simple steps | | point | Initial state marker (FSM) | Reserve for state machines only | | folder | File group, repository | Don't use for services |

---

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