> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/coleam00/excalidraw-diagram-skill/llms.txt
> Use this file to discover all available pages before exploring further.

# Depth Assessment

> Before designing, determine what level of detail your diagram needs. Simple vs Comprehensive.

# Depth Assessment

**Before designing any diagram, determine what level of detail it needs.**

This is the first decision you make — before research, before planning, before anything else. The depth determines everything that follows.

## The Two Categories

### 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")
* You want a quick overview or summary
* The audience already knows the details

**Time to explain**: \~30 seconds\
**What viewers learn**: The structure

### 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, documentation)
* The audience needs to understand what things actually look like
* You're showing how multiple technologies integrate
* You want the diagram itself to teach

**Time to explain**: \~2-3 minutes\
**What viewers learn**: The structure AND the details

<Warning>
  For technical diagrams, you **MUST include evidence artifacts**. See the [Evidence Artifacts](/concepts/evidence-artifacts) page.
</Warning>

## Decision Framework

Use this comparison table to decide which type you need:

| Aspect                | Simple Diagram                           | Comprehensive Diagram                                     |
| --------------------- | ---------------------------------------- | --------------------------------------------------------- |
| **Labels**            | Generic: "Input" → "Process" → "Output"  | Specific: shows what the input/output actually looks like |
| **Components**        | Named boxes: "API", "Database", "Client" | Named boxes + examples of actual requests/responses       |
| **Events**            | "Events" or "Messages" label             | Timeline with real event/message names from the spec      |
| **UI Elements**       | "UI" or "Dashboard" rectangle            | Mockup showing actual UI elements and content             |
| **Explanation time**  | \~30 seconds                             | \~2-3 minutes of teaching content                         |
| **Learning outcome**  | Viewer learns the structure              | Viewer learns the structure AND the details               |
| **Research required** | Minimal                                  | Extensive — look up actual specs                          |

## Examples

### Simple Diagram Example

Showing the concept of a feedback loop:

```text theme={null}
Input → Process → Output
  ↑                 ↓
  └─── Feedback ────┘
```

No specific technologies, no real data formats — just the abstract concept.

### Comprehensive Diagram Example

Showing a real streaming protocol integration:

```text theme={null}
CopilotKit Runtime
├─ AG-UI streams:
│  • RUN_STARTED
│  • STATE_DELTA  
│  • A2UI_UPDATE
│
└─> Frontend renders via:
    createA2UIMessageRenderer({
      component: CustomUI
    })
```

Real event names, actual API methods, concrete examples.

## When Comprehensive Is Required

<Note>
  If you're creating diagrams for:

  * **Documentation sites** → Comprehensive
  * **Educational content** → Comprehensive
  * **Architecture reviews** → Comprehensive
  * **Integration guides** → Comprehensive
  * **System design tutorials** → Comprehensive

  These contexts demand accuracy and teaching value.
</Note>

## The Research Mandate

**For comprehensive/technical diagrams, research the actual specifications before designing.**

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

<CardGroup cols={2}>
  <Card title="Bad" icon="xmark">
    "Protocol" → "Frontend"

    Generic, teaches nothing.
  </Card>

  <Card title="Good" icon="check">
    "AG-UI streams events (RUN\_STARTED, STATE\_DELTA, A2UI\_UPDATE)" → "CopilotKit renders via createA2UIMessageRenderer()"

    Specific, educational, accurate.
  </Card>
</CardGroup>

<Tip>
  **Research makes diagrams accurate AND educational.**

  When viewers see real event names and actual API calls, they learn what things actually look like — not just what they're conceptually called.
</Tip>

## Common Mistake

The most common mistake is creating a simple diagram when a comprehensive one is needed.

**Symptom**: Someone looks at your diagram and asks "But what does the data actually look like?" or "What's the real API method name?"

**Fix**: Go back and add evidence artifacts. Show concrete examples. Do the research.

## Next Steps

Once you've determined your diagram needs to be comprehensive:

1. Read [Evidence Artifacts](/concepts/evidence-artifacts) to understand what to include
2. Read [Multi-Zoom Architecture](/concepts/multi-zoom) to structure your diagram at multiple levels
3. Start with research before you design anything