Journey diagrams in Mermaid: map user experience flows

Customer journey maps live in whiteboards, Figma files, and PDFs that never get updated. By next quarter, nobody knows if the map reflects reality anymore. But a journey diagram in Mermaid is text, versioned, searchable, and easy to review when it changes.

Mermaid's journey diagram type lets you map a user's experience across stages, track emotional state at each touchpoint, and document the transitions that matter. No special tools — just a diagram in your docs that stays in sync with how your product actually works.

Journey diagram basics

A journey diagram tracks a user through stages (the x-axis) with emotional state (the y-axis) marking how they feel at each step:

journey
    title Onboarding a New Free User
    section Sign up
      Sign up form: 5: User
      Email verification: 4: User
    section Activate
      Create first diagram: 5: User
      Export as PNG: 5: User
    section Explore
      Read templating guide: 3: User
      Discover AI mode: 4: User
    section Upgrade decision
      See pricing page: 2: User
      Start trial: 4: User

The numeric score (1–5) represents emotional state:

• 5 = excited, satisfied
• 4 = happy
• 3 = neutral
• 2 = frustrated
• 1 = angry, lost

Each stage represents a phase of the journey. Within each phase, list the touchpoints where the user interacts with your product or team.

Mapping a customer lifecycle

Here's how a B2B SaaS team maps the full lifecycle from lead to churned customer:

journey
    title Full Lifecycle: Enterprise Customer
    section Awareness
      See case study: 3: Prospect
      Sales call: 4: Prospect
    section Evaluation
      Free trial sign up: 4: Prospect
      Import their data: 3: Prospect
      Create test diagrams: 4: Prospect
    section Purchase
      Contract negotiation: 2: Prospect
      IT security review: 1: Prospect, IT
      Go-live signed: 5: Customer
    section Onboarding
      Admin training: 5: Customer
      Team members invited: 4: Team
      First diagrams shipped: 5: Team
    section Production
      Support request resolved: 5: Customer
      Feature request granted: 5: Customer
      Encounter perf issue: 1: Customer
    section Renewal
      Success review: 4: Customer
      Renewal negotiation: 2: Customer
      Churn risk: 1: Customer

Notice the multiple actors (Prospect, Customer, IT, Team). A journey diagram can track how different people experience your product differently. The IT security review drops emotional state for IT while the prospect sits in an inflection point.

Support and customer success workflows

Support teams use journey diagrams to map ticket resolution, escalation paths, and customer satisfaction:

journey
    title Support Ticket Resolution Path
    section Incoming
      Customer opens ticket: 2: Customer
      Auto-categorized: 3: Customer
    section Triage
      Support agent assigned: 3: Customer, Support
      Initial response sent: 4: Support, Customer
    section Investigation
      Troubleshooting steps: 2: Customer
      Customer provides logs: 3: Support, Customer
    section Resolution
      Root cause found: 4: Support
      Workaround provided: 4: Customer
    section Closure
      Customer confirms fix: 5: Customer
      Ticket closed: 5: Support

When you map actual support workflows this way, pain points become obvious. If customers are consistently frustrated during "Troubleshooting steps," that's a signal to improve your docs or automate diagnostics.

User research and discovery

Product managers use journey maps during user research to document what they've learned about actual user behavior:

journey
    title Small Business Owner: Documenting Their Process
    section Problem
      Team process is undocumented: 1: User
      Knowledge silos: 2: Manager
    section Discovery
      Peer recommendation: 4: User
      Free trial (15 mins): 3: User
    section Adoption attempt
      Share with team: 3: User
      First diagram (took 20 mins): 2: User
      Team feedback negative: 1: Team
    section Iteration
      Read tutorial: 3: User
      Second diagram (took 5 mins): 4: User
    section Success
      Team now uses templates: 5: Team
      Process standardized: 5: Manager
    section Advocacy
      Recommends to peer: 5: User

This captures actual user research: what worked, what didn't, where friction appeared, and what unlocked adoption. When you have interviews from three customers with similar journeys, combine them into one "archetypical journey" that the team can reference.

Error and recovery flows

When things go wrong, how do users recover? Journey diagrams capture the emotional arc:

journey
    title Recovery from Diagram Data Loss
    section Incident
      User loses connection mid-edit: 1: User
      Refreshes page: 1: User
      Diagram appears blank: 1: User
    section Awareness
      Checks browser cache: 2: User
      Contacts support: 2: User, Support
    section Resolution
      Support checks recovery: 3: Support
      Backup version found: 4: Support, User
    section Restoration
      Data restored from backup: 5: User
      User verifies content: 5: User
    section Prevention
      Cloud sync explained: 4: User, Support
      Auto-save enabled: 5: User

This makes it clear where you lose trust and where you rebuild it. The goal is to pull emotional state back up by recovery — if you can't do that, you'll lose customers.

Branching journeys (different paths by cohort)

Complex products have multiple paths through the onboarding. Track them separately:

journey
    title Onboarding by User Type
    section Free User Path
      Sign up: 4: Free
      Create diagram: 5: Free
      Hit diagram limit: 2: Free
      See upgrade prompt: 3: Free
    section Paid User Path
      Sign up + subscribe: 4: Paid
      Create diagram: 5: Paid
      Invite team member: 4: Paid
      Team member collaborates: 5: Paid

When journeys differ significantly by cohort, split them. Compare the emotional arcs side by side. If free users plateau at step 3 but paid users push to step 5, that's insight: the paywall is a transition point that shifts behavior.

Turning insights into action

Journey diagrams are most powerful when you use them to find the drop-off points — the moments when emotional state crashes. Those are your improvement priorities.

Map current state first. Interview users or run analytics to get the real path and emotional state. Don't invent the ideal journey.

Mark pain points explicitly. When you find a step with low emotional state, tag it. That's where you invest in improvement.

Re-map after you change something. If you redesigned the signup flow, run it again with new users. The before/after shows if your fix worked.

Use it in roadmap meetings. "Here's where we're losing users" is a stronger case for roadmap priority than "we should improve the error message."

Link from design and product docs. A journey diagram lives in your product strategy doc, shared across design, engineering, and support. Everyone should know which flow they're working on.

FAQ

How often should we update journey diagrams? After major product changes or when you conduct new user research. At minimum, once a quarter when you revisit strategy. They should stay fresh enough to be useful.

Should all journey diagrams use 1–5 scoring? Not necessarily. Some teams use "satisfied/neutral/frustrated." The scale matters less than consistency within your org.

Can I use a journey diagram to track A/B tests? Yes — map variant A and variant B as separate journeys, then overlay the emotional state from your metrics. A/B tests that don't improve emotional state aren't worth the lift.

What's the difference between a journey diagram and a user story map? A journey diagram tracks emotional state across touchpoints over time. A user story map breaks a workflow into tasks. They're complementary — use both.

Start by mapping your most critical user flow. Interview three customers on that path and ask them to rate their satisfaction at each step. Sketch it as a journey diagram. The emotional arc tells you exactly where to focus next.