Customizing Mermaid Diagram Themes, Colors, and Fonts

Mermaid Theme Customization

Mermaid provides a powerful theming system that lets you control colors, fonts, line styles, and overall appearance. You can use built-in themes or create fully custom styles.

Built-in Themes

Mermaid ships with several themes that you can activate with the init directive:

%%{init: {'theme': 'forest'}}%%
flowchart LR
    A --> B --> C

Available themes:

Theme	Description
default	Blue and gray palette
dark	Dark background with light text
forest	Green-heavy nature palette
neutral	Grayscale, print-friendly
base	Minimal theme for full customization

Theme Variables

Override specific colors and fonts using themeVariables:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#4f46e5',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#3730a3',
    'secondaryColor': '#f59e0b',
    'tertiaryColor': '#f3f4f6',
    'lineColor': '#6b7280',
    'fontFamily': 'Inter, sans-serif',
    'fontSize': '14px'
  }
}}%%
flowchart TD
    A[Step 1] --> B[Step 2]
    B --> C[Step 3]
    C --> D[Step 4]

Common Theme Variables

Variable	What it affects
primaryColor	Main node fill color
primaryTextColor	Text color inside primary nodes
primaryBorderColor	Border of primary nodes
secondaryColor	Alternate node fill color
lineColor	Arrow and line color
fontFamily	Global font family
fontSize	Base font size
nodeTextColor	Default text color in nodes

Per-Node Styling

Apply CSS-like styles to individual nodes using the style keyword:

flowchart LR
    A[Normal] --> B[Highlighted] --> C[Error]
    style B fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style C fill:#fee2e2,stroke:#dc2626,color:#991b1b

Class-Based Styling

Define reusable style classes:

flowchart LR
    A[Step 1]:::success --> B[Step 2]:::warning --> C[Step 3]:::danger
    classDef success fill:#dcfce7,stroke:#16a34a,color:#166534
    classDef warning fill:#fef9c3,stroke:#ca8a04,color:#854d0e
    classDef danger fill:#fee2e2,stroke:#dc2626,color:#991b1b

Tips

1. Start with base theme for maximum customization control.
2. Match your brand — set primaryColor to your company's brand color for consistent documentation.
3. Test in dark and light modes — ensure your custom colors have sufficient contrast in both.
4. Keep it readable — avoid overly saturated colors that strain the eyes.