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
      Task: Visit sign-up page: 5: User
      Task: Enter email and password: 4: User
      Task: Verify email link: 3: User
    section Onboarding
      Task: Choose a plan: 4: User
      Task: Enter payment info: 2: User
      Task: See confirmation: 5: User
    section Daily Use
      Task: Log in next day: 5: User
      Task: 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
      Task: Find the API docs: 3: Developer
      Task: Read authentication guide: 3: Developer
      Task: Copy example curl request: 4: Developer
    section Implementation
      Task: Set up SDK in project: 4: Developer
      Task: Handle webhook signing: 2: Developer
      Task: Test with sandbox credentials: 4: Developer
      Task: Debug first failed charge: 1: Developer
    section Deployment
      Task: Switch to live keys: 2: Developer
      Task: Monitor first transaction: 4: Developer
      Task: 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
      Task: Visit help center: 4: Customer
      Task: Find refund policy: 2: Customer
      Task: Locate contact form: 1: Customer
    section Support
      Task: Submit refund request: 2: Customer
      Task: Wait for response: 1: Customer
      Task: Receive approval: 4: Customer
    section Completion
      Task: 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
      Task: Browse products: 5: Customer
      Task: Add to cart and check out: 4: Customer
      Task: Confirm payment: 4: Customer
      Task: See order confirmation: 5: Customer
    section Fulfillment
      Task: Process order: 5: Warehouse
      Task: Pick items: 4: Warehouse
      Task: Pack and label: 4: Warehouse
      Task: Hand to carrier: 4: Carrier
    section Delivery
      Task: Sort and transport: 3: Carrier
      Task: Attempt delivery: 4: Carrier
      Task: 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
      Task: Find refund policy: 1: Customer
      Task: Email support: 1: Customer
      Task: Wait 5–7 days: 1: Customer
      Task: Receive decision: 2: Customer
    section With Self-Service Refunds
      Task: Click 'Request Refund': 5: Customer
      Task: Select reason: 4: Customer
      Task: Instant approval (if within window): 5: Customer
      Task: 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.