> ## 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.

# 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:

<Steps>
  ### Install dependencies

  ```bash theme={null}
  cd ~/.claude/skills/excalidraw-diagram/references
  uv sync
  ```

  ### Install Chromium for Playwright

  ```bash theme={null}
  uv run playwright install chromium
  ```
</Steps>

You only need to do this once.

## The Render-View-Fix Loop

<Steps>
  ### Step 1: Render to PNG

  Run the render script with the path to your `.excalidraw` file:

  ```bash theme={null}
  cd ~/.claude/skills/excalidraw-diagram/references
  uv run python render_excalidraw.py /path/to/your/diagram.excalidraw
  ```

  This outputs a PNG file next to the `.excalidraw` file with the same name:

  * Input: `diagram.excalidraw`
  * Output: `diagram.png`

  <Tip>
    The script uses Playwright to load Excalidraw's official renderer, ensuring pixel-perfect output matching what users will see.
  </Tip>

  ### Step 2: View the PNG

  Use the Read tool to actually view the rendered image:

  ```bash theme={null}
  # In your conversation with the assistant:
  "Read the PNG at /path/to/your/diagram.png"
  ```

  The assistant will display the image so you can visually inspect it.

  ### Step 3: Audit Against Your Vision

  **Before looking for bugs**, compare the rendered result to what you designed. Ask:

  <AccordionGroup>
    <Accordion title="Does the visual structure match the conceptual structure?">
      * Did you plan a fan-out pattern? Is it actually fanning out?
      * Did you plan a timeline? Does it read as a timeline?
      * Does each section use the pattern you intended?
    </Accordion>

    <Accordion title="Does the eye flow through the diagram correctly?">
      * Is there a clear visual path?
      * Do arrows guide the eye in the intended order?
      * Are there any dead ends or confusing jumps?
    </Accordion>

    <Accordion title="Is the visual hierarchy correct?">
      * Are hero elements dominant?
      * Are supporting elements appropriately smaller?
      * Do font sizes create clear hierarchy?
    </Accordion>

    <Accordion title="For technical diagrams: are evidence artifacts readable?">
      * Can you read the code snippets?
      * Are data examples properly formatted?
      * Do real event names/API calls stand out?
    </Accordion>
  </AccordionGroup>

  ### Step 4: Check for Visual Defects

  Now look for specific visual problems:

  #### Text Issues

  * ✅ Text clipped by its container
  * ✅ Text overflowing beyond container edges
  * ✅ Text too small to read at the rendered size
  * ✅ Text overlapping other elements

  #### Shape & Arrow Issues

  * ✅ Shapes overlapping other shapes unintentionally
  * ✅ Arrows crossing through elements instead of routing around them
  * ✅ Arrows landing on the wrong element
  * ✅ Arrows pointing into empty space
  * ✅ Arrow bindings not visually connecting to intended elements

  #### Layout Issues

  * ✅ Labels floating ambiguously (not clearly anchored to what they describe)
  * ✅ Uneven spacing between elements that should be evenly spaced
  * ✅ Sections with too much whitespace next to cramped sections
  * ✅ Overall composition feels lopsided or unbalanced

  <Warning>
    Don't skip the visual inspection step. Issues that are invisible in JSON become obvious in the rendered image.
  </Warning>

  ### Step 5: Fix

  Edit the JSON to address everything you found. Common fixes:

  <Tabs>
    <Tab title="Text Clipping">
      **Problem:** Text is cut off inside a shape.

      **Fix:** Increase the shape's width and/or height:

      ```json theme={null}
      {
        "id": "my_rect",
        "type": "rectangle",
        "width": 180,  // Increase from 120
        "height": 90,  // Increase from 60
        // ...
      }
      ```
    </Tab>

    <Tab title="Element Overlap">
      **Problem:** Shapes or text overlap unintentionally.

      **Fix:** Adjust `x` and `y` coordinates to add spacing:

      ```json theme={null}
      // Move element 2 to the right
      {
        "id": "element2",
        "x": 400,  // Increase from 300
        "y": 100
        // ...
      }
      ```
    </Tab>

    <Tab title="Arrow Routing">
      **Problem:** Arrow crosses through other elements.

      **Fix:** Add waypoints to the arrow's `points` array to route around obstacles:

      ```json theme={null}
      {
        "id": "my_arrow",
        "type": "arrow",
        "points": [
          [0, 0],       // Start
          [100, 0],     // Waypoint 1 (go right)
          [100, 150],   // Waypoint 2 (go down)
          [200, 150]    // End
        ]
        // ...
      }
      ```
    </Tab>

    <Tab title="Floating Labels">
      **Problem:** Label isn't clearly associated with its element.

      **Fix:** Move the label closer to the element it describes:

      ```json theme={null}
      {
        "id": "label_text",
        "x": 305,  // Adjust to be near the element
        "y": 105,  // Slight offset for clarity
        // ...
      }
      ```
    </Tab>

    <Tab title="Unbalanced Composition">
      **Problem:** Diagram feels lopsided.

      **Fix:** Resize elements to rebalance visual weight:

      ```json theme={null}
      // Make hero element larger
      {
        "id": "hero_rect",
        "width": 300,  // Increase from 180
        "height": 150  // Increase from 90
      },
      // Make supporting elements smaller
      {
        "id": "support_rect",
        "width": 120,  // Decrease from 180
        "height": 60   // Decrease from 90
      }
      ```
    </Tab>
  </Tabs>

  ### Step 6: Re-render & Re-view

  Run the render script again:

  ```bash theme={null}
  cd ~/.claude/skills/excalidraw-diagram/references
  uv run python render_excalidraw.py /path/to/your/diagram.excalidraw
  ```

  Then view the updated PNG to see if your fixes worked.

  ### Step 7: Repeat

  Keep cycling through steps 2-6 until the diagram passes both:

  1. **Vision check** (Step 3): matches your conceptual design
  2. **Defect check** (Step 4): no visual issues

  Typically takes 2-4 iterations.
</Steps>

## When to Stop

The loop is done when:

<Checklist>
  * [ ] The rendered diagram matches the conceptual design from your planning
  * [ ] No text is clipped, overlapping, or unreadable
  * [ ] Arrows route cleanly and connect to the right elements
  * [ ] Spacing is consistent and the composition is balanced
  * [ ] You'd be comfortable showing it to someone without caveats
</Checklist>

**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

<AccordionGroup>
  <Accordion title="Render script fails with 'uv: command not found'">
    Install `uv` first:

    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```

    Then retry the setup steps.
  </Accordion>

  <Accordion title="Playwright chromium not found">
    Run the install command from the references directory:

    ```bash theme={null}
    cd ~/.claude/skills/excalidraw-diagram/references
    uv run playwright install chromium
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Advanced: Batch Rendering

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

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Creating Diagrams" icon="pencil" href="/guides/creating-diagrams">
    Review the full end-to-end workflow
  </Card>

  <Card title="Large Diagrams" icon="diagram-project" href="/guides/large-diagrams">
    Section-by-section strategy for complex diagrams
  </Card>

  <Card title="Quality Checklist" icon="clipboard-check" href="/reference/quality-checklist">
    Complete checklist for diagram quality
  </Card>
</CardGroup>