Skip to main content
The detailed style and layout rules for authoring diagrams on this site. For the reader-facing summary and when to draw a diagram at all, see conventions/diagramming; for making diagram nodes navigable, see conventions/mermaid-links.

​
Diagram style

One diagram per concern. Do not combine.

​
The site theme

The site applies one theme to every diagram: the base theme with the look:'handDrawn' style, colored from the site’s color tokens. Diagrams follow the reader’s light or dark setting. So a diagram never carries its own %%{init} directive; the documentation standards (rule P11) reject one.

​
Shape vocabulary

  • Stadium ([Label]) for services and processes
  • Cylinder [(Label)] for data stores
  • Diamond {Label} for decisions / gates
  • Circle ((Label)) for endpoints / external actors
  • Hexagon {{Label}} for special-purpose nodes (use sparingly)
  • Subgraphs for things that physically or logically co-locate (a cluster, a host, a network, a repo group). Never for roles or phases

​
House node classes

Color nodes with the house classes below. The site defines them once and adds them to every flowchart, in light and dark. Assign one per node with class A,B hop or A:::hop. Never write a classDef in a diagram; the documentation standards (rule P15) reject one. A new kind of node gets a new house class, not a one-off color. Every class shares one fill and text color. The border color carries the meaning.

​
Canonical edge palette (indexed linkStyle)

​
Fun touches (consistent across the site)

Within the canonical palette, these are encouraged for personality:
  • Mix node shapes purposefully. Use stadiums for processes, cylinders for stores, diamonds for decisions, circles for external actors. Variety helps readers parse at a glance.
  • Short labels. claude process, not the Claude Code subprocess. Two lines max (use <br/> sparingly).
  • Edge labels are fine when they add information ("renew leases", "hands off", "applies"). Skip them when the chain is obvious.
  • FontAwesome icons in node labels where they reinforce the shape: [fa:fa-shield Security], [fa:fa-server Host]. Stick to filled variants for visual weight.

​
Mermaid layout rules

Before emitting any mermaid block, run the four checks below. If a diagram fails ANY check, redesign it before writing the fence.

​
Rule 1 · One narrative shape per diagram

Decide which of these four shapes the data IS, then commit to it. If you can’t pick one, you have two concerns. Split into two diagrams.
  • LINEAR CHAIN: A → B → C → D → E. Use flowchart LR. No subgraphs for “roles” or “phases” (they always cause zigzag). To show role/owner, color nodes with the house classes. Don’t put them in columns.
  • PARALLEL CONVERGENCE: two chains that join at the end. Use flowchart LR. Declare the longer chain first (its nodes appear higher in source). ELK ranks the shorter chain on the second row.
  • HIERARCHY / TREE: a parent with grouped children. Use flowchart TB. Children grouped in subgraphs with direction LR. Cap subgraph contents at 5 nodes; overflow gets a second subgraph at the same rank.
  • HUB AND SPOKES: one central node connected to 4–8 leaves. Use flowchart LR, put leaves in a single subgraph with direction TB. Do not draw all edges from hub. Chain leaves inside the subgraph with invisible ~~~ links so they stack, then one edge hub → first leaf.

​
Rule 2 · Subgraphs are for THINGS that live together, not for ROLES

Subgraphs add a visual box. If the box doesn’t represent something that physically or logically co-locates, do NOT make it a subgraph.
  • Forbidden subgraph names: Human, AI, Automation, Phase 1, any role or temporal phase. A workflow that hands off Human → AI → Human → AI draws a zigzag because arrows cross subgraph boundaries N times; visual complexity goes O(n) → O(n²).
  • Allowed subgraph names, for actual co-location: Proxmox cluster, Cribl tier, UniFi network, AWS DR, Edge, Infrastructure, Configuration, Nix, AI Development, Observability.
  • For role/owner: color the nodes with the house classes. The chain stays linear.

​
Rule 3 · Density caps: measured, not vibed

  • Max 5 nodes per rank (per LR column or TB row).
  • Max 5 nodes inside any single subgraph. 6+ → split into two subgraphs at the same rank.
  • Max 12 nodes per diagram total. Past 12, you have two diagrams.
  • Max ONE subgraph boundary per edge. An edge that crosses two boundaries means a subgraph is in the wrong place; reorder source declarations until each edge crosses ≤1 boundary.
Aspect-ratio sanity check (mentally render before emitting):
  • Wider than 2.5:1 → outer direction is wrong (use TB instead)
  • Taller than 1:1.2 → too many siblings somewhere (cap at 5)
  • Goal: between 16:9 and 4:3.

​
Rule 4 · House classes always, linkStyle by index

  • Never emit per-node style statements. Always use a house class. A diagram with 8 identical style X fill:... lines is a code smell. The 8 nodes share a category; give them a class.
  • Never emit a global linkStyle default stroke:#E06B4A. It paints every edge the same color and throws away semantic differentiation. Color edges by what they represent, using indexed linkStyle:
Edge index = declaration order, zero-based. Count carefully. Standard edge palette for this site:

​
Self-check before emitting

  • Diagram is one of the four shapes (chain / convergence / hierarchy / hub)
  • No subgraph is named for a role (Human, AI, Phase 1, etc.)
  • Every rank ≤5 nodes, every subgraph ≤5 nodes, total ≤12
  • Every edge crosses ≤1 subgraph boundary
  • Zero style and classDef statements; all visual grouping via the house classes
  • Zero linkStyle default; edges colored by semantic category
  • Mentally rendered aspect ratio between 4:3 and 16:9
If ANY box is unchecked, redesign before responding. Show the self-check as a comment block ABOVE the mermaid fence so a human can verify your reasoning:

​
When NOT to use Mermaid

If the content is a flat list, a comparison, or sequential steps without branching, prefer the native Mintlify primitive instead. Mermaid is for shapes; tables and Steps are for everything else.