# Diagram Design

Best practices for creating research diagrams with Excalidraw MCP tools

- Repository: https://github.com/vstorm-co/pydantic-deepagents (1111 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -g -a claude-code -y`
Codex: `npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -g -a codex -y`
Cursor: `npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -g -a cursor -y`
Gemini CLI: `npx skills add vstorm-co/pydantic-deepagents --skill diagram-design -g -a gemini-cli -y`

## Description

Best practices for creating research diagrams with Excalidraw MCP tools

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Diagram Design Guide for Research

## When to Create Diagrams

Create a diagram when your research findings involve:
- **Comparing 3+ options**, comparison table or matrix diagram
- **Process with 4+ steps**, flowchart or sequence diagram
- **System with multiple components**, architecture diagram
- **Chronological events**, timeline
- **Hierarchical relationships**, tree or mind map
- **Data flows**, data flow diagram

## Excalidraw Workflow

1. **Plan the diagram**, decide type, elements, and layout before creating
2. **Create elements**, use `create_element` or `batch_create_elements`
3. **Arrange**, use `align_elements` and `distribute_elements` for clean layout
4. **Inspect**, use `describe_scene` to verify the diagram looks right
5. **Adjust**, use `update_element` to fix positioning or text
6. **Group**, use `group_elements` to lock related items together

> **Note:** Do NOT export or share links, the user sees a live embedded canvas that auto-syncs.

## Color Palette

Use consistent colors across diagrams:

| Purpose | Color | Hex |
|---------|-------|-----|
| Primary concepts | Blue | #1971c2 |
| Positive / supported | Green | #2f9e44 |
| Negative / limitations | Red | #e03131 |
| Warning / caveats | Orange | #e8590c |
| Neutral / context | Gray | #868e96 |
| Highlight / focus | Yellow | #f08c00 |

## Layout Patterns

- **Top-to-bottom**: Process flows, decision trees, timelines
- **Left-to-right**: Comparisons, before/after, pipelines
- **Radial / center-out**: Concept maps, mind maps
- **Grid**: Feature matrices, comparison tables

## Element Guidelines

### Text
- Use short labels (2-4 words per element)
- Title font size: 20-24px
- Label font size: 14-16px
- Add detail in sub-labels, not element titles

### Shapes
- **Rectangles**: Processes, components, entities
- **Diamonds**: Decision points
- **Ellipses**: Start/end points, concepts
- **Rectangles with rounded corners**: Groups, categories

The rest: https://github.com/vstorm-co/pydantic-deepagents/blob/HEAD/apps/deepresearch/skills/diagram-design/SKILL.md