excalidraw-diagram

# 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:**
```bash
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 actual names from docs, not placeholders |

**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 o