Time to actually build Wardley Map support for Mermaid. Here’s the journey from “I should do this” to a working PR.
Understanding the Codebase
Mermaid is a mature project—70k+ stars, hundreds of contributors, years of history. Before writing code, I spent time understanding:
- How existing diagram types are structured: Each diagram type lives in
packages/mermaid/src/diagrams/{type}/ - The Langium-based parser architecture: Grammar files in
packages/parser/src/language/ - The rendering pipeline: Parse → Database → Renderer → SVG
- The test patterns: Unit tests, integration tests, visual regression tests
The Pie, Packet, and Architecture diagrams all follow the modern Langium pattern. I used them as templates.
The Grammar
The heart of any Mermaid diagram is its grammar file. Langium makes this declarative:
WardleyComponent:
'component' id=ID label=STRING coords=Coordinates
;
Coordinates:
'[' visibility=NUMBER ',' evolution=NUMBER ']'
;
WardleyEdge:
from=[WardleyComponent:ID] '->' to=[WardleyComponent:ID]
;
No imperative parsing code. Just structure. Langium generates the parser, AST types, and validation from this definition.
The Syntax
The resulting syntax is clean and readable:
wardleyMap
title Platform Strategy
component user "End User" [0.95, 0.7]
component webapp "Web Application" [0.8, 0.6]
component api "API Layer" [0.65, 0.55]
component auth "Authentication" [0.5, 0.82]
component db "Database" [0.35, 0.75]
component compute "Compute" [0.15, 0.9]
user -> webapp
webapp -> api
api -> auth
api -> db
db -> compute
evolve api 0.75
Components have an ID, label, and [visibility, evolution] coordinates. Dependencies use arrow syntax. Evolution markers show where things are heading.
The Implementation
The PR adds ~3,700 lines across these key files:
| File | Purpose |
|---|---|
wardley.langium |
Grammar definition |
wardleyParser.ts |
Parses AST into database |
wardleyDb.ts |
Stores components, edges, config |
wardleyRenderer.ts |
Generates SVG output |
wardleyTheme.ts |
Color schemes and styling |
What’s Working
The current implementation handles:
- Component positioning: Place components anywhere on the visibility/evolution grid
- Dependencies: Draw arrows between components showing value chain
- Evolution stages: Background bands for Genesis, Custom, Product, Commodity
- Theming: Default, dark, forest, and other Mermaid themes
- Labels: Smart positioning to avoid overlaps
- Configuration: Customizable colors, fonts, dimensions
The test suite covers parsing, database operations, and rendering. The integration tests verify end-to-end behavior.
What’s Next
The PR is in draft, working through code review. Outstanding items:
- Accessibility improvements: Screen reader support, ARIA labels
- Edge cases: Complex dependency graphs, label collision handling
- Documentation polish: More examples, configuration reference
The documentation covers basic usage, and there are sample diagrams showing various configurations.
Once it lands in Mermaid core, GitHub will render Wardley Maps natively. That’s the goal.
Next: a deeper look at how the pieces fit together.
