Diagram Design: evidence-driven visual explanations
Your first Diagram Design brief: choose audience, size and fidelity before drawing
Turn a vague request for an architecture picture into an explicit output brief and a reviewable record of what was preserved or simplified.
What you will learn
- Write the explanation before the drawing request
- Simplification needs an accountable boundary
- Inspect the first static result
Before you start
- Basic HTML and SVG concepts
- Ability to distinguish a system relationship from its visual layout
Choose a useful representation, account for simplification and interpret checker findings within their real scope.
Key takeaways
- Choose format, size, detail and audience separately.
- A complexity limit is a ceiling, not a content target.
- Keep an explicit record of meaningful simplification.
Write the explanation before the drawing request
Start with a narrow sentence such as: explain how an order request reaches persistent storage. List the actual components and relationships supplied by the project. Do not add a queue, cache or security gateway just because those shapes make an architecture diagram look sophisticated. An unknown component role should remain unknown until clarified.
Set format, size, detail and audience before drawing. These choices are independent: a technical audience does not automatically justify a denser canvas, and a larger canvas does not make tiny text readable on a projected slide. The output specification couples size presets to typography, so resizing after layout is not a complete adaptation.
Simplification needs an accountable boundary
The documented balanced level permits up to 12 nodes and 16 edges; simplified permits seven and nine. Faithful allows up to 24 nodes and 32 edges with additional zoning conditions. These ceilings are not targets to fill. A six-component story should not grow to twelve merely because the chosen budget allows it.
When the source exceeds the useful budget, consolidate only with a reason and keep a fidelity ledger. Record which duplicates merged, which groups collapsed and which meaningful details were omitted. Splitting an overview from a detailed view often preserves more information than shrinking every label until the diagram technically fits.
Inspect the first static result
Ask for a static first artifact and check the path from entry to outcome. Are arrows directional and labeled where the relationship is ambiguous? Does the chosen accent identify the important decision? Does the caption explain a limitation? These are reader checks, not consequences guaranteed by supplying a sufficiently long prompt.
The brief below is an editorial example, not a parser configuration accepted by every host. No host package was installed during this review. Once an approved installation is available, use the repository’s host-specific workflow, inspect its output, and keep the source brief beside the artifact so revisions remain explainable.
Implementation steps
- 1
Write one learning question and list verified relationships.
- 2
Choose the destination and reading audience.
- 3
Set a detail budget and document planned cuts.
- 4
Render and check whether the reader can follow the story.
Copy-ready example
{
"editorialBriefExample": {
"question": "How does an order reach storage?",
"format": "html",
"size": "doc-inline",
"detail": "balanced",
"audience": "mixed",
"knownPath": ["Client", "Gateway", "Orders", "Database"]
},
"hostCommandExecuted": false
}Frequently asked questions
Should balanced output always contain twelve nodes?
No. Twelve is the documented ceiling. Use only the components needed to explain the chosen question.
Can I turn a document diagram into a slide by enlarging it?
A slide also needs an appropriate type scale, density and viewing-distance check. Enlarging the image alone does not establish readability.
Sources
- skills/diagram-design/references/output-spec.mdSource checked 2026-09-08
- README.mdSource checked 2026-09-08