> ## 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.
# Evidence Artifacts
> Concrete examples that prove your diagram is accurate and help viewers learn. Essential for technical diagrams.
# Evidence Artifacts
Evidence artifacts are **concrete examples that prove your diagram is accurate and help viewers learn**. They're essential for comprehensive/technical diagrams.
Instead of just labeling a box "API Response," you show what the API response actually looks like.
## Why They Matter
Evidence artifacts transform a diagram from explanatory to educational:
A box labeled "Event Stream"
Viewers know events exist but not what they're called or how they're structured.
A code snippet showing:
```text theme={null}
RUN_STARTED
STATE_DELTA
A2UI_UPDATE
```
Viewers learn the actual event names and can recognize them in code.
**Key principle**: Show what things actually look like, not just what they're called.
## Types of Evidence Artifacts
Choose the artifact type based on what you're explaining:
| Artifact Type | When to Use | How to Render |
| ------------------------ | ------------------------------------------ | -------------------------------------------- |
| **Code snippets** | APIs, integrations, implementation details | Dark rectangle + syntax-colored text |
| **Data/JSON examples** | Data formats, schemas, payloads | Dark rectangle + colored text |
| **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 |
Refer to the color palette reference for the specific colors to use for evidence artifact backgrounds and text.
## Example 1: Streaming Protocol
For a diagram about a streaming protocol, you might show:
### Without Evidence Artifacts (Bad)
```text theme={null}
[Server] ──> [Events] ──> [Client]
```
This tells you there are events, but nothing else.
### With Evidence Artifacts (Good)
```text theme={null}
[AG-UI Runtime]
│
├─ Streams:
│ • RUN_STARTED
│ • STATE_DELTA
│ • A2UI_UPDATE
│
└──> [Frontend]
Renders via:
createA2UIMessageRenderer({
component: CustomUI
})
```
Now viewers learn:
* The actual event names from the spec
* The real API method to handle rendering
* How to connect these pieces in code
## Example 2: Data Transformation Pipeline
For a diagram about a data transformation pipeline:
### Without Evidence Artifacts (Bad)
```text theme={null}
[Input] ──> [Transform] ──> [Output]
```
### With Evidence Artifacts (Good)
```text theme={null}
Input:
{
"user": "alice",
"action": "click"
}
│
▼
[Enrichment Pipeline]
│
▼
Output:
{
"user": "alice",
"action": "click",
"timestamp": "2026-03-04T10:30:00Z",
"session_id": "abc123"
}
```
Now viewers learn:
* What the input format actually looks like
* What the output format actually looks like
* What fields get added during transformation
## Example 3: API Integration
For a diagram showing how to integrate with an API:
### Without Evidence Artifacts (Bad)
```text theme={null}
[Client] ──> [API] ──> [Response]
```
### With Evidence Artifacts (Good)
```text theme={null}
POST /api/v1/chat/completions
{
"model": "gpt-4",
"messages": [{
"role": "user",
"content": "Hello"
}]
}
│
▼
[OpenAI API]
│
▼
{
"id": "chatcmpl-123",
"choices": [{
"message": {
"role": "assistant",
"content": "Hi there!"
}
}]
}
```
Viewers now know:
* The actual endpoint path
* The exact request format
* The exact response structure
* Field names they'll encounter in code
## When to Include Evidence Artifacts
**Required for comprehensive diagrams that:**
* Diagram a real system, protocol, or architecture
* Will be used for teaching or documentation
* Show how technologies integrate
* Need to convey actual implementation details
**Optional for simple diagrams that:**
* Explain abstract concepts or mental models
* Are just high-level overviews
* Target audiences who already know the details
## Visual Rendering Guidelines
### Code Snippets & JSON Examples
Use dark rectangles with syntax-colored text:
* **Background**: Dark color from palette (evidence artifact background)
* **Text**: Syntax-colored using palette colors
* **Font**: Monospace (fontFamily: 3)
* **Padding**: Ensure text isn't cramped
### Event Sequences & Timelines
Use a timeline pattern:
* **Vertical or horizontal line** as the spine
* **Small dots (10-20px ellipses)** at intervals
* **Free-floating labels** beside each dot with real event/step names
* No boxes needed — lines + text is cleaner
### UI Mockups
Use nested rectangles:
* **Outer rectangle**: Represents the window/container
* **Inner elements**: Buttons, text fields, content areas
* **Labels**: Show actual UI text, not "Button 1", "Button 2"
## The Research Connection
Evidence artifacts require research. You can't include real event names or actual JSON formats without looking them up.
**Before creating evidence artifacts:**
1. **Find the official docs** — API references, protocol specs, SDK documentation
2. **Copy actual examples** — Don't invent plausible-looking formats
3. **Use real names** — Event names, method names, field names from the spec
4. **Verify accuracy** — Double-check that what you're showing matches reality
If you find yourself writing "exampleEvent1" or "getData()" — **stop**. Go research the real names.
## Quality Check
Ask yourself:
* ✅ Could a developer copy these event names into their code?
* ✅ Could someone recognize this JSON format in a real system?
* ✅ Are these the actual method/function names from the docs?
* ✅ Would this help someone implement or debug this system?
If you answer "no" to any of these, add more evidence artifacts or make them more specific.
## Next Steps
Once you understand evidence artifacts, learn how to structure them within your diagram using [Multi-Zoom Architecture](/concepts/multi-zoom).