draw-diagrams — a diagram skill built for chat | Work

Why

Easy to turn on, hard to get right

Turning on Mermaid in a chat is a prompt line away. Making it good isn’t. Every team that adds it meets the same four walls: it draws for everything, shows broken diagrams, looks generated, and trusts whatever the model writes.
I’d worked through all four shipping diagrams in Strive’s chat. So I wanted anyone to get there too: good-looking, meaningful diagrams from the first wiring, without inheriting my product to get them.

Turning it on

One prompt line
Draws for every answer
Broken source on screen
Mermaid’s default look, light only
Model output trusted as is

Getting it rightthe skill

A tool that decides when
Only when a picture helps
A broken diagram never shows
A considered look, light and dark
Model output treated as untrusted

Rendering a diagram is solved. Knowing when to draw one isn’t.

Research

What’s out there today

Before writing a line, I read 15 public Mermaid skills from source, not from listings. They’re good at what they do, and nearly every one is for docs or images: an agent writing a diagram into a file. The one that touched a chat covered only the renderer.
A chat needs different things. Only three say when not to draw, the few that check a diagram do it while the agent writes, colours are fixed for light mode, and none strips model styling or tests when the model draws. That gap is what this skill fills.

What a chat needs, compared
	draw-diagrams	Most Mermaid skills
Who it’s for	A chat where your model draws for your users	An agent writing diagrams into docs or images
When to draw	A tool that decides when. Numbers go to charts, one diagram per answer	Mostly how to draw. 3 of 15 say when not to
Checking	The real parser on every call, a repair hint, one retry, then prose	A few check, and only while the agent writes
When it breaks	Nothing shows, live or on reload	A broken diagram or raw source can show
Look	Meaning mapped to your theme, in light and dark	Theme presets, or colours fixed for light mode
Model styling	Stripped, so the theme always wins	Kept. Some still recommend a deprecated directive
Accessibility	Measured contrast, a 10px text floor, a name for screen readers	A few mention contrast
Security	Model output is untrusted. HTML and links are stripped	Rarely covered
Proof	An eval of when it draws, and a fresh agent building from it	No test of when it draws

The idea

Built for the chat, not the doc

Teaching a model to write Mermaid is one layer. A chat needs four: a tool whose description decides when to draw, guidance that teaches how, a gate that runs the real parser on every call, and a renderer that draws only what the gate accepted.
When to draw is the product, so it’s the part that gets measured: an eval of six prompts that should draw and four that shouldn’t, run through your real chat, before and after every prompt change.

Decide The tool’s description draw when a picture helps; numbers go to charts
Teach The model’s guidance the right type, a chat-width shape, safe syntax
Check The server gate the real parser, a repair hint, one retry
Draw The renderer accepted diagrams only, themed and named

an eval checks the first step, before and after every change

Most skills are only the second box.

Care · accessibility

Contrast is measured, not assumed. The quiet grey connectors I’d carried over came out at 2.56:1, under the 3:1 a line needs. They’re 4.8:1 now, and a dash, not a paler grey, says “optional”.
Meaning never rides on colour alone: the label says it, the main path is thicker as well as coloured, and muted steps are dashed. Text never drops under 10px, measured per diagram, and every diagram is named for screen readers from its title and caption.

Contrast for the default palette (WCAG ratio)
Pair	Light	Dark	Needs
Labels on steps and washes	14.5–17.7	11.0–16.1	4.5
Muted text: edge labels, headings	4.6–4.8	6.3–6.9	4.5
Connectors	4.6–4.8	3.4–3.7	3
The main path	5.2	7.0	3
Outcome borders on their wash	4.7–5.9	5.1–7.3	3

Care · theming

Meaning, mapped to any theme

The model never picks a colour. It marks what a step means: the main path, the step that matters, a good, at-risk or bad outcome, or something out of scope. The theme decides how that looks, in light and dark.
Colours are named by role, with Tailwind defaults you can swap for your own, even oklch tokens. Along the way it fixes what Mermaid gets wrong on its own: a grey shadow that glows in dark mode, hard-wired journey colours, and arrowheads that ignore the main path.

==>The one main path
:::accentThe step that matters
:::success / warning / dangerGood, at-risk and bad outcomes
:::mutedOut of scope
-.->Optional, or a loop back

The model says what a step means. Your theme decides how it looks.

Care · reuse and safety

Copy it, don’t adopt it

It works with any framework and the main model providers: tool definitions for Anthropic, OpenAI and the Vercel AI SDK, all type-checked, and four code files you copy as they are. The server gate fails open, so an outage never blocks chat.
The source is model output, so it’s treated as untrusted. With Mermaid’s strict mode on, an image tag and a click link still got through, so the renderer strips HTML, links and styling before Mermaid sees them.

Model output A diagram from draw_diagram Untrusted: it may carry HTML, links or styling

A chart type, or over 80 lines?

Sent back with a hint, never drawn

Does it parse once HTML, links and styling are stripped?

Nothing is drawn, live or on reload

clean, parsed, and the server said rendered

In chat Drawn with the theme Named for screen readers from its title and caption

Treat it like any input you didn’t write.

Design calls

The calls, and why

Every default in the skill has its reason written next to it, so you can argue with it instead of guessing.
Many of the calls are about restraint: what to leave out, turn off or wait for, so a diagram only shows up when it’s right.

Calls I made, and why
The call	Why
A skill, not a package	No dependency to keep in sync. You copy what your stack needs and own it.
A generic look, not my design system	Nobody should have to inherit my tokens to get a good diagram. Rules and Tailwind defaults travel.
Framework-neutral	Chats are built on everything. The core is plain code, with notes for React, Vue, Svelte and plain JS.
Draw only after the server’s verdict	Drawing as soon as the arguments arrived flashed diagrams the server then rejected.
Fail open	A validator outage must never block chat. The browser parses again and hides anything broken.
One retry, then prose	A second failure rarely fixes itself, and the user is waiting.
Class, requirement, git and C4 off by default	They parse, but haven’t passed the light and dark check. Turning one on is one line.
A caption that’s a string, not null	It stays valid under every provider’s strict tool mode.

Proof

Tested before trusted

Every rule was rendered on Mermaid 12.2, in light, dark and at phone width, before it was written down. Pitfalls other skills still repeat were checked too: one no longer applies, and one (a---ops) silently draws the wrong thing.
Then a fresh agent built a chat from the skill alone, with a stubbed model. Round one found a blocker: the retry never ran. Round two resolved 12 of 15 issues and surfaced six more, all fixed.

Read Only the skill no context from the build, no edits allowed
Build A React chat a stubbed model that streams tool calls
Log FRICTION.md file, line and severity for every gap
Fix The skill, not the app then the same agent builds again

two rounds: 15 issues, then 6 new ones

A reread can’t find what a stranger trips on.

Misses & lessons

What I’d tell day-zero me

MissPlanned to ship my product’s theme as code.

LessonShare the rules, not the tokens. A DESIGN.md and Tailwind defaults travel. My design system doesn’t.
MissSet a fixed shrink floor, 75% and then 80%. Labels still dropped under 10px on a phone.

LessonMeasure, don’t assume. The renderer now reads the smallest text in each diagram.
MissTrusted Mermaid’s strict mode with model output.

LessonTest with a hostile input. An image tag and a link got through, so the renderer strips them first.
MissCalled the docs done once they read well.

LessonHand them to a stranger. A fresh agent found a blocker in its first build.