Field notes · 3 min read
A shout-out to diagram-design
Every diagram on this site was drawn by an AI agent using one skill, Cathryn Lavery's diagram-design. What it is, why it works, and how Hangar uses it.
Every diagram on this site was drawn with one tool, and it isn't a drawing tool. It's diagram-design, a skill you add to an AI coding agent like Claude Code. You describe what you want to show, and the agent produces a self-contained HTML page with an SVG diagram in it: no build step, no external images, nothing to install to open it.
Who made it
diagram-design is by Cathryn Lavery, the founder of BestSelf, and it's open source under the MIT licence. You can tell it was made by someone who cares about design, because most of the skill isn't about drawing boxes. It's about restraint.
Why I like it
A lot of AI-made diagrams look like AI-made diagrams: too many boxes, too many colours, arrows everywhere, and a sense that everything mattered equally. diagram-design starts from the opposite end. Its own guide says "the highest-quality move is usually deletion", and it means it.
- One accent, used sparingly. Only one or two things in a diagram get the accent colour, so your eye goes where it should.
- A strict 4-pixel grid. Its author calls this the thing that keeps the diagrams from feeling AI-generated, and I agree.
- Three typefaces with three jobs. Instrument Serif for titles and callouts, Geist for labels, Geist Mono for anything technical. I liked them so much that they became this site's fonts too.
- A self-check. It ships a script that checks a finished diagram's geometry and accessibility, so the agent can catch its own mistakes before I ever see them.
- Brand profiles. You can teach it your colours and fonts once and reuse them everywhere.
- Motion, when it helps. A diagram can play through once to show a sequence, and anyone who prefers reduced motion just gets the finished picture.
How Hangar uses it
Hangar has its own profile for the skill: the amber and sky from the Hangar brand, on a warm paper background, with a dark version of every colour. A small Python generator in the Hangar repo builds every page from that profile, so all 90 diagrams in the gallery share one visual language, and each one works in light and dark.
I added one rule of my own on top: every diagram separates what's built from what's only a proposal. That fits the skill's whole philosophy. A diagram should tell you the truth, and nothing more than you need.
If you write design docs, architecture notes or essays with an AI agent, give it a try. It's the closest I've come to having a designer on the team, and it raised the bar for everything else on this site.
Install it from github.com/cathrynlavery/diagram-design. I have no connection to the project beyond being a happy user.