> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/coleam00/excalidraw-diagram-skill/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```text theme={null}
┌───────────────────────────┐ ← 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
What's the single most important concept? Make it the largest element (300×150px).
What are the 3-5 main concepts? Use primary size (180×90px).
Everything else uses secondary (120×60px) or small (60×40px or less).
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):**
```text theme={null}
┌────┐ ┌────┐ ┌────┐ ┌────┐
│ A │ │ B │ │ C │ │ D │ ← All equal spacing
└────┘ └────┘ └────┘ └────┘ No hierarchy
```
**Good (varied spacing):**
```text theme={null}
┌────────┐ ← 200px whitespace
│ B │ (hero element)
└────────┘
┌────┐ ┌────┐ ← 150px whitespace
│ A │ │ C │ (primary elements)
└────┘ └────┘
┌───┐ ┌───┐ ┌───┐ ← 60px whitespace
│ D │ │ E │ │ F │ (grouped secondary)
└───┘ └───┘ └───┘
```
### Whitespace Techniques
Put 200px+ of empty space around the hero element to make it dominant
Reduce whitespace between related elements (60px) to show they belong together
Use large gaps (150px+) to separate distinct sections or phases
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
```text theme={null}
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
```text theme={null}
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
```text theme={null}
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
```text theme={null}
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
Based on the concept's nature (sequence, hierarchy, distribution, etc.)
Where does the viewer's eye land first? Usually top-left or center.
Mentally follow the eye movement. There should be a clear narrative progression.
Use arrows, size progression, or color progression to reinforce flow.
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):**
```text theme={null}
┌────┐ ┌────┐ ← Are these related?
│ A │ │ B │ Unclear!
└────┘ └────┘
```
**Good (explicit connection):**
```text theme={null}
┌────┐ → ┌────┐ ← 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
Every arrow must have clear start and end points. Use bindings to attach to shapes.
Arrows should route around elements, not through them. Use waypoints in the `points` array.
Arrow direction should match conceptual flow (cause → effect, input → output).
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
```json theme={null}
"appState": {
"gridSize": 20
}
```
Align elements to a 20px grid for:
* Consistent spacing
* Visual cleanliness
* Easier maintenance
### Alignment Principles
Elements in the same conceptual row should align horizontally (same `y` coordinate).
Elements in the same conceptual column should align vertically (same `x` coordinate).
Related elements can center-align if they're in a parent-child or hub-spoke relationship.
Gaps between similar elements should be consistent (e.g., all 80px apart).
### Example: Aligned vs Misaligned
**Bad (misaligned):**
```text theme={null}
┌────┐ ┌────┐
│ A │ ┌────┐│ ← y-coordinates
└────┘ │ B ││ don't match
└────┘│
┌────┐ │
│ C │ │
└────┘
```
**Good (aligned):**
```text theme={null}
┌────┐ ┌────┐ ┌────┐ ← All same y-coordinate
│ A │ │ B │ │ C │ Horizontally aligned
└────┘ └────┘ └────┘
```
***
## Balanced Composition
### Visual Weight Distribution
A diagram should feel **balanced** across the canvas.
Equal visual weight on left and right. Use for comparisons and side-by-side layouts.
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):**
```text theme={null}
┌────┐ ┌────┐ ┌────┐
│ A │ │ B │ │ C │ ┌───┐ ← All weight on left
└────┘ └────┘ └────┘ │ D │
┌────┐ ┌────┐ └───┘
│ E │ │ F │
└────┘ └────┘
```
**Good (balanced):**
```text theme={null}
┌────┐ ┌────┐ ┌────┐ ┌────┐
│ 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:**
```text theme={null}
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:**
```text theme={null}
┌─ 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:**
```text theme={null}
┌─ 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
* [ ] Hero element is 2-3x larger than primary elements
* [ ] Size differences between levels are at least 1.5x
* [ ] Most important element is visually dominant
* [ ] 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
* [ ] 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
* [ ] Every relationship has an explicit arrow or line
* [ ] Arrows route around elements, not through them
* [ ] Arrow direction matches conceptual flow
* [ ] No ambiguous proximity relationships
* [ ] Elements snap to 20px grid
* [ ] Horizontal rows align vertically (same y)
* [ ] Vertical columns align horizontally (same x)
* [ ] Even spacing between similar elements
* [ ] 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