Large Diagrams

Section-by-section strategy for comprehensive technical diagrams

For comprehensive or technical diagrams, you must build the JSON one section at a time. This is a hard constraint—attempting to generate the entire file in a single pass will fail or produce poor quality results.

Why Section-by-Section?

There are three reasons this approach is mandatory:

1. Token limits: Claude has a ~32,000 token output limit per response. A comprehensive diagram easily exceeds that in one shot.
2. Quality: Generating everything at once leads to rushed decisions and inconsistent spacing.
3. Maintainability: Section-by-section JSON with descriptive IDs is far easier to debug and modify.

What NOT to do:

• Don’t generate the entire diagram in one response
• Don’t use a coding agent to generate the JSON (lacks context about skill rules)
• Don’t write a Python generator script (adds debugging complexity)

The Three-Phase Workflow

Planning Section Boundaries

Plan your sections around natural visual groupings from your diagram plan. A typical large diagram might split into:

Each section should be independently understandable: its elements, internal arrows, and any cross-references to adjacent sections should form a coherent unit.

Example: Section-by-Section Workflow

Here’s a concrete example of building a 4-section diagram:

Step 1: Create base file

# Create file with Section 1 (entry point)
touch diagram.excalidraw

# Add JSON wrapper + Section 1 elements:
# - Start ellipse (id: "start_ellipse", seed: 100001)
# - Trigger text (id: "trigger_text", seed: 100002)
# - Arrow to next section placeholder

Multi-Zoom Architecture

Comprehensive diagrams operate at multiple zoom levels simultaneously. For large diagrams, ensure you include all three levels:

Level 1: Summary Flow

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

Example: Input → Processing → Output or Client → Server → Database

Level 2: Section Boundaries

Labeled regions that group related components. These create visual “rooms” that help viewers understand what belongs together.

Example: Grouping by responsibility (Backend / Frontend), by phase (Setup / Execution / Cleanup), or by team (User / System / External)

Level 3: Detail Inside Sections

Evidence artifacts, code snippets, and concrete examples within each section. This is where the educational value lives.

Example: Inside a “Backend” section, show the actual API response format, not just a box labeled “API Response”

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

Troubleshooting

Arrow not connecting across sections

Check:

1. Arrow’s endBinding.elementId matches the target element’s id
2. Target element’s boundElements includes {"id": "arrow_id", "type": "arrow"}
3. Both elements exist in the elements array

Sections feel unbalanced

After adding all sections, adjust:

• Element sizes (width/height) to rebalance visual weight
• Spacing between sections (200-400px recommended)
• Font sizes for hierarchy consistency

Can't find where an element is defined

Use descriptive IDs! Search for the ID string in your JSON. If using random IDs like "x7k2m9", you’ll waste time hunting.

Next Steps

Render & Validate

Learn the mandatory render-view-fix loop

Element Templates

Copy-paste templates for all element types