Stop shipping Mermaid slop: Diagram Design for editorial agent diagrams

I have shipped too many eng-blog diagrams that look like every other eng-blog diagram: pastel rounded boxes, hairline chaos, and a Mermaid default that screams “an agent drew this in twelve seconds.” The content was fine. The visual identity was not. Readers notice when a diagram looks nothing like the site around it — and once you see it, you cannot unsee it.

Diagram Design is the fix I have been looking for — an agent skill that produces editorial HTML+SVG diagrams instead of generic chart soup. Browse the live gallery if you want the short version: self-contained files, no shadows, no Mermaid slop, and no Figma required for routine diagrams.

The highest-quality move is usually deletion.

What it actually ships

Thirty-nine editorial diagram types. Each one is self-contained HTML with inline SVG — open the file in a browser, offline, no build step. That matters for a static site like Autopilot Engineer: I can drop a diagram next to a post, or export a PNG/SVG when I need a still for slides or social. There is no renderer dependency hiding behind a CDN, and nothing that breaks when the post goes offline in a reader app.

For eng-blog work I care about the staples first:

• Architecture — components and connections without the pastel box farm.
• Flowchart — decision logic that still reads at blog width.
• Sequence — messages over time (including the OAuth-style examples in the gallery).
• State — states and transitions that do not look like a whiteboard screenshot.

Beyond that, the skill covers a wide map: loops, Wardley maps, swimlanes, ER, timelines, Sankey, deployment, dependency graphs, and plenty more. I will use the staples constantly and reach for the rest when a post needs a different grammar — not because every article needs a Wardley map. Breadth is useful; defaulting to architecture and sequence is how most AE posts will actually use it.

Density and deletion, not decoration

The design philosophy is the part that sold me. Accent color is reserved for one or two focal elements. Target density sits around 4/10. Every node has to earn its place. That is the opposite of what most model-default diagrams do, which is fill every gap until the figure looks “complete.”

In practice that means I ask for less: collapse leaf clusters, drop the sticky-note noise, keep the request path. The skill’s own import path encodes that with detail dials when you redraw an existing Mermaid or draw.io source — faithful, balanced, or simplified — so you are not stuck with every node from the original file. Format and size are dials too: same source, different deliverable for a doc inline, a 16:9 slide, or a social card.

Brand onboarding in one prompt

Default skin is fine for screenshots. Brand match is better for a real site. You ask the agent to onboard to a site URL. It fetches the page, extracts paper / ink / muted / accent / fonts into a style guide, and runs WCAG contrast checks before writing tokens. After that, new diagrams inherit the brand instead of fighting it.

For Autopilot Engineer that is the difference between “nice diagram” and “looks like it belongs on autopilotengineer.com.” Same skill, same types — different paper and accent. I would rather spend sixty seconds onboarding once than keep pasting brand hex codes into every prompt.

Install (Claude Code and friends)

Claude Code install is two plugin commands:

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

It also works with Codex, Pi, OpenCode (copy or symlink the skill), and other Agent Skills hosts. I am not going to paste every host’s install path here — the repo README covers them. The point is: this is not a Claude-only toy. If your agent runtime can load a skill directory, you can put Diagram Design on the path and ask for an architecture diagram in plain language.

Redraw what you already have

If you already have draw.io or Mermaid sources, you do not start from scratch. Point the skill at the file or fenced block and it redraws the content into the editorial system with format, size, and detail dials. Size presets include things like doc-inline, slide-16x9, and social-og — useful when the same architecture needs a blog figure and an OG card.

Export is first-class: PNG and SVG out of the HTML for slides and social. That is the ContentOS angle for me — blog diagrams that match the site, then stills and social cards from the same source with export sizes instead of a separate Figma session. Routine diagrams stay in HTML; the export path is for the places that still want a raster or a standalone SVG.

Why I’m adding it to the AE toolkit

Autopilot Engineer posts lean technical. Architecture and sequence diagrams show up often. I want those figures to match the brand, stay dense enough to read, and still be something an agent can produce without me babysitting Bezier handles. Diagram Design hits that brief: editorial HTML+SVG, brand onboarding from a URL, import from Mermaid/draw.io, export for ContentOS stills.

The workflow I want is boring on purpose. Draft the post. Ask for the diagram type that fits. Onboard once if the style guide is still default. Export a social size when ContentOS needs a card. Skip Figma unless the figure is genuinely special. That is how agent skills should feel: less ceremony, more output that matches the site.

Next step on my side is onboard to autopilotengineer.com, redraw one existing Mermaid architecture block at balanced detail, and see whether the exported social-og still is good enough to ship without a designer pass. If it is, Mermaid defaults are done for this blog.

Project: github.com/cathrynlavery/diagram-design. Gallery: cathrynlavery.github.io/diagram-design.