Skip to content

Diagrams

"A diagram should feel like a note on a whiteboard — clear, calm, informative. Not a neon billboard."

Philosophy

Diagrams are light islands on a dark page — like a whiteboard pinned to a dark wall. White nodes, soft grey borders, thin muted connectors. Semantic colours only where meaningful (green=success, red=error). No emojis in nodes.

Reference: Stripe Docs — Quotes

🔴 Guardrails (Non-negotiable)

  1. No inline style or classDef in Mermaid markdown — the theme handles all colours
  2. No emojis in node labels — text only, clean and scannable
  3. No neon colours — #66ffff, #ff66ff, #39ff14 are permanently banned
  4. Light canvas always — diagrams are light even on dark pages (whiteboard effect)
  5. All diagrams must look identical — same container, same node style, same connector weight

How It Works (Implemented)

Mermaid Theme (baseof.html)

The theme produces white nodes with dark grey text on any page:

Nodes:    white fill (#FFFFFF), subtle border (#E5E5E5), dark text (#414552)
Lines:    light grey (#C4C8D0), smooth curves (basis)
Clusters: light grey fill (#F5F5F5), subtle border (#E5E5E5)
Labels:   dark text (#414552) on #FAFAFA background

Container CSS

Every .mermaid element gets a light dot-grid canvas:

.mermaid {
  background: radial-gradient(circle, #D4D4D4 1px, transparent 1px);
  background-size: 24px 24px;
  background-color: #FAFAFA;
  border: 1px solid #E5E5E5;
  border-radius: 10px;
  padding: 2rem;
}

/* Rounded node corners — soft pills */
.mermaid .node rect,
.mermaid .node polygon {
  rx: 12 !important;
  ry: 12 !important;
}

Fullscreen Button

Every diagram gets a subtle ⛶ button (bottom-right, appears on hover). Uses native requestFullscreen() with iOS CSS fallback. Script: static/js/zt-diagram.js.

CSS Files

Selector File Covers
.content-body .mermaid style.css Default single pages
.lic-single-content pre.mermaid licensing.css Licensing plan pages
.zt-reading-body .mermaid zt-reading.css Blog reading layout

All three must stay in sync — same light canvas, same rounded corners.

Writing Mermaid Diagrams

Do

` ` `mermaid
flowchart LR
    A[Draft] --> B[Review]
    B --> C{Approved?}
    C -->|Yes| D[Published]
    C -->|No| E[Revise]
    E --> B
` ` `
  • Use flowchart TD for hierarchies, flowchart LR for processes
  • Keep nodes short — 3-5 words max
  • Use <br/> for line breaks (not \n)
  • Keep diagrams compact — 6-10 nodes ideal
  • Split complex flows into multiple smaller diagrams

Don't

  • ❌ style A fill:#... stroke:#... color:#... — theme handles this
  • ❌ classDef definitions — not needed
  • ❌ Emojis in node labels: ["🔐 Security"] → ["Security"]
  • ❌ \n for line breaks → use <br/> instead
  • ❌ Diagrams with 15+ nodes — break them up
  • ❌ color:#ffffff or any inline colour overrides

Result

White rounded nodes, thin grey arrows, on a light dot-grid canvas. Calm, scannable, professional — like Stripe Docs.