Diagramming with Excalidraw
Generate valid .excalidraw JSON files.
File Format
{ "type": "excalidraw", "version": 2, "source": "https://excalidraw.com", "elements": [], "appState": { "viewBackgroundColor": "#ffffff" }, "files": {} }
Field Type Description
type
string Always "excalidraw"
version
number Schema version (currently 2 )
source
string Origin URL
elements
array All diagram elements
appState
object Canvas settings (background, etc.)
files
object Binary files keyed by fileId (images)
Workflow
-
Plan - Choose diagram type, layout, colors
-
Generate - Create elements with proper structure
-
Validate - Check bindings and structure before writing
Validation Checklist
Before writing a diagram, verify:
Bindings
-
Arrows connecting shapes have both startBinding and endBinding set
-
Arrow x,y sits at the source shape's edge, not floating in space
-
Shapes list connected arrows in their boundElements (bidirectional)
-
Text labels have containerId pointing to their container
-
Containers have boundElements referencing their text
Polygons
-
Polygon labels use groupIds (not containerId )
-
Text positioned manually at polygon center
-
Polygons cannot have arrow bindings - bind to grouped text label instead
-
Polygon's boundElements must be null
Layout
-
Elements don't overlap unexpectedly
-
Arrows route around shapes, not through them
-
Minimum 40px between sibling elements
-
All IDs are unique
-
Label text matches actual names (verify spelling)
Text
-
Use standard font sizes: S (16), M (20), L (28), XL (36)
-
Bound text: set containerId , textAlign: "center" , verticalAlign: "middle"
-
Position bound text at container center; Excalidraw adjusts automatically
Frames (presentations only)
- Frames are slides/artboards, not for grouping elements in a single diagram
Reference Index
Load references progressively based on need:
Elements
Reference Load When
shapes.md Using rectangles, diamonds, ellipses
text.md Adding labels, fonts, text styling
linear.md Creating arrows, lines, bindings
freedraw.md Hand-drawn paths
images.md Embedding images
frames.md Slides/artboards for presentations
polygons.md Custom polygon shapes
Styling
Reference Load When
fill-stroke.md Fill patterns, strokes
colors.md Color palette selection
positioning.md Layout, alignment, spacing
grouping.md Groups, z-ordering