Mermaid draw: a diagram without design skills

To mermaid draw without becoming a designer first, type a few claims and let a layout engine place the boxes. You don't need a design background, a grid, or an eye for spacing. You need a process you can say out loud, and the patience to draw the unhappy path before you touch a color. Ugly and accurate beats pretty and stale. I have a folder of pretty diagrams I stopped updating because I didn't want to ruin the layout. The ugly ones are the ones that still match the code.

This is a beginner path. One flowchart, built up from two boxes to the decision we were actually arguing about. If you want every shape and every arrow type, the flowchart how-to is that reference. Stay here until you have one chart you'd show a teammate.

You don't need a design eye

The layout engine places nodes. It tries to keep arrows from tying themselves in knots, and it does not care about your slide template. That feels like a loss if you're used to dragging boxes until they align. It's a gain the first time someone else edits the file. They change a label. The boxes move. Nothing is "misaligned," because alignment was never the artifact. The sentences were.

Your job is the sentences. "An order is placed." "We check whether payment captured." "If it didn't, we hold." Each sentence becomes a node or an arrow. If you can't say the sentence, you don't have a node yet. I used to draw empty boxes and plan to name them later. Later never came, and the review was a discussion of rectangles. Name the box with the claim, even if the name is clumsy. Clumsy and specific is reviewable. "Process" is not.

You also don't pick fonts, and you don't kern anything. Default theme. Default shapes. A rectangle for a step, a diamond for a question, an arrow for "then." The cheat sheet is the list of those shapes when you get curious. You can draw the chart in this post without it. Curiosity is how beginners end up styling a three-node graph for an hour. I've done the hour. The chart was still the wrong process, just in a nicer green.

Open a plain text buffer. The first line will be flowchart TD. TD means top to bottom, which matches the way you read a decision. LR is left to right, which matches a pipeline. This walkthrough is a decision, so it's TD. You can switch later by editing two letters. You don't redraw.

Start with two boxes

Forget the whole business. Write the first thing that happens and the next thing that happens if nothing goes wrong. For an order, that's "placed" and "payment captured." I know that's incomplete. Incomplete is the point of the first version. A complete chart on the first try is usually a guess wearing ten boxes.

flowchart TD
  placed[Order placed] --> captured[Payment captured]

Two ids, placed and captured. The words in brackets are the labels. The arrow says the second follows the first. There is no decision yet. If your real process can stop between these two, this chart is already a lie, and that's useful information. Don't paper over it with a note in the label. You'll add the decision in a minute, as its own node, where a reviewer can see it.

Look at the ids. They're short and they aren't the full sentence. When I rename the label to "Order placed by the customer," the id stays placed, and I don't have to edit the arrow. If I had used the sentence as the id, the arrow would change too, and the diff would look bigger than the edit. This is the only "technique" I insist on with beginners. Ids for you, labels for everyone else.

Run it. You should see two boxes and an arrow. If you see a parse error, the usual cause at this stage is a missing bracket or a smart quote copied from a chat app. Replace the quotes with boring ones. If the first line isn't flowchart TD, put it back. A title above the keyword belongs outside the diagram, in the Markdown heading. I put "Checkout" as line one once and spent ten minutes convinced arrows were illegal.

Don't add color. Don't add a subgraph. Don't add a start oval and an end oval "because diagrams have those." placed is the start. You'll have an end when you know what done means. A decorative start node called "Start" is a box that makes no claim. I delete those on sight.

Add the decision you kept explaining in chat

The reason you're drawing this is probably a question you keep retyping. For checkout, mine is whether the payment actually captured. That question is a diamond, not a second rectangle. A rectangle labeled "Check payment" hides the two answers. A diamond forces you to draw both.

Change captured from a step into the question, and give each answer a place to go.

flowchart TD
  placed[Order placed] --> captured{Payment captured?}
  captured -->|Yes| ship[Ship the order]
  captured -->|No| hold[Hold the order]

The diamond id is still captured. The label now asks a question. The edges wear the answers. Yes ships. No holds. I deleted the idea that "payment captured" is a step that always happens. Sometimes it doesn't, and the old two-box chart was the happy path pretending to be the process. That's the most common beginner diagram I see, and I still produce it when I'm tired. The fix is always the same. Find the sentence you say after "it depends," and make that sentence a diamond.

Edge labels stay short. Yes and No are enough when the diamond asked a yes-or-no question. Payment provider returned a captured status and the webhook signature matched is a paragraph. Put the paragraph under the figure. The arrow only needs to tell the two paths apart. Long edge labels collide and make the diamond look broken when the syntax is fine.

Both answers need a node. A Yes arrow with no No arrow is the chart flattering you. If you truly don't know what No does, write hold[Hold the order] anyway, or write hold[We do not know yet]. The second one is embarrassing and effective. I have put "we do not know yet" on a node to force the question into a review. Someone always knows. They just weren't in the room when the happy path got drawn.

Templates can hand you a checkout-shaped chart at this point. I'd wait. A template includes decisions you may not have, and you'll feel obligated to keep them because they're already neat. Two boxes you typed will teach you more than thirty you inherited. When you do open a template later, delete until it matches the process you can defend. Don't defend the template.

Name the unhappy path before you decorate anything

Hold isn't the end of the story. An order on hold either gets a payment later or it doesn't. Shipping isn't the end either, if you can be out of stock. I'm adding one more diamond, on the success side, because "ship it" was another happy path hiding inside the first one. This is still the same flowchart. We're editing it, not starting a second picture.

flowchart TD
  placed[Order placed] --> captured{Payment captured?}
  captured -->|No| hold[Hold the order]
  captured -->|Yes| stock{In stock?}
  stock -->|Yes| ship[Ship the order]
  stock -->|No| back[Backorder]
  hold --> captured

Read the new claims. If payment didn't capture, we hold, and the hold goes back to the payment question. That loop is a claim that we will reconsider when payment shows up. If that's wrong, if a human has to cancel and start over, delete the arrow from hold to captured and send hold somewhere honest, like cancel[Cancel the order]. I drew the loop because our shop actually waits. Yours might not. Don't keep my loop to make your chart look finished.

If payment captured and the item is in stock, we ship. If it isn't, we backorder. Backorder doesn't point at ship. I left it dangling on purpose. A dangling node is a question: what happens next? If the answer is "a later restock ships it," draw that arrow. If the answer is "the warehouse handles it outside this service," the dangling node is the boundary, and the paragraph under the figure should say so. A fake arrow into ship would claim the service ships backorders itself. I added that fake arrow once because a dangling node looked like a mistake. The mistake was the arrow.

The loop is the part that will layout a little awkwardly. The edge from hold back to captured may cross something. Leave it. Routing the arrow by hand isn't available, and adding invisible nodes to shove it aside is how a simple chart becomes a puzzle nobody wants to edit. Awkward and true beats tidy and missing the loop. This is the opinion I'll repeat because I've paid for the other one. I spent an afternoon nudging a chart with spacing hacks so a screenshot looked balanced. The next week the payment provider added a third status, and I didn't want to rebalance, so the chart kept two statuses. The code had three. Pretty had made the update feel expensive. An ugly chart would have taken the third diamond in five minutes.

Don't name a node end. It's a reserved-feeling word and a real closer in other diagram types. If the process is over, name the node ship or cancel or done. done is boring and fine. end is how a file that used to be a flowchart and became a sequence starts failing in a way you won't connect to a label.

Out of stock and unpaid are different unhappy paths. Don't merge them into problem[Handle the problem] to save a box. The merge is the prettiness instinct. The two paths need different humans. A merged box sends both to the same team in the reader's head. If that's actually true, the merge is a real claim and you should make it on purpose, with a label that says who handles it. If it isn't true, keep the split. More boxes are cheaper than a wrong merge.

Ugly and accurate

Accuracy is a test you can run without taste. Pick a real order from last week that went badly. Walk it on the chart. Which node is it in at each step? If you get stuck, the chart is missing a state that happened in production. Add the node. Do this with a success too, so you don't only encode disasters. I walk one of each before I show anyone. It takes ten minutes. It has saved me from presenting a chart that couldn't represent the order in the ticket I pasted below it.

Staleness is the other test. If you're afraid to add a node because the screenshot in the deck will need recropping, the chart is already too precious. Delete the styling. Commit the source. Regenerate the picture when the deck is actually due. A deck that owns the diagram will lose. The diagram should own the deck.

A few specific ways I make charts pretty and wrong:

1. I drop the failure node because the column looked unbalanced. The failure still happens. The reader now thinks it doesn't.
2. I rename a label to something softer. "Reject" becomes "Follow up." The code rejects. The chart has become customer-support copy. Put the soft words in the email template. Put the verb the code uses on the node.
3. I add colors, green for good and red for bad, and then a third case arrives that is neither. The color says it's bad because I had to pick one. A label would have said "manual review." I trust the label.
4. I split one chart into three so each fits a slide. The arrows between them lived only in my head. Reviewers approved each slide. Nobody approved the join. Keep one chart until it genuinely answers two questions, then split by question, not by slide height.
5. I paste a screenshot into the doc and delete the source "so nobody edits the old version." Everyone edits nothing. The next change is a new screenshot beside the old one. Keep the source. The what a diagram is page is the longer argument for why the file, not the picture, is the thing you own.

You will feel an itch to align the backorder node with the ship node. Let it itch. The engine's placement isn't an insult. If a node is hard to find, the label is vague or the chart is doing two jobs. Fix the words or split the chart. Don't fight the coordinates. There aren't any coordinates in the file, which is why the file works in git.

Show the ugly version to someone who knows the process and doesn't care about diagrams. Ask them which arrow is wrong. If they talk about fonts, you asked the wrong person, or the chart has so little content that fonts are the only thing to notice. Add the missing unhappy path until the feedback turns into "that's not how holds work." That sentence is the review. The font conversation is not.

Stop decorating

When the walk-through matches real orders, stop. More shapes will not add truth. A subgraph around "payment" is optional and usually early. Add it when two teams own different nodes and a reader mixes them up. Give the subgraph a short id. Close it with end on its own line if you use one. Don't reach for icons. A cylinder for a database is a claim that a database is involved. If this flowchart is about the order and not the tables, a cylinder is costume.

Notes under the figure are where the numeric threshold goes, the provider's name, the link to the flag. The figure keeps the branch. I write three or four sentences under every chart I intend to keep. Charts with no sentences get misread in the direction of whatever the reader fears. The sentences are the correction. They're also easier to update than a label stuffed with clauses.

If you're blocked on the syntax rather than the process, describe the order in one paragraph and use the AI diagram generator to draft a flowchart. Then apply the same tests. Walk a bad order. Delete the decorative start node it will probably add. Check that every diamond has every answer you can defend, and no answer you can't. Generators love a node called "Process payment" with a single arrow out. That node is the hiding place. Split it or don't ship it.

The prompt-to-diagram route is the same idea from the prompt side. A good prompt includes the failure. "Draw checkout" gets you a straight line. "Draw checkout where payment can fail and stock can be missing, and a failed payment waits and retries the check" gets you something closer to the chart above. You still walk an order through it. The prompt is not the review.

How to make a diagram steps back from flowcharts to the choice of picture. If you notice you're adding actors and messages ("then the warehouse texts us"), you might want a sequence diagram instead of a sixth box. Making a flow chart stays on this type if the boxes are right and you want more examples. Switch kinds when the question changes. Don't switch kinds because the flowchart looks plain. Plain was the goal.

A second flowchart for a different process is a different file or a different fence. Don't keep editing this one into "the company diagram." Checkout doesn't need the org chart on it. I combined them once. It was impressive and useless. Nobody could find the hold.

Put the ugly chart where it will get edited

Paste the final fence into the doc that already describes checkout. Above it, write the sentences the nodes don't hold: what "captured" means for your provider, and what hold does to inventory. Commit that. When the process changes, edit the fence in the same pull request. If the edit makes the layout worse, ship it anyway. You can remove a styling hack. You can't recover a chart nobody wanted to touch.

Open the editor if you want the boxes to update while you type. No signup, live preview, and you can break the diamond and fix it without a save dance. Copy the source back into the repo when a real order walks cleanly from placed to ship or back or hold. Leave the colors alone. The next person who adds a status will thank you, or at least they won't be afraid of the file. That's the whole skill. Not drawing. Being willing to change the drawing when the orders change.