← Back

It Shipped: Cynefin Diagrams in Mermaid

posted by admin

May 6, 2026

PR #7535 merged today. Mermaid now has a Cynefin framework diagram type, the first text-based DSL for Cynefin diagrams anywhere.

This post wraps up the series. Eight months, eight posts, two diagram implementations, one merged PR, and a lot of lessons about how open source actually works.

If you’re not familiar with the Cynefin framework, I wrote a full introduction earlier in this series. The short version: it’s a sense-making model that helps you decide how to decide, by categorizing problems into five domains based on the relationship between cause and effect.

I was introduced to Cynefin years ago by Faidon Liambotis, my Director at the Wikimedia Foundation. He used it to map and manage the complexity of the ecosystems we operated in, and he was absolutely right. It changed how I think about problems. So when I found myself contributing diagram types to Mermaid and realized nobody had ever built a text-based DSL for Cynefin, the two threads came together. Complex systems thinking and open source, two of my favorite things.

The Arc

For anyone picking this up cold, here’s where we’ve been:

Identified the gap: Strategic frameworks like Wardley Maps and Cynefin had no text-based diagramming support. You couldn’t put them in a README, version-control them, or diff them in a PR.
Chose the platform: Mermaid.js, with native rendering in GitHub, GitLab, Notion, Obsidian, and dozens of other tools. One contribution, massive reach.
Built Wardley Maps: A complete, tested, modular implementation. 3,700 lines, 90 tests, six-file renderer.
Got scooped: The maintainers merged their own Wardley Map implementation while I was polishing mine. Closed my PR.
Pivoted to Cynefin: Filed the issue first this time. No existing work. No competing implementations. No text-based DSL for Cynefin anywhere in the world.
Landed it: Four rounds of review, 2,379 lines added, merged today.

The Wardley Maps work wasn’t wasted. The architecture knowledge, the Langium fluency, and the understanding of mermaid’s contribution process all transferred directly. The Cynefin implementation took a fraction of the time the Wardley work did, because I’d already paid the learning cost.

What Made It Through Review

The PR went through four review rounds. Each one made the code better. Here’s what changed between submission and merge:

Round 1 caught the fundamentals: missing Langium generated files, no Cypress visual regression tests, no changeset. Admin pieces, but critical. The project’s CI gates on all of them.

Round 2 was where the real engineering feedback landed. Self-loop transitions producing NaN coordinates. Item badge widths estimated heuristically instead of measured. Confusion domain items overflowing the ellipse. Inline styling duplicating the CSS. Six praise items, four important items, three suggestions. Every point was actionable.

Round 3 from Knut himself: useMaxWidth config being ignored, the config key not matching the -beta keyword convention. Small things, but the kind of consistency that matters when your diagram type ships alongside 20 others in a mature project.

Round 4 was the formal sign-off. No new findings. Just confirmation that the prior rounds had been addressed and a note that the PR would merge with the next minor bump.

Total review feedback: 3 blocking items (all resolved in the first follow-up commit), 9 important items, 8 nits, 8 suggestions, 19 praise items. Every blocking and important item was addressed. The code that merged is meaningfully better than what I submitted.

Lessons from the Full Journey

File the issue first. I said this at the end of the Wardley Maps post. I did it this time. Issue #7534 went up before I wrote a line of code. No competing work emerged. The lesson transferred.

The second contribution is faster. Not because the code is easier, but because you’ve already learned the project’s rhythms: how CI works, what reviewers care about, where the generated files live, how changesets get created. The architecture knowledge from the Wardley work applied directly to Cynefin.

Reviews are the feature, not the obstacle. Four rounds of review sounds heavy. It wasn’t. Each round took a day or two to address, and every piece of feedback pointed at a real issue. The NaN self-loop bug would have shipped to production. The heuristic badge widths would have looked wrong with non-ASCII text. The config key inconsistency would have confused users. The reviewers caught things I missed because they’ve seen the patterns across dozens of diagram types.

Novel contributions get more traction. The Wardley Map implementation, however good, was competing with existing work. The Cynefin diagram had no competition because nobody had built a text-based DSL for Cynefin before. When you’re contributing to open source, the greenfield opportunities, the things nobody has done, are where your effort has the most leverage.

Persistence matters more than perfection. The first submission wasn’t perfect. It shipped with hardcoded colors, missing tests, and a debugging HTML file committed to the repo. Four rounds of review later, it was right. The willingness to address feedback thoroughly and quickly is what gets PRs across the line.

Thank You to the Reviewers

Open source contributions don’t land without reviewers, and I was fortunate to have genuinely excellent ones.

Knut Sveidqvist (@knsv), the creator of Mermaid, reviewed the PR personally and approved it. His feedback on config conventions and useMaxWidth handling reflected someone who’s spent years thinking about how diagram types should behave consistently across the project. His direct comment, “The diagrams look great!”, meant a lot coming from the person who started all of this.

Ashish Jain (@ashishjain0512) delivered the most thorough technical review I’ve received on any PR, anywhere. The NaN self-loop analysis, the getBBox recommendation for badge widths, the confusion overflow observation, the inline-vs-CSS styling critique: every item was precise, actionable, and technically correct. The review also included a focused security pass confirming no XSS or injection vectors. That’s the kind of review that makes you a better engineer.

Both reviewers balanced rigor with encouragement. Every review round opened with what was working well before identifying what needed to change. That matters. It’s easy to be thorough; it’s harder to be thorough and kind. They managed both across four rounds and weeks of back-and-forth.

The mermaid project’s review culture (structured, constructive, technically deep) is a model for how open source maintenance should work. It made the code better and made me want to contribute again.

What You Can Do With It

Once this ships in a Mermaid release, you’ll be able to write this in any GitHub README, Notion doc, or Obsidian note:

cynefin-beta
  title Incident Response

  complex
    "Investigate root cause"
    "Run chaos experiment"

  complicated
    "Analyze performance data"

  clear
    "Restart service"
    "Apply known fix"

  chaotic
    "Page on-call immediately"

  confusion
    "Unknown failure mode"

  complex --> complicated : "Pattern identified"
  clear --> chaotic : "Complacency"

Five domains. Wavy organic boundaries. The cliff between Clear and Chaotic. Transition arrows. Full theme support. Accessibility built in.

Once Mermaid ships a release with Cynefin support, this code block will render as a live diagram right here. For now, you can preview it on the deploy preview from the PR.

Strategic thinking, native to where you work.

What’s Next

The -beta suffix means the syntax might evolve based on community feedback. I’m watching for:

How people use transitions. Are self-loops meaningful? Should confusion-to-domain transitions be constrained?
Whether the item overflow patterns work for real-world usage
Community requests for features like annotations, timestamps, or domain metadata

And there are still frameworks with no text-based diagramming at all. The architecture pattern (Langium grammar, parser bridge, database, renderer) is proven and repeatable.

If you use Cynefin in your work and have opinions about the syntax, open an issue. This is how open source gets better.