MermanDraw
Open Editor

Mermaid guide

Mermaid User Journey Diagram: Sections, Tasks, and Satisfaction Scores

The user journey diagram maps a workflow as a sequence of tasks, each with a satisfaction score from 1 to 5 and the actor who performs it. Mermaid renders it as a timeline with coloured faces, which makes it a quick way to show where an experience drags.

It is deliberately simple: no branching, no timing, no dependencies. If you need those, a flowchart or Gantt chart is the better tool. Use the journey diagram when the point is the emotional curve of a flow, not its logic.

  • UX walkthroughs
  • onboarding analysis
  • service blueprints
  • design reviews

Example

Mermaid User Journey exampleUser
Discovery
DiscoveryUser
Find MermanDraw
Find MermanDrawUser
Visit landing page
Visit landing page
Creating
CreatingUser
Open editor
Open editorUser
Paste Mermaid code
Paste Mermaid codeUser
See live preview
See live previewUser
Adjust theme
Adjust themeUser
Tweak layout
Tweak layout
Sharing
SharingUser
Click Share
Click ShareUser
Copy link
Copy linkUser
Send to team
Send to teamUser creates a diagram
journey
    title User creates a diagram
    section Discovery
      Find MermanDraw: 3: User
      Visit landing page: 4: User
    section Creating
      Open editor: 5: User
      Paste Mermaid code: 4: User
      See live preview: 5: User
      Adjust theme: 4: User
      Tweak layout: 3: User
    section Sharing
      Click Share: 5: User
      Copy link: 5: User
      Send to team: 5: User
Open in editor → Cheatsheet →

Syntax

Structure

journey
    title Checkout flow
    section Browse
      Search catalogue: 4: Customer
      Compare products: 3: Customer
    section Buy
      Enter payment: 2: Customer
      Confirm order: 5: Customer, System
Structure — Mermaid journeyCustomerSystem
Browse
BrowseCustomer
Search catalogue
Search catalogueCustomer
Compare products
Compare products
Buy
BuyCustomer
Enter payment
Enter paymentCustomerSystem
Confirm order
Confirm orderCheckout flow

Each task line is Task name: score: Actor1, Actor2. Scores are integers 1 (worst) to 5 (best). Sections group tasks into labelled columns.

Try this snippet →

Multiple actors

journey
    title Support ticket
    section Report
      Open ticket: 3: User
      Triage: 4: Agent
    section Resolve
      Fix and reply: 5: Agent, Engineer
      Confirm fixed: 4: User
Multiple actors — Mermaid journeyAgentEngineerUser
Report
ReportUser
Open ticket
Open ticketAgent
Triage
Triage
Resolve
ResolveAgentEngineer
Fix and reply
Fix and replyUser
Confirm fixed
Confirm fixedSupport ticket

Each actor gets a colour in the legend; a task with several actors shows all of them.

Try this snippet →

Common mistakes

These are the parse errors that come up most, including in code written by ChatGPT and Claude. Paste any failing diagram into the editor and it marks the offending line.

  • A score outside 1 to 5, or a decimal score.

    Fix: Round to an integer in range. Mermaid does not validate, but out-of-range scores draw outside the chart.

  • A task line without an actor: Search: 4.

    Fix: Add at least one actor after the second colon. The legend is built from actors, so a missing one leaves a blank.

  • Colons inside the task name (Step 1: search: 4: User).

    Fix: The parser splits on colons, so avoid them in task text. Use a dash or parentheses instead.

Real-world examples

Complete, copy-ready user journeys for common situations. Each one opens in the editor with a click.

Browse all examples →

FAQ

Can I draw branches in a user journey?

No. The journey diagram is strictly linear. Describe each path as its own section, or use a flowchart when the branching itself matters.

Where does the journey diagram fit in a design document?

Right after the problem statement, as a before picture. Follow it with the proposed flow (often a flowchart) and, if you have metrics, an XY chart of the measured improvement.