Building MermaidCreator: A Diagram Editor That Thinks in Three Modes

The Friction Nobody Talks About

Every engineer has lived this loop. You open a pull request, add a Mermaid diagram to the README, push, and then stare at GitHub waiting to see whether it rendered. Sometimes it does. Sometimes you get a silent failure, a blank box, or a cryptic parse error on line 14 of a flowchart you can no longer read in your head. So you edit, commit, refresh, and check again.

Mermaid is a genuinely great format. It is text-first, version-controllable, and renders natively in GitHub, GitLab, Notion, and most documentation platforms. That is exactly why it won. But the authoring experience around it has always been split between two camps that never talked to each other.

On one side you have visual tools like Lucidchart and Figma. They feel great to draw in, but they trap your work in proprietary binary formats that do not live in your repo and do not diff in a pull request. On the other side you have raw Mermaid syntax in a text editor, which is portable and clean but unforgiving the moment your diagram grows past a handful of nodes.

MermaidCreator exists to collapse that split. It treats visual editing, code editing, and AI generation as three views of the same diagram rather than three different products.

One Diagram, Three Ways In

The core design decision was that no mode is the "real" one. The diagram is the source of truth, and every mode is a window onto it. Change something in one view and the others update instantly.

Visual mode is an infinite canvas where you drag, drop, and connect nodes. Every interaction writes clean Mermaid underneath. This is the entry point for people who think spatially and do not want to memorize arrow syntax just to sketch a flow.

Code mode is direct Mermaid syntax with a live preview rendered side by side. This is home for developers who already know the language and want the precision and speed of typing. No mouse gymnastics, no fighting auto-layout.

AI mode is where natural language becomes a diagram. Describe a system in plain English and it generates the structure. Paste a broken diagram and it repairs the syntax. Hand it an existing flow and ask it to restructure or extend it.

The hard part was not building any one of these. It was making the round-trip lossless. When AI generates a diagram, you should be able to nudge a node in visual mode, then drop into code to fine-tune a label, and never lose work or fight the tool. Getting that synchronization right, so that three editing surfaces stay in agreement over a single underlying model, was the central engineering problem of the project.

Why I Reached for Claude

The AI mode is powered by Claude, and that was a deliberate choice rather than a default. Diagram generation is a deceptively structured task. The model is not writing prose. It is producing valid Mermaid syntax that has to parse on the first try, respect the grammar of whichever diagram type the user wants, and reflect the actual relationships described in the prompt.

Two behaviors mattered most. The first is generation: turning "a user signs up, we send a verification email, they confirm, and then they land on the dashboard" into a correct flowchart. The second, and the one that surprised me with how much people lean on it, is repair: taking a diagram that fails to render and fixing the syntax without changing the intent.

That repair use case is a quiet superpower. It turns the most frustrating moment in the entire Mermaid workflow, the silent render failure, into a one-click fix. Claude is strong at exactly this kind of constrained, format-aware transformation, where the answer has to be syntactically perfect and semantically faithful at the same time.

The Export Problem Is Harder Than It Looks

If I had to name the part of the build that consumed the most time relative to how simple it sounds, it would be export. Users want PNG for slides, SVG for crisp documentation, and PDF for sharing. On paper this is "render the diagram and save the file." In practice it is a thicket of edge cases.

Mermaid renders to SVG in the browser, but that SVG references fonts, styles, and sometimes HTML labels that do not survive a naive serialization. Convert to PNG and you have to rasterize at the right resolution without blurring text. Generate a PDF and you have to think about page sizing and embedding. Each format has its own failure mode, and most of them only show up on real diagrams, not the toy examples you test with first.

The lesson here is one I keep relearning on side projects: the feature that looks like a footnote on the roadmap is often the one that decides whether people trust the tool. An export that quietly drops a label or ships a blurry PNG undermines everything upstream of it, no matter how good the editor felt.

Text-First Was the Whole Point

It would have been easy, somewhere along the way, to start storing diagrams in a richer proprietary format to make the visual editor's life easier. I deliberately did not. The entire value proposition rests on diagrams staying portable, versionable, and text-first.

That means what you build in MermaidCreator is never locked in. You can copy the Mermaid out and paste it into a GitHub README, embed it in your docs, drop it into a Notion page, or share it as a live link. The tool is a better place to author the format, not a walled garden that holds the format hostage. In a world of opaque binary diagram files, betting on plain text is the most user-respecting decision in the product.

Lowering the Barrier to the First Diagram

One product principle shaped a lot of the small decisions: reduce the distance between landing on the page and having a diagram you like. You do not need an account to start exploring. The free tier includes a handful of AI generations and cloud storage so your work is not lost. Premium exists for people who lean on it heavily.

This matters because diagram tools have a brutal funnel. Most people arrive with a specific diagram in mind and a low tolerance for setup. If they hit a signup wall before they have produced anything, they leave. Letting the tool prove itself before asking for anything is not generosity, it is just respecting how people actually evaluate software.

What I Would Tell Another Builder

A few decisions held up well enough that I would make them again:

• Pick the source of truth first. Making the Mermaid text the single model, with every mode as a view onto it, prevented a whole class of sync bugs that would have been miserable to untangle later.
• Treat AI as a feature, not the product. Claude-powered generation and repair are genuinely useful, but they sit on top of a solid editor. The AI is the fastest way in, not the only way.
• Budget real time for the boring infrastructure. Export, rendering edge cases, and format fidelity deserve more respect than they usually get on a side-project roadmap.
• Do not betray the format. Staying text-first cost some convenience in the editor and bought enormous trust. That was the right trade every time.

MermaidCreator started as a fix for a small, specific annoyance: the edit-commit-check loop of getting a diagram to render. It grew into a broader argument that you should not have to choose between drawing and coding, and that AI can sit comfortably alongside both rather than replacing either.

If you make diagrams and have ever rage-quit a broken flowchart, give it a try. I would genuinely like to hear which of the three modes you reach for first.