Skip to main content

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

Without Evidence

A box labeled “Event Stream”Viewers know events exist but not what they’re called or how they’re structured.

With Evidence

A code snippet showing:
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 TypeWhen to UseHow to Render
Code snippetsAPIs, integrations, implementation detailsDark rectangle + syntax-colored text
Data/JSON examplesData formats, schemas, payloadsDark rectangle + colored text
Event/step sequencesProtocols, workflows, lifecyclesTimeline pattern (line + dots + labels)
UI mockupsShowing actual output/resultsNested rectangles mimicking real UI
Real input contentShowing what goes IN to a systemRectangle with sample content visible
API/method namesReal function calls, endpointsUse 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)

[Server] ──> [Events] ──> [Client]
This tells you there are events, but nothing else.

​
With Evidence Artifacts (Good)

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

[Input] ──> [Transform] ──> [Output]

​
With Evidence Artifacts (Good)

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)

[Client] ──> [API] ──> [Response]

​
With Evidence Artifacts (Good)

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us