6.1.1 Why Theming and Styling Matter
By default, Mermaid diagrams render with a neutral theme. While this is sufficient for technical drafts, production environments often require:
Theming controls global appearance.
Styling controls local customization.
Structure must always come first. Styling enhances communication.
6.1.2 Global Theme Configuration
Mermaid supports predefined themes:
To configure theme in JavaScript:
This changes the entire diagram appearance.
6.1.3 Setting Theme via Directive
Inside Mermaid code, you can use an initialization directive:
This is useful in Markdown environments where JS configuration is unavailable.
6.1.4 Custom Theme Variables
Mermaid allows overriding theme variables.
Example:
Key variables include:
This enables branding alignment.
6.1.5 Class-Based Styling (Flowcharts)
For fine-grained control, use classDef.
Syntax:
Example:
This visually separates layers.
6.1.6 Styling Multiple Nodes
You can apply a style to multiple nodes:
Grouping reduces redundancy.
6.1.7 Inline Node Styling
For one-off styling:
Use inline styling sparingly.
Prefer class-based styling for maintainability.
6.1.8 Styling Links
You can style links using linkStyle.
Example:
linkStyle 0 refers to the first defined link.
Useful for highlighting:
High-priority dependencies
6.1.9 Theming in Class Diagrams
Example:
Styling emphasizes domain importance.
6.1.10 Theming in Sequence Diagrams
Sequence diagrams support theme variables but limited inline styling.
Example:
For production documentation, ensure theme consistency across all diagram types.
6.1.11 Dark Mode Support
If your documentation site supports dark mode, use dynamic theme switching via JS:
This ensures accessibility.
6.1.12 Branding Example — Corporate Style
This aligns diagram visuals with enterprise branding.
6.1.13 Styling Best Practices
Keep color palette minimal
Maintain contrast for accessibility
Highlight only critical components
Ensure consistency across chapters
Good styling supports comprehension.
Over-styling creates distraction.
6.1.14 Refactoring Exercise (Hands-On)
Start simple:
Enhance with architectural styling:
Notice the visual hierarchy.
6.1.15 Common Mistakes
Using low-contrast color combinations
Inconsistent theme usage across diagrams
Styling before structural correctness
Overloading diagrams with decorative colors
Remember:
A clean monochrome diagram is better than a visually noisy one.
6.1.16 Accessibility Considerations
Ensure:
High contrast between text and background
Avoid color-only differentiation
Maintain readable font size
Test diagrams in dark and light modes
Professional documentation must be accessible.
6.1.17 Key Takeaways
Theming controls global appearance.
Styling controls local emphasis.
Mermaid supports:
Styling should enhance meaning, not replace structure.
In the next topic, we will explore Embedding in Markdown and Documentation Systems, where you will learn how to integrate Mermaid into real-world documentation workflows.
