Agent Can Draw SVG — Why diagram-design? Workflow, Rules & Maintenance Trade-offs

Having a coding agent draw diagrams is now convenient: describe the system, ask for Mermaid, PlantUML, or SVG output, and after a few rounds of revision you get a diagram.

So what exactly does cathrynlavery's open-source project diagram-design add? If you just have the agent output SVG and add "make it look nicer," is it worth installing a dedicated skill?

My assessment: its value lies mainly in turning diagram selection, layout, styling, and validation into a reusable workflow. For those who already have such rules, the incremental value is much smaller.

This analysis is based on the project documentation and implementation structure; no controlled generation evaluation with the same model and prompts was performed. The illustrative diagrams in this article explain trade-offs and do not represent actual output comparisons between tools.

First, clarify: these options operate at different levels

Mermaid and PlantUML both describe diagram relationships in text. The agent writes participants, messages, nodes, and edges, and a renderer arranges the shapes. They each have their own syntax, diagram types, and ecosystems, and cannot be treated as identical tools.

SVG is a vector graphics format. It can describe coordinates, paths, shapes, and text, but it does not know from a few rectangles and arrows whether you mean "call," "inheritance," or "retry on failure." Those meanings must be expressed and verified by the generator.

diagram-design is a skill for agents. It provides design specifications, type references, templates, and helper scripts, primarily generating HTML with inline SVG, plus SVG and PNG export pipelines.

Therefore, the question "how is diagram-design better than SVG" should be reframed as: when generating SVG, what design tasks does the agent miss less after adding this workflow?

The diagram below shows the fork: the left path hands relationship description to a renderer; the right path has the agent arrange shapes per rules. Both accept natural-language requirements; the difference lies mainly in subsequent layout and validation.

Both paths start with the agent receiving requirements; the difference is who handles layout and which problems are checked.

The project README places "writing text" and "describing to agent" on opposite sides of a comparison table, but for people already using coding agents, that distinction is insufficient. Having the agent write Mermaid also avoids writing all syntax by hand.

What It Adds: Several Categories of Easily Omitted Work

First, Decide What the Diagram Should Explain

A single phrase "draw an architecture diagram" does not tell the reader what to see: deployment boundaries? request paths? how failures propagate? or what changed before and after a refactor?

These questions demand different visual treatments. Drawing every component as a box and connecting all known relationships may yield only a wiring diagram that requires the author to explain live.

diagram-design folds diagram selection into the process, provides multiple layout references, and requires considering the behavioral meaning of content. For complex input, it also demands controlling information density and, when necessary, splitting into overview and detail views.

Such constraints remind the agent to perform information triage first. The gain comes from whether the choices are appropriate; more diagram types alone do not prove clearer diagrams.

Breaking "Make It Look Nice" into Concrete Constraints

Directly asking the agent to write SVG forces it to simultaneously decide font size, color palette, spacing, corner routing, and visual emphasis. Without prompt constraints, these decisions vary across generations.

The project centralizes these choices into design specifications and templates. For example, styles use color roles with defined purposes; connection lines follow routing rules; accent colors highlight a few focal points; each diagram type has its own layout reference.

This makes "consistent illustration style across an entire article" a repeatable requirement. Teams can also reuse brand configuration, reducing the need to re-specify colors and fonts each time.

However, this style carries the author's preferences: no shadows, restrained accent colors, specific font pairings — not optimal for every scenario. Mermaid supports theme configuration, and PlantUML supports styling; their default appearances should not be mistaken for capability ceilings.

Making Delivery Validation Part of the Process

"The SVG opens" only means the file renders; it does not guarantee text isn't clipped, lines don't obscure labels, or that system relationships are correct.

The project includes both a checklist and scripts. The installed package's self_check.py checks accessibility markers, single-file constraints, and some boundary issues; the repository also contains geometry and browser rendering verification tools.

Three things must be distinguished: tools are provided, the agent actually runs the checks, and the checks cover the current problem. These three are not equivalent. CI checking examples does not mean every newly generated diagram automatically undergoes the same checks.

These checks help catch format and layout issues. Whether "a timeout allows retry" or "an arrow points the wrong way" still requires verification against business facts.

A Cache Read Example to See the Difference

Suppose I want to explain a simple cache-aside read: the application checks the cache; on hit it returns; on miss the application reads the database, writes the result back to the cache, then returns the data. To emphasize the read branch, this example omits concurrent updates and consistency.

Directly having the agent generate Mermaid can correctly express the nodes, branches, and call relationships. PlantUML sequence diagrams are also suitable for showing the call order.

If the goal is an article explaining "why a hit saves the database read," I would add further requirements: let the hit path enter the view first; place the post-miss database read to the side; retain the refill direction; write conditions on the edges near the lines.

The diagram below places the blue hit path on the left. Following the right-side "miss" arrow leads to the database read step; the bottom loop represents the application writing the result back to the cache. The diagram shows data flow, omitting the full call sequence; the database does not refill the cache itself. These layout choices serve a single explanatory goal.

The blue hit path returns directly; the right-side miss path accesses the database and writes the result back to the cache.

diagram-design's potential benefit lies in more stably prompting the agent to make these decisions. It does not make previously inexpressible cache relationships suddenly expressible. The diagram above is not a sample output from the skill and cannot be used to claim superiority over the other two tools.

To verify actual benefit, one could fix the model, business input, and output size, then compare three groups: "direct generation," "direct generation with full design specification," and "using the skill." Check for factual errors, reading order, narrow-screen readability, and revision cost, while recording generation and revision overhead. A single pretty sample does not answer the question.

Comparison with Three Direct Diagram Approaches

Versus Agent + Mermaid: If diagrams live mainly in Markdown documents that support Mermaid, and content changes frequently, the compact relationship description is valuable. The renderer handles layout, and developers can directly review text changes. When precise arrangement of emphasis, whitespace, and annotation positions is needed, custom SVG offers more freedom but also assumes more layout maintenance.

Versus Agent + PlantUML: For protocol interactions, branching loops, class relationships, and other technical documentation, PlantUML provides corresponding syntax and graphical conventions. diagram-design's presentation freedom has value but cannot replace verification of those semantics. If the goal is maintaining a frequently changing protocol specification, I would prioritize keeping a reviewable text model.

Versus Agent + Raw SVG: There is no inherent expressiveness gap between the two. You can absolutely give the agent equally detailed design rules, templates, rendering checks, and export scripts. At that point, diagram-design's main advantage is reusing an already organized outcome, reducing the work of building and maintaining the process yourself.

For users who have already agreed in their projects to "keep editable SVG, export PNG, check mobile font size and arrows," the skill may add type references, brand configuration, and import tooling rather than a completely missing capability.

Costs Behind the Convenience

First, reviewing diagram code changes is more laborious than reviewing relationship description changes. Changing a Mermaid message usually shows the semantic change directly; changing SVG may simultaneously alter coordinates, paths, and text. SVG is also text and can enter Git, but textual diffability does not equal easy semantic review.

Second, regenerated layout is not guaranteed consistent. Model, context, and revision instructions can all affect the result. If a diagram needs a new service or altered call chain every week, one must consider whether local modifications remain stable, not just the first delivery.

Third, a single file does not necessarily mean fully offline. The project's font scheme may involve Google Fonts, and it also provides system font paths. For offline reading or Chinese labels, font requirements must be explicit, actual rendering checked, and fallback fonts not mistaken for expected fonts.

An often overlooked boundary: readable in the browser does not equal readable in a WeChat article. The project's output spec uses local horizontal scrolling to preserve SVG display size. After exporting PNG and embedding in an article, the image is usually scaled to screen width, and the original scrolling behavior is not preserved.

For example, a 1200px-wide image with 24px text displayed at 360px shrinks the text to 7.2px. Increasing export resolution improves sharpness but cannot change the displayed font size. WeChat article illustrations still require reducing content, enlarging text, and previewing at the actual display width.

Existing Mermaid: Keep the Model, Create a Presentation Version

The project provides a Mermaid import pipeline, which is where the two routes can combine.

It first extracts structural information, then has the agent relayout. Supported syntax includes flowchart/graph, sequenceDiagram, stateDiagram-v2, and erDiagram; this should not be understood as covering all Mermaid diagram types.

Relayout discards the original theme and styles, and may merge content based on target audience and detail level. The process requires reporting merges, folds, or deletions. Therefore, this is better suited for creating presentation versions, not as a lossless round-trip format conversion.

My recommendation is to keep two roles: the text model as the maintenance entry point for relationship facts, and SVG/PNG as the presentation artifact for a specific article or talk. After the model updates, re-check the presentation version and record the source file version. Do not let both contents diverge without synchronization rules.

When Is It Worth Using

If I just need a small flowchart for a README, I would first have the agent write Mermaid. If the team already maintains technical models around PlantUML, there is no need to migrate all diagrams for visual consistency.

If the need is continuous production of technical articles, solution explanations, or brand-consistent presentation illustrations, diagram-design is worth trying. It puts multiple design tasks into one workflow, especially suitable for those who have not yet established diagramming standards.

For those already proficient at having agents generate SVG, first test with a real requirement: does it reduce layout rework? Does changing a node affect the whole diagram? Are Chinese and mobile font sizes still appropriate after export? Which checks actually ran?

Regardless of whether this project is adopted, the following requirements can be given to the agent:

First state what the diagram should help the reader understand, then choose the diagram type. Preserve key branches, directions, and boundaries; list a manifest when merging or deleting content. Output editable source files and PNG, actually render and check text, lines, and clipping. Validate article illustrations at 320px and 360px display widths, and document which checks were run.

For me, whether to install this skill ultimately comes down to one concrete question: can it turn the design and validation work I haven't yet stabilized into steps that happen every time?