# Excalidraw Diagram

> Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, pipelines, or concepts for BidDeed.AI or ZoneWise.AI.

- Skill: `breverdbidder/excalidraw-diagram` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add breverdbidder/excalidraw-diagram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/breverdbidder/excalidraw-diagram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: breverdbidder (https://skillmd.com/u/breverdbidder)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/breverdbidder/excalidraw-diagram

---


# Excalidraw Diagram Creator — BidDeed.AI / ZoneWise.AI

Generate `.excalidraw` JSON files that **argue visually**, not just display information.

**Forked from** [coleam00/excalidraw-diagram-skill](https://github.com/coleam00/excalidraw-diagram-skill) with house brand customizations.

**Setup:** If the user asks you to set up this skill (renderer, dependencies, etc.), see the Setup section below.

## Customization

**All colors and brand-specific styles live in one file:** `references/color-palette.md`. Read it before generating any diagram and use it as the single source of truth for all color choices — shape fills, strokes, text colors, evidence artifact backgrounds, everything.

**Templates** for common patterns live in `templates/`. Check if a template exists for your diagram type before designing from scratch.

---

## Core Philosophy

**Diagrams should ARGUE, not DISPLAY.**

A diagram isn't formatted text. It's a visual argument that shows relationships, causality, and flow that words alone can't express. The shape should BE the meaning.

**The Isomorphism Test**: If you removed all text, would the structure alone communicate the concept? If not, redesign.

**The Education Test**: Could someone learn something concrete from this diagram, or does it just label boxes? A good diagram teaches—it shows actual formats, real event names, concrete examples.

---

## Brand Defaults

Before generating any diagram, apply these defaults:

| Setting | Value | Notes |
|---------|-------|-------|
| `fontFamily` | `2` | Helvetica (closest to Inter) |
| `roughness` | `0` | Clean/modern for all professional diagrams |
| `opacity` | `100` | Always full opacity |
| Canvas (light) | `#ffffff` | Technical docs, README diagrams |
| Canvas (dark) | `#020617` | Investor decks, marketing, presentations |

**Default to light canvas** unless the diagram is for investor materials, marketing, or the user requests dark mode.

---

## Templates (Check First)

Before designing from scratch, check if a template exists in `templates/`:

### BidDeed.AI Templates
- `templates/biddeed/pipeline-12stage.md` — Everest Ascent 12-stage linear flow
- `templates/biddeed/bid-decision.md` — BID/REVIEW/SKIP decision tree
- `templates/biddeed/financial-evidence.md` — Bid amounts, ROI, judgment ratios

### ZoneWise.AI Templates
- `templates/zonewise/waterfall-tier.md` — N-tier fallback with cost annotations
- `templates/zonewise/multi-repo-map.md` — Repo → deploy → datastore network
- `templates/zonewise/county-grid.md` — FL county status matrix
- `templates/zonewise/nightly-pipeline.md` — GitHub Actions cron workflow
- `templates/zonewise/cost-comparison.md` — Before/after side-by-side with $

### Shared Templates
- `templates/shared/team-org.md` — Multi-agent hierarchy
- `templates/shared/smart-router.md` — Multi-tier LLM routing
- `templates/shared/data-flow.md` — Input → transform → output with JSON evidence

Templates provide layout guidance and element patterns. Combine with the color palette for final colors.

---

## Depth Assessment (Do This First)

Before designing, determine what level of detail this diagram needs:

### 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")

### 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)
- The audience needs to understand what things actually look like
- You're showing how multiple technologies integrate

**For technical diagrams, you MUST include evidence artifacts** (see below).

---

## Research Mandate (For Technical Diagrams)

**Before drawing anything technical, research the actual specifications.**

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: "Scraper" → "Database"
Good: "Firecrawl ($83/mo) → markdown" → "Gemini Flash (FREE) → structured JSON" → "Supabase multi_county_auctions (245K rows)"

**Research makes diagrams accurate AND educational.**

---

## Evidence Artifacts

Evidence artifacts are concrete examples that prove your diagram is accurate and help viewers learn. Include them in technical diagrams.

**Types of evidence artifacts** (choose what's relevant to your diagram):

| Artifact Type | When to Use | How to Render |
|---------------|-------------|---------------|
| **Code snippets** | APIs, integrations, implementation details | Dark rectangle + syntax-colored text (see color palette for evidence artifact colors) |
| **Data/JSON examples** | Data formats, schemas, payloads | Dark rectangle + colored text (see color palette) |
| **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 |
| **Cost annotations** | Pricing, billing, ROI | Dark rectangle + orange text ($F59E0B) |
| **Financial data** | Bid amounts, savings, losses | Dark rectangle + green (positive) or red (negative) |
| **Status badges** | ACTIVE/LEGACY/DEPRECATED, BID/REVIEW/SKIP | Small colored rounded rectangles (see color palette) |

The key principle: **show what things actually look like**, not just what they're called.

---

## Multi-Zoom Architecture

Comprehensive diagrams operate at multiple zoom levels simultaneously. Think of it like a map that shows both the country borders AND the street names.

### Level 1: Summary Flow
A simplified overview showing the full pipeline or process at a glance. Often placed at the top or bottom of the diagram.

*Example*: `Firecrawl → Gemini → Claude → Supabase` or `Discovery → Scraping → Analysis → Report`

### Level 2: Section Boundaries
Labeled regions that group related components. These create visual "rooms" that help viewers understand what belongs together.

*Example*: Grouping by tier (Tier 1 / Tier 2 / Tier 3), by phase (Scrape / Parse / Store), or by cost (FREE / Paid)

### Level 3: Detail Inside Sections
Evidence artifacts, code snippets, cost data, and concrete examples within each section. This is where the educational value lives.

*Example*: Inside a "Tier 2" section, you might show the actual Gemini Flash API response format, not just a box labeled "AI Parser"

**For comprehensive diagrams, aim to include all three levels.**

### Bad vs Good

| Bad (Displaying) | Good (Arguing) |
|------------------|----------------|
| 5 equal boxes with labels | Each concept has a shape that mirrors its behavior |
| Card grid layout | Visual structure matches conceptual structure |
| Icons decorating text | Shapes that ARE the meaning |
| Same container for everything | Distinct visual vocabulary per concept |
| Everything in a box | Free-floating text with selective containers |
| "API" label | Actual endpoint + sample response |

---

## Container vs. Free-Floating Text

**Not every piece of text needs a shape around it.** Default to free-floating text. Add containers only when they serve a purpose.

| Use a Container When... | Use Free-Floating Text When... |
|------------------------|-------------------------------|
| It's the focal point of a section | It's a label or description |
| It needs visual grouping with other elements | It's supporting detail or metadata |
| Arrows need to connect to it | It describes something nearby |
| The shape itself carries meaning (decision diamond, etc.) | Typography alone creates sufficient hierarchy |
| It represents a distinct "thing" in the system | It's a section title, subtitle, or annotation |
| It's a cost annotation or status badge | It's a cost label next to a node |

**Typography as hierarchy**: Use font size, weight, and color to create visual hierarchy without boxes. A 28px title doesn't need a rectangle around it.

**The container test**: For each boxed element, ask "Would this work as free-floating text?" If yes, remove the container.

---

## Design Process (Do This BEFORE Generating JSON)

### Step 0: Check Templates
Before designing from scratch, check `templates/` for an existing pattern that matches your diagram type.

### Step 1: Assess Depth Required
Determine if this needs to be:
- **Simple/Conceptual**: Abstract shapes, labels, relationships
- **Comprehensive/Technical**: Concrete examples, code snippets, real data, cost annotations

**If comprehensive**: Do research first. Look up actual specs, formats, event names, APIs.

### Step 2: Understand Deeply
Read the content. For each concept, ask:
- What does this concept **DO**? (not what IS it)
- What relationships exist between concepts?
- What's the core transformation or flow?
- **What would someone need to SEE to understand this?**
- **What does it cost?** (if relevant — always include cost data for infrastructure diagrams)

### Step 3: Map Concepts to Patterns
For each concept, find the visual pattern that mirrors its behavior:

| If the concept... | Use this pattern |
|-------------------|------------------|
| Spawns multiple outputs | **Fan-out** (radial arrows from center) |
| Combines inputs into one | **Convergence** (funnel, arrows merging) |
| Has hierarchy/nesting | **Tree** (lines + free-floating text) |
| Is a sequence of steps | **Timeline** (line + dots + free-floating labels) |
| Loops or improves continuously | **Spiral/Cycle** (arrow returning to start) |
| Is an abstract state or context | **Cloud** (overlapping ellipses) |
| Transforms input to output | **Assembly line** (before → process → after) |
| Compares two things | **Side-by-side** (parallel with contrast) |
| Separates into phases | **Gap/Break** (visual separation between sections) |
| Falls through tiers | **Waterfall** (vertical cascade with fallback arrows) |
| Routes to different handlers | **Fan-out with decision** (diamond → multiple paths) |

### Step 4: Ensure Variety
For multi-concept diagrams: **each major concept must use a different visual pattern**. No uniform cards or grids.

### Step 5: Sketch the Flow
Before JSON, mentally trace how the eye moves through the diagram. There should be a clear visual story.

### Step 6: Generate JSON
Only now create the Excalidraw elements. **See below for how to handle large diagrams.**

### Step 7: Render & Validate (MANDATORY)
After generating the JSON, you MUST run the render-view-fix loop until the diagram looks right. See the **Render & Validate** section below.

---

## Large / Comprehensive Diagram Strategy

**For comprehensive or technical diagrams, you MUST build the JSON one section at a time.** Do NOT attempt to generate the entire file in a single pass. This is a hard constraint — Claude Code has a ~32,000 token output limit per response, and a comprehensive diagram easily exceeds that in one shot.

### The Section-by-Section Workflow

**Phase 1: Build each section**

1. **Create the base file** with the JSON wrapper (`type`, `version`, `appState`, `files`) and the first section of elements.
2. **Add one section per edit.** Each section gets its own dedicated pass.
3. **Use descriptive string IDs** (e.g., `"trigger_rect"`, `"arrow_fan_left"`) so cross-section references are readable.
4. **Namespace seeds by section** (e.g., section 1 uses 100xxx, section 2 uses 200xxx) to avoid collisions.
5. **Update cross-section bindings** as you go.

**Phase 2: Review the whole**

After all sections are in place, check:
- Are cross-section arrows bound correctly on both ends?
- Is the overall spacing balanced?
- Do IDs and bindings all reference elements that actually exist?

**Phase 3: Render & validate**

Now run the render-view-fix loop from the Render & Validate section.

### What NOT to Do

- **Don't generate the entire diagram in one response.**
- **Don't use a coding agent** to generate the JSON.
- **Don't write a Python generator script.**

---

## Visual Pattern Library

### Fan-Out (One-to-Many)
Central element with arrows radiating to multiple targets. Use for: sources, orchestrators, root causes, central hubs.
```
        ○
       ↗
  □ → ○
       ↘
        ○
```

### Convergence (Many-to-One)
Multiple inputs merging through arrows to single output. Use for: aggregation, funnels, synthesis.
```
  ○ ↘
  ○ → □
  ○ ↗
```

### Waterfall (Tiered Fallback) ★ NEW
Vertical cascade where each tier catches what the previous tier couldn't handle. Use for: scraper pipelines, LLM routing, error handling chains.
```
  ┌──────────┐
  │  Tier 1  │──→ success
  └────┬─────┘
       ↓ fallback
  ┌──────────┐
  │  Tier 2  │──→ success
  └────┬─────┘
       ↓ fallback
  ┌──────────┐
  │  Tier 3  │──→ success
  └──────────┘
```
Each tier gets a cost annotation and success rate. Arrows going right = success path. Arrows going down = fallback path.

### Tree (Hierarchy)
Parent-child branching with connecting lines and free-floating text. Use for: file systems, org charts, repo maps.
```
  label
  ├── label
  │   ├── label
  │   └── label
  └── label
```

### Spiral/Cycle (Continuous Loop)
Elements in sequence with arrow returning to start.
```
  □ → □
  ↑     ↓
  □ ← □
```

### Cloud (Abstract State)
Overlapping ellipses with varied sizes.

### Assembly Line (Transformation)
Input → Process Box → Output with clear before/after. Include actual data samples.
```
  ○○○ → [PROCESS] → □□□
  chaos              order
```

### Side-by-Side (Comparison)
Two parallel structures with visual contrast. Use for: before/after, cost comparison, old vs new.

### Gap/Break (Separation)
Visual whitespace or barrier between sections.

### Lines as Structure
Use lines (type: `line`, not arrows) as primary structural elements:
- **Timelines**: Line + small dots + free-floating labels
- **Tree structures**: Vertical trunk + horizontal branches + text labels
- **Dividers**: Thin dashed lines to separate sections
- **Flow spines**: A central line that elements relate to

---

## Shape Meaning

| Concept Type | Shape | Why |
|--------------|-------|-----|
| Labels, descriptions, details | **none** (free-floating text) | Typography creates hierarchy |
| Section titles, annotations | **none** (free-floating text) | Font size/weight is enough |
| Markers on a timeline | small `ellipse` (10-20px) | Visual anchor, not container |
| Start, trigger, input | `ellipse` | Soft, origin-like |
| End, output, result | `ellipse` | Completion, destination |
| Decision, condition | `diamond` | Classic decision symbol |
| Process, action, step | `rectangle` | Contained action |
| Abstract state, context | overlapping `ellipse` | Fuzzy, cloud-like |
| Hierarchy node | lines + text (no boxes) | Structure through lines |
| Status indicator | small `rectangle` (60×24) | Badge pattern |
| Cost annotation | small `rectangle` dark bg | Evidence artifact |

**Rule**: Default to no container. Add shapes only when they carry meaning. Aim for <30% of text elements to be inside containers.

---

## Color as Meaning

Colors encode information, not decoration. Every color choice should come from `references/color-palette.md`.

**Key principles:**
- Each semantic purpose has a specific fill/stroke pair
- Free-floating text uses color for hierarchy (titles, subtitles, details)
- Evidence artifacts use dark background + colored text
- Cost annotations use orange accent text on dark background
- Status badges use semantic colors (green=active/bid, orange=legacy/review, red=deprecated/skip)
- Always pair a darker stroke with a lighter fill for contrast

**Do not invent new colors.** If a concept doesn't fit an existing semantic category, use Primary/Neutral or Secondary.

---

## Modern Aesthetics

### Roughness
- `roughness: 0` — Clean, crisp edges. **Default for all BidDeed/ZoneWise diagrams.**
- `roughness: 1` — Hand-drawn, organic feel. Only if explicitly requested.

### Stroke Width
- `strokeWidth: 1` — Thin, elegant. Good for lines, dividers.
- `strokeWidth: 2` — Standard. Good for shapes and primary arrows.
- `strokeWidth: 3` — Bold. Use sparingly for emphasis.

### Opacity
**Always use `opacity: 100` for all elements.**

### Small Markers Instead of Shapes
Instead of full shapes, use small dots (10-20px ellipses) as:
- Timeline markers
- Bullet points
- Connection nodes
- Visual anchors for free-floating text

---

## Layout Principles

### Hierarchy Through Scale
- **Hero**: 300×150 - visual anchor, most important
- **Primary**: 180×90
- **Secondary**: 120×60
- **Small**: 60×40
- **Badge**: 60×24

### Whitespace = Importance
The most important element has the most empty space around it (200px+).

### Flow Direction
Guide the eye: typically left→right or top→bottom for sequences, top→bottom for waterfalls, radial for hub-and-spoke.

### Connections Required
Position alone doesn't show relationships. If A relates to B, there must be an arrow.

---

## Text Rules

**CRITICAL**: The JSON `text` property contains ONLY readable words.

```json
{
  "id": "myElement1",
  "text": "Start",
  "originalText": "Start"
}
```

Settings: `fontSize: 16`, `fontFamily: 2`, `textAlign: "center"`, `verticalAlign: "middle"`

---

## JSON Structure

```json
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}
```

For dark canvas mode, set `"viewBackgroundColor": "#020617"`.

## Element Templates

See `references/element-templates.md` for copy-paste JSON templates. Pull colors from `references/color-palette.md` based on each element's semantic purpose.

---

## Render & Validate (MANDATORY)

You cannot judge a diagram from JSON alone. After generating or editing the Excalidraw JSON, you MUST render it to PNG, view the image, and fix what you see — in a loop until it's right.

### How to Render

```bash
# PNG (default)
cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <path-to-file.excalidraw>

# SVG export
cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <path-to-file.excalidraw> --svg
```

This outputs a PNG/SVG next to the `.excalidraw` file. Then use the **Read tool** on the PNG to actually view it.

### The Loop

**1. Render & View** — Run the render script, then Read the PNG.

**2. Audit against your original vision** — Compare the rendered result to what you designed:
- Does the visual structure match the conceptual structure?
- Does each section use the intended pattern?
- Does the eye flow through the diagram correctly?
- Is the visual hierarchy correct?
- For technical diagrams: are evidence artifacts readable?
- **For dark mode: is all text readable against the dark background?**
- **Are cost annotations clearly visible and correctly positioned?**
- **Do status badges render at the right size and position?**

**3. Check for visual defects:**
- Text clipped by or overflowing its container
- Text or shapes overlapping other elements
- Arrows crossing through elements
- Labels floating ambiguously
- Uneven spacing
- Text too small to read
- Overall composition lopsided
- **On dark canvas: text blending into background**

**4. Fix** — Edit the JSON. Common fixes:
- Widen containers for clipped text
- Adjust coordinates for spacing
- Add waypoints to arrow `points` arrays
- Reposition labels closer to their element
- Resize for visual balance
- **Switch text colors for dark canvas readability**

**5. Re-render & re-view**

**6. Repeat** — Typically 2-4 iterations.

### When to Stop

The loop is done when:
- The rendered diagram matches the conceptual design
- No text is clipped, overlapping, or unreadable
- Arrows route cleanly
- Spacing is consistent and composition is balanced
- You'd be comfortable showing it to an investor without caveats

### First-Time Setup
```bash
cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium
```

---

## Quality Checklist

### Depth & Evidence
1. **Research done**: Did you look up actual specs, formats, costs?
2. **Evidence artifacts**: Code snippets, JSON examples, cost data present?
3. **Multi-zoom**: Summary flow + section boundaries + detail?
4. **Concrete over abstract**: Real content shown, not just labeled boxes?
5. **Educational value**: Could someone learn something concrete?

### Conceptual
6. **Isomorphism**: Visual structure mirrors concept behavior?
7. **Argument**: Diagram SHOWS something text alone couldn't?
8. **Variety**: Each major concept uses a different visual pattern?
9. **No uniform containers**: No card grids or equal boxes?

### Container Discipline
10. **Minimal containers**: Could any boxed element work as free-floating text?
11. **Lines as structure**: Tree/timeline patterns using lines + text?
12. **Typography hierarchy**: Font size and color creating hierarchy?

### Structural
13. **Connections**: Every relationship has an arrow or line
14. **Flow**: Clear visual path for the eye
15. **Hierarchy**: Important elements larger/more isolated

### Brand Compliance
16. **Font**: `fontFamily: 2` (Helvetica)
17. **Roughness**: `roughness: 0`
18. **Opacity**: `opacity: 100`
19. **Colors**: All from `color-palette.md`
20. **Canvas**: Correct mode (light or dark) for audience
21. **Container ratio**: <30% of text inside containers

### Visual Validation (Render Required)
22. **Rendered to PNG**: Visually inspected
23. **No text overflow**: All text fits
24. **No overlapping**: Nothing overlaps unintentionally
25. **Even spacing**: Consistent spacing
26. **Arrows correct**: Connect to intended elements
27. **Readable**: Text legible in rendered PNG
28. **Balanced**: No large voids or overcrowded regions
29. **Dark mode check**: If dark canvas, all text readable