markus41/plugins/drawio-diagramming/skills/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

| Fill Color | Recommended fontColor | Example | |-----------|----------------------|---------| | #DAE8FC (blue) | #333333 | Services | | #D5E8D4 (green) | #333333 | Data stores | | #FFF2CC (yellow) | #333333 | Decisions | | #F8CECC (red) | #333333 | Errors | | #E1D5E7 (purple) | #333333 | External | | #F5F5F5 (gray) | #333333 | Containers | | #08427B (C4 blue) | #FFFFFF | C4 person | | #438DD5 (C4 mid) | #FFFFFF | C4 system | | #1B1B1B (dark) | #FFFFFF | Dark mode | | #143642 (blueprint) | #DADADA | Blueprint |

Auto-Fix Patterns

When critique finds issues, apply these automatic fixes:

| Issue | Fix | |-------|-----| | Missing rounded=1 on edge | Add rounded=1;jettySize=auto; to edge style | | Missing shadow=1 on shape | Add shadow=1; to vertex style | | Missing layers | Add <mxCell id="layer-notes" value="Annotations" parent="0"/> | | background not set | Add background="none" to <mxGraphModel> | | No html=1 on labeled shape | Add html=1; and wrap value in <b> tags | | Sharp edge corners | Add rounded=1; to edge style | | Thin primary edges | Add strokeWidth=2; to primary flow edges | | No title | Add text cell on annotations layer |