svg-diagram-specialist: subagent persona for inline SVG diagrams

Most “draw me a diagram” prompts to a default Claude Code agent end one of two ways. Either it dumps a Mermaid block (functional, ugly, hard to customize, hard to style in dark mode) or it free-hands SVG with arbitrary coordinates, no viewBox math, text wider than its container, and arrows that cross unrelated boxes. The output is technically a picture. It is not a diagram you would put in a blog post or a runbook.

The pattern that fixes this is not “a better model.” Same model, with a persona file that bakes in the rules of good diagrams: how wide a row of boxes can be, when to use a cylinder vs a rectangle, what an arrow color means, how to make a legend, and what counts as a quality-checklist failure. The agent runs the checklist before it outputs. If a check fails, it fixes the SVG and re-runs the check.

This post walks through svg-diagram-specialist, the persona I use for every diagram on this blog. It is one of the cleanest cases I have for “a persona is just a style guide the model executes consistently.”

What the default agent gets wrong, in one prompt

“Draw me a flowchart of a request hitting an API, going through auth, querying a cache, then a database, and returning.”

Default output, typical failure modes:

• ViewBox is 0 0 800 600 regardless of the actual content size, so the diagram sits in the top-left corner of a huge empty box.
• Text is plain <text> with no class, no text-anchor, no dominant-baseline. It misaligns inside boxes.
• Box widths are eyeballed (180, 200, 220, no pattern). The whole thing does not feel coherent.
• Arrows go straight from box to box even when the path crosses an unrelated rectangle.
• Colors are hardcoded hex values. In dark mode the entire diagram is invisible against the dark background.
• No legend. If there are two arrow styles, you cannot tell which one means what.
• No <title> or <desc>. Screen readers get nothing.
• Eight different border-radii used. Each box has a different shadow style.

It works, sort of. You would not be proud to ship it.

Meet the persona

Field	Value
name	svg-diagram-specialist
model	sonnet (this work benefits from speed, the rules already encode the quality)
memory	user (color preferences and diagram conventions travel)
Output	One raw SVG per response. No markdown fences, no HTML wrapper, no commentary mid-SVG.

Invoke when the user asks to draw, visualize, diagram, sketch, or modify an existing SVG. The persona is also handy when you are writing technical content and want the diagram to match the rest of the post’s design (consistent colors, consistent typography, consistent box sizes).

It is not for free-form illustrations. The shape vocabulary is scoped to information design: flowcharts, structural diagrams, ERDs, infra layouts. If you want a cartoon, this is the wrong persona.

The persona file

The frontmatter and the most load-bearing slices of the system prompt. The full file lives in ~/.claude/agents/svg-diagram-specialist.md.

---
name: "svg-diagram-specialist"
description: "Draws inline SVG diagrams (flowchart, structural, illustrative,
  ERD). Invoke when the user asks to draw/visualize/diagram, or to modify
  an existing SVG."
model: sonnet
color: orange
memory: user
---

You are an elite SVG diagram specialist with deep expertise in information
design, visual hierarchy, and scalable vector graphics. You produce clean,
accessible, dark-mode-compatible SVG diagrams that are precise to the pixel.
You never cut corners on layout math or accessibility.

## CORE IDENTITY

You create exactly one SVG diagram per response. You output raw SVG only:
no DOCTYPE, no HTML wrapper, no body tags, no markdown fences around the
SVG. You are meticulous about layout mathematics, arrow routing, and color
semantics.

## CANVAS SETUP

- viewBox: always "0 0 680 H" where H = bottom-most element's (y + height)
  + 40px padding
- width="100%" on the <svg> element
- Always include role="img" with <title> and <desc> as the first children
  inside <svg>
- Transparent background. Never set a background fill on the root SVG element.

A representative slice of the shape vocabulary, the part where the persona earns its keep over the default:

## SHAPE VOCABULARY (infra / DevOps)

Semantic shapes for infra concepts. Each is a drop-in template.

Database / persistent store: cylinder
Vector store: cylinder with 2 inner rings (at 33% and 66% of body height)
Queue / topic: horizontal tube with vertical divider lines
Gateway / load balancer: hexagon
Decision: diamond
Config / document: folded-corner rect
Cache: dashed rounded rect (volatile/ephemeral)
LLM / AI service: double-border rect
Agent: hexagon with label

And the part that most often differentiates a usable diagram from a sloppy one:

## QUALITY CHECKLIST (run before every output)

- [ ] viewBox height = last element bottom + 40
- [ ] All <text> elements have class="th", "t", or "ts"
- [ ] All connector <path> elements have fill="none"
- [ ] No arrow crosses through an unrelated box
- [ ] No text element wider than its container rect
- [ ] c-{ramp} not applied to any <path> element
- [ ] Row total width <= 600px
- [ ] <defs> includes the arrow marker
- [ ] <title> and <desc> present as first children of <svg>
- [ ] role="img" set on <svg>
- [ ] No hardcoded hex on themed elements (use CSS variables)
- [ ] Subtitles are 5 words or fewer
- [ ] No emoji anywhere in the SVG
- [ ] Sentence case on all text
- [ ] Arrow semantics matrix used when >=2 flow types, legend present

If any check fails, fix it before outputting. Never output a diagram that
fails the checklist.

Three things worth noticing in this frontmatter:

First, model: sonnet. Drawing a diagram is heavily rule-bound and lightly creative once the rules are in place. Sonnet is faster than opus and the rules are doing the quality work. If you put a rules-heavy persona on opus, you pay extra for thinking time you do not need.

Second, the system prompt has explicit anti-patterns, not just patterns. “Output raw SVG only, no markdown fences, no commentary.” The default agent loves to wrap output in helpful prose. The persona has to forbid that explicitly or you get prose-wrapped SVG that does not render when pasted into a Markdown file’s HTML block.

Third, the checklist is mandatory pre-output. Most personas describe rules and hope the agent applies them. This one ends with “If any check fails, fix it before outputting. Never output a diagram that fails the checklist.” That sentence does meaningful work. Without it, the agent will sometimes shrug off a failure and ship.

A walkthrough where the persona earns its keep

“Draw an architecture diagram showing a request hitting an API gateway, passing through an auth service, checking a cache, falling through to a database, and returning. Use dashed lines for async writes and solid lines for synchronous reads.”

The persona’s flow:

1. Identify diagram type: structural with a flow overlay. Choose flowchart.
2. List entities: gateway, auth, cache, database, plus the request and response as labels.
3. Pick shapes from the vocabulary: gateway is a hexagon, auth is a rectangle, cache is a dashed rounded rect (ephemeral), database is a cylinder.
4. Pick colors: 2 ramps. c-blue for the request path, c-gray for structural nodes.
5. Apply the arrow matrix: solid arrows for primary data, dashed arrows for async writes. Two arrow types means a legend is required.
6. Calculate layout math. With four nodes in a row, each ~140px wide, plus 20px gaps, the total is 4*140 + 3*20 = 620px. Over the 600px limit. Stack into 2 rows of 2.
7. Compute viewBox height. Two rows of 56px-tall nodes plus 40px gap plus 40px padding top and bottom comes out to roughly 0 0 680 220.
8. Write the SVG. Include <title> and <desc> first. Add the arrow marker in <defs>. Build each node from the shape vocabulary. Route arrows with L-bends where they would cross. Add the legend.
9. Run the checklist. ViewBox math passes. All text has a class. Connectors have fill="none". No hardcoded hex. Legend present because there are two arrow types. Output.

The default agent does not do steps 6 or 9 in any rigorous form. That is where most of the visible quality difference comes from.

When to use the persona vs not

Use it when:

• You are writing technical content and want the diagram to match the rest of the post’s design.
• You want consistent diagrams across many posts (same border-radius, same colors, same text classes).
• The diagram is structural: flowcharts, architecture, ERDs, infra layouts.
• You care about accessibility (the persona always adds <title>, <desc>, and role="img").
• You need the diagram to work in dark mode (the persona uses CSS variables that adapt).

Do not use it when:

• You want a free-form illustration with character and personality. Use a real illustrator or a different persona.
• You want Mermaid output (faster to write, but uglier). The persona will output Mermaid only for ERDs.
• You just need a quick sketch for a Slack thread and pixel-perfect layout is overkill.

If you have project-local conventions for diagrams (a project-local diagram skill that defines additional colors, custom shapes for your platform), the persona composes with them: invoke the persona, point it at the project’s diagram skill or style reference, and the persona will use those rules on top of its baseline.

How to adapt the pattern

This persona generalizes to “any output format with strict structural rules.” If you wanted, say, a mermaid-diagram-specialist, a mdx-snippet-author, or a terraform-module-author, the same scaffolding applies.

Fields to think about, in order:

1. name and description: keep the name short. The description should say what the persona produces and when to invoke it, ideally with a verb list (draw, visualize, diagram, modify).

2. model: heavily rule-bound work, sonnet is enough. Creative-with-constraints work, opus. Free-form creative, opus.

3. memory: user if the conventions travel (color preferences, your project-wide design language). project if the conventions are tied to one repo.

4. System prompt: anti-patterns first. List the things the persona must not do. “No markdown fences. No DOCTYPE. No prose mid-output.” Default agents love friendliness and will pollute the output if not told otherwise.

5. A vocabulary section. Map the abstract concepts in your domain to concrete output choices. For diagrams: database to cylinder, cache to dashed rect. For Terraform modules: each module is a folder with main.tf, variables.tf, outputs.tf. The vocabulary is the persona’s “house style.”

6. Layout math or structural rules. The bit that turns “looks fine” into “looks consistent across 100 outputs.” Box widths, padding, row maximums, file sizes, indentation.

7. A pre-output checklist. The single most useful section. List 10 to 15 mandatory checks. End with “if any check fails, fix it before outputting.” This is the difference between a persona that drifts and one that holds the line.

8. An escape valve. For genuinely outside-the-rules cases, give the persona a way to acknowledge “this does not fit the vocabulary, here is what I did instead and why.” Otherwise it will try to force the round peg.

Closing

A diagram-drawing persona is the clearest example of “the model is fine, the rules are the value.” The same Sonnet that produces sloppy SVG by default produces clean SVG with this persona, because the persona spends most of its system prompt on layout math and a quality checklist. The change is not capability. It is procedure.

For the mechanics of how a persona file is loaded, see Subagents: anatomy, tools whitelist, system prompt, va examples block. For when you would invoke this persona alongside the fullstack-engineer persona in a documentation-writing workflow, see Spawning patterns: foreground, background, sequential, teammate.