Mermaid Diagram Skill

This skill provides guidance on creating beautiful, professional Mermaid diagrams that render correctly on GitHub and work well in both light and dark mode.

Core Principles

1. Use dark fills with light strokes — Ensures readability in both light and dark mode
2. Set subgraph fills to none — Allows subgraphs to adapt to any background
3. Use rounded shapes — ([text]) for stadium shapes, ((text)) for circles
4. No Font Awesome icons — GitHub doesn't support fa:fa-* icons, they render as text
5. Quote subgraph labels — Use subgraph Name["Label Text"] syntax
6. Define classDef styles at the top — Keep all styling together for maintainability
7. Render and self-check: auto-layout makes its own routing choices, so always preview the rendered image and iterate until the lines are easy to follow

Render, check, and iterate (do this every time)

Writing valid Mermaid is not the goal; producing a diagram a person can actually follow is. Mermaid's auto-layout (dagre) decides where nodes sit and how edges route, so a diagram that looks fine in source often renders as spaghetti. Always render it, look at it as a reader, and iterate before you ship.

1. Render to an image and open it. Mermaid-cli with a dark background mimics GitHub: