#Diagrams as code with Mermaid and Claude

Like many engineers, I have two reflexes when I run into a complex problem:

1. Draw it as a diagram to get a clearer view
2. Write it as code rather than drawing it in Miro or Google Slides

The nice thing about diagrams written as code is that they’re easy to save and to version in Git.

If you know Markdown (a language for formatting structured text), there’s an increasingly popular equivalent for diagrams: Mermaid. We use it a lot at work to map out how technical components interact.

The trouble with Mermaid is that expressing complex logic, or polishing the layout, quickly gets tedious.

Luckily, AI can now take the grind out of that part. Claude’s Artifacts, for example, can generate and render Mermaid diagrams from a brief written in natural language.

Here’s an example below, tackling one of the great challenges of everyday life: keeping track of your kids’ homework.

flowchart TD
    Start([Time for Homework!]) --> Setup[Create Quiet Study Space]
    Setup --> Ready{Is Child Focused?}

    Ready -- No --> Break[Take Short Break]
    Break --> Setup

    Ready -- Yes --> Understand{Does Child Understand Task?}

    Understand -- No --> Help[Explain Instructions]
    Help --> Understand

    Understand -- Yes --> Work[Child Works on Task]

    Work --> Check{How's it Going?}
    Check -- Needs Help --> Guide[Give Hints & Support]
    Guide --> Work

    Check -- Done --> Review[Check Work Together]
    Review -- Needs Fixing --> Guide
    Review -- All Good! --> Done([Homework Complete!])

    style Start fill:#4CAF50,stroke:#333,stroke-width:2px
    style Done fill:#2196F3,stroke:#333,stroke-width:2px
    style Guide fill:#FFA726,stroke:#333,stroke-width:2px