Skip to content
MermaidViewer

Planning diagram

Mermaid user journey

Mermaid user journey syntax for sections, tasks and scores, with a customer journey you can edit online.

By MermaidViewer editorsPublished Updated

Basic user journey example

Basic user journey example diagram
mermaid
journey
    title Signing up for a SaaS tool
    section Discover
      Find site via search: 4: Visitor
      Read pricing page: 3: Visitor
    section Sign up
      Create account: 3: Visitor
      Verify email: 2: Visitor
    section First use
      Complete onboarding: 4: User
      Create first diagram: 5: User
      Invite teammate: 3: User, Teammate
Open in the live editor

User journey diagrams show the steps a person takes to achieve a goal and how they feel at each step. Every task gets a score from 1 to 5 and a list of actors, so pain points stand out immediately.

Product managers and UX designers use them to align teams on where the experience breaks down and which improvements matter most.

When to use a user journey

  • Customer journey and onboarding analysis
  • UX research synthesis
  • Service blueprints
  • Prioritising product improvements

User Journey syntax reference

SyntaxWhat it does
journeyStart a user journey.
title TextJourney title.
section NameA stage of the journey.
Task: 5: Actor1, Actor2Task with score (1–5) and actors.

User Journey examples

Online grocery order

Low scores highlight friction in delivery.

Online grocery order diagram
mermaid
journey
    title Weekly grocery order
    section Shop
      Browse offers: 4: Customer
      Add items: 4: Customer
    section Checkout
      Choose delivery slot: 2: Customer
      Pay: 4: Customer
    section Delivery
      Wait for driver: 2: Customer, Driver
      Receive groceries: 5: Customer
Open in the live editor

Feelings along a task list are the point. A mermaid user journey scores each step from 1 to 5 for a named person, grouped into sections that act like chapters. It's not a flowchart of your backend, and it's not a persona poster. The useful part is the drop in the score, because that's the step you should fix.

Sections, scores, and actors

journey opens the diagram and title names the experience. section is a chapter, such as a day or a stage. Each task is one line: Create workspace: 4: New hire. The order is the task, then the score, then the actor. The colons are the separators.

The score runs from 1 to 5. Five is the best face and one is the worst. Teams that use one as "top priority" invert the chart and then argue about a picture that's working as designed. Write the scale in the caption if your readers don't know it.

The actor is a role, not a full name. "New hire" can repeat on every line. A second actor, separated by a comma, shares the task when two people really do it together. If every task lists three actors, the diagram is a RACI matrix and the faces get lost.

Sections are how a reader finds the bad day. A journey with one section is a flat list. A journey with a section per task is all headings. Group the steps that happen in the same sitting.

Worked example

A new hire's first week starts fine and gets worse when they try to ship.

Mermaid diagram
mermaid
journey
    title First week
    section Day 1
      Create workspace: 4: New hire
      Invite team: 3: New hire
    section Day 3
      Ship a change: 2: New hire
Open in the live editor

Day 1 is a 4 and then a 3. The workspace is easy, the invite is a bit clumsy, and nothing is on fire. Day 3 drops to 2. That drop is the sentence the diagram exists to say. A roadmap would have hidden it under "onboarding." The score makes the friction obvious without a paragraph.

The actor is the same on every line because this journey is one person's. If a manager had to approve the change, you would add : New hire, Manager only on that task, and only if the manager's experience is in scope. Otherwise you have changed the subject.

Don't use the score as a priority rank. A 2 means the step felt bad, not that it's scheduled second. If you need a backlog order, use a kanban board. If you need the systems behind "Ship a change," use a sequence diagram and link it from the doc.

When this is the wrong diagram

A flowchart is the better picture of the internal steps, with decisions and retries, and no feelings. A sequence diagram is the better picture when the pain is a specific call between services. Use a user journey when you can name the person and say how the step felt.

Common mistakes

  1. Swapping the fields, as in Create workspace: New hire: 4. The middle field is the score and the last field is the actor. The line reads Task: 5: Me.
  2. Treating 1 as the best score. In this diagram 5 is the happy end of the scale and 1 is the unhappy end.
  3. Leaving the actor off, so the task is only a label and a number. The person is part of the sentence.
  4. One section for the whole journey, which hides the chapter where the score falls. Split at the change of scene.

Where to go next

The AI user journey generator will score a story if you describe the rough patches. Adjust the numbers in the editor, and the cheat sheet has the task line. The customer journey template applies the same scale to a purchase, if a first week is the wrong story.

Scores are opinions, say whose

A journey score is a feeling you are willing to attribute to a person, not a KPI. Write the actor on the section (Customer, Support) and keep the score in the range Mermaid expects, usually 1 to 5. A 5 on "Waited on hold" needs a sentence under the chart explaining why, or a reader will assume the diagram is sarcastic and ignore the rest.

One actor per section keeps the line readable. If sales and the customer both act in the same step, that is two tasks, not one task with a slash in the name. The AI journey generator will draft tasks from a story. You still pick the scores.

Actors and use cases are not a journey score. The method is the use case diagram generator post, and a blog, a shop, and a support tool are the use case diagram examples.

Tips and best practices

  • Use real research data for scores where possible; it keeps discussions grounded.
  • Name sections after the user's goals, not your internal systems.
  • List multiple actors when a step depends on someone else (support, driver, teammate).

Generate a user journey with AI

Not sure where to start? Describe what you need and the AI user journey generator writes the Mermaid code for you. Try prompts like:

  • “Patient booking a doctor's appointment online”
  • “First-time user setting up a smart home device”
  • “Traveller checking in for a flight”

User Journey templates

User Journey FAQ

What do the numbers in a Mermaid journey mean?

Each task has a score from 1 (very negative) to 5 (very positive) that represents the user's satisfaction at that step. Mermaid colors the task accordingly.

Can multiple people be involved in one step?

Yes. List several actors after the score separated by commas.