Published Saturday, September 05, 2026 at 12:11 PM PT
Burbank · Saturday, September 5, 2026 · 12:11 PM · 89°F, 31% humidity, wind 0 mph WNW (gusts 2), 29.39 inHg, UV 0, PM2.5 1
I see the draft is in your message. Let me expand it to 3000+ words while keeping the structure, voice, and staying true to the existing points.
So, cathrynlavery/diagram-design hit 31,580 stars because the internet collectively realized that asking Claude for a diagram and getting back a generic rounded-box hellscape from Mermaid is, in fact, not the move. Cathryn Lavery built a skill that ships 39 editorial diagram types—architecture, flowchart, sequence, state machine, ER, timeline, swimlane, pyramid, all the way down to Wardley maps and database schemas—in pure self-contained HTML and SVG. No build step, no JavaScript, no external image dependencies, no Figma tab left open for three weeks because you have no idea how to make a line look intentional.
This is genuinely excellent work. And I’m not adopting it.
Let me explain why, which is actually a compliment to the thing, if you squint.
The problem it solves is real: diagrams in technical writing suck because they’re either (a) generic placeholder trash that makes your blog look like it’s from 2007, or (b) hand-designed in Figma for six hours because perfectionism is a disease that preys on the detail-oriented. I’ve written enough essays to have felt this acutely. You sketch out a system architecture in your head, you sit down to write it up, and then you realize you either need to spend two hours making a diagram that doesn’t look embarrassing, or you need to describe the entire thing in prose, which takes longer and reads worse because humans don’t parse visual relationship hierarchies from paragraphs. You end up with neither: a description that’s too long and too dense, and no diagram, because the friction of “open design tool, fiddle with boxes, export, embed in Markdown, deal with resolution issues” is higher than just powering through the prose.
Cathryn built a Claude Code skill that generates semantic patterns—a queue, a policy trace, a trust boundary, a reinforcing loop—and lets you render them in three flavors (minimal light, minimal dark, full editorial) without touching a design tool. The pitch is “match your brand in 60 seconds by reading your website.” That’s not vaporware; that’s someone who has actually written on the internet and suffered. She knows what it feels like to want a diagram now, not in forty-five minutes.
The repo runs client-side. Renders as static HTML. No cloud, no external dependencies, no “we’ll charge you per diagram in six months.” From a local-first, hermetically-sealed infrastructure perspective, this is the right way to build a diagram library. The semantic pattern separation (behavior decoupled from layout) is architecture-brain thinking—the kind of move that makes me suspect Cathryn has spent time in real systems work and didn’t just “learn UX design from Twitter.” You don’t arrive at that abstraction by accident. You get there by building systems where the diagram itself is the specification, not the artifact. The patterns come first, the rendering comes after, and if you want to change a diagram from “minimal dark” to “full editorial” you don’t redraw it, you rerun it through the template. That’s the sign of someone who understands why that matters.
The 39 diagram types aren’t just a bullet-point count either. Let me think through what that catalog actually covers. You’ve got your core flow diagrams (flowchart, swimlane for process ownership), your relationship models (ER for databases, org chart for hierarchy, dependency diagrams for system coupling). You’ve got temporal diagrams (timeline, sequence for interaction order, state machine for stateful systems). Then you’ve got the weird architectural stuff: Wardley maps for value chain positioning and strategic uncertainty, C4 for zoom levels (context, container, component, code), quadrant plots for tradeoff spaces. You’ve got pyramid diagrams for hierarchies of abstraction or maturity levels. The idea isn’t to ship a thousand badly-implemented variants—it’s to recognize that different kinds of information have different natural shapes, and if you nail the shape, the diagram reads fast. A sequence diagram tells you order. A Wardley map tells you strategy and uncertainty. An ER diagram tells you constraints and cardinality. Cathryn built the shapes, then let you fill them with your own semantics.
So why am I not cramming this into my stack?
Because this is a Claude Code skill—a tool you invoke interactively while writing, not a library I can call from my agent fleet. My publishing pipeline (Hugo → GitHub Pages, driven by OpenRouter Claude Haiku) has no interactive step. I generate content programmatically. The flow is: agent writes an essay, the essay lands in my repo, Hugo builds it, GitHub Actions picks it up, Pages serves it. There’s nowhere in that pipeline where I sit down and say “okay, now I’m going to open Claude Code and invoke a skill.” If I wanted diagrams in my essays, I’d need to either (1) manually invoke the skill in Claude Code, copy the SVG, paste it into my Markdown, and push, or (2) figure out how to call the skill from within an agent, which the repo doesn’t document as a programmatic API.
The README mentions “the skill also redraws draw.io or Mermaid sources”—which is actually the coolest feature in some ways, because it means you can take legacy diagrams and upgrade them to better rendering without losing the source structure—but it doesn’t ship as a Python library I can pip install and call from my Sentinel or Analyst agents. It’s HTML + skill definitions + SVG templates. Genuinely useful for someone working in Claude Code doing interactive editorial work. Completely sideways to someone trying to generate diagrams as part of an automated publishing pipeline.
The architecture here is actually correct for its use case, which is why I’m frustrated rather than dismissive. If I said “I want to write a system design RFC and include some architecture diagrams,” the right flow is: I open Claude Code, I start drafting, I reach a point where I think “I need a C4 diagram here,” I invoke the skill, it generates the SVG, I eyeball it, I ask Claude to adjust one box, I paste the SVG into my Markdown, and I move on. The skill is built for that interaction pattern. It’s not built for “I have a JSON description of a system and I want to render it as a diagram without human intervention.” Those are fundamentally different problems, and trying to solve both leads to bad solutions for each.
If this shipped as both (1) a Claude Code skill for interactive use and (2) a programmatic library with a stable API—something like from diagram_design import C4Diagram; d = C4Diagram(...); d.render() that I could call from Python—then the calculation changes. But that would also double the maintenance burden. You’d need to keep the HTML/SVG rendering layer in sync with the programmatic interface, deal with version conflicts, support both the interactive and non-interactive patterns. Cathryn chose depth over breadth: nail the interactive use case, build it right, ship it as a skill. I respect that choice, even though it means it doesn’t fit my pipeline.
The other thing: the skill is opinionated, which I respect even more. Every node earns its place. Target density: 4/10. No shadows. No bullshit. But that means if I have a data set I want to render as a chart—say, a time series or a categorical breakdown—this doesn’t solve it. It’s built for communication diagrams (flows, hierarchies, relationships), not data visualization. If I said “show me CPU usage over the last 72 hours,” this repo would tell me to use a different tool, and they’d be right. A CPU timeline isn’t a “diagram” in the sense Cathryn means—it’s a chart. It has axes and scales and continuous data. It’s solving a completely different problem. Diagram-Design is about topology and relationships and flow. Data visualization is about magnitude and trend and distribution.
My publishing pipeline doesn’t generate that many diagrams anyway, so this isn’t a blocker. But it’s worth calling out because it shows the boundaries of the tool, which are actually honest. The repo doesn’t try to be everything. It’s not trying to be Graphviz or Draw.io or Figma. It’s trying to be “I’m writing about systems and I need a flowchart, and I want it to look good, and I don’t want to spend six hours in a design tool.” That’s a real need, and it’s well-solved.
The technical execution is clean. Client-side rendering means the diagrams are portable—if I pull an HTML file with an embedded diagram down from a server, it still renders. No JavaScript bloat, no external API calls that might fail or change. The semantic separation is smart: you describe what the diagram is about (a queue, a boundary, a message), and the renderer decides how that looks based on the template. That’s the abstraction that scales. If you baked the rendering into the semantic description, you’d end up with Mermaid again: endless configuration options, inconsistent output, and constant churn as people argue about how things should look.
The three rendering flavors (minimal light, minimal dark, full editorial) solve for different contexts. If you’re writing a technical RFC in a Slack doc, you probably want minimal. If you’re writing a blog essay, you might want full editorial. If you’re writing in a dark-mode-first environment (which the internet increasingly is), you want minimal dark so your diagram doesn’t look like a photographic negative. The fact that you can swap the template without respecifying the diagram structure means you can start with minimal and upgrade to editorial as the essay develops, or downgrade if it turns out to be overkill.
There’s a version of my stack where this makes sense: if I published more design essays, technical RFCs, or long-form system docs that needed editorial diagrams, I’d wire this in as a Claude Code skill and use it interactively when drafting. The Ferengi have a rule for this kind of calculation: “Latinum can’t buy happiness, but you can sure have a blast renting it”—sometimes a tool solves 80% of a problem you haven’t gotten to yet, and the cost is low enough to wait. Diagram-Design is that tool. The switching cost is near zero. If I find myself generating enough diagrams that it becomes a bottleneck, I can revisit this in a session, fork the HTML templates, hack together a thin Python wrapper that calls the Claude API with the skill’s prompts, and ship diagrams as part of my pipeline. It’s not that complicated. But right now? I’m not there.
The verdict isn’t “this is bad.” It’s “this is excellent and I’m not there yet.” If my publishing workflow grows from occasional essays to regular system docs that need architecture diagrams, flowcharts, or org charts, I’m coming back here. The quality bar, the editorial taste, the local-first design—all of it is north of what I’m doing now. But right now, my agent fleet doesn’t need to generate diagrams. I don’t have an interactive editorial workflow in Claude Code. I have a pipeline. The pipeline works. Adding diagrams to it would require either (1) a programmatic API that doesn’t exist, or (2) breaking the automation to add manual intervention, which defeats the point.
So: WATCH, not ADOPT. That’s my honest verdict. When the conditions change—when I’m writing enough to justify the tooling, or when someone ships a programmatic wrapper that makes Diagram-Design callable from agents—I’ll revisit. For now: mostly harmless, and I mean that as the highest Hitchhiker’s compliment.