Other diagram kinds

User journeys

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.

Ask your agent

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.

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

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.

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.	`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:

Onboarding a new team: 7 tasks in 3 stages, average satisfaction 3.4 of 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:

1journey "A morning on the phone" desc="Tasks written outside any section are drawn with no frame."2
3task "Open the app" score=54task "Read the news" score=4 actors="Me"5task "Reply to a message" score=2 actors="Me, Boss" sub="It needed a long answer"6task "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.

1journey2  title Checkout experience3  section Browse4    Find a product: 5: Customer5    Compare prices: 3: Customer, Support agent6  section Pay7    Enter card details: 2: Customer8    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`

Doc	Why
Writing diagrams	The language for flow, sequence, and schema diagrams, and the options every kind shares
Examples to copy	Finished diagrams with the prompt that makes each one
Migrating from Mermaid	How the converter works and what every diagnostic code means
Git graphs	Branches, merges, and tags as lanes
Gantt charts	A plan in days, with dependencies
Class diagrams	Classes, members, and the relations between them
State diagrams	States and the transitions between them
Timelines	Events along a scale of time
Mind maps	An idea and its branches
Language reference	Every statement and option of every kind
Diagram kinds	What each kind draws and how its header starts