Diagram Design: evidence-driven visual explanations
Diagram Design explained: a visual system for agent-authored technical diagrams
Understand the difference between a diagram skill, a rendering engine and an editor, and why semantic patterns matter more than another box template.
What you will learn
- A skill package, not a diagramming server
- Separate meaning from arrangement
- Judge the delivered artifact
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
- The package guides an agent; it is not a hosted diagram editor.
- Semantic behavior and visual layout are separate decisions.
- Review the artifact and its source meaning, not just its template name.
A skill package, not a diagramming server
Diagram Design packages instructions, type references, examples and checking scripts for compatible agent hosts. The inspected manifest reports version 2.6.17. It is not a hosted collaboration canvas, a database-backed diagram service or a replacement JavaScript renderer for every diagram language. The authoring agent applies a documented visual system to produce an artifact.
The repository describes 39 visual types and three static variants: light, dark and full editorial. These are layout families, not 117 independent capabilities or a measured quality score. A sequence explains ordered messages; a tree explains ownership; an architecture view explains components. Choosing among them starts with what a reader needs to understand.
Separate meaning from arrangement
Eight semantic patterns describe behaviors such as queues, policy traces and traceable decomposition, then route to an existing visual type. This prevents each new behavior from becoming another loosely defined template. A queue may need an architectural arrangement, but its backlog and producer-consumer relationship still require a meaningful explanation.
The traceable-block pattern illustrates the distinction particularly well: stable IDs, parents and implementation references add meaning to an existing tree layout. Its documentation explicitly avoids claiming formal modeling-standard compliance. A picture with IDs can support navigation and review without proving that its metadata accurately describes the implementation.
Judge the delivered artifact
Static HTML and inline SVG are the default output model. Optional motion has a restricted controller contract rather than arbitrary generated scripts. Font loading is a separate concern: the documentation discusses Google Fonts and brand fonts, so self-contained markup should not be advertised as universal zero-network rendering in every configuration.
Our review pins primary files and runs 16 synthetic cases through the unchanged rectangle checker. It does not install the host package or exercise a complete import/export workflow. The useful adoption question is whether the resulting diagram preserves the system story and stays readable, not whether a repository badge or a checker alone promises editorial quality.
Implementation steps
- 1
State the question the diagram should answer.
- 2
Select a layout appropriate to that relationship.
- 3
Record the source revision and output audience.
- 4
Review the rendered result and explicit verification limits.
Copy-ready example
{
"packageVersion": "2.6.17",
"visualTypesDocumented": 39,
"semanticPatternsDocumented": 8,
"defaultOutput": "static HTML with inline SVG",
"hostPluginInstalledInThisReview": false
}Frequently asked questions
Is Diagram Design a replacement for a collaborative canvas?
The inspected project is an agent skill package and artifact workflow. Collaborative editing, hosting and application state are separate requirements.
Does every pattern add another diagram type?
No. Patterns define behavior and route to existing layouts; a new type requires a genuinely different layout grammar.
Sources
- README.mdSource checked 2026-09-08
- .codex-plugin/plugin.jsonSource checked 2026-09-08
- LICENSESource checked 2026-09-08
- docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.mdSource checked 2026-09-08
- docs/adr/0010-block-registry-metadata-contract.mdSource checked 2026-09-08