Creating User Journey Maps with Mermaid.js

What Are User Journey Maps?

User journey maps are visual representations of the steps a user takes to accomplish a goal with your product or service. They document the user's experience at each step, including their satisfaction level, pain points, and emotional response.

Journey maps are essential tools for:

• UX research — Understanding current user experience
• Product design — Identifying improvement opportunities
• Stakeholder communication — Making user pain points visible
• Onboarding optimization — Smoothing the new user experience
• Service design — Mapping end-to-end customer journeys

Mermaid.js provides a journey diagram type that lets you create these maps as code — quick to write, easy to update, and version-controllable.

Basic Syntax

journey
    title My Working Day
    section Morning
        Wake up: 3: Me
        Commute to work: 1: Me
        Arrive at office: 5: Me
    section Afternoon
        Lunch meeting: 3: Me, PM
        Code review: 4: Me, Dev
    section Evening
        Leave office: 5: Me
        Dinner: 5: Me, Family

Key Elements

• title — The journey map's title
• section — Groups steps into phases (shown as labeled sections)
• Steps — Format: Task name: score: actors
• Score — Satisfaction rating from 1 (worst) to 5 (best)
• Actors — Who's involved in this step (comma-separated)

Scoring Guide

The score (1-5) represents the user's experience at each step:

• 5 — Delighted, exceeded expectations, wow moment
• 4 — Satisfied, smooth experience, no issues
• 3 — Neutral, acceptable but unremarkable
• 2 — Frustrated, encountering friction or confusion
• 1 — Very unhappy, major pain point, might abandon

Mermaid visualizes these scores with color coding — higher scores appear in green tones, lower scores in red/orange tones. This makes pain points immediately visible.

Practical Example: E-Commerce Purchase Journey

journey
    title Online Shopping Experience
    section Discovery
        Google search for product: 3: Customer
        Land on product page: 4: Customer
        Browse similar items: 4: Customer
        Read reviews: 5: Customer
    section Decision
        Compare prices: 3: Customer
        Check shipping options: 2: Customer
        Calculate total with tax: 2: Customer
    section Purchase
        Add to cart: 5: Customer
        Create account: 1: Customer
        Enter payment details: 3: Customer
        Confirm order: 4: Customer
    section Post-Purchase
        Receive confirmation email: 5: Customer
        Track shipment: 4: Customer
        Receive package: 5: Customer
        Unbox product: 5: Customer

Insights from This Journey

Looking at the scores, we can immediately identify:

• Pain points: Account creation (1), shipping options (2), tax calculation (2)
• Delight moments: Reviews (5), add to cart (5), confirmation email (5), unboxing (5)
• Improvement opportunities: Simplify account creation (guest checkout), be transparent about total costs earlier

Practical Example: SaaS Onboarding Journey

journey
    title New User Onboarding
    section Sign Up
        Visit landing page: 4: User
        Click Sign Up: 5: User
        Fill registration form: 3: User
        Verify email: 2: User
        Complete profile: 2: User
    section First Use
        See empty dashboard: 1: User
        Find tutorial: 3: User
        Create first project: 4: User, App
        Import data: 2: User, App
        See first results: 5: User
    section Activation
        Invite team member: 3: User
        Set up integration: 2: User, Admin
        Configure settings: 3: User, Admin
        Complete onboarding: 4: User
    section Retention
        Daily usage: 4: User
        Discover advanced feature: 5: User
        Hit usage limit: 1: User
        Upgrade decision: 3: User

Analysis

- The empty dashboard (score: 1) is a critical moment — new users who see nothing are likely to churn.

• Email verification (score: 2) creates friction before the user sees any value.
• Hitting usage limits (score: 1) is a conversion moment but needs careful handling to avoid frustration.

Practical Example: Developer API Integration

journey
    title API Integration Journey
    section Research
        Find API documentation: 3: Developer
        Read getting started guide: 4: Developer
        Review API reference: 3: Developer
        Check pricing/limits: 4: Developer
    section Setup
        Create developer account: 3: Developer
        Generate API key: 5: Developer
        Install SDK: 4: Developer
        Configure environment: 3: Developer
    section Integration
        Make first API call: 5: Developer
        Handle authentication: 3: Developer
        Implement error handling: 2: Developer
        Parse response data: 4: Developer
    section Production
        Test under load: 3: Developer, DevOps
        Deploy to production: 4: Developer, DevOps
        Monitor performance: 3: Developer, DevOps
        Handle rate limits: 2: Developer

Multiple Actors

Journey maps can track multiple actors to show different perspectives:

journey
    title Restaurant Dining Experience
    section Arrival
        Find restaurant: 3: Customer
        Welcome guests: 5: Customer, Host
        Show to table: 4: Customer, Host
    section Ordering
        Browse menu: 4: Customer
        Take order: 4: Customer, Waiter
        Send to kitchen: 3: Waiter, Chef
    section Dining
        Prepare food: 3: Chef
        Serve food: 5: Customer, Waiter
        Enjoy meal: 5: Customer
        Check on table: 4: Customer, Waiter
    section Payment
        Request bill: 3: Customer, Waiter
        Process payment: 3: Customer, Waiter
        Leave tip: 4: Customer
        Say goodbye: 5: Customer, Host

This multi-actor view helps identify where interactions between roles create friction or delight.

Using Journey Maps in UX Research

Step 1: Gather Data

Before creating a journey map, collect data through:

- User interviews and surveys

- Analytics data (funnel analysis, drop-off rates)

- Customer support tickets and common complaints

- Session recordings (Hotjar, FullStory, etc.)

- NPS and satisfaction surveys

Step 2: Map the Current State

Create a journey map reflecting the actual user experience:

journey
    title Current Checkout Experience
    section Cart Review
        View cart: 4: User
        Update quantities: 3: User
        Apply coupon: 1: User
    section Shipping
        Enter address: 3: User
        Choose shipping: 2: User
        See delivery estimate: 4: User
    section Payment
        Enter card details: 3: User
        See order summary: 4: User
        Click purchase: 5: User
    section Confirmation
        See confirmation: 5: User
        Get email receipt: 5: User

Step 3: Identify Opportunities

Look for steps with scores of 1-2 — these are your improvement opportunities:

- Coupon application (1): Make the UI more intuitive

- Shipping options (2): Simplify choices, show costs upfront

Step 4: Map the Desired State

Create a target journey map showing the ideal experience:

journey
    title Improved Checkout Experience
    section Cart Review
        View cart: 5: User
        Update quantities: 5: User
        Apply coupon (auto-suggest): 4: User
    section Shipping
        Auto-fill address: 5: User
        Smart shipping recommendation: 4: User
        Real-time delivery estimate: 5: User
    section Payment
        Saved payment method: 5: User
        Clear order summary: 5: User
        One-click purchase: 5: User
    section Confirmation
        Instant confirmation: 5: User
        Rich email receipt: 5: User

Compare the current vs. desired maps to build your product roadmap.

Journey Maps in Documentation

Add journey maps to your product documentation:

In README Files

## User Experience

journey

title Getting Started with OurTool

section Setup

Install CLI: 5: Developer

Run init command: 5: Developer

Configure project: 4: Developer

section First Use

Create first item: 5: Developer

See preview: 5: Developer

Deploy: 4: Developer

In Design Documents

Include journey maps in your product design docs to:

- Show the current user experience

- Highlight pain points that justify the proposed changes

- Illustrate the expected improved journey

In Sprint Retrospectives

Map the team's development experience:

journey
    title Sprint 14 Developer Experience
    section Planning
        Sprint planning meeting: 3: Team
        Ticket breakdown: 4: Team
        Estimation: 2: Team
    section Development
        Pick up tickets: 5: Dev
        Local development: 4: Dev
        Code review turnaround: 2: Dev
    section Deployment
        CI pipeline: 3: Dev, DevOps
        Staging deploy: 4: Dev, DevOps
        Production deploy: 5: Dev, DevOps

Tips for Effective Journey Maps

1. Base scores on data, not assumptions. Use analytics, surveys, and user feedback to assign scores.

1. Keep it focused. Map one journey (one user goal) per diagram. Don't try to map every possible path.

1. Use sections meaningfully. Sections should represent distinct phases of the journey, not arbitrary groupings.

1. Include all relevant actors. If a support agent is involved in a step, include them — it reveals handoff points.

1. Update regularly. Journey maps should evolve as you ship improvements. Update scores when you fix pain points.

1. Pair with metrics. Link journey map steps to actual metrics: "Cart Review (score: 4) — 85% proceed to next step."

1. Keep scores honest. A journey map full of 5s isn't useful. The whole point is to reveal where the experience needs improvement.

1. Share widely. Journey maps are communication tools. Share them with engineering, design, product, and leadership.

Limitations of Mermaid Journey Maps

• No custom icons or images — Steps are text-only
• Linear flow only — You can't show branching paths or loops
• Limited styling — Colors are determined by scores, not customizable
• No annotations — You can't add detailed notes to individual steps
• Simple scoring — Only integer scores 1-5 are supported

For more sophisticated journey mapping with detailed annotations, emotional curves, and branching paths, consider dedicated UX tools like Figma, Miro, or Smaply. Mermaid journey maps excel at quick, version-controlled documentation that lives alongside your code.

Conclusion

Mermaid journey maps bring user experience visualization into your development workflow. They're quick to create, easy to update, and version-controllable — making them perfect for documenting user journeys in README files, design documents, and sprint retrospectives. Start by mapping your most important user journey, identify the low-scoring steps, and use that data to drive product improvements.

Create journey maps in our free Mermaid Live Editor →