Excalidraw Diagram Creator

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

Setup: If the user asks you to set up this skill (renderer, dependencies, etc.), see README.md for instructions.

AY Automate Style Defaults (always apply unless told otherwise)

Visual style

roughness:   2          ← hand-drawn / sketchy (NOT clean/sharp) — boxes only
strokeWidth: 2          ← medium stroke weight
roundness:   {"type":3} ← rounded corners on all rectangles
fontFamily:  1          ← Virgil (handwritten font) — NOT mono, NOT sans

Boxes / shapes: strokeStyle: "dotted" + roughness: 2

Arrows / lines: strokeStyle: "solid" + roughness: 1 — arrows are clean, only boxes are dotted

Text rules

• Titles are free text — never wrap the title in a box. Just a plain text element above the diagram.
• Write titles in lowercase — "ralph loop", not "RALPH LOOP". Natural handwritten feel.
• Use line breaks inside node labels — split label and sub-label with \n
• Keep labels short and human — "reads files" not "file ingestion module"
• Write like you're explaining to a non-technical person
• Free-floating annotations are better than boxing everything

Color mode

• Dark (viewBackgroundColor: "#14141c") — internal docs, LinkedIn content, agent diagrams
• Light (viewBackgroundColor: "#f0edee") — client deliverables, onboarding, proposals
• Ask or infer from context. Default = dark.
• Colors come from references/color-palette.md.

Brand

Periwinkle #8182C1 is the accent. Never use generic blue #3b82f6 or any purple #7c3aed.

Output path: 008_Builds/excalidraw/output/{slug}.excalidraw

Render path: 008_Builds/excalidraw/output/{slug}.png

Render command:

cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py ../../../008_Builds/excalidraw/output/{slug}.excalidraw

Common use cases:

• Agent architecture maps (Claude → n8n → Supabase → client)
• Client onboarding flows (what we build, in what order)
• AI pipeline explainers (for LinkedIn content)
• Internal system diagrams (for engineers on client projects)
• Ralph loop / agentic flow diagrams
• Competitor / comparison maps
• GTM funnel visualizations

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.

To make this skill produce diagrams in your own brand style, edit color-palette.md. Everything else in this file is universal design methodology and Excalidraw best practices.

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.

Depth Assessment (Do This First)

Before designing, determine what level of detail this diagram needs:

Simple/Conceptual Diagrams

Use abstract shapes when:

• Explaining a mental model or philosophy
• The audience doesn't need technical specifics
• The concept IS the abstraction (e.g., "separation of concerns")

Comprehensive/Technical Diagrams

Use concrete examples when:

• Diagramming a real system, protocol, or architecture
• The diagram will be used to teach or explain (e.g., YouTube video)
• The audience needs to understand what things actually look like
• You're showing how multiple technologies integrate

For technical diagrams, you MUST include evidence artifacts (see below).

Research Mandate (For Technical Diagrams)

Before drawing anything technical, research the actual specifications.

If you're diagramming a protocol, API, or framework:

1. Look up the actual JSON/data formats
2. Find the real event names, method names, or API endpoints
3. Understand how the pieces actually connect
4. Use real terminology, not generic placeholders

Bad: "Protocol" → "Frontend" Good: "AG-UI streams events (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)" → "CopilotKit renders via createA2UIMessageRenderer()"

Research makes diagrams accurate AND educational.

Evidence Artifacts

Evidence artifacts are concrete examples that prove your diagram is accurate and help viewers learn. Include them in technical diagrams.

Types of evidence artifacts (choose what's relevant to your diagram):

Example: For a diagram about a streaming protocol, you might show:

• The actual event names from the spec (not just "Event 1", "Event 2")
• A code snippet showing how to connect
• What the streamed data actually looks like

Example: For a diagram about a data transformation pipeline:

• Show sample input data (actual format, not "Input")
• Show sample output data (actual format, not "Output")
• Show intermediate states if relevant

The key principle: show what things actually look like, not just what they're called.

Multi-Zoom Architecture

Comprehensive diagrams operate at multiple zoom levels simultaneously. Think of it like a map that shows both the country borders AND the street names.

Level 1: Summary Flow

A simplified overview showing the full pipeline or process at a glance. Often placed at the top or bottom of the diagram.

Example: Input → Processing → Output or Client → Server → Database

Level 2: Section Boundaries

Labeled regions that group related components. These create visual "rooms" that help viewers understand what belongs together.

Example: Grouping by responsibility (Backend / Frontend), by phase (Setup / Execution / Cleanup), or by team (User / System / External)

Level 3: Detail Inside Sections

Evidence artifacts, code snippets, and concrete examples within each section. This is where the educational value lives.

Example: Inside a "Backend" section, you might show the actual API response format, not just a box labeled "API Response"

For comprehensive diagrams, aim to include all three levels. The summary gives context, the sections organize, and the details teach.

Bad vs Good

Simple vs Comprehensive (Know Which You Need)