/excalidraw-mcp-diagramming

Canvas Layout Patterns

Load during Step 4 (Plan the Layout) when you need coordinate templates or are deciding which layout pattern to use. Each pattern includes validated starting coordinates for standard box size 230×160 with roughness: 0.

Pattern Selection

1. Vertical Flow

Best for: Layered architectures, multi-tier systems, anything where data moves top-to-bottom through distinct responsibility layers.

Title (y = -50, standalone text)

[Zone 1 background: x=0, y=0, height=260]
  [Box A: x=40, y=50]    [Box B: x=480, y=50]    [Box C: x=920, y=50]

[Zone 2 background: x=0, y=350, height=260]
  [Box D: x=40, y=400]   [Box E: x=480, y=400]

[Zone 3 background: x=0, y=700, height=260]
  [Box F: x=240, y=750]

Spacing rules:

• Column pitch (labeled arrows): 440px — box 230 + gap 210
• Column pitch (unlabeled arrows): 360px — box 230 + gap 130
• Row pitch: 350px — box 160 + gap 190
• Starting columns: x = 40, 480, 920
• Zone background: y = row_y − 50, height = box_height + 100
• Zone width: covers all columns + 60px right padding

Arrow style: Vertical arrows pointing downward. Cross-zone arrows use strokeStyle: "dashed".

2. Horizontal Pipeline

Best for: Data processing stages where input enters from the left and output exits to the right. ETL flows, transformation chains, streaming pipelines.

[Source: x=40] ──► [Transform 1: x=480] ──► [Transform 2: x=920] ──► [Output: x=1360]
All boxes at same y=200

Spacing rules:

• Column pitch: 440px (laborded arrows) or 360px (unlabeled)
• All boxes at the same y — do not vary row height in this pattern
• Annotations and side notes: place at y ± 200 (above or below the pipeline)
• Stage labels: standalone text at y = main_y + box_height + 30

Arrow style: Horizontal, left to right. Arrow text label appears at midpoint. Keep labels short (< 15 chars) or they clip in narrow gaps.

3. Hub and Spoke

Best for: Event buses, message brokers, API gateways that fan out to multiple consumers. Any pattern where one central component connects to many peers.

                    [Consumer A: x=540, y=40]
                            ▲
                            │
[Producer: x=40, y=300] ──► [Hub: x=380, y=300] ──► [Consumer B: x=720, y=300]
                            │
                            ▼
                    [Consumer C: x=540, y=560]

Coordinates:

• Hub centre: x=380, y=300
• Consumer A (top): x = hub_x + (hub_width/2) − 115, y = hub_y − 260
• Consumer C (bottom): same x, y = hub_y + 260
• Consumer B (right): x = hub_x + hub_width + 80, same y
• Producer (left): x = hub_x − producer_width − 80, same y

Arrow style: Radiate from hub edges. Use distinct strokeColor per consumer type to distinguish channels/topics. Label arrows with the event name or topic.

4. Data Flow Trace

Best for: Tracing a single parameter, request, or data object through architectural layers — showing how form changes at each boundary.

Three-column structure:

x ≤ -50        x: 60–360            x: 570+
Layer labels   Centre flow column   Data form annotations
(gray, sm)     (colored boxes)      (orange, sm)

Coordinates (validated for 5-layer trace):

Colour by layer role:

• Blue (#a5d8ff/#1971c2): user-facing API layers
• Purple (#eebefa/#9c36b5): internal processing layers
• Green (#b2f2bb/#2f9e44): execution layer / success outcomes
• Yellow (#fff3bf/#fab005): decision nodes
• Red (#ffc9c9/#e03131): expensive or error paths

WHY context box (optional, recommended for technical explanations): Place a grey-background rectangle at x=460, y=80 containing 3–4 text items:

• Problem description (red stroke #e03131)
• Why it is expensive or wrong (red stroke)
• Current gap (neutral)
• Solution (green stroke #2f9e44)

5. Tree (Hierarchy)

Best for: File system structures, org charts, concept taxonomies. Uses lines and free-floating text rather than boxes — this keeps it clean.

Root label (center top)
    │
    ├── Branch A label
    │       ├── Leaf A1 label
    │       └── Leaf A2 label
    └── Branch B label
            └── Leaf B1 label

Implementation:

• Use type: "line" elements for the trunk and branch connectors.
• Place type: "text" elements (no container) beside each node.
• Do not use rectangles — the tree structure reads cleaner without boxes.
• Font size: 16px for branches, 14px for leaves.

Sizing Rules (Summary)

Err on the side of more space. Diagrams that feel "too spread out" when planning almost always look right on screen. Tight diagrams hide arrow labels and look cluttered in screenshots.

6. Sequence Diagram

Best for: Actor-to-actor interactions, API call chains, authentication flows, request/response cycles. Anything where the order and direction of messages between named participants matters more than the topology.

Structure

  Actor A          Actor B          Actor C
  x=100            x=400            x=700
    │                │                │
    │──── req ──────►│                │      y=180
    │                │──── fwd ──────►│      y=260
    │                │◄─── resp ──────│      y=340
    │◄─── resp ──────│                │      y=420
    │                │                │

Coordinates (validated, standard 3-actor layout)

Spacing rules

• Column pitch: 300px — narrower than architecture diagrams because message arrows are horizontal and labels are short
• Message row pitch: 80px — tighter than architecture patterns; sequence diagrams are tall, not wide
• Lifeline start y: 120 (bottom edge of actor box + 20px gap)
• Lifeline end y: last_message_y + 100 (extend below final message)
• Actor columns: x = 100, 400, 700, 1000 … (add 300px per actor)

Actor box colours

Use the standard component colour for the actor's role:

• Human user / browser: #fff3bf / #f59e0b (yellow)
• Service / API: #d0bfff / #7048e8 (purple)
• Database: #b2f2bb / #2f9e44 (green)
• External system: #ffc9c9 / #e03131 (red)
• Auth / IdP: #ffe8cc / #fd7e14 (orange)

Message arrow colours

Example — 3-actor OAuth flow

Actors: User (x=100), App (x=400), Auth Server (x=700)

Messages (y spaced 80px apart from y=180):
  y=180  User ──► App      "Login request"
  y=260  App  ──► Auth     "Redirect + client_id"
  y=340  Auth ──► User     "Login page"
  y=420  User ──► Auth     "Credentials"
  y=500  Auth ──► App      "auth_code" (dashed — redirect)
  y=580  App  ──► Auth     "Exchange code"
  y=660  Auth ──► App      "access_token" (return, grey dashed)
  y=740  App  ──► User     "Authenticated session"

Batch order: actor boxes → lifelines → activation bars → message arrows (top to bottom) → fragment boxes (opt/loop) → standalone title.

Camera size guidance