Quality Critique

Diagram Quality Critique

Run this critique on every generated diagram XML BEFORE writing the file. Fix all issues found before saving — do not write substandard diagrams.

Critique Checklist

1. Structure (must pass — blank file prevention)

• XML starts with <mxfile> wrapping <diagram> wrapping <mxGraphModel>
• background="none" set on <mxGraphModel> (transparent, not white)
• Cells id="0" and id="1" parent="0" present
• At least 2 layers defined (content + annotations)
• All cell IDs are unique
• All parent references point to existing cells
• All source/target on edges point to existing vertices

2. Layout Quality

• Shapes are grid-aligned (x, y coordinates are multiples of 10)
• No overlapping shapes (check x, y, width, height for collisions)
• Consistent spacing between related elements (60-80px gaps)
• Logical flow direction (top-to-bottom or left-to-right)
• Container/group boundaries have 20px+ padding around children
• Title annotation present at top-left

3. Edge/Connection Quality (critical — prevents ugly routing)

• ALL edges use rounded=1;jettySize=auto; (no sharp 90-degree bends)
• Primary flow edges use strokeWidth=2;
• Edges between non-aligned shapes specify exitX/exitY/entryX/entryY
• No edges crossing through shapes (reroute or add waypoints)
• Crossing edges use jumpStyle=arc;jumpSize=16;
• Return/response edges use dashed=1;dashPattern=8 4;
• Edge labels are positioned to not overlap shapes

4. Visual Quality

• All primary shapes have shadow=1; for depth
• HTML labels enabled (html=1;) with <b> for titles
• Font size >= 11pt for shape labels, >= 9pt for edge labels
• Fill colors use the standard palette (not random hex values)
• Text has sufficient contrast against fill (dark text on light fills, white text on dark fills)
• fontColor explicitly set (use #333333 for light fills, #FFFFFF for dark fills)
• Container headers use fontStyle=1; (bold)

5. Sophistication

• Related elements grouped in containers (container=1;collapsible=1;)
• Semantic layers used (not all elements on default layer)
• Color coding is consistent and meaningful (blue=services, green=data, etc.)
• Legend present if 3+ color categories used
• Metadata via <object> tags where appropriate (services, APIs)
• Multi-page used for complex diagrams (10+ major elements → drill-down pages)

6. Platform Compatibility

• Azure DevOps: export as PNG (not SVG) — SVG rendering is broken
• GitHub: use .drawio.svg with --embed-diagram for editability
• Transparent background for clean embedding in all contexts

Contrast Reference

Auto-Fix Patterns

When critique finds issues, apply these automatic fixes: