Mermaid Wardley Map Tutorial - Syntax, Examples, and Best Practices

What You Will Learn

How to recognize when Wardley Map is the right Mermaid diagram, write the opening declaration, and shape a readable first version.

Best Fit

Platform strategy, Build-versus-buy analysis, Capability planning.

Start Here

Copy the starter example, replace labels with your domain language, then simplify anything that does not help the reader.

Syntax Basics

Start with the diagram declaration, then add the smallest set of labels, relationships, and annotations needed to communicate the idea.

Identify the user need first.
Place components by visibility and evolution.
Connect dependencies from user need to capabilities.
Use annotations to explain strategic movement.

Read Mermaid Like A Picture

If you are new to Mermaid, do not try to memorize every keyword. Read the code as drawing instructions: first choose the diagram type, then identify the labels, then follow the connections.

Start with the rendered picture first. Then scan the code and ask: which line created this label, connector, section, or value?

Read the first line first

wardley

The first line chooses the diagram family. If it says wardley, every line below follows the rules for a Mermaid Wardley Map.

Look for visible labels

[Label], "Label", title, section

Labels are the words readers see in the final diagram. Good labels are short, concrete, and written in the language of the page.

Find the relationships

-->, ->>, :, ||--o{

Connectors, arrows, colons, and relationship markers explain how items interact, move, depend on each other, or belong together.

Use indentation as hierarchy

child line

Indented lines usually belong to the line above them. This matters for sections, mindmaps, trees, tasks, and grouped structures.

Official Documentation Coverage

The Mermaid documentation for Wardley Map covers the following syntax areas. This tutorial condenses those topics into practical guidance for day-to-day documentation.

Diagram declaration

Diagram declaration is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Coordinate system

Coordinate system is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Components and anchors

Components and anchors is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Decorators

Decorators is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Links and dependencies

Links and dependencies controls how elements connect. Treat these connections as the main information layer, and label them when direction, ownership, or meaning is not obvious.

Evolution and movement

Evolution and movement is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Pipelines

Pipelines is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Custom evolution stages

Custom evolution stages is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

How This Tutorial Uses The Official Docs

Mermaid syntax evolves, so the official page remains the primary reference. This tutorial turns that reference material into an authoring workflow, review checklist, and production guidance.

Start with the official grammar

The official Mermaid Wardley Map page is the source of truth for syntax changes. Use this tutorial to choose the right authoring pattern, then confirm exact keywords and edge cases in the official reference.

Prioritize the core sections

For the first pass, focus on Diagram declaration, Coordinate system, Components and anchors, Decorators. These sections usually explain the minimum structure required for a valid Wardley Map.

Add advanced syntax only when it earns its space

Treat Links and dependencies, Evolution and movement, Pipelines, Custom evolution stages as optional layers. They are valuable when the diagram needs precision, but they should not make the first version harder to read.

Syntax Reference Map

Use this map as a practical reading order for the official syntax page. It separates the first concepts to learn from the advanced details that are better added after the diagram already communicates the right idea.

Phase

Topic

How to use it

Start

Diagram declaration

Diagram declaration is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Does this diagram declaration detail make the wardley map easier to understand or maintain?

Start

Coordinate system

Coordinate system is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Does this coordinate system detail make the wardley map easier to understand or maintain?

Refine

Components and anchors

Components and anchors is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Does this components and anchors detail make the wardley map easier to understand or maintain?

Refine

Decorators

Decorators is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Does this decorators detail make the wardley map easier to understand or maintain?

Refine

Links and dependencies

Links and dependencies controls how elements connect. Treat these connections as the main information layer, and label them when direction, ownership, or meaning is not obvious.

Does this links and dependencies detail make the wardley map easier to understand or maintain?

Polish

Evolution and movement

Evolution and movement is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Does this evolution and movement detail make the wardley map easier to understand or maintain?

Polish

Pipelines

Pipelines is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Does this pipelines detail make the wardley map easier to understand or maintain?

Polish

Custom evolution stages

Custom evolution stages is part of the official Mermaid Wardley Map syntax surface. Add it when the starter example needs more precision for production documentation.

Does this custom evolution stages detail make the wardley map easier to understand or maintain?

How To Study The Official Syntax

The official Mermaid page is broad because it documents the full parser surface. For a working tutorial, read it in passes instead of trying to memorize every option at once.

Step 1

Skim the official Wardley Map documentation once to understand the full syntax surface before copying examples into production docs.

Step 2

Focus first on Diagram declaration, Coordinate system, Components and anchors, Decorators, Links and dependencies because these topics usually explain the core authoring model.

Step 3

After the first diagram renders, revisit the official styling, configuration, and advanced sections only when the diagram needs that extra precision.

Authoring Workflow

This workflow turns the official syntax reference into a repeatable writing process for docs, specs, and product pages.

Step 1

Frame the reader question

Before writing syntax, decide what question the Wardley Map should answer. Good diagrams usually answer one question clearly instead of answering several partially.

Step 2

Draft the smallest valid diagram

Start with the declaration for wardley, add only the required elements, and render it before introducing advanced styling or configuration.

Step 3

Add semantic labels

Replace placeholder names with business or system language that readers already know. Labels should reduce explanation work.

Step 4

Review for maintenance

Remove details that are likely to drift quickly. If a value, date, or dependency changes often, explain who owns the update.

Quick Syntax Cheat Sheet

Use this compact reference when you already know the goal and need to write a valid Mermaid Wardley Map quickly.

Declaration

wardley

Start the code block with wardley so Mermaid selects the Wardley Map renderer.

Core content

Identify the user need first.

Add the smallest number of statements that express the main idea before adding visual polish.

Connections

Connect dependencies from user need to capabilities.

Use connections only where they explain ownership, sequence, flow, dependency, or hierarchy.

Advanced topic

Diagram declaration

Use official syntax topics as optional layers, not as requirements for every diagram.

Practice Prompts

Use these prompts after reading the official syntax sections. They force the diagram to stay practical instead of becoming a syntax inventory.

Exercise 1

Create a Wardley Map for platform strategy using no more than eight visible elements.

Exercise 2

Rewrite the starter example with labels from your own product or engineering domain, then remove any line that does not change the reader's understanding.

Exercise 3

Add one official syntax feature from Diagram declaration, Coordinate system, Components and anchors and explain why that feature makes the diagram clearer.

Exercise 4

Compare the result with architecture and c4 and write one sentence explaining why Wardley Map is still the better fit.

Examples

Each example shows the Mermaid code next to the rendered result, so you can see exactly how syntax becomes a diagram.

Platform Capability Map

A lightweight strategy map outline.

Edit this example

Mermaid code

flowchart TD
  U[User need: create diagrams] --> E[Editor]
  E --> R[Rendering]
  E --> X[Export]
  R --> M[Mermaid engine]
  X --> S[Storage]

Rendered result

Enter Mermaid code to see preview

Example Walkthrough

Read Mermaid examples from top to bottom. The first meaningful line usually selects the diagram parser; the following lines add labels, relationships, values, states, or layout hints.

flowchart TD

This line adds one piece of content to the diagram. Read it as an instruction for what Mermaid should draw.

U[User need: create diagrams] --> E[Editor]