Drawbridge

Drawbridge Diagram Skill

Generate hand-drawn style diagrams as Excalidraw JSON. Uses the simplified element format with convertToExcalidrawElements handling all the heavy lifting (text measurement, container binding, arrow routing).

Element Format (Simplified)

Only specify what matters. convertToExcalidrawElements fills in all required internal properties (groupIds, frameId, seeds, versions, etc.).

Required Fields (all elements)

type, id (unique string), x, y

Defaults (skip these)

strokeColor="#1e1e1e", backgroundColor="transparent", fillStyle="solid", strokeWidth=2, roughness=1, opacity=100

Labeled Shapes (PREFERRED)

Add label to any shape for auto-centered text. No separate text elements needed:

jsonCopy code
{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80,
  "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
  "label": { "text": "API Server", "fontSize": 20 } }

• Works on rectangle, ellipse, diamond
• Text auto-centers and container auto-resizes to fit
• Always include "roundness": { "type": 3 } for rounded corners

Standalone Text (titles, annotations only)

jsonCopy code
{ "type": "text", "id": "t1", "x": 150, "y": 50, "text": "System Architecture", "fontSize": 28 }

• x is the LEFT edge of the text
• To center text at position cx: x = cx - (text.length * fontSize * 0.5) / 2
• textAlign does NOT control horizontal position — it only affects multi-line wrapping

Arrows

jsonCopy code
{ "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"

Arrow Labels

Annotate arrows with text:

jsonCopy code
{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow",
  "label": { "text": "API call", "fontSize": 16 } }

Arrow Bindings

Bind arrows to shapes so they stay connected when shapes are moved. Use start and end with the target element's id:

jsonCopy code
{
  "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow",
  "start": { "id": "box1" },
  "end": { "id": "box2" }
}

IMPORTANT: Use start/end (skeleton format), NOT startBinding/endBinding (internal format). convertToExcalidrawElements resolves the bindings automatically, including setting up boundElements on the target shapes.

The binding point is calculated from the arrow's position relative to the shape. Position the arrow's x,y to start at the right edge of the source shape for a left-to-right connection.

Background Zones

Group related elements with low-opacity rectangles:

jsonCopy code
{ "type": "rectangle", "id": "zone1", "x": 80, "y": 80, "width": 540, "height": 400,
  "backgroundColor": "#d3f9d8", "fillStyle": "solid", "roundness": { "type": 3 },
  "strokeColor": "#22c55e", "strokeWidth": 1, "opacity": 35 }

Add a zone label as standalone text:

jsonCopy code
{ "type": "text", "id": "zone1-label", "x": 100, "y": 86, "text": "Frontend Layer",
  "fontSize": 16, "strokeColor": "#15803d" }

Color Palette

Primary Colors (strokes, text)

Fills (pastel, for shape backgrounds)

Background Zones (use with opacity: 30-35)

Sizing Rules

Font Sizes

• Minimum 16 for body text, labels, descriptions
• Minimum 20 for titles and headings
• Minimum 14 for secondary annotations only (sparingly)
• NEVER use fontSize below 14

Element Sizes

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

Drawing Order (CRITICAL)

Array order = z-order (first = back, last = front).

Emit progressively: background zone → shape → its arrows → next shape

• GOOD: zone → box1 → arrow1 → box2 → arrow2 → box3
• BAD: box1 → box2 → box3 → arrow1 → arrow2

This matters for streaming to the live viewer where elements appear one at a time.

Complete Examples

Two Connected Labeled Boxes

jsonCopy code
[
  { "type": "rectangle", "id": "b1", "x": 100, "y": 100, "width": 200, "height": 100,
    "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
    "label": { "text": "Start", "fontSize": 20 } },
  { "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0,
    "points": [[0,0],[150,0]], "endArrowhead": "arrow",
    "start": { "id": "b1" },
    "end": { "id": "b2" } },
  { "type": "rectangle", "id": "b2", "x": 450, "y": 100, "width": 200, "height": 100,
    "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid",
    "label": { "text": "End", "fontSize": 20 } }
]

System Architecture with Zones

jsonCopy code
[
  { "type": "text", "id": "title", "x": 200, "y": 10, "text": "System Architecture", "fontSize": 28 },
  { "type": "rectangle", "id": "zone-fe", "x": 80, "y": 60, "width": 300, "height": 200,
    "backgroundColor": "#dbe4ff", "fillStyle": "solid", "roundness": { "type": 3 },
    "strokeColor": "#4a9eed", "strokeWidth": 1, "opacity": 35 },
  { "type": "text", "id": "zone-fe-label", "x": 100, "y": 66, "text": "Frontend",
    "fontSize": 16, "strokeColor": "#1971c2" },
  { "type": "rectangle", "id": "app", "x": 120, "y": 100, "width": 200, "height": 80,
    "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
    "label": { "text": "React App", "fontSize": 20 } },
  { "type": "arrow", "id": "a1", "x": 320, "y": 140, "width": 150, "height": 0,
    "points": [[0,0],[150,0]], "endArrowhead": "arrow",
    "label": { "text": "REST API", "fontSize": 14 } },
  { "type": "rectangle", "id": "api", "x": 470, "y": 100, "width": 200, "height": 80,
    "roundness": { "type": 3 }, "backgroundColor": "#d0bfff", "fillStyle": "solid",
    "label": { "text": "API Server", "fontSize": 20 } }
]

Output Options

1. Push to Excalidraw Live (real-time)

Push elements to the live viewer via HTTP API:

bashCopy code
curl -s -X POST http://localhost:3062/api/session/SESSION_NAME/elements \
  -H "Content-Type: application/json" \
  -d '{"elements": [...]}'

Live viewer URL: http://localhost:3060/#SESSION_NAME (or your configured host)

API endpoints:

• POST /api/session/:id/elements — Replace all elements
• POST /api/session/:id/append — Add elements to existing
• POST /api/session/:id/clear — Clear canvas
• POST /api/session/:id/undo — Undo last operation
• GET /api/session/:id — Get current elements

2. Save as .excalidraw file

Wrap elements in the document structure:

jsonCopy code
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [ /* your elements array */ ],
  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": null },
  "files": {}
}

3. Render to SVG or PNG

bashCopy code
# From .excalidraw file (skeleton or resolved elements both work)
npx tsx scripts/render.ts input.excalidraw output.png
npx tsx scripts/render.ts input.excalidraw output.svg

# From a live session
curl -s http://localhost:3062/api/session/SESSION_NAME | \
  python3 -c "import json,sys; d=json.load(sys.stdin); json.dump({'type':'excalidraw','version':2,'source':'https://excalidraw.com','elements':d['elements'],'appState':{'viewBackgroundColor':'#ffffff','gridSize':None},'files':{}}, open('/tmp/diagram.excalidraw','w'))"
npx tsx scripts/render.ts /tmp/diagram.excalidraw /tmp/diagram.png

Uses headless Chromium + Excalidraw 0.18. Handles skeleton elements (with label, start/end) automatically via convertToExcalidrawElements. Takes ~5-8 seconds.

Generation Workflow

1. Plan layout — Decide zones, flow direction, element grouping
2. Generate elements — Follow progressive drawing order
3. Push to live viewer — For real-time review with user
4. Render to PNG/SVG — For embedding in docs, reports, or sharing