Excalidraw Diagram

Excalidraw Diagram is a community skill for creating and editing Excalidraw diagrams programmatically, covering diagram element creation, layout arrangement, style configuration, export handling, and collaborative editing integration for whiteboard-style technical diagrams.

What Is This?

Overview

Excalidraw Diagram provides patterns for generating hand-drawn style diagrams using the Excalidraw format. It covers element creation that builds shapes, text, arrows, and connectors through the Excalidraw JSON schema, layout arrangement that positions elements using grid alignment and automatic spacing algorithms, style configuration that applies colors, stroke widths, font families, and fill patterns to diagram elements, export handling that renders diagrams to PNG, SVG, or the native Excalidraw format, and collaborative integration that manages shared diagram state for multi-user editing. The skill enables developers to generate technical diagrams programmatically with the approachable hand-drawn aesthetic.

Who Should Use This

This skill serves developers generating architecture and flow diagrams from code or data, technical writers embedding diagrams in documentation, and teams using Excalidraw for collaborative design sessions.

Why Use It?

Problems It Solves

Creating diagrams manually is time-consuming and difficult to keep synchronized with changing system architecture. Formal diagramming tools produce stiff visuals that feel overly final for early design discussions. Diagram-as-code approaches using Mermaid or PlantUML have limited layout control and styling options. Sharing diagrams requires export and reimport workflows that lose editability.

Core Highlights

Element builder creates rectangles, ellipses, arrows, and text nodes with configurable properties. Layout engine positions elements on a grid with automatic spacing and alignment. Style manager applies consistent colors and stroke patterns across diagram elements. Export renderer outputs to PNG, SVG, or native Excalidraw JSON.

How to Use It?

Basic Usage

import json
import uuid

class ExcalidrawElement:
  def __init__(
    self,
    elem_type: str,
    x: int, y: int,
    width: int,
    height: int,
    text: str = ''
  ):
    self.data = {
      'id': str(
        uuid.uuid4()),
      'type': elem_type,
      'x': x, 'y': y,
      'width': width,
      'height': height,
      'strokeColor':
        '#000000',
      'backgroundColor':
        'transparent',
      'fillStyle':
        'hachure',
      'roughness': 1}
    if text:
      self.data[
        'text'] = text
      self.data[
        'fontSize'] = 20

class DiagramBuilder:
  def __init__(self):
    self.elements = []

  def add_box(
    self,
    x: int, y: int,
    w: int, h: int,
    label: str = ''
  ):
    box = ExcalidrawElement(
      'rectangle',
      x, y, w, h)
    self.elements\
      .append(box.data)
    if label:
      txt =\
        ExcalidrawElement(
          'text',
          x + 10,
          y + h // 3,
          w - 20, 30,
          text=label)
      self.elements\
        .append(txt.data)

  def export(
    self
  ) -> str:
    return json.dumps({
      'type':
        'excalidraw',
      'version': 2,
      'elements':
        self.elements},
      indent=2)

Real-World Examples

class ArchDiagram:
  def __init__(self):
    self.builder =\
      DiagramBuilder()
    self.y_offset = 0

  def add_layer(
    self,
    name: str,
    services:\
      list[str]
  ):
    box_w = 150
    gap = 30
    total_w = (
      len(services)
      * (box_w + gap))
    x = 50
    for svc in services:
      self.builder\
        .add_box(
          x,
          self.y_offset,
          box_w, 60,
          label=svc)
      x += box_w + gap
    self.y_offset += 100

  def render(self) -> str:
    return self.builder\
      .export()

diagram = ArchDiagram()
diagram.add_layer(
  'Frontend',
  ['Web App', 'Mobile'])
diagram.add_layer(
  'Backend',
  ['API', 'Auth',
   'Workers'])
print(diagram.render())

Advanced Tips

Use bound arrows with start and end binding properties that reference element IDs so arrows stay connected when elements are repositioned. Set roughness to 0 for clean lines or 2 for a more hand-drawn appearance depending on the diagram context. Group related elements using frame elements to create visual sections that can be moved together.

When to Use It?

Use Cases

Generate architecture diagrams from infrastructure code or service configuration files. Create flow diagrams that update automatically when the underlying workflow definition changes. Build a documentation pipeline that renders system diagrams from structured data sources.

Related Topics

Excalidraw, diagramming, architecture diagrams, diagram-as-code, SVG export, and technical documentation.

Important Notes

Requirements

Understanding of the Excalidraw JSON schema for element construction. Python or JavaScript runtime for programmatic diagram generation. Excalidraw application or compatible viewer for rendering the output files.

Usage Recommendations

Do: use consistent element sizing and spacing across diagrams for visual coherence. Store diagram source data in version control alongside the generated Excalidraw files. Include element IDs in arrow bindings to maintain connections during layout changes.

Don't: hardcode pixel positions without a layout algorithm which makes diagrams fragile to content changes. Generate diagrams with overlapping elements which reduces readability. Ignore the Excalidraw schema version field which affects how elements are interpreted by the viewer.

Limitations

Programmatic layout cannot match the quality of manually positioned diagrams for complex arrangements. Arrow routing does not automatically avoid crossing other elements without additional pathfinding logic. Text sizing and wrapping depends on font metrics that may vary across rendering environments.