Cynefin Framework Diagram

Requires Mermaid 11.16.0+

Cynefin is a Mermaid 11.16.0 feature. The plugin recognizes the language at any runtime, but rendering only works against Mermaid 11.16.0 or newer. Pick the runtime under Settings > Tools > Mermaid Studio > Mermaid Runtime if you’ve pinned an older version.

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.

Beta diagram type

Cynefin is a beta diagram type in Mermaid.js, so its syntax and rendering may still change as the upstream implementation matures.

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.

Armada Dark

Islands Dark

Islands Light

IDE Support

Mermaid Studio implements Cynefin as a full language with its own lexer and parser, so editing support goes beyond highlighting. Mermaid Studio provides:

• Syntax highlighting for the cynefin-beta keyword, domain names, item strings, transition arrows, transition labels, titles, and comments
• Validation that flags an unknown domain name as an error, with a quick-fix that replaces the typo with the nearest valid domain
• Self-loop inspection that warns when a transition points a domain at itself (for example complex --> complex), with a quick-fix to remove it
• Completion for the five domain names and the title, accTitle, and accDescr statements at the start of a line, and for domain names after a --> arrow
• Code folding to collapse a domain down to its name, hiding its items
• Code formatter with domain-body indentation; configurable under Settings > Editor > Code Style > Mermaid > Cynefin
• Spellchecking scoped to prose only, so item strings, title text, and accessible-description text are checked while keywords and operators are skipped

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

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

Items

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

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

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

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.