Render & Validate

The mandatory render-view-fix loop for polishing diagrams

You cannot judge a diagram from JSON alone. After generating or editing the Excalidraw JSON, you must render it to PNG, view the image, and fix what you see—in a loop until it’s right.

This is a core part of the workflow, not a final check.

Why This Is Mandatory

JSON shows you coordinates and IDs. The rendered image shows you:

• Whether text is clipped or overflowing
• Whether shapes overlap unintentionally
• Whether arrows land on the right elements
• Whether spacing is consistent
• Whether the composition is balanced
• Whether the visual hierarchy matches your intent

You will always find issues on first render. Budget for 2-4 iterations.

Setup (First Time Only)

If the render script hasn’t been set up yet:

You only need to do this once.

The Render-View-Fix Loop

When to Stop

The loop is done when:

Don’t stop after one pass just because there are no critical bugs. If the composition could be better, improve it.

Common Iteration Patterns

Iteration 1: Fix Critical Issues

First render usually reveals:

• Text clipping (most common)
• Major overlaps
• Broken arrow bindings

Fix these first.

Iteration 2: Improve Spacing

Second render shows:

• Uneven gaps between elements
• Sections that need more breathing room
• Elements that could be closer together

Adjust coordinates for better balance.

Iteration 3: Polish

Third render is for fine-tuning:

• Font size adjustments
• Minor alignment tweaks
• Final arrow routing improvements

Iteration 4: Final Check

Fourth render confirms everything looks good. If new issues appear, continue iterating.

Troubleshooting

Render script fails with 'uv: command not found'

Install uv first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then retry the setup steps.

Playwright chromium not found

Run the install command from the references directory:

cd ~/.claude/skills/excalidraw-diagram/references
uv run playwright install chromium

PNG looks different from expected

This is normal! The rendered output often reveals issues invisible in JSON. That’s exactly why this step is mandatory.

Follow the fix loop to address visual problems.

How do I know which coordinates to change?

Use the rendered PNG as a reference:

1. Note which elements need to move
2. Estimate the direction and distance (50px? 100px?)
3. Find those elements in JSON by their id
4. Adjust x/y coordinates
5. Re-render to verify

Trial and error is normal—that’s why you iterate.

Advanced: Batch Rendering

If you’re working on multiple diagrams, you can render them all at once:

cd ~/.claude/skills/excalidraw-diagram/references
for file in /path/to/diagrams/*.excalidraw; do
  uv run python render_excalidraw.py "$file"
done

This generates PNGs for all .excalidraw files in the directory.

Next Steps

Creating Diagrams

Review the full end-to-end workflow

Large Diagrams

Section-by-section strategy for complex diagrams

Quality Checklist

Complete checklist for diagram quality