To turn a Mermaid journey into a story map, paste it into a new CardBoard board. Each
section becomes an activity across the top. Each task under it becomes a card in the row
below, in its own column, so the activity spans its steps the way a backbone should. The
journey’s title names the board, and each task’s score and actors stay on its card.
Mermaid draws a journey as a mood curve: steps along the bottom, a face for how each one felt. That’s a fine picture for a slide. It isn’t something a team can plan from, because a picture can’t hold priority or scope. A story map can, and a journey already has the part of a story map that’s hardest to get right: the order a person moves through the thing you’re building.
The journey your AI already wrote
Ask Claude or ChatGPT for one. A prompt that works:
Write a Mermaid user journey for an employee submitting an expense report, from taking a photo of the receipt to getting paid. Group the steps into sections. Score each step 1 to 5 for how it feels today, and name who does it.
What comes back looks like this:
journey title Submit an expense report section Capture Snap the receipt: 4: Employee App reads the amount: 2: Employee Fix the wrong total: 1: Employee section Submit Pick a cost center: 2: Employee Attach to a trip: 3: Employee Send for approval: 4: Employee section Approve Get the approval request: 3: Manager Check against policy: 2: Manager, Finance Approve or send back: 4: Manager section Get paid See the payout date: 3: Employee Money arrives: 5: EmployeeRead it before you paste it. The model will get some steps wrong for your product, and it’s faster to fix a line of text than a card. See how to make diagrams with AI for getting a draft worth keeping.
Paste it into a board
In CardBoard, create a board and pick Paste Mermaid. Paste the journey, fences and all, and create the board. The expense journey above becomes this:
| Mermaid | On the map |
|---|---|
title Submit an expense report | The board’s name |
section Capture | An activity card in the top row |
Snap the receipt: 4: Employee | A card in the row beneath, with “Score 4 · Employee” in its description |
| The order of sections and tasks | The order of columns, left to right |
Four sections and eleven tasks give you four activities over eleven columns. Nothing is dropped. A score of 1 and a list of three actors land on the card as text, where anyone can read them and nobody has to guess what a smiley face meant.
The import works over MCP too. An agent connected to CardBoard can send the same journey to
create_map and get the board back without anyone opening the paste box. See
CardBoard for agents.
The scores tell you where to slice
This is the part the picture can’t do. The journey scored every step for how it feels today, and the low scores are a list of where the product hurts. In the expense journey, “Fix the wrong total” scored 1. “App reads the amount,” “Pick a cost center,” and “Check against policy” scored 2.
On a map, a release is a line drawn across every column. Draw the first one so it holds the fixes for those four cards and the bare minimum everywhere else, and you have a first release that changes how the whole journey feels, not one polished step in a journey that still hurts. The story mapping guide covers slicing in full.
Then fill in what the journey left out:
- Add stories under the painful steps. “Fix the wrong total” is one card now. Beneath it go the options: let the user edit the amount, show the receipt next to the number, flag low confidence reads. Stack them by priority.
- Write acceptance criteria on each card. The card has a field for them. “The amount is editable before submit” is testable. “Reading works better” isn’t.
- Hand an agent the first slice. Over MCP, an agent can read only the cards above the first line and propose criteria and splits as ghosts you accept or reject.
What the import doesn’t do
It doesn’t draw release slices. Where the first line goes is your call, and the scores are evidence for it, not the answer.
It gives every task its own column. A journey’s tasks are the steps of the backbone, so they spread left to right. Stories you add later stack beneath them.
It doesn’t write the map back to Mermaid. Once the journey is a map, the map is the copy you keep. If your team keeps diagrams in the repo, keep the journey there as the record of how it started.
Mermaid import is in beta. Flowcharts, mindmaps, and sequence diagrams import too, as process maps, mind maps, and step-by-step process maps. The full list is in the diagrams guide.
Frequently asked questions
Can I turn a Mermaid user journey into a story map?
Yes. Paste a Mermaid journey into a new CardBoard board. Sections become activities across
the top, tasks become cards beneath them in journey order, and the title names the board.
What happens to the scores and actors?
Each task’s score and actors are written into its card’s description, for example “Score 2 · Manager, Finance”. They aren’t turned into colors or a curve. They’re there to read when you decide what goes in the first release.
Does the import create release slices?
No. The map arrives with its backbone and one card per task. You draw the slices, usually starting with the lowest-scored steps.
Can an AI agent do this without the paste box?
Yes. CardBoard’s MCP server accepts Mermaid when an agent creates a map, so Claude can write a journey and turn it into a board in one step. After that, the agent proposes changes to the board and you accept or reject each one.
Can I export the map back to Mermaid?
Not today. The map is the working copy once you’ve imported it.
What does it cost?
Mapping is free for three boards, with no card, and guests never pay.
Written by Josh Colter, who owns and builds CardBoard, the story mapping tool featured in Jeff Patton’s User Story Mapping.