Mermaid User Journey Diagram Tutorial: Map Experience and Satisfaction
Mermaid's journey diagram maps a process from the user's point of view, scoring each step by satisfaction so the low points that need fixing stand out.
A user journey diagram answers a question a flowchart cannot: not just what the steps are, but how they feel to the person going through them. By scoring each step with a satisfaction rating, it surfaces the emotional low points - the moment the signup form asks for too much, the confusing confirmation screen - which are exactly the places worth fixing. Mermaid's "journey" diagram makes this lightweight enough to sketch in a meeting, because the whole thing is a few lines of text.
This tutorial covers the journey syntax and how to use the satisfaction scores to actually drive decisions, with examples for the Mermaid editor at /diagram-tools/mermaid-editor. The rendered journey is editable in Atlas Diagram Studio at /diagrams, ready to share with a product or CX team. If you want to start from a narrative description of a customer's experience, the AI diagram generator at /diagram-tools/ai-diagram-generator can turn it into a first journey you refine with the real scores from research.
The journey syntax
A journey diagram opens with the keyword "journey", usually followed by a "title" naming the experience, such as "Sign up for the service." The body is organized into sections, each declared with the "section" keyword and a name like "Discovery" or "Onboarding." Sections group related steps into the phases of the journey, giving the diagram a structure that mirrors how people actually think about a multi-stage experience.
Within each section, every task is a single line with three parts separated by colons: the task name, a satisfaction score from 1 to 5, and a comma-separated list of the actors involved. A line like "Complete profile: 3: User, Support" means the "Complete profile" step scored a middling 3 and involved both the user and support. The score drives the vertical position of the point on the rendered curve, so the diagram literally rises and falls with satisfaction across the journey.
Scores, actors, and reading the curve
The scoring and actor conventions are simple but carry the whole meaning of the diagram. The bullets below lay them out.
- Begin with "journey" and a "title" describing the overall experience.
- Group steps with "section Onboarding", and every task until the next section belongs to it.
- Write a task as "Task name: score: Actor1, Actor2".
- Use a satisfaction score from 1 (frustrating) to 5 (delightful); it sets the point's height on the curve.
- List every actor involved in a step so you can see who is present at the low points.
- Multiple actors on a step are drawn as separate colored markers, making handoffs visible.
- Keep task names as verb phrases - "Verify email," "Choose plan" - so the journey reads as actions.
Turning the diagram into decisions
The reason to build a journey diagram is to act on it, and the satisfaction curve is the guide. The dips are your priorities: a step scored 1 or 2 is a spot where you are losing goodwill or users, and it usually deserves attention before you polish a step that already scores well. Looking at which actors appear at the low points is equally revealing - if support is present at every dip, that is a signal the product is offloading friction onto a human safety net rather than fixing the underlying experience.
Honesty about the scores is what separates a useful journey from a self-congratulatory one. It is tempting to score your own product generously, but the diagram is only valuable if the low points are real, which is why the scores should come from user research, session recordings, or support tickets rather than from the team's optimism. A journey built from actual evidence becomes a shared, undeniable picture of where the experience hurts, which is far more persuasive in a prioritization discussion than an opinion.
Journey versus flowchart
A journey diagram and a flowchart describe overlapping territory but answer different questions. A flowchart from /diagram-tools/flowchart-maker shows the logic - the branches, the decisions, the exact paths a user can take. A journey diagram shows the experience - the sequence of steps and how satisfying each one is, without the conditional detail. They complement each other: use the flowchart to design the mechanics of a flow and the journey to evaluate how that flow feels and where to invest.
Because the journey is quick to write, it is easy to keep as a living artifact that you re-score after each round of improvements, watching the dips lift over time. Draft and edit it in the Mermaid editor at /diagram-tools/mermaid-editor, style it for stakeholders in Atlas Diagram Studio at /diagrams. For the wider family of experience and process diagrams you can write as text, the complete Mermaid guide at /guides/mermaid-js-complete-guide is the reference.