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

# Quickstart

> Create your first Excalidraw diagram in under 2 minutes using natural language descriptions.

This guide will get you from zero to your first working diagram as quickly as possible.

## Your First Diagram

Once the skill is installed, ask your coding agent to create a diagram:

```text theme={null}
Create an Excalidraw diagram showing how a streaming protocol sends events from a backend to a frontend
```

The agent will:

1. **Analyze** the concept and map it to visual patterns
2. **Generate** Excalidraw JSON with appropriate shapes and flows
3. **Render** the diagram to PNG using the render pipeline
4. **View** the rendered image to check for issues
5. **Fix** any layout problems (overlaps, clipping, misalignments)
6. **Re-render** and repeat until the diagram looks right

You'll receive a `.excalidraw` file and a `.png` file.

<Tip>
  The render-view-fix loop is automatic and mandatory — every diagram is visually validated before delivery.
</Tip>

## Example: Simple Conceptual Diagram

For a simple, high-level diagram:

```text theme={null}
Create a diagram showing the difference between diagrams that "display" information vs diagrams that "argue" visually
```

The agent will create a side-by-side comparison using abstract shapes and visual contrast.

## Example: Comprehensive Technical Diagram

For a detailed technical diagram with real examples:

```text theme={null}
Create a comprehensive diagram of the AG-UI protocol showing:
- How events stream from an AI agent to a frontend UI
- Real event names from the specification
- Actual code snippets for connecting
- Sample JSON payloads
```

The agent will:

* Research the actual AG-UI protocol specification
* Include real event names (e.g., `RUN_STARTED`, `STATE_DELTA`, `A2UI_UPDATE`)
* Add code snippets showing how to use the protocol
* Display sample JSON payloads with proper formatting
* Create a multi-zoom diagram with summary flow, section boundaries, and detailed evidence artifacts

<Note>
  For technical diagrams, the agent **must research actual specifications** before generating JSON. This ensures diagrams are accurate and educational.
</Note>

## Understanding the Output

### The `.excalidraw` File

This is the editable source — a JSON file you can open in [Excalidraw](https://excalidraw.com) to make manual adjustments if needed.

```json theme={null}
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    // All shapes, arrows, text elements
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}
```

### The `.png` File

This is the rendered output — a publication-ready image you can embed in documentation, slides, or articles.

## What Makes These Diagrams Different

<Steps>
  <Step title="Visual Patterns Mirror Concepts">
    Instead of uniform boxes, each concept gets a shape that reflects its behavior:

    * Fan-outs for one-to-many relationships
    * Convergence for aggregation
    * Timelines for sequences
    * Spirals for loops
  </Step>

  <Step title="Real Examples, Not Placeholders">
    Technical diagrams include:

    * Actual code snippets with syntax highlighting
    * Real event names from specifications
    * Sample JSON payloads
    * Concrete examples instead of generic labels
  </Step>

  <Step title="Visual Validation Built-In">
    Every diagram is:

    * Rendered to PNG
    * Inspected by the agent for overlaps, clipping, and spacing issues
    * Fixed and re-rendered in a loop
    * Delivered only when it passes visual validation
  </Step>
</Steps>

## Common Patterns

Here are some common diagram requests and what the agent will create:

<AccordionGroup>
  <Accordion title="Architecture Diagrams">
    ```
    Create a diagram of our microservices architecture showing:
    - Service boundaries
    - API contracts between services
    - Data flow
    - Include real endpoint paths and request/response formats
    ```

    The agent will create a comprehensive diagram with actual API payloads and clear service boundaries.
  </Accordion>

  <Accordion title="Data Flow Diagrams">
    ```
    Show how user data flows through our analytics pipeline:
    - Raw input format
    - Transformation steps
    - Final output structure
    - Include sample data at each stage
    ```

    The agent will use an assembly-line pattern with before/after examples at each transformation.
  </Accordion>

  <Accordion title="State Machine Diagrams">
    ```
    Create a diagram of our order processing state machine:
    - All possible states
    - Transitions between states
    - Events that trigger transitions
    - Use real state and event names from our codebase
    ```

    The agent will create a cycle/spiral pattern with specific state names and transition labels.
  </Accordion>

  <Accordion title="Comparison Diagrams">
    ```
    Compare our old authentication flow vs the new OAuth implementation side-by-side
    ```

    The agent will create parallel structures with visual contrast showing the differences.
  </Accordion>
</AccordionGroup>

## Tips for Better Diagrams

<CardGroup cols={2}>
  <Card title="Be Specific" icon="bullseye">
    Instead of "create a diagram of our API", say "create a diagram showing the authentication flow with real JWT payload structure"
  </Card>

  <Card title="Request Evidence" icon="code">
    Ask for "real code examples", "actual event names", or "sample JSON payloads" to get educational diagrams
  </Card>

  <Card title="Specify Depth" icon="layer-group">
    Use "simple" for conceptual overviews or "comprehensive" for detailed technical diagrams with examples
  </Card>

  <Card title="Name the Pattern" icon="shapes">
    If you know what pattern fits, mention it: "use a fan-out pattern" or "show this as a timeline"
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Design Principles" icon="compass-drafting" href="/concepts/philosophy">
    Learn the methodology behind the diagrams
  </Card>

  <Card title="Visual Patterns" icon="diagram-project" href="/methodology/pattern-library">
    Explore the pattern library (fan-out, convergence, timelines, etc.)
  </Card>

  <Card title="Customization" icon="palette" href="/guides/customization">
    Customize colors to match your brand
  </Card>

  <Card title="Render & Validate" icon="eye" href="/guides/render-validate">
    Master the render-view-fix loop
  </Card>
</CardGroup>

<Warning>
  The agent will **not** create diagrams without visual validation. Every diagram goes through the render-view-fix loop. This is a feature, not a limitation — it ensures quality.
</Warning>