# User journeys

> Page: https://docs.plotwork.dev/user-journeys. Index of every page: https://docs.plotwork.dev/llms.txt

A journey diagram shows the steps a person takes, how satisfied they are at each one, and who is involved. It draws a track of stages with a smooth satisfaction curve across the tasks, a face for each score, a card for each task, and a legend of the actors. It is for product, support, and design teams who want to show where an experience goes wrong, and for anyone who has a Mermaid `journey` to move over.

## TL;DR

| Question | Answer |
|---|---|
| What is it for? | Showing an experience from the person's side: each task has a score from 1 (frustrated) to 5 (delighted), so the dips and the peaks are visible at a glance. |
| What does a task need? | A name and a `score=` from 1 to 5. The actors and a second line are optional. |
| How do I start one? | The first line is `journey "Title"`. Add `marks=dots`, `legend=off`, or `desc="Summary"` to the header if you need them. |
| How is a score shown? | Three ways at once, so color is never the only sign: the height of the mark on the curve, a face (or a number), and the number on the task card. |
| How big may it be? | Up to 100 tasks, 25 stages, 24 actors, and 8 actors in one task. A journey over that is refused with error `E140`. A warning starts at 16 tasks. |
| Which Mermaid type converts? | `journey`. See [From Mermaid](#from-mermaid). |

## Ask your agent

```text
Use Plotwork to draw the journey of a shopper who buys a product online. Stages: Browse, Pay, Deliver. Tasks: find a product, compare prices, enter card details, confirm with the bank, get a receipt, track the parcel, receive it. Score each from 1 to 5 for how the shopper feels, and name who is involved in each task.
```

```text
Use Plotwork to draw the onboarding of a new team as a journey with numbers on the curve instead of faces. Stages: Sign up, Set up, Adopt. Mark the hard steps with low scores.
```

## Example

**Diagram source**

```diagram
journey "Checkout experience" desc="How a shopper feels from finding a product to holding the parcel, and who is involved at each step."

actor "Customer" tone=blue
actor "Support agent" tone=violet
actor "Bank"
actor "Courier"

section "Browse" {
  task "Find a product" score=5 actors="Customer"
  task "Compare prices" score=3 actors="Customer, Support agent" sub="Asks about delivery"
}

section "Pay" {
  task "Enter card details" score=2 actors="Customer"
  task "Confirm with the bank" score=1 actors="Customer, Bank"
  task "Get a receipt" score=4 actors="Customer"
}

section "Deliver" {
  task "Track the parcel" score=4 actors="Customer, Courier"
  task "Receive it" score=5 actors="Customer, Courier"
}
```

*Picture: Checkout experience: 7 tasks in 3 stages, average satisfaction 3.4 of 5. How a shopper feels from finding a product to holding the parcel, and who is involved at each step.*

**Text description**

**Satisfaction runs from 1 (frustrated) to 5 (delighted).**

- Browse: 2 tasks, average 4.0
  1. Find a product: 5 of 5 (delighted), with Customer
  2. Compare prices: 3 of 5 (neutral), with Customer and Support agent. Asks about delivery
- Pay: 3 tasks, average 2.3
  3. Enter card details: 2 of 5 (unhappy), with Customer
  4. Confirm with the bank: 1 of 5 (frustrated), with Customer and Bank
  5. Get a receipt: 4 of 5 (happy), with Customer
- Deliver: 2 tasks, average 4.5
  6. Track the parcel: 4 of 5 (happy), with Customer and Courier
  7. Receive it: 5 of 5 (delighted), with Customer and Courier

**Actors: Customer, Support agent, Bank, and Courier.**

**Lowest: "Confirm with the bank" at 1. Highest: "Find a product" and "Receive it" at 5.**

## The language

One statement per line. Names and text are in double quotes, options are `key=value`, and a `#` starts a comment.

| Statement | Meaning | Example |
|---|---|---|
| `journey "Title" desc="..." marks=faces\|dots legend=on\|off` | The header, always the first line. `marks=faces` (the default) draws a face on the curve, and `marks=dots` draws the score as a number in a dot. `legend=off` hides the legend. | `journey "Checkout experience" marks=faces` |
| `desc "text"` | One or two sentences for the text description. It is the same as `desc=` on the header. | `desc "A shopper finds a product and pays."` |
| `actor "Name" tone=<tone>` | Declares an actor, so its color is chosen and a task that names someone else is an error. Optional. See [The cast](#the-cast). | `actor "Support agent" tone=violet` |
| `section "Name" tone=<tone> {`, the tasks, then `}` | A stage: a named run of tasks drawn as a frame with a corner tab. It needs at least one task. `tone=` tints the frame, and the default is neutral. | `section "Browse" {` |
| `task "Name" score=<1-5> actors="A, B" sub="..."` | A step. `score` is required and is a whole number from 1 to 5. `actors=` lists who is involved, separated by commas. `sub=` is a second line under the name. | `task "Find a product" score=5 actors="Customer"` |

The scores run from 1 to 5, and each has a face on the curve: a wide open smile for 5, a smile for 4, a flat mouth for 3, a frown for 2, and a deep frown with worried brows for 1. The curve is colored by height, red at the bottom and green at the top, and it never swings past a mark.

With `marks=dots`, the score is written as a number in a dot instead of a face:

**Diagram source**

```diagram
journey "Onboarding a new team" marks=dots

section "Sign up" {
  task "Create an account" score=4 actors="Admin"
  task "Verify the email address" score=3 actors="Admin"
}
section "Set up" {
  task "Invite the team" score=2 actors="Admin, Member"
  task "Connect the data source" score=1 actors="Admin, Engineer"
  task "Run a first import" score=4 actors="Engineer"
}
section "Adopt" {
  task "Build a dashboard" score=5 actors="Member, Engineer"
  task "Share with the board" score=5 actors="Admin, Member"
}
```

*Picture: Onboarding a new team: 7 tasks in 3 stages, average satisfaction 3.4 of 5.*

**Text description**

**Satisfaction runs from 1 (frustrated) to 5 (delighted).**

- Sign up: 2 tasks, average 3.5
  1. Create an account: 4 of 5 (happy), with Admin
  2. Verify the email address: 3 of 5 (neutral), with Admin
- Set up: 3 tasks, average 2.3
  3. Invite the team: 2 of 5 (unhappy), with Admin and Member
  4. Connect the data source: 1 of 5 (frustrated), with Admin and Engineer
  5. Run a first import: 4 of 5 (happy), with Engineer
- Adopt: 2 tasks, average 5.0
  6. Build a dashboard: 5 of 5 (delighted), with Member and Engineer
  7. Share with the board: 5 of 5 (delighted), with Admin and Member

**Actors: Admin, Member, and Engineer.**

**Lowest: "Connect the data source" at 1. Highest: "Build a dashboard" and "Share with the board" at 5.**

### Tasks without a stage

A task written outside any `section` is drawn with no frame, in a stage of its own. A short, flat journey needs no stages:

```plotwork
journey "A morning on the phone" desc="Tasks written outside any section are drawn with no frame."

task "Open the app" score=5
task "Read the news" score=4 actors="Me"
task "Reply to a message" score=2 actors="Me, Boss" sub="It needed a long answer"
task "Close the app" score=3
```

### The cast

| Rule | Why |
|---|---|
| Without `actor` statements, the actors are the names the tasks use, in the order they first appear. | The shortest source works. |
| With any `actor` statement, every actor a task names must be declared. An unknown one is error `E131`, and the hint gives the nearest name. | A typo such as "Custmer" is caught, not drawn as a second actor. |
| Two spellings that differ only in case or spacing are one actor, spelled the way it first appears. | `Me` and `me` are not two people. |
| An actor takes the tone it was given, or else the next tone nobody chose, in the order blue, violet, neutral, aqua, orange, amber, green, red. | The tones that are not on the satisfaction scale come first, so a chip is not taken for a score. |
| A chip shows the initials of the name, such as `Cu` and `Co` when two actors would share one letter. | Initials are unique within a journey, and the legend names every actor. |

### What is drawn

| Part | How it looks |
|---|---|
| Stage | A rounded frame with a corner tab that holds its name. The tab grows to fit the name. |
| Task card | The name (up to 3 lines), the second line (up to 2), then a row with the score and the actors. All cards have one height. |
| Score on the card | A rounded square in the score's tone that holds the number. In `marks=dots` the number is in the dot instead. |
| Actor chip | A pill with the initials of the actor, in the actor's tone. |
| Mark and curve | A disc on the curve at the height of the score, with the face inside, and one smooth line through all the marks. |
| Connector | A dotted line from each mark down to its card. |
| Legend | The five faces with their numbers, then each actor's chip and name. `legend=off` removes it. |

## Limits and warnings

A journey may have up to 100 tasks, 25 stages, 24 actors, and 8 actors in one task. Over any of these the diagram is refused with `E140` before any drawing starts. Split the journey by stage long before that: the warning for more than 16 tasks tells you when.

| Code | When it fires | What to do |
|---|---|---|
| `E100` | A task name that is not quoted, a section with no `{`, a section inside a section, an actor inside a section, or text after a `}`. | Fix the line the error points at. |
| `E101` | A string that is never closed. | Add the closing quote. |
| `E110` | A word that is not a statement. The hint names the nearest of `section`, `task`, `actor`, and `desc`. | Use one of those words. |
| `E121` | `tone=` is not a tone. | Choose a tone from the language reference. |
| `E130` | An actor declared twice. | Declare it once. |
| `E131` | A task names an actor nobody declared, in a journey that declares some. | Declare the actor, or fix the spelling the hint suggests. |
| `E133` and `E134` | A section that is never closed, or a `}` with nothing to close. | Match each `{` with a `}`. |
| `E135` | An option that does not exist. The hint gives the nearest one. | Use an option from the tables above. |
| `E136` | `marks=` or `legend=` with a value that is not one of its choices. | Write `marks=faces` or `marks=dots`, and `legend=on` or `legend=off`. |
| `E140` | More tasks, stages, actors, or actors in one task than the limits above. | Split the journey. |
| `E400` | A task with no `score=`. | Add `score=` from 1 to 5. |
| `E401` | A score that is not a whole number from 1 to 5. | Write a whole number from 1 to 5. |
| `E402` | A section with no task, or a journey with no task at all. | Add a task, or remove the empty section. |
| `E403` | An empty name: a task, a section, an actor, or one entry of `actors=`. | Write the name. |
| `W200` | More than 16 tasks. | Split the journey by stage. |
| `W202` | The picture is wider than the page reads at, over about 1100px. | Shorten the names or split the journey. |
| `W203` | A task, stage, or actor name was cut with an ellipsis. The full text stays in the text description. | Shorten the name. |
| `W350` | Three or more tasks all have one score, so the curve is a straight line. | Check the scores. A flat journey says little. |
| `W351` | More actors than the 8 tones, so some chips share a color. | Name fewer actors. The legend and the initials still tell them apart. |
| `W352` | A declared actor that no task names. | Remove the actor, or add it to a task. |
| `W353` | Two actors that differ by one letter, in a cast nobody declared. It is probably one name typed twice. | Fix the spelling, or declare the actors. |

## From Mermaid

A Mermaid `journey` converts to a Plotwork `journey` with `convert_mermaid` and `sync_markdown`, and with the `import` command. The sections, tasks, scores, and actors carry over. Mermaid colors the actors by their order, and Plotwork gives each actor the next tone in its own order, so the picture matches in spirit and the theme owns the color.

```mermaid-source
journey
  title Checkout experience
  section Browse
    Find a product: 5: Customer
    Compare prices: 3: Customer, Support agent
  section Pay
    Enter card details: 2: Customer
    Confirm with the bank: 1: Customer, Bank
```

| Mermaid | Plotwork | Code |
|---|---|---|
| `title ...` | The title in the header. A `title:` in front matter wins. | `M214` when the journey has none |
| `accTitle:`, `accDescr:` | The title, when there is none, and `desc=` | |
| `section Name` | `section "Name" {`, the tasks, then `}` | |
| `Name: 4: Actor, Actor` | `task "Name" score=4 actors="Actor, Actor"` | |
| Tasks before the first `section` | `task` lines with no frame | |
| A score of 0, 6 or more, below zero, or a fraction | The nearest whole score from 1 to 5 | `M270` |
| An empty actor name, or `me` after `Me` | The empty name is dropped and the first spelling is used | `M271` |
| A section with no task | Dropped | `M216` |
| Text after the actors | Dropped, as Mermaid drops it | `M203` |
| HTML, Markdown, entities, and Font Awesome tokens in names | Plain text | `M205`, `M215` |
| Comments and blank lines | Dropped | |
| Front matter `config:` and `%%{init}%%` (theme, colors, margins, font sizes) | Dropped | `M200` |
| A line that is not a task, a title, or a section | Refused. With `lenient`, the line is skipped. | `M110`, or `M218` when skipped |
| More than 100 tasks or 25 stages | Refused. Split the journey. | `M102` |
| No task at all | Refused | `M103` |

## See also

| Doc | Why |
|---|---|
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The language for flow, sequence, and schema diagrams, and the options every kind shares |
| [Examples to copy](https://docs.plotwork.dev/examples.md) | Finished diagrams with the prompt that makes each one |
| [Migrating from Mermaid](https://docs.plotwork.dev/migrating-from-mermaid.md) | How the converter works and what every diagnostic code means |
| [Git graphs](https://docs.plotwork.dev/git-graphs.md) | Branches, merges, and tags as lanes |
| [Gantt charts](https://docs.plotwork.dev/gantt-charts.md) | A plan in days, with dependencies |
| [Class diagrams](https://docs.plotwork.dev/class-diagrams.md) | Classes, members, and the relations between them |
| [State diagrams](https://docs.plotwork.dev/state-diagrams.md) | States and the transitions between them |
| [Timelines](https://docs.plotwork.dev/timelines.md) | Events along a scale of time |
| [Mind maps](https://docs.plotwork.dev/mind-maps.md) | An idea and its branches |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every statement and option of every kind |
| [Diagram kinds](https://docs.plotwork.dev/reference/language/kinds.md) | What each kind draws and how its header starts |