Layout Principles - Excalidraw Diagram Skill

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

Identify the hero

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

Determine primary elements

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

Size supporting details

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

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

Choose the primary flow pattern

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

Establish the entry point

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

Trace the visual path

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

Add directional cues

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

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

Horizontal alignment

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

Vertical alignment

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

Center alignment

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

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

Draw an imaginary vertical line down the middle of the canvas
Estimate visual weight on each side (size × number of elements)
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

Get Started

Core Concepts

Design Methodology

Guides

​Hierarchy Through Scale

​Size Categories

​Example: API Request Flow

​Applying Scale Hierarchy

​Whitespace = Importance

​Whitespace Guidelines

​Before vs After: Whitespace

​Whitespace Techniques

Isolation

Grouping

Separation

Balance

​Flow Direction

​Primary Flow Patterns

​Left → Right Flow

​Top → Bottom Flow

​Radial Flow (Center → Out)

​Circular Flow

​Flow Direction Guidelines

​Connections Required

​Proximity ≠ Relationship

​Connection Types

​Arrow Guidelines

Start and End

Routing

Direction

Labels

​Line Guidelines (Non-Directional)

​Alignment and Grid

​Grid Snapping

​Alignment Principles

​Example: Aligned vs Misaligned

​Balanced Composition

​Visual Weight Distribution

Symmetrical Balance

Asymmetrical Balance

​Checking Balance

​Canvas Dimensions

​Recommended Canvas Sizes

​Multi-Zoom Architecture

​Level 1: Summary Flow

​Level 2: Section Boundaries

​Level 3: Detail Inside Sections

​Layout Checklist

​Anti-Patterns

​Equal Spacing Everywhere

​No Clear Entry Point

​Spaghetti Arrows

​Dead Ends and Orphans

​Overcrowding

Build docs developers (and LLMs) love

Hierarchy Through Scale

Size Categories

Example: API Request Flow

Applying Scale Hierarchy

Whitespace = Importance

Whitespace Guidelines

Before vs After: Whitespace

Whitespace Techniques

Flow Direction

Primary Flow Patterns

Left → Right Flow

Top → Bottom Flow

Radial Flow (Center → Out)

Circular Flow

Flow Direction Guidelines

Connections Required

Proximity ≠ Relationship

Connection Types

Arrow Guidelines

Line Guidelines (Non-Directional)

Alignment and Grid

Grid Snapping

Alignment Principles

Example: Aligned vs Misaligned

Balanced Composition

Visual Weight Distribution

Checking Balance

Canvas Dimensions

Recommended Canvas Sizes

Multi-Zoom Architecture

Level 1: Summary Flow

Level 2: Section Boundaries

Level 3: Detail Inside Sections

Layout Checklist

Anti-Patterns

Equal Spacing Everywhere

No Clear Entry Point

Spaghetti Arrows

Dead Ends and Orphans

Overcrowding