Mermaid Styling Guide

Complete guide for styling Mermaid diagrams using CSS custom properties and theme variables

🎨 Mermaid Styling Guide

Complete guide for customizing Mermaid diagrams with CSS custom properties and theme configurations.

🚀 Quick Fix: CSS Custom Properties

The simplest way to style Mermaid diagrams is using CSS custom properties in your component:

.mermaid-container {
  // Essential text readability
  --text-color: #4f46e5;           // Text inside boxes
  
  // Arrow and connection styling
  --line-color: #6b7280;           // Arrows and connecting lines
  --edge-label-color: #374151;     // Text on arrows/connections  
  --edge-label-background: #f8fafc; // Background for arrow text
  --arrow-marker-color: #6b7280;   // Arrow heads/markers
  
  // Brand colors
  --mermaid-primary: #3b82f6;      // Primary brand color
  --mermaid-secondary: #8b5cf6;    // Secondary brand color
  
  // Status colors  
  --mermaid-success: #10b981;      // Success states
  --mermaid-warning: #f59e0b;      // Warning states
  --mermaid-error: #ef4444;        // Error states
  --mermaid-info: #06b6d4;         // Info states
}

✨ This approach:

✅ Works immediately - No complex CSS selectors
✅ Uses Mermaid's system - Leverages built-in custom properties
✅ Consistent across all diagrams - One place to control everything
✅ Easy to maintain - Change one variable, update everywhere

🎯 Core Styling Approach

Method 1: CSS Custom Properties (Recommended)

Simple and effective for most use cases:

.mermaid-container {
  --text-color: #1f2937;           // Text inside boxes
  --line-color: #6b7280;           // Lines and arrows
  --edge-label-color: #374151;     // Text on arrows (like "Click Button")
  --background-color: #ffffff;     // Box backgrounds
  --border-color: #d1d5db;         // Box borders
}

Method 2: Mermaid Configuration

For advanced theming with complete control:

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#ffffff',
    primaryTextColor: '#000000',
    primaryBorderColor: '#6b7280',
    lineColor: '#6b7280',
    secondaryColor: '#f8f9fa',
    tertiaryColor: '#e9ecef'
  }
});

📋 Complete CSS Variables Reference

Essential Variables

.mermaid-container {
  // TEXT COLORS - Most important for readability
  --text-color: #000000;              // Primary text color (inside boxes)
  --secondary-text-color: #6b7280;    // Secondary text (labels)
  --edge-label-color: #374151;        // Text ON arrows (like "Click Button")
  
  // BACKGROUND COLORS  
  --background-color: #ffffff;        // Main background
  --node-background: #ffffff;         // Box/node backgrounds
  --edge-background: #f9fafb;         // Label backgrounds
  
  // BORDER AND LINE COLORS
  --border-color: #d1d5db;            // Box borders
  --line-color: #6b7280;              // Connection lines
  --arrow-color: #6b7280;             // Arrow markers
  
  // BRAND COLORS
  --primary-color: #3b82f6;           // Primary brand
  --secondary-color: #8b5cf6;         // Secondary brand
  --accent-color: #06b6d4;            // Accent highlights
  
  // STATUS COLORS
  --success-color: #10b981;           // Success states
  --warning-color: #f59e0b;           // Warning states  
  --error-color: #ef4444;             // Error states
  --info-color: #06b6d4;              // Info states
}

Dark Mode Support

@media (prefers-color-scheme: dark) {
  .mermaid-container {
    --text-color: #ffffff;
    --secondary-text-color: #d1d5db;
    --background-color: #374151;
    --node-background: #1f2937;
    --edge-background: rgba(55, 65, 81, 0.8);
    --border-color: #6b7280;
    --line-color: #9ca3af;
    --arrow-color: #9ca3af;
  }
}

🎨 Ready-to-Use Themes

Professional Theme

.mermaid-container {
  --text-color: #1f2937;
  --line-color: #6b7280;
  --background-color: #ffffff;
  --border-color: #d1d5db;
  --primary-color: #3b82f6;
  --secondary-color: #6366f1;
}

High Contrast Theme

.mermaid-container {
  --text-color: #000000;
  --line-color: #374151;
  --background-color: #ffffff;
  --border-color: #000000;
  --primary-color: #1f2937;
}

Brand Theme Example

.mermaid-container {
  --text-color: #064e3b;           // Dark green text
  --line-color: #059669;           // Green connections
  --background-color: #ecfdf5;     // Light green backgrounds
  --border-color: #10b981;         // Green borders
  --primary-color: #10b981;        // Brand green
}

Minimalist Theme

.mermaid-container {
  --text-color: #374151;
  --line-color: #e5e7eb;
  --background-color: #ffffff;
  --border-color: #f3f4f6;
  --primary-color: #f9fafb;
}

🛠️ Advanced Configuration

Inline Theme Configuration

For specific diagrams with custom themes:

```mermaid Custom Branded Diagram
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#3b82f6',
    'primaryTextColor': '#1f2937',
    'primaryBorderColor': '#3b82f6',
    'lineColor': '#6b7280',
    'secondaryColor': '#f8f9fa',
    'tertiaryColor': '#e9ecef'
  }
}}%%
graph TD
    A[Your App] --> B[Your Service]
    B --> C[Your Database]


### Complete Theme Variables Reference

```javascript
// Complete list of available theme variables
{
  theme: 'base',
  themeVariables: {
    // Primary elements
    primaryColor: '#ffffff',           // Main background color
    primaryTextColor: '#000000',       // Text color inside nodes
    primaryBorderColor: '#6b7280',     // Border color for nodes
    
    // Secondary elements  
    secondaryColor: '#f8f9fa',         // Secondary background
    secondaryTextColor: '#6b7280',     // Secondary text
    secondaryBorderColor: '#d1d5db',   // Secondary borders
    
    // Tertiary elements
    tertiaryColor: '#e9ecef',          // Tertiary background
    tertiaryTextColor: '#9ca3af',      // Tertiary text
    tertiaryBorderColor: '#e5e7eb',    // Tertiary borders
    
    // Lines and connections
    lineColor: '#6b7280',              // All connecting lines
    
    // Background and layout
    background: '#ffffff',             // Overall background
    mainBkg: '#ffffff',               // Main background
    secondBkg: '#f8f9fa',             // Secondary background
    
    // Specific diagram colors
    cScale0: '#ffffff',               // Color scale 0
    cScale1: '#f8f9fa',               // Color scale 1  
    cScale2: '#e9ecef',               // Color scale 2
    
    // Git graph specific
    git0: '#ffffff',                  // Git branch color 0
    git1: '#f8f9fa',                  // Git branch color 1
    git2: '#e9ecef',                  // Git branch color 2
    gitBranchLabel0: '#000000',       // Git branch label color 0
    gitBranchLabel1: '#000000',       // Git branch label color 1
    gitBranchLabel2: '#000000',       // Git branch label color 2
    
    // Edge labels
    edgeLabelBackground: '#f9fafb'    // Background for edge labels
  }
}

💡 Best Practices

1. Start Simple

// Begin with just the essentials
.mermaid-container {
  --text-color: #000000;        // Fix text readability first
  --line-color: #6b7280;        // Then set connection colors
}

2. Use Design System Colors

// Integrate with your existing design tokens
.mermaid-container {
  --text-color: var(--gray-900);
  --line-color: var(--gray-500);
  --primary-color: var(--blue-600);
  --background-color: var(--white);
}

3. Test Both Themes

.mermaid-container {
  // Light theme (default)
  --text-color: #000000;
  --background-color: #ffffff;
  
  // Dark theme  
  @media (prefers-color-scheme: dark) {
    --text-color: #ffffff;
    --background-color: #374151;
  }
}

4. Brand Consistency

// Use your brand colors
.mermaid-container {
  --text-color: var(--brand-text);
  --primary-color: var(--brand-primary);
  --line-color: var(--brand-secondary);
}

🔧 Common Use Cases

Fix Text Readability (Most Common Issue)

.mermaid-container {
  --text-color: #4f46e5;  // Readable text inside boxes
}

Style Sequence Diagram Arrows & Labels

.mermaid-container {
  // For arrows like in your screenshot
  --line-color: #3b82f6;           // Blue arrows  
  --edge-label-color: #1e40af;     // Dark blue text ("Click Button", "POST /api/data")
  --edge-label-background: #eff6ff; // Light blue backgrounds for text
  --arrow-marker-color: #3b82f6;   // Blue arrow heads
}

Corporate Branding

.mermaid-container {
  --text-color: #1f2937;
  --primary-color: #your-brand-color;
  --line-color: #6b7280;
  --background-color: #ffffff;
}

High Contrast for Accessibility

.mermaid-container {
  --text-color: #000000;
  --background-color: #ffffff;
  --line-color: #374151;
  --border-color: #000000;
  --edge-label-color: #000000;
}

Sequence Diagram Arrows & Labels

.mermaid-container {
  // Control arrows and their text labels
  --line-color: #3b82f6;           // Blue arrows
  --edge-label-color: #1e40af;     // Dark blue text on arrows
  --edge-label-background: #eff6ff; // Light blue backgrounds
  --arrow-marker-color: #3b82f6;   // Blue arrow heads
}

Minimalist Style

.mermaid-container {
  --text-color: #374151;
  --line-color: #e5e7eb;
  --background-color: #fafafa;
  --border-color: #f3f4f6;
}

🎯 Quick Reference

Most Important Variables

Variable	Purpose	Recommended Value
`--text-color`	Text inside boxes	`#4f46e5` (readable)
`--line-color`	Lines and arrows	`#6b7280` (gray)
`--edge-label-color`	Text on arrows	`#374151` (dark gray)
`--background-color`	Box backgrounds	`#ffffff` (white)
`--border-color`	Box borders	`#d1d5db` (light gray)
`--edge-label-background`	Arrow text background	`#f8fafc` (subtle)

Color Palette Examples

Theme	Text	Lines	Background	Border
Professional	`#1f2937`	`#6b7280`	`#ffffff`	`#d1d5db`
High Contrast	`#000000`	`#374151`	`#ffffff`	`#000000`
Minimalist	`#374151`	`#e5e7eb`	`#fafafa`	`#f3f4f6`
Brand Blue	`#1e3a8a`	`#3b82f6`	`#eff6ff`	`#3b82f6`

⚡ Implementation Examples

In Angular Component

// mermaid-diagram.component.scss
.mermaid-container {
  --text-color: #000000;
  --line-color: #6b7280;
  
  // Responsive adjustments
  @media (max-width: 768px) {
    --text-color: #000000;  // Maintain readability on mobile
  }
}

In Global Styles

// styles.scss
:root {
  --mermaid-text: #000000;
  --mermaid-lines: #6b7280;
  --mermaid-bg: #ffffff;
}

.mermaid-container {
  --text-color: var(--mermaid-text);
  --line-color: var(--mermaid-lines);
  --background-color: var(--mermaid-bg);
}

Theme Switching

// In your component
switchTheme(theme: 'light' | 'dark' | 'brand') {
  const container = document.querySelector('.mermaid-container') as HTMLElement;
  
  switch(theme) {
    case 'light':
      container.style.setProperty('--text-color', '#000000');
      container.style.setProperty('--line-color', '#6b7280');
      break;
    case 'dark':
      container.style.setProperty('--text-color', '#ffffff');  
      container.style.setProperty('--line-color', '#9ca3af');
      break;
    case 'brand':
      container.style.setProperty('--text-color', '#1e3a8a');
      container.style.setProperty('--line-color', '#3b82f6');
      break;
  }
}

🔍 Troubleshooting

Text Not Visible?

// Add this to force text visibility
.mermaid-container {
  --text-color: #000000 !important;
}

Lines Too Light?

// Make connections more visible
.mermaid-container {
  --line-color: #374151;  // Darker gray
}

Inconsistent Across Diagram Types?

// Use CSS custom properties instead of complex selectors
.mermaid-container {
  --text-color: #000000;  // Works for all diagram types
}

💡 Pro Tips

Start with --text-color - Fix readability first
Use your design system colors - Reference existing CSS variables
Test both light and dark modes - Ensure accessibility
Keep it simple - CSS custom properties over complex selectors
Test all diagram types - Flowcharts, sequences, classes, etc.

📚 Resources

Test your themes: Mermaid Live Editor
Official theming: Mermaid Theming Guide
Color inspiration: Use your existing design system variables

✅ Quick Checklist

Text is readable (dark text on light backgrounds)
Lines are visible but not overwhelming (gray)
Consistent across all diagram types
Works in both light and dark modes
Matches your brand/design system
Tested in mermaid.live

🎉 Remember: Simple CSS custom properties solve 90% of styling needs! 🎨