Cynefin Framework Diagram
Last updated:
Mermaid Studio provides language support for Cynefin diagrams inside IntelliJ IDEA and other JetBrains IDEs. The Cynefin framework is a sense-making model that sorts situations into five decision domains, so a team can match its response to the kind of problem it faces. A Cynefin diagram lists the items that belong in each domain and the transitions that move work from one domain to another.
Syntax Highlighting
Section titled “Syntax Highlighting”Syntax highlighting integrates directly with IntelliJ’s color scheme system, so diagram colors always match your editor theme. The screenshots below show the same Cynefin diagram across three themes.
IDE Support
Section titled “IDE Support”The summary below shows the IDE support Mermaid Studio ships for Cynefin diagrams, grouped by capability.
Folding lets you collapse and expand structural blocks of the diagram source (subgraphs, frontmatter, multi-line strings) directly in the editor gutter. It keeps long diagrams navigable without forcing you to scroll past detail you don’t need right now.
Use the gutter triangles, Code → Folding, or the standard JetBrains shortcuts (
When the cursor sits next to a bracket, brace, or paren, Mermaid Studio highlights its matching pair across the whole diagram and lets you jump between them. This is especially valuable in nested syntax (subgraph blocks, JSON-style style strings, multi-shape labels) where it’s easy to lose track of which closer goes with which opener.
The line-comment action (
When you type a quote character to start a string, Mermaid Studio inserts the matching closing quote and places the cursor between them. Backspacing through an empty pair removes both characters at once. This keeps quoted labels balanced and reduces fiddly cursor work.
The formatter rewrites your diagram source to a canonical layout (consistent indentation, alignment of multi-line links, normalized whitespace around operators) without changing semantics.
It also clears up the whitespace mistakes that Mermaid’s parser is picky about, normalizing spacing between tokens so the parser accepts the diagram on the first read instead of throwing a confusing syntax error.
Run it with Code → Reformat Code (
Pressing
A dedicated Grammar-Kit parser backs the highlighting, so tokens are colored by what they mean in the diagram (a type reference versus a label versus a style), not just what they look like. The same parser validates the syntax as you type, flagging malformed statements in place instead of letting one mistake cascade through the file.
This is the foundation richer features build on; the same grammar drives completions, refactoring, and inspections.
Per-diagram annotators apply rule-based highlighting above the lexer and parser, running on every keystroke and painting their results directly in the editor. Mermaid Studio uses them across the full range the platform supports: highlighting that token types alone cannot decide (coloring a reference by what it resolves to), semantic errors and warnings (an edge pointing at an undefined node, an invalid direction value), and inline cues such as marking duplicate labels. Unlike inspections (configurable checks listed in Settings), annotators are always on, whether a rule ends in a color or a warning.
As you type, Mermaid Studio offers context-aware suggestions filtered to what’s valid at the cursor: node shapes, arrow types, keywords, icon names, identifiers, frontmatter keys, theme variables, and more. Completions cut down on typos and make the diagram syntax self-documenting.
Completion and validation for the YAML frontmatter block above the diagram body, driven by the diagram type’s slice of the Mermaid config schema. Config keys, enum values, and color properties complete as you type, and unknown or mistyped keys are flagged in place.
Inspections are static analyzers that run continuously and surface problems as you edit: duplicate IDs, undefined references, malformed syntax, deprecated patterns, missing required fields. Each inspection has a configurable severity (error, warning, info), can be suppressed inline, and most ship with a quick fix that resolves the issue with one keystroke.
This is where most of the editorial intelligence lives: a diagram type with rich inspections is much harder to break in subtle ways.
The IDE’s spellchecker runs inside labels, strings, and comments, with the diagram grammar telling it which tokens are prose and which are identifiers. Typos get the familiar squiggle and Alt+Enter correction, and identifiers stay out of the dictionary’s way.
Mermaid Studio implements Cynefin as a full language with its own lexer and parser, so editing support goes beyond highlighting. Validation is domain-aware: unknown domain names and self-loop transitions are flagged with one-click fixes, and completion knows the five domain names in both declaration and transition positions. Spellchecking is scoped to prose, so item strings and titles are checked while keywords and operators are skipped.
Quick Syntax Reference
Section titled “Quick Syntax Reference”A Cynefin diagram starts with the cynefin-beta keyword, lists items under each domain, and then declares the transitions between domains.
The example below sorts engineering practices into their domains and shows two transitions.
cynefin-beta title Team Decision Domains complex "Run a chaos experiment" "Probe, sense, respond" complicated "Expert analysis needed" clear "Follow the runbook" chaotic "Crisis response" confusion "Unclear which domain" complex --> complicated : "Pattern identified" chaotic --> complex : "Stabilized"Domains
Section titled “Domains”Every item belongs to one of five fixed domains. The names are case-sensitive, and any other bareword is flagged as an unknown domain:
| Domain | Meaning in the Cynefin framework |
|---|---|
clear | Cause and effect are obvious; apply best practice |
complicated | Cause and effect require analysis or expertise; apply good practice |
complex | Cause and effect are clear only in retrospect; let practice emerge |
chaotic | No perceivable cause and effect; act first, then find novel practice |
confusion | You do not yet know which of the other four domains applies |
List the items in a domain as quoted strings under the domain name. Both double and single quotes work:
cynefin-beta complex "New product bet" 'Run a spike' clear "Deploy via runbook"Transitions
Section titled “Transitions”Connect two domains with a --> arrow to show how work moves between them.
Add an optional label with a colon and a quoted string:
cynefin-beta complicated --> clear : "Codified" chaotic --> complex : "Stabilized"Titles and accessibility metadata
Section titled “Titles and accessibility metadata”Add a title for the diagram, and accTitle or accDescr for accessible labels.
The accDescr form also accepts a multi-line { ... } block:
cynefin-beta title Engineering Practices by Domain accTitle: Cynefin domains for engineering work accDescr { Practices grouped by the Cynefin decision domain they belong to. } clear "Rotate credentials"Theme variables
Section titled “Theme variables”Cynefin exposes a dedicated cynefin object under themeVariables for customizing the domain backgrounds, boundaries, and arrows.
Set it in the YAML frontmatter:
---config: theme: base themeVariables: cynefin: complexBg: "#EDE9FE" complicatedBg: "#DBEAFE" clearBg: "#DCFCE7" chaoticBg: "#FFE4E6" confusionBg: "#F3F4F6" boundaryColor: "#475569" arrowColor: "#475569"---cynefin-beta title Team Decision Domains complex "Probe, sense, respond" clear "Follow the runbook"For complete syntax details, see the Mermaid Cynefin documentation.