Diagram Style Guide¶

This guide documents conventions for creating diagrams in this documentation. Following these patterns ensures consistency, maintainability, and proper rendering across light/dark modes.

Quick Reference¶

Mermaid Conventions¶

Critical Syntax Rules¶

Rule 1: Define Nodes SEPARATELY from Edges¶

The color property in classDef only works reliably when nodes are defined on their own lines, separate from edge definitions.

CORRECT - Nodes defined separately, then connected:

flowchart LR
    classDef phase fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD

    %% Define nodes FIRST
    A[Phase 1: Research]:::phase
    B[Phase 2: Strategy]:::phase
    C[Phase 3: Solution]:::phase

    %% Then define edges
    A --> B --> C

WRONG - Mixing node definitions with edges (causes white/invisible text):

flowchart LR
    classDef phase fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF

    %% DON'T do this - text color will be ignored!
    A[Phase 1: Research]:::phase --> B[Phase 2: Strategy]:::phase

Rule 2: Use Inline :::class Syntax¶

Apply classes using the inline :::className syntax immediately after the node definition. The class A,B,C className statement at the end of diagrams is unreliable for text color.

CORRECT:

flowchart LR
    classDef research fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD

    A[Research]:::research
    B[Analysis]:::research
    A --> B

UNRELIABLE:

flowchart LR
    classDef research fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD

    A[Research]
    B[Analysis]
    A --> B

    class A,B research  %% Text color may not apply!

Rule 3: Avoid Reserved Words¶

error is a reserved word in Mermaid. Use errorStyle instead.

%% WRONG - 'error' is reserved
classDef error fill:#FFEBEE,stroke:#F44336,color:#B71C1C

%% CORRECT
classDef errorStyle fill:#FFEBEE,stroke:#F44336,color:#B71C1C

Rule 4: No HTML in Labels¶

HTML tags like <br/> and escape sequences like \n get escaped by MkDocs. Use single-line labels.

# AVOID - HTML gets escaped
A["Phase 1<br/>Research"] --> B["Phase 2<br/>Strategy"]

Label Formatting¶

Do: Use simple, single-line labels with classes applied on separate lines

flowchart LR
    classDef phase fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD

    A[Phase 1: Research]:::phase
    B[Phase 2: Strategy]:::phase
    C[Phase 3: Solution]:::phase

    A --> B --> C

Supported CSS Properties¶

Properties that DON'T work: background (use fill), border (use stroke), padding, margin, text-align

Styling with classDef¶

Define reusable style classes. Always define nodes on separate lines from edges:

flowchart LR
    classDef primary fill:#303F9F,stroke:#1A237E,color:#E8EAF6
    classDef secondary fill:#37474F,stroke:#263238,color:#ECEFF1
    classDef success fill:#1B5E20,stroke:#0D3D13,color:#E8F5E9
    classDef warning fill:#E65100,stroke:#BF360C,color:#FFF3E0
    classDef errorStyle fill:#B71C1C,stroke:#7F0000,color:#FFEBEE

    A[Start]:::primary
    B[Process]:::secondary
    C{Decision}:::secondary
    D[Success]:::success
    E[Retry]:::warning

    A --> B --> C
    C -->|Yes| D
    C -->|No| E

Recommended Class Definitions¶

Copy-paste these semantic class definitions (dark theme, indigo-aligned):

flowchart LR
    %% Dark theme semantic classes (indigo-aligned)
    classDef research fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD
    classDef design fill:#5D4037,stroke:#3E2723,color:#FFF8E1
    classDef validate fill:#B71C1C,stroke:#7F0000,color:#FFEBEE
    classDef success fill:#1B5E20,stroke:#0D3D13,color:#E8F5E9
    classDef primary fill:#303F9F,stroke:#1A237E,color:#E8EAF6
    classDef neutral fill:#37474F,stroke:#263238,color:#ECEFF1

    %% Define nodes on separate lines
    R[Research]:::research
    D[Design]:::design
    V[Validate]:::validate
    S[Success]:::success
    P[Primary]:::primary
    N[Neutral]:::neutral

    %% Then define edges
    R --> D --> V --> S
    P --> N

Complete Class Library¶

%% Copy this block to the top of your Mermaid diagrams
%% Dark theme (indigo-aligned for MkDocs Material)

%% Phase colors (for workflows) - Dark fills, light text
classDef research fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD
classDef design fill:#5D4037,stroke:#3E2723,color:#FFF8E1
classDef validate fill:#B71C1C,stroke:#7F0000,color:#FFEBEE
classDef success fill:#1B5E20,stroke:#0D3D13,color:#E8F5E9

%% Role colors (for actors/components)
classDef primary fill:#303F9F,stroke:#1A237E,color:#E8EAF6
classDef neutral fill:#37474F,stroke:#263238,color:#ECEFF1

%% Status colors
classDef errorStyle fill:#B71C1C,stroke:#7F0000,color:#FFEBEE
classDef warning fill:#E65100,stroke:#BF360C,color:#FFF3E0
classDef info fill:#01579B,stroke:#002F6C,color:#E1F5FE

Theme Configuration¶

Let MkDocs Material handle theming automatically. Avoid setting explicit themes unless needed:

%% AVOID: Forces a specific theme
%%{init: {'theme': 'dark'}}%%
flowchart LR
    A --> B --> C

PREFER: Let Material handle light/dark mode automatically - don't specify a theme.

Subgraph Styling¶

flowchart TB
    subgraph Pipeline[Build Pipeline]
        A[Build]:::research
        B[Test]:::design
        C[Deploy]:::success
        A --> B --> C
    end

    %% Style the subgraph container with dark theme
    style Pipeline fill:#263238,stroke:#37474F,stroke-width:2px,color:#ECEFF1

    classDef research fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD
    classDef design fill:#5D4037,stroke:#3E2723,color:#FFF8E1
    classDef success fill:#1B5E20,stroke:#0D3D13,color:#E8F5E9

Anti-Patterns to Avoid¶

D2 Conventions¶

Critical: Classes Don't Work with mkdocs-d2-plugin¶

DOES NOT WORK (colors ignored, uses theme defaults):

# This looks correct but DOESN'T WORK with mkdocs-d2-plugin
classes: {
  research: {
    style.fill: "#DBEAFE"
    style.stroke: "#3B82F6"
    style.font-color: "#1E40AF"
  }
}

node1.class: research  # Ignored!

WORKS - Use inline styles (dark theme):

Complete Style Properties¶

Color & Fill:

Border & Shape:

Typography:

Animation:

Label Formatting¶

Do: Use block strings with markdown for multi-line labels

Don't: Use \n escape sequences

Container Structure¶

Use containers to group related elements:

Styling Example with Inline Styles¶

Since classes don't work, apply styles inline (dark theme, indigo-aligned):

Copy-Paste Style Snippets¶

Since you can't use classes, copy these style blocks as needed (dark theme):

# Research/Understand phase (dark blue)
style.fill: "#1E3A5F"
style.stroke: "#0D47A1"
style.font-color: "#E3F2FD"

# Design/Create phase (dark amber)
style.fill: "#5D4037"
style.stroke: "#3E2723"
style.font-color: "#FFF8E1"

# Validate/Test phase (dark red)
style.fill: "#B71C1C"
style.stroke: "#7F0000"
style.font-color: "#FFEBEE"

# Complete/Success phase (dark green)
style.fill: "#1B5E20"
style.stroke: "#0D3D13"
style.font-color: "#E8F5E9"

# Primary/Orchestrator (indigo)
style.fill: "#303F9F"
style.stroke: "#1A237E"
style.font-color: "#E8EAF6"

# Neutral (dark blue-grey)
style.fill: "#37474F"
style.stroke: "#263238"
style.font-color: "#ECEFF1"

Semantic Color Palette (Dark Theme)¶

Use these dark colors to match the MkDocs Material indigo theme:

Theme Configuration¶

Our mkdocs.yml configuration:

• Light mode: theme: 0 (Neutral Default)
• Dark mode: dark_theme: 200 (Dark Mauve)

When inline styles are needed for special cases:

Layout Engine¶

We use ELK (layout: elk) for:

• Better handling of complex hierarchies
• More professional appearance
• Consistent spacing

Special Shapes¶

Available shapes:

Connection Styles¶

Arrowhead Styles¶

Available arrowheads: triangle (default), arrow, diamond, circle, cf-one, cf-many, cf-one-required, cf-many-required

When to Use Which Tool¶

Use Mermaid For:¶

• Simple flowcharts
• Sequence diagrams
• Quick documentation diagrams
• GitHub README compatibility
• Diagrams that need to work without plugins

Use D2 For:¶

• Architecture diagrams
• Complex system overviews
• Professional/publication-ready output
• Diagrams with containers/grouping
• When you need sketch mode

File Organization¶

docs/
├── reference/
│   ├── diagram-comparison.md    # Tool comparison
│   └── diagram-style-guide.md   # This file
└── **/*.md                      # Inline diagrams in docs

For complex diagrams that are reused, consider:

1. Creating standalone .d2 files
2. Using the image tag syntax: ![Diagram](path/to/diagram.d2)

Accessibility Considerations¶

WCAG Color Contrast Requirements¶

Accessible Color Combinations¶

Our dark semantic palette is designed for WCAG AA compliance (light text on dark backgrounds):

Best Practices¶

1. Color contrast - All our semantic colors meet 4.5:1 minimum
2. Don't rely on color alone - Use shapes, labels, patterns
3. Alt text - Provide context in surrounding prose
4. Keep it simple - Complex diagrams are harder for screen readers
5. Test with tools - Use WebAIM Contrast Checker

Configuration Reference¶

mkdocs.yml D2 Settings¶

plugins:
  - d2:
      executable: /path/to/d2
      layout: elk           # dagre, elk, or tala
      theme: 0              # Light theme (0-17)
      dark_theme: 200       # Dark theme (200-201)
      sketch: false         # Hand-drawn style
      pad: 100              # Padding around diagram
      scale: 0.8            # Scale factor

Available D2 Themes¶

Light themes: 0 (Neutral Default), 1-17 (various styles) Dark themes: 200 (Dark Mauve), 201 (Dark Flagship)

See D2 Themes for full catalog.