excalidraw-diagram

name	excalidraw-diagram
description	Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts with Radian Group branding.

Excalidraw Diagram Creator

Generate .excalidraw JSON files that argue visually, not just display information.

Quick Start

# Generate a diagram from description
python3 automation/diagram-generator.py "System architecture for automation workflow" --output diagrams/architecture

# Use Radian brand colors (default)
python3 automation/diagram-generator.py "API flow diagram" --brand radian --output diagrams/api-flow

Setup

First-time setup:

cd skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium

Customization

All colors and brand-specific styles live in one file: references/color-palette.md. Read it before generating any diagram and use it as the single source of truth for all color choices — shape fills, strokes, text colors, evidence artifact backgrounds, everything.

Radian Group Brand Colors:

• Primary: Engineering Blue #1E40AF
• Secondary: Construction Orange #EA580C
• Accent: Tech Green #059669
• Neutral: Slate grays

---

Core Philosophy

Diagrams should ARGUE, not DISPLAY.

A diagram isn't formatted text. It's a visual argument that shows relationships, causality, and flow that words alone can't express. The shape should BE the meaning.

The Isomorphism Test: If you removed all text, would the structure alone communicate the concept? If not, redesign.

The Education Test: Could someone learn something concrete from this diagram, or does it just label boxes? A good diagram teaches—it shows actual formats, real event names, concrete examples.

---

Design Process

Step 0: Assess Depth Required

Determine if this needs to be:

• Simple/Conceptual: Abstract shapes, labels, relationships
• Comprehensive/Technical: Concrete examples, code snippets, real data

Step 1: Understand Deeply

Read the content. For each concept, ask:

• What does this concept DO?
• What relationships exist between concepts?
• What's the core transformation or flow?

Step 2: Map Concepts to Patterns

If the concept...	Use this pattern
Spawns multiple outputs	Fan-out (radial arrows from center)
Combines inputs into one	Convergence (funnel, arrows merging)
Has hierarchy/nesting	Tree (lines + free-floating text)
Is a sequence of steps	Timeline (line + dots + free-floating labels)
Loops or improves continuously	Spiral/Cycle (arrow returning to start)
Transforms input to output	Assembly line (before → process → after)

Step 3: Use Radian Brand Colors

All colors from references/color-palette.md:

• Engineering Blue #1E40AF for primary elements
• Construction Orange #EA580C for secondary/warnings
• Tech Green #059669 for success/completion
• Slate grays for text and neutral elements

---

Container vs. Free-Floating Text

Not every piece of text needs a shape around it. Default to free-floating text. Add containers only when they serve a purpose.

Use a Container When...	Use Free-Floating Text When...
It's the focal point of a section	It's a label or description
It needs visual grouping with other elements	It's supporting detail or metadata
Arrows need to connect to it	It describes something nearby
The shape itself carries meaning	Typography alone creates sufficient hierarchy

---

Radian Brand Styling

Shape Colors

Purpose	Fill	Stroke
Primary	#DBEAFE	#1E40AF (Engineering Blue)
Secondary	#FED7AA	#EA580C (Construction Orange)
Success	#A7F3D0	#059669 (Tech Green)
Warning	#FEE2E2	#DC2626

Text Colors

Level	Color
Title	#1E40AF (Engineering Blue)
Subtitle	#EA580C (Construction Orange)
Body	#64748B (Slate 500)

Visual Style

• roughness: 0 — Clean, professional edges
• strokeWidth: 2 — Standard for shapes
• opacity: 100 — No transparency
• fontFamily: 3 — Clean font

---

JSON Structure

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}

Element Templates

See references/element-templates.md for copy-paste JSON templates.

---

Render & Validate

After generating the JSON, you MUST render it to PNG and verify:

cd skills/excalidraw-diagram/references
uv run python render_excalidraw.py /path/to/file.excalidraw

The Loop

1. Render & View — Run the render script, then view the PNG
2. Audit — Does it match your vision? Any text overflow? Overlaps?
3. Fix — Edit JSON to address issues
4. Re-render — Run again
5. Repeat — Until satisfied

---

Quality Checklist

• Uses Radian brand colors (Blue/Orange/Green)
• Each concept uses appropriate visual pattern
• Free-floating text preferred over containers
• All relationships have arrows or lines
• Clear visual flow
• Rendered to PNG and visually inspected
• No text overflow or overlaps
• Balanced composition

---

Integration with OpenClaw

Telegram Command

/diagram [description]

Example:

/diagram System architecture showing Radian Group automation workflow with n8n, Telegram bot, and AI agents

Output

• .excalidraw file — editable in Excalidraw
• .png file — ready to use in posts/tutorials

Location

Generated files are saved to:

• output/diagrams/ — for general diagrams
• output/github/posts/ — for GitHub blog posts