> ## 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.
# Quality Checklist
> 27-item checklist for validating diagram quality before delivery
## 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.
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?
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")
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
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
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.
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
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?
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
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.
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
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
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.
Every relationship has an arrow or line
**Why 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
Clear visual path for the eye to follow
**Why 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)
Important elements are larger/more isolated
**Why 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.
`text` contains only readable words
**Why it matters:** The `text` property is what gets rendered. It must contain only the actual display text.
**What to check:**
```json theme={null}
// Good
{
"id": "myElement1",
"text": "Start",
"originalText": "Start"
}
// Bad - contains markup or formatting
{
"id": "myElement1",
"text": "**Start**",
"originalText": "**Start**"
}
```
`fontFamily: 3`
**Why 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
`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
`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)
Less than 30% of text elements should be inside containers
**Why 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](/reference/render-pipeline) for rendering instructions.
Diagram has been rendered and visually inspected
**How to render:**
```bash theme={null}
cd .claude/skills/excalidraw-diagram/references
uv run python render_excalidraw.py
```
Then use the Read tool to view the PNG.
All text fits within its container
**What 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
Shapes and text don't overlap unintentionally
**What 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
Similar elements have consistent spacing
**What 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
Arrows connect to intended elements without crossing others
**What 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
Text is legible in the rendered PNG
**What 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)
No large empty voids or overcrowded regions
**What 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.