Excalidraw Diagram Skill

Create diagrams by writing standard Excalidraw element JSON and saving as

.excalidraw

Workflow

1. Load this skill (you already did)
2. Write the elements JSON -- an array of Excalidraw element objects
3. Save the file using

   write_file

   to create a

   .excalidraw

   file
4. Optionally upload for a shareable link using

   scripts/upload.py

   via

   terminal

Saving a Diagram

Wrap your elements array in the standard

.excalidraw

write_file

{
  "type": "excalidraw",
  "version": 2,
  "source": "hermes-agent",
  "elements": [ ...your elements array here... ],
  "appState": {
    "viewBackgroundColor": "#ffffff"
  }
}

Save to any path, e.g.

~/diagrams/my_diagram.excalidraw

Uploading for a Shareable Link

Run the upload script (located in this skill's

scripts/

python skills/diagramming/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw

This uploads to excalidraw.com (no account needed) and prints a shareable URL. Requires the

cryptography

pip install cryptography

Element Format Reference

Required Fields (all elements)

type

id

x

y

width

height

Defaults (skip these -- they're applied automatically)

• strokeColor

  :

  "#1e1e1e"

• backgroundColor

  :

  "transparent"

• fillStyle

  :

  "solid"

• strokeWidth

  :

  2

• roughness

  :

  1

  (hand-drawn look)

• opacity

  :

  100

Canvas background is white.

Element Types

Rectangle:

{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }

• roundness: { "type": 3 }

  for rounded corners

• backgroundColor: "#a5d8ff"

  ,

  fillStyle: "solid"

  for filled

Ellipse:

{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }

Diamond:

{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }

Labeled shape (container binding) -- create a text element bound to the shape:

WARNING: Do NOT use

"label": { "text": "..." }

on shapes. This is NOT a valid Excalidraw property and will be silently ignored, producing blank shapes. You MUST use the container binding approach below.

The shape needs

boundElements

containerId

{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80,
  "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
  "boundElements": [{ "id": "t_r1", "type": "text" }] },
{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25,
  "text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "r1", "originalText": "Hello", "autoResize": true }

• Works on rectangle, ellipse, diamond
• Text is auto-centered by Excalidraw when

  containerId

  is set
• The text

  x

  /

  y

  /

  width

  /

  height

  are approximate -- Excalidraw recalculates them on load

• originalText

  should match

  text

• Always include

  fontFamily: 1

  (Virgil/hand-drawn font)

Labeled arrow -- same container binding approach:

{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow",
  "boundElements": [{ "id": "t_a1", "type": "text" }] },
{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20,
  "text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "a1", "originalText": "connects", "autoResize": true }

Standalone text (titles and annotations only -- no container):

{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20,
  "fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Hello", "autoResize": true }

• x

  is the LEFT edge. To center at position

  cx

  :

  x = cx - (text.length * fontSize * 0.5) / 2

• Do NOT rely on

  textAlign

  or

  width

  for positioning

Arrow:

{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow" }

• points

  :

  [dx, dy]

  offsets from element

  x

  ,

  y

• endArrowhead

  :

  null

  |

  "arrow"

  |

  "bar"

  |

  "dot"

  |

  "triangle"

• strokeStyle

  :

  "solid"

  (default) |

  "dashed"

  |

  "dotted"

Arrow Bindings (connect arrows to shapes)

{
  "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0,
  "points": [[0,0],[150,0]], "endArrowhead": "arrow",
  "startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] },
  "endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] }
}

fixedPoint

top=[0.5,0]

bottom=[0.5,1]

left=[0,0.5]

right=[1,0.5]

Drawing Order (z-order)

• Array order = z-order (first = back, last = front)
• Emit progressively: background zones → shape → its bound text → its arrows → next shape
• BAD: all rectangles, then all texts, then all arrows
• GOOD: bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ...
• Always place the bound text element immediately after its container shape

Sizing Guidelines

Font sizes:

• Minimum

  fontSize

  : 16 for body text, labels, descriptions
• Minimum

  fontSize

  : 20 for titles and headings
• Minimum

  fontSize

  : 14 for secondary annotations only (sparingly)
• NEVER use

  fontSize

  below 14

Element sizes:

• Minimum shape size: 120x60 for labeled rectangles/ellipses
• Leave 20-30px gaps between elements minimum
• Prefer fewer, larger elements over many tiny ones

Color Palette

See

references/colors.md

#a5d8ff

#b2f2bb

#ffd8a8

#d0bfff

#ffc9c9

#fff3bf

#c3fae8

Tips

• Use the color palette consistently across the diagram
• Text contrast is CRITICAL -- never use light gray on white backgrounds. Minimum text color on white:

  #757575

• Do NOT use emoji in text -- they don't render in Excalidraw's font
• For dark mode diagrams, see

  references/dark-mode.md

• For larger examples, see

  references/examples.md