User journey maps with Mermaid: visualize customer flows

User journey maps are a cornerstone of product thinking — they show what a user does, thinks, and feels at each step. But most journey maps live in Figma or a spreadsheet, disconnected from the code and architecture that builds them. Mermaid's journey diagram brings customer flows into version control, making it easy for product, design, and engineering to stay aligned.

Why visualize user journeys?

A journey map answers questions that a feature list can't:

• Where do users get stuck? (friction points)
• What emotions or pain points exist at each touchpoint?
• Which moments are most critical to the experience?
• How do systems talk to each other to make the user's job easy?

A well-placed user journey in a README or design doc prevents the "we built this feature but nobody uses it" moment. It forces clarity before you ship.

Journey diagram syntax

A journey diagram has three parts: the title, sections (stages of the user's journey), and tasks (the things the user does at each stage, with emotional signals).

journey
    title "User journey: Signing up for a subscription"
    section Authentication
      Visit sign-up page: 5: User
      Enter email and password: 4: User
      Verify email link: 3: User
    section Onboarding
      Choose a plan: 4: User
      Enter payment info: 2: User
      See confirmation: 5: User
    section Daily Use
      Log in next day: 5: User
      Create first diagram: 5: User

Each task has a score (1–5, where 5 is happy/excited and 1 is frustrated) and an actor. The score visualizes the emotional arc — where the experience excels and where it drags.

A real-world example: API integration

Here's a developer's journey when integrating a payment API:

journey
    title "Developer journey: Integrating the payment API"
    section Discovery
      Find the API docs: 3: Developer
      Read authentication guide: 3: Developer
      Copy example curl request: 4: Developer
    section Implementation
      Set up SDK in project: 4: Developer
      Handle webhook signing: 2: Developer
      Test with sandbox credentials: 4: Developer
      Debug first failed charge: 1: Developer
    section Deployment
      Switch to live keys: 2: Developer
      Monitor first transaction: 4: Developer
      Handle refunds: 3: Developer

The low scores at "webhook signing" and "debug failed charge" are opportunities: better docs, clearer error messages, or a test harness that catches the issue earlier.

Mapping emotions and pain points

The score is your most powerful tool. A journey where scores drop sharply reveals friction:

journey
    title "Customer journey: Getting a refund"
    section Initiation
      Visit help center: 4: Customer
      Find refund policy: 2: Customer
      Locate contact form: 1: Customer
    section Support
      Submit refund request: 2: Customer
      Wait for response: 1: Customer
      Receive approval: 4: Customer
    section Completion
      Money hits bank account: 5: Customer

The dip at "wait for response" signals a process problem (lack of status updates?). The dip at "find refund policy" signals a UX problem (policy buried in docs). These become actionable insights.

Multi-actor journeys

Complex systems have multiple actors. Show how they interact:

journey
    title "Shipping a package: multi-actor journey"
    section Order
      Browse products: 5: Customer
      Add to cart and check out: 4: Customer
      Confirm payment: 4: Customer
      See order confirmation: 5: Customer
    section Fulfillment
      Process order: 5: Warehouse
      Pick items: 4: Warehouse
      Pack and label: 4: Warehouse
      Hand to carrier: 4: Carrier
    section Delivery
      Sort and transport: 3: Carrier
      Attempt delivery: 4: Carrier
      Deliver successfully: 5: Customer

Each actor sees a different part of the journey. Showing them together surfaces dependencies: the carrier can't deliver until the warehouse ships, and the warehouse can't ship until payment clears. These cause real delays and support tickets.

Journey maps for feature planning

Use journey maps to evaluate new features. Should you add a feature? Check if it improves the journey:

journey
    title "Current vs. proposed: Asking for a refund"
    section Current Process
      Find refund policy: 1: Customer
      Email support: 1: Customer
      Wait 5–7 days: 1: Customer
      Receive decision: 2: Customer
    section With Self-Service Refunds
      Click 'Request Refund': 5: Customer
      Select reason: 4: Customer
      Instant approval (if within window): 5: Customer
      Money back in 2 days: 5: Customer

The visual difference in score patterns justifies the engineering work to build self-service refunds.

Keeping journey maps alive

The most common failure: journey maps that get created, reviewed once, then ignored. Two practices prevent that:

Put the journey in the README of the relevant service. When a new engineer checks out the repo, they see the customer journey before they see the code. That context matters.

Update it when you learn something new. After a user research sprint, adjust the scores. After a feature launch, add a new section. A journey map that's written in plain text lives in the same PR as your code changes.

Journey maps vs. swimlane diagrams

These are complementary. A swimlane diagram (Mermaid sequenceDiagram or flowchart with subgraphs) shows what systems call what. A journey map shows what the user experiences. A product team often needs both:

• Journey map: Shows user pain points and emotional highs/lows (product strategy)
• Swimlane diagram: Shows who calls which API and in what order (engineering implementation)

A journey in the product spec, a swimlane in the design doc, and both get linked from the README.

Journey diagram tips

Keep sections short. 3–5 tasks per section read better than 15.

Use consistent actor names. "Customer," "Backend," "Warehouse," not "User," "System," "Fulfillment Ops."

Score honestly. A 4 for "customer got an error message" is a 4; don't inflate it to 5 just because the error was helpful. Real pain points emerge from honest scoring.

Link to the action. Does the journey map reveal that customers get stuck at "choose a plan"? Link to the analytics that proves it, or to the feature you're building to fix it.

FAQ

Q: Can I show parallel paths, like two ways to sign up? A: Journey diagrams show a single path. If you have two distinct user flows (e.g., web signup vs. mobile), create two separate journey maps and link them.

Q: Should every task have a different score? A: No. Consistent happiness at 4–5 shows a polished flow; consistent dips show systematic problems. The pattern matters more than variation.

Q: Where do I put journey maps in my repo? A: In a docs/journeys/ folder, or directly in the README if there's only one or two. Link them from the product spec, design doc, and service README.

Map your next feature's user journey in the MermaidCreator editor — seeing the emotional arc change as you refine the flow makes the design clearer instantly.