technical-diagrams

Technical Diagrams

Mermaid is the standard for all technical diagrams in this project. It renders natively in GitHub, GitLab, MkDocs (with Material theme), and most modern documentation platforms.

This skill provides:

• Critical styling rules to ensure readability (especially color contrast)
• Quick reference examples for common diagram types
• Reference files for advanced syntax when building complex diagrams

Always wrap Mermaid code in fenced code blocks with the mermaid language identifier.

---

Why Mermaid

Native rendering — GitHub, GitLab, Notion, MkDocs, and Docusaurus render Mermaid blocks without plugins or build steps. No external image generation tools needed.

Text-based and diffable — Diagrams live alongside code in version control. Changes appear in pull request diffs, making reviews straightforward and history trackable.

No external tools — No Lucidchart exports, no draw.io XML files, no PNG screenshots that go stale. The diagram source is the single source of truth.

Maintainable — Updating a diagram means editing text, not wrestling with a GUI. Refactoring a component name? Find-and-replace works on diagrams too.

Consistent — A shared syntax produces visually consistent diagrams across all documentation, regardless of who authored them.

---

Critical Styling Rules

This is the most important section. Light text on light backgrounds is the most common Mermaid readability issue. Follow these rules strictly.

Rule 1: Always use dark text on nodes

Every node must have color:#000 (or another dark color like #1a1a1a, #333). Never use white, light gray, or any light-colored text.

Caveat — this assumes a light page. color:#000 is correct for GitHub and MkDocs light mode, but it is not self-sufficient on renderers that auto-switch themes — most notably MkDocs Material's dark (slate) scheme, which flips Mermaid's theme colors and turns this dark text light-on-light. When a diagram will render on a dark-capable site, pair this palette with the dark-mode companion stylesheet in Dark-mode rendering below. Do not "fix" it by switching to light text — that just inverts the problem.