/excalidraw-diagram

name: excalidraw-diagram
description: Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, agent systems, client deliverables, or any concept as a diagram. Triggers on phrases like "draw a diagram", "make an excalidraw", "visualize this system", "diagram this flow", "map this architecture", "show me how X connects to Y".

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):

| Artifact Type | When to Use | How to Render | |---------------|-------------|---------------| | **Code snippets** | APIs, integrations, implementation details | Dark rectangle + syntax-colored text (see color palette for evidence artifact colors) | | **Data/JSON examples** | Data formats, schemas, payloads | Dark rectangle + colored text (see color palette) | | **Event/step sequences** | Protocols, workflows, lifecycles | Timeline pattern (line + dots + labels) | | **UI mockups** | Showing actual output/results | Nested rectangles mimicking real UI | | **Real input content** | Showing what goes IN to a system | Rectangle with sample content visible | | **API/method names** | Real function calls, endpoints | Use