/excalidraw-diagram-skill

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

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.

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

| Bad (Displaying) | Good (Arguing) | |------------------|----------------| | 5 equal boxes with labels | Each concept has a shape that mirrors its behavior | | Card grid layout | Visual structure matches conceptual structure | | Icons decorating text | Shapes that ARE the meaning | | Same container for everything | Distinct visual vocabulary per concept | | Everything in a box | Free-floating text with selective containers |

Simple vs Comprehensive (Know Which You Need)

| Simple Diagram | Comprehensive Diagram | |----------------|--------------------