Wardley Maps (v11.14.0+)

Wardley Maps are visual representations of business strategy that map value chains and component evolution. They help identify strategic opportunities, dependencies, and guide technology decisions.

Introduction

Wardley Maps position components along two axes:

• Visibility (Y-axis): How visible/valuable a component is to users (0.0 = infrastructure, 1.0 = user-facing)
• Evolution (X-axis): How evolved/mature a component is (0.0 = genesis/novel, 1.0 = commodity/utility)

This dual positioning enables strategic analysis of:

• Value chain dependencies
• Evolution of components over time
• Build vs. buy decisions
• Inertia and resistance to change

Basic Example

Code:

Ctrl + Enter|

Syntax

Diagram Declaration

Every Wardley diagram starts with the wardley-beta keyword:

Code:

Ctrl + Enter|

• wardley-beta - Required diagram type identifier (beta release)
• title - Optional title displayed at top
• size - Optional canvas dimensions in pixels (default: [1100, 600])

Coordinate System

IMPORTANT: Wardley Maps use the OnlineWardleyMaps (OWM) format: [visibility, evolution]

• First value (Visibility): 0.0-1.0 (bottom to top) - Y-axis position
• Second value (Evolution): 0.0-1.0 (left to right) - X-axis position

This is opposite of typical (x, y) notation!

Code:

Ctrl + Enter|

Components and Anchors

Components

component Name [visibility, evolution]
component Name [visibility, evolution] label [offsetX, offsetY]
component Name [visibility, evolution] (decorator)

Example:

Code:

Ctrl + Enter|

Names may contain hyphens (real-time processing, end-user) without quoting. Quote a name only if it begins with a non-letter or contains a character the grammar does not otherwise accept.

Code:

Ctrl + Enter|

Anchors

Anchors represent users or customers with bold labels:

Code:

Ctrl + Enter|

Decorators

Inertia

Mark components resistant to change:

Code:

Ctrl + Enter|

Source Strategy

Indicate build/buy/outsource decisions:

• (build) - Triangle symbol
• (buy) - Diamond symbol
• (outsource) - Square symbol
• (market) - Circle symbol

Code:

Ctrl + Enter|

Links and Dependencies

A -> B              %% Basic dependency
A --> B             %% Basic dependency (alternative style)
A -> B; label       %% With annotation
A -.-> B            %% Dashed flow
A +> B              %% Flow (with arrow marker)
A +< B              %% Reverse flow
A +<> B             %% Bi-directional flow
A +'text'> B        %% Labeled flow

Example:

Code:

Ctrl + Enter|

Evolution and Movement

Evolution Arrows

Show component evolution with red dashed arrows:

Code:

Ctrl + Enter|

Trend Indicators

Show predicted future position:

Component -.- (x, y)

Note: Trends use standard (x, y) order, not [visibility, evolution]!

Pipelines

Pipeline components share visibility and only vary by evolution:

Code:

Ctrl + Enter|

Custom Evolution Stages

Define custom axis labels:

Code:

Ctrl + Enter|

Dual Labels

Code:

Ctrl + Enter|

Custom Stage Widths

Specify custom boundary widths using @ notation:

Code:

Ctrl + Enter|

Annotations and Notes

Notes

Add contextual notes at specific coordinates:

note "text" [visibility, evolution]

Note: Text must be enclosed in quotes.

Code:

Ctrl + Enter|

Numbered Annotations

Create numbered references with optional annotation box:

annotations [x, y]              # Optional: position for annotation numbers
annotation number,[x, y] "text"

Note: Annotation text must be enclosed in quotes.

Code:

Ctrl + Enter|

Visual Elements

Accelerators and Deaccelerators

Forces affecting evolution:

Code:

Ctrl + Enter|

Advanced Features

Label Positioning

Fine-tune label placement:

component Name [visibility, evolution] label [offsetX, offsetY]

Negative X moves left, positive X moves right. Negative Y moves up, positive Y moves down.

Custom Canvas Size

Code:

Ctrl + Enter|

Complete Example

Code:

Ctrl + Enter|

Configuration

Wardley Maps support Mermaid's theme system. Use standard Mermaid configuration to customize appearance.

Resources

• Wardley Mapping Book by Simon Wardley
• OnlineWardleyMaps - Interactive mapping tool
• Wardley Maps Community
• Learn Wardley Mapping

Syntax Summary

Element	Syntax	Example
Diagram	wardley-beta	wardley-beta
Title	title Text	title My Map
Size	size [width, height]	size [1100, 800]
Component	component Name [vis, evo]	component API [0.6, 0.7]
Anchor	anchor Name [vis, evo]	anchor User [0.9, 0.95]
Link	A -> B	API -> Database
Flow	A +> B	User +> API
Evolve	evolve Name targetEvo	evolve API 0.85
Note	note "Text" [vis, evo]	note "Key insight" [0.4, 0.5]
Annotation	annotation N,[x,y] "Text"	annotation 1,[0.5,0.5] "Critical"
Inertia	(inertia)	component DB [0.4, 0.6] (inertia)
Strategy	(build|buy|outsource|market)	component API [0.6, 0.7] (buy)
Pipeline	pipeline Parent { ... }	See pipeline example above
Evolution	evolution Stage1 -> Stage2 -> ...	See evolution examples above

Limitations

• Handdrawn/rough mode (look: handDrawn) is not currently supported for Wardley Maps. The diagram uses a custom D3 renderer rather than the shared shape system.