Skip to main content

​
Overview

Every diagram must pass this 27-item checklist before it’s considered complete. The checklist is organized into categories that match the diagram creation workflow.
Visual validation (items 21-27) requires rendering the diagram to PNG. You cannot complete the checklist from JSON alone.

​
Checklist Categories

​
Depth & Evidence (Check First for Technical Diagrams)

For technical diagrams (architectures, protocols, APIs, integrations), these items are mandatory. For simple/conceptual diagrams, items 2-4 may not apply.
1

Research done

Did you look up actual specs, formats, event names?Why it matters: Generic placeholders like “API” or “Event” don’t teach. Real names and formats make diagrams educational.What to check:
  • Are you using real method/function names from the docs?
  • Are event names, message types, or API endpoints actual values from the spec?
  • Did you verify the terminology against official documentation?
2

Evidence artifacts

Are there code snippets, JSON examples, or real data?Why it matters: Evidence artifacts prove accuracy and help viewers learn what things actually look like.What to check:
  • Code snippets showing real implementation patterns
  • JSON/data examples with actual field names and types
  • Sample input/output content (not just labels saying “Input” or “Output”)
  • Real UI mockups (not just boxes labeled “UI”)
3

Multi-zoom

Does it have summary flow + section boundaries + detail?Why it matters: Comprehensive diagrams operate at multiple zoom levels simultaneously, like a map showing both country borders and street names.What to check:
  • Level 1 (Summary): Simplified overview of the full process
  • Level 2 (Sections): Labeled regions grouping related components
  • Level 3 (Detail): Evidence artifacts and concrete examples within sections
4

Concrete over abstract

Real content shown, not just labeled boxes?Why it matters: “Process” in a box teaches nothing. Showing what the process actually does teaches.What to check:
  • For data transformations: show sample input AND output
  • For protocols: show actual message formats
  • For integrations: show real API requests/responses
  • For UIs: show what the interface actually displays
5

Educational value

Could someone learn something concrete from this?The test: If you showed this diagram to someone unfamiliar with the system, could they:
  • Understand the structure AND some details?
  • See what things actually look like (not just what they’re called)?
  • Walk away with concrete knowledge, not just a vague overview?
Failing examples:
  • “Input → Process → Output” with no detail
  • Boxes with generic labels and no context
  • Diagrams that just restate what a bullet list already said

​
Conceptual

These items ensure the diagram argues visually rather than just displaying labeled boxes.
1

Isomorphism

Does each visual structure mirror its concept’s behavior?The Isomorphism Test: If you removed all text, would the structure alone communicate the concept?What to check:
  • One-to-many concepts use fan-out (radial arrows from center)
  • Many-to-one concepts use convergence (funnel, arrows merging)
  • Hierarchies use tree structures (lines + text, not nested boxes)
  • Loops use cycles (arrow returning to start)
  • Transformations use assembly line (before → process → after)
  • Each shape choice reflects what the thing DOES, not just labels what it IS
2

Argument

Does the diagram SHOW something text alone couldn’t?Why it matters: If the diagram just repeats what the text says, delete it.What to check:
  • Does it reveal relationships that are hard to express in prose?
  • Does it show causality, flow, or dependencies visually?
  • Would removing the diagram make the concept harder to understand?
3

Variety

Does each major concept use a different visual pattern?Why it matters: Uniform cards or grids don’t distinguish concepts. Different patterns create meaning through form.What to check:
  • No more than 2 concepts should use the same pattern
  • Avoid “everything in equal boxes” or card grid layouts
  • Each section should look visually distinct based on what it represents
4

No uniform containers

Avoided card grids and equal boxes?Why it matters: Card grids are for displaying items of the same type. Most diagrams show relationships between different types.What to check:
  • Shapes vary in size based on importance
  • Different concept types use different shapes (ellipse vs rectangle vs diamond vs lines)
  • Avoided the temptation to put everything in same-sized boxes for “consistency”

​
Container Discipline

These items ensure you’re using containers purposefully, not automatically.
1

Minimal containers

Could any boxed element work as free-floating text instead?The container test: For each boxed element, ask “Would this work as free-floating text?” If yes, remove the container.What to check:
  • Section titles, subtitles, and labels should be free-floating (no boxes)
  • Descriptions and details should use typography for hierarchy, not containers
  • Only use containers when they serve a purpose: focal points, grouping, arrow targets, or when the shape carries meaning
  • Target: less than 30% of text elements should be inside containers
2

Lines as structure

Are tree/timeline patterns using lines + text rather than boxes?Why it matters: Lines create cleaner structure than nested boxes for hierarchies and sequences.What to check:
  • Timelines use a line + small dots (10-20px ellipses) + free-floating labels
  • Hierarchies use trunk + branch lines + free-floating text (not boxes)
  • No “boxes connected by lines” where just “lines + text” would work
3

Typography hierarchy

Are font size and color creating visual hierarchy (reducing need for boxes)?Why it matters: A 28px title doesn’t need a rectangle around it. Typography IS hierarchy.What to check:
  • Titles use larger font size (24-28px) and Title color from palette
  • Subtitles use medium size (18-20px) and Subtitle color
  • Details use standard size (16px) and Detail color
  • Containers are reserved for elements that actually need them (see item 10)

​
Structural

These items ensure the diagram’s structure supports understanding.
1

Connections

Every relationship has an arrow or lineWhy it matters: Position alone doesn’t show relationships. If A relates to B, there must be a visual connection.What to check:
  • Every dependency, flow, or relationship is explicitly drawn
  • Arrows have clear start and end points (using bindings)
  • No “implied” relationships based on proximity alone
2

Flow

Clear visual path for the eye to followWhy it matters: The viewer’s eye should move through the diagram in a logical order.What to check:
  • Sequences flow left→right or top→bottom
  • Hub-and-spoke patterns use radial flow from center
  • The most important element is visually dominant (size + whitespace)
  • There’s a clear entry point (where to start reading)
3

Hierarchy

Important elements are larger/more isolatedWhy it matters: Visual weight = conceptual importance.What to check:
  • Hero elements: 300×150 or larger
  • Primary elements: 180×90
  • Secondary elements: 120×60
  • Most important element has the most whitespace around it (200px+)

​
Technical

These items ensure valid Excalidraw JSON and proper configuration.
1

Text clean

text contains only readable wordsWhy it matters: The text property is what gets rendered. It must contain only the actual display text.What to check:
// Good
{
  "id": "myElement1",
  "text": "Start",
  "originalText": "Start"
}

// Bad - contains markup or formatting
{
  "id": "myElement1",
  "text": "**Start**",
  "originalText": "**Start**"
}
2

Font

fontFamily: 3Why it matters: Font family 3 is Excalidraw’s hand-drawn font, which matches the aesthetic.What to check:
  • All text elements have "fontFamily": 3
  • No elements using fontFamily 1 (Virgil) or 2 (Helvetica) unless explicitly intended
3

Roughness

roughness: 0 for clean/modern (unless hand-drawn style requested)Why it matters: Roughness controls the sketch-like wobble. Modern diagrams should be crisp.What to check:
  • "roughness": 0 for clean, technical diagrams
  • "roughness": 1 only if hand-drawn style was explicitly requested
4

Opacity

opacity: 100 for all elements (no transparency)Why it matters: Transparency makes diagrams look washed out. Use color, size, and stroke width for hierarchy instead.What to check:
  • All elements have "opacity": 100
  • No elements using partial transparency (less than 100)
5

Container ratio

Less than 30% of text elements should be inside containersWhy it matters: Too many containers creates visual clutter and weakens hierarchy.How to check:
  • Count total text elements
  • Count text elements with "type": "text" that have a corresponding container (rectangle, ellipse, diamond)
  • Ratio should be under 30%
If ratio is too high: Look for section titles, labels, and descriptions that could be free-floating.

​
Visual Validation (Render Required)

You MUST render the diagram to PNG and view it to complete these items. JSON inspection alone cannot validate visual quality.
See Render Pipeline for rendering instructions.
1

Rendered to PNG

Diagram has been rendered and visually inspectedHow to render:
cd .claude/skills/excalidraw-diagram/references
uv run python render_excalidraw.py <path-to-file.excalidraw>
Then use the Read tool to view the PNG.
2

No text overflow

All text fits within its containerWhat to check in the PNG:
  • No text is clipped at edges of rectangles/ellipses
  • Multi-line text has enough vertical space
  • Long labels don’t spill outside their shapes
How to fix: Increase container width and/or height in JSON
3

No overlapping elements

Shapes and text don’t overlap unintentionallyWhat to check in the PNG:
  • No text sitting on top of other text
  • No shapes covering other shapes (unless layering is intentional)
  • Free-floating labels are clearly anchored to one element, not ambiguous between two
How to fix: Adjust x and y coordinates to add spacing
4

Even spacing

Similar elements have consistent spacingWhat to check in the PNG:
  • Elements in a sequence (e.g., timeline) are evenly spaced
  • Gaps between sections are consistent
  • No awkward bunching in one area while other areas are sparse
How to fix: Calculate spacing as (total_width - sum_of_element_widths) / (num_elements + 1) and apply uniformly
5

Arrows land correctly

Arrows connect to intended elements without crossing othersWhat to check in the PNG:
  • Arrow start and end points attach to the correct shapes
  • Arrows don’t pass through unrelated elements
  • Curved arrows ("roundness": {"type": 2}) route around obstacles
How to fix:
  • Verify startBinding and endBinding reference correct element IDs
  • Add waypoints to points array to route around elements
  • Adjust arrow roundness to create clearer paths
6

Readable at export size

Text is legible in the rendered PNGWhat to check in the PNG:
  • All text is sharp and readable at the exported resolution
  • No text is too small to read comfortably
  • Minimum font size should be 16px for body text, 12px for labels
How to fix:
  • Increase fontSize in JSON
  • Re-render with higher --scale parameter (default is 2, try 3)
7

Balanced composition

No large empty voids or overcrowded regionsWhat to check in the PNG:
  • Visual weight is distributed across the canvas
  • No huge empty spaces next to cramped sections
  • The diagram feels centered and intentional, not accidentally lopsided
  • Important elements have breathing room (200px+ of whitespace)
How to fix:
  • Redistribute elements to balance left/right or top/bottom
  • Add more spacing in cramped areas
  • Consider if empty areas could be filled with evidence artifacts or supporting details

​
Render & Validate Loop

The visual validation items (21-27) cannot be completed in one pass. You must iterate: 
1. Render to PNG
2. View the PNG (use Read tool)
3. Audit against original vision (items 1-15)
4. Check for visual defects (items 21-27)
5. Fix issues in JSON
6. Re-render and re-view
7. Repeat until all items pass
Typically takes 2-4 iterations.

​
When to Stop

The loop is complete when:
  • All 27 checklist items pass
  • The rendered diagram matches your conceptual design
  • You’d be comfortable showing it without caveats

​
Quick Reference

First-time diagram creators: Focus on items 1, 6, 10, 13, and 21-27. These catch the most common issues.
Technical diagrams: Items 1-5 are mandatory. If you skip research and evidence artifacts, the diagram will be generic and unhelpful.
Simple/conceptual diagrams: Items 2-4 may not apply. Focus on items 6-9 (conceptual quality) instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us