Layout Principles

Guidelines for hierarchy, whitespace, flow direction, and connections that create clear, scannable diagrams

Layout isn’t decoration—it’s how you guide the viewer’s eye and communicate importance.

A well-laid-out diagram tells a visual story. The viewer should know where to start, where to look next, and what matters most.

---

Hierarchy Through Scale

Size communicates importance. Use consistent size categories to create visual hierarchy.

Size Categories

Category	Dimensions	Use Case	Visual Weight
Hero	300×150px	Visual anchor, most important element	Dominant
Primary	180×90px	Main concepts, key steps	Strong
Secondary	120×60px	Supporting details, sub-steps	Moderate
Small	60×40px	Minor details, markers	Subtle

The hero element should be 2-3x larger than primary elements. This creates immediate visual hierarchy.

Example: API Request Flow

┌───────────────────────────┐  ← Hero (300×150)
│   Central API Gateway     │     Most important
└───────────────────────────┘

  ┌──────────────┐  ┌──────────────┐  ← Primary (180×90)
  │ Auth Service │  │ Data Service │     Key components
  └──────────────┘  └──────────────┘

    ┌────────┐  ┌────────┐  ┌────────┐  ← Secondary (120×60)
    │ Cache  │  │ Logger │  │ Queue  │     Supporting
    └────────┘  └────────┘  └────────┘

      ●  ●  ●  ← Small (10-20px)
    Markers     Minor details

Applying Scale Hierarchy

1. Identify the hero

   What’s the single most important concept? Make it the largest element (300×150px).

2. Determine primary elements

   What are the 3-5 main concepts? Use primary size (180×90px).

3. Size supporting details

   Everything else uses secondary (120×60px) or small (60×40px or less).

4. Check contrast

   Ensure at least 1.5x size difference between hierarchy levels for clear distinction.

---

Whitespace = Importance

The most important element has the most empty space around it.

Whitespace Guidelines

Importance Level	Minimum Whitespace	Purpose
Hero element	200px+ on each side	Isolation creates dominance
Primary elements	100-150px	Clear breathing room
Secondary elements	60-80px	Comfortable spacing
Small/grouped elements	40-60px	Prevents crowding

If everything has equal spacing, nothing stands out. Vary whitespace to create hierarchy.

Before vs After: Whitespace

Bad (equal spacing):

┌────┐  ┌────┐  ┌────┐  ┌────┐
│ A  │  │ B  │  │ C  │  │ D  │  ← All equal spacing
└────┘  └────┘  └────┘  └────┘    No hierarchy

Good (varied spacing):

                ┌────────┐                 ← 200px whitespace
                │   B    │                   (hero element)
                └────────┘

  ┌────┐                        ┌────┐     ← 150px whitespace  
  │ A  │                        │ C  │       (primary elements)
  └────┘                        └────┘

        ┌───┐  ┌───┐  ┌───┐              ← 60px whitespace
        │ D │  │ E │  │ F │                (grouped secondary)
        └───┘  └───┘  └───┘

Whitespace Techniques

Isolation

Put 200px+ of empty space around the hero element to make it dominant

Grouping

Reduce whitespace between related elements (60px) to show they belong together

Separation

Use large gaps (150px+) to separate distinct sections or phases

Balance

Distribute whitespace evenly across the canvas to avoid lopsided composition

---

Flow Direction

Guide the eye through the diagram with deliberate flow patterns.

Primary Flow Patterns

Pattern	When to Use	Visual Signature
Left → Right	Sequences, processes, pipelines	Standard Western reading order
Top → Bottom	Hierarchies, timelines, cascading flows	Gravity and time
Radial (center → out)	Fan-out, hub-and-spoke, central triggers	Explosive/distributive
Circular	Loops, cycles, iterative processes	Continuous/repeating
Z-pattern	Multi-phase with returns	Reading flow with progression
F-pattern	Content-heavy with hierarchy	Natural scanning pattern

Left → Right Flow

Use for: Sequences, transformations, pipelines

Input → Process → Transform → Output

Best practices:

• Start on the left (entry point)
• Progress rightward through steps
• End on the right (completion)
• Use arrows to reinforce direction

Top → Bottom Flow

Use for: Hierarchies, timelines, dependencies

Parent
  ↓
Child 1
  ↓
Child 2
  ↓
Child 3

Best practices:

• Place the origin at the top
• Cascade downward through levels
• Use vertical arrows or lines
• Works well for tree structures

Radial Flow (Center → Out)

Use for: Fan-out, distribution, central hub

        Output 1
         ↗
    Hub  →  Output 2
         ↘
        Output 3

Best practices:

• Center is the focal point (largest)
• Radiating elements evenly spaced (30°-45° apart)
• Arrows emanate from center
• Good for showing “one source, many destinations”

Circular Flow

Use for: Loops, cycles, feedback

Step 1 → Step 2
  ↑        ↓
Step 4 ← Step 3

Best practices:

• Start at top-left (12 o’clock or 10 o’clock position)
• Progress clockwise
• Return arrow should be visually distinct (different color or dashed)
• Can add center label for cycle name

---

Flow Direction Guidelines

1. Choose the primary flow pattern

   Based on the concept’s nature (sequence, hierarchy, distribution, etc.)

2. Establish the entry point

   Where does the viewer’s eye land first? Usually top-left or center.

3. Trace the visual path

   Mentally follow the eye movement. There should be a clear narrative progression.

4. Add directional cues

   Use arrows, size progression, or color progression to reinforce flow.

5. Check for dead ends

   Every element should connect to the flow. No isolated orphans.

---

Connections Required

Position alone doesn’t show relationships. If A relates to B, there must be an arrow or line.

Proximity ≠ Relationship

Bad (proximity without connection):

┌────┐  ┌────┐  ← Are these related?
│ A  │  │ B  │    Unclear!
└────┘  └────┘

Good (explicit connection):

┌────┐  →  ┌────┐  ← Clear relationship
│ A  │     │ B  │
└────┘     └────┘

Connection Types

Connection	Element Type	Use Case
Arrow	type: "arrow"	Directional flow, causality, transformation
Line	type: "line"	Association, grouping, structure (non-directional)
Dashed arrow	strokeStyle: "dashed"	Optional flow, async, weak dependency
Dashed line	strokeStyle: "dashed"	Boundary, soft grouping, suggestion

Arrow Guidelines

Start and End

Every arrow must have clear start and end points. Use bindings to attach to shapes.

Routing

Arrows should route around elements, not through them. Use waypoints in the points array.

Direction

Arrow direction should match conceptual flow (cause → effect, input → output).

Labels

Label arrows when the relationship isn’t obvious (“triggers”, “validates”, “sends to”).

Line Guidelines (Non-Directional)

Use lines for:

• Tree structures (trunk and branches)
• Timelines (vertical or horizontal spine)
• Section dividers
• Grouping boundaries

Do NOT use lines for:

• Causal relationships (use arrows)
• Sequential flows (use arrows)
• Transformations (use arrows)

---

Alignment and Grid

Grid Snapping

"appState": {
  "gridSize": 20
}

Align elements to a 20px grid for:

• Consistent spacing
• Visual cleanliness
• Easier maintenance

Alignment Principles

1. Horizontal alignment

   Elements in the same conceptual row should align horizontally (same y coordinate).

2. Vertical alignment

   Elements in the same conceptual column should align vertically (same x coordinate).

3. Center alignment

   Related elements can center-align if they’re in a parent-child or hub-spoke relationship.

4. Even spacing

   Gaps between similar elements should be consistent (e.g., all 80px apart).

Example: Aligned vs Misaligned

Bad (misaligned):

┌────┐   ┌────┐
│ A  │ ┌────┐│  ← y-coordinates
└────┘ │ B  ││    don't match
       └────┘│
      ┌────┐ │
      │ C  │ │
      └────┘

Good (aligned):

┌────┐  ┌────┐  ┌────┐  ← All same y-coordinate
│ A  │  │ B  │  │ C  │    Horizontally aligned
└────┘  └────┘  └────┘

---

Balanced Composition

Visual Weight Distribution

A diagram should feel balanced across the canvas.

Symmetrical Balance

Equal visual weight on left and right. Use for comparisons and side-by-side layouts.

Asymmetrical Balance

Unequal but balanced weight. Use when one side is more important but composition needs balance.

Checking Balance

1. Draw an imaginary vertical line down the middle of the canvas
2. Estimate visual weight on each side (size × number of elements)
3. Adjust positioning if one side feels too heavy

Bad (lopsided):

┌────┐ ┌────┐ ┌────┐
│ A  │ │ B  │ │ C  │          ┌───┐  ← All weight on left
└────┘ └────┘ └────┘          │ D │
┌────┐ ┌────┐                 └───┘
│ E  │ │ F  │
└────┘ └────┘

Good (balanced):

┌────┐ ┌────┐          ┌────┐ ┌────┐
│ A  │ │ B  │          │ E  │ │ F  │
└────┘ └────┘          └────┘ └────┘
                                      ← Balanced
   ┌────┐     ┌────┐     ┌────┐
   │ C  │     │ D  │     │ G  │
   └────┘     └────┘     └────┘

---

Canvas Dimensions

Recommended Canvas Sizes

Diagram Complexity	Canvas Width	Canvas Height	Use Case
Simple	800-1200px	600-800px	Single concept, 3-5 elements
Medium	1400-1800px	800-1200px	Multi-concept, 6-12 elements
Complex	2000-3000px	1200-1800px	Comprehensive, 13+ elements
Very Large	3000-5000px	1800-2400px	Multi-section technical diagrams

Leave 100-200px of margin on all sides. Don’t crowd elements to the edge.

---

Multi-Zoom Architecture

Comprehensive diagrams operate at multiple zoom levels simultaneously.

Level 1: Summary Flow

A simplified overview showing the full pipeline or process at a glance. Often placed at the top or bottom.

Example:

Input → Processing → Output

Purpose: Give the viewer context before diving into details.

Level 2: Section Boundaries

Labeled regions that group related components. These create visual “rooms”.

Example:

┌─ Backend ──────────┐  ┌─ Frontend ─────────┐
│                    │  │                    │
│  [components]      │  │  [components]      │
│                    │  │                    │
└────────────────────┘  └────────────────────┘

Purpose: Help viewers understand what belongs together.

Level 3: Detail Inside Sections

Evidence artifacts, code snippets, and concrete examples within each section.

Example:

┌─ Backend ─────────────────────────────┐
│                                       │
│  ┌─ API Response ──────────────────┐ │
│  │ {                               │ │
│  │   "status": "success",         │ │
│  │   "data": { ... }              │ │
│  │ }                               │ │
│  └─────────────────────────────────┘ │
│                                       │
└───────────────────────────────────────┘

Purpose: This is where the educational value lives.

For comprehensive diagrams, aim to include all three levels. The summary gives context, the sections organize, and the details teach.

---

Layout Checklist

Hierarchy

• Hero element is 2-3x larger than primary elements
• Size differences between levels are at least 1.5x
• Most important element is visually dominant

Whitespace

• Hero element has 200px+ whitespace on all sides
• Primary elements have 100-150px spacing
• Related elements grouped with reduced spacing (60px)
• Large gaps (150px+) separate distinct sections

Flow

• Clear entry point (where eye lands first)
• Obvious visual path through the diagram
• Flow pattern matches concept (sequence, hierarchy, radial, circular)
• Arrows reinforce directional flow

Connections

• Every relationship has an explicit arrow or line
• Arrows route around elements, not through them
• Arrow direction matches conceptual flow
• No ambiguous proximity relationships

Alignment

• Elements snap to 20px grid
• Horizontal rows align vertically (same y)
• Vertical columns align horizontally (same x)
• Even spacing between similar elements

Balance

• Visual weight distributed across canvas
• No large empty voids
• No overcrowded regions
• Composition feels stable

---

Anti-Patterns

Equal Spacing Everywhere

Problem: No hierarchy, everything feels equally important

Fix: Vary whitespace based on importance

No Clear Entry Point

Problem: Viewer doesn’t know where to start

Fix: Use size, position, or visual isolation to establish entry point (usually top-left or center)

Spaghetti Arrows

Problem: Arrows crossing everywhere, routing through elements

Fix: Add waypoints to route arrows cleanly. Reorganize elements to minimize crossing.

Dead Ends and Orphans

Problem: Elements with no connections, isolated from the flow

Fix: Connect every element to the narrative, or remove it

Overcrowding

Problem: Too many elements crammed into too little space

Fix: Increase canvas size, use multi-zoom architecture, or split into multiple diagrams