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

# Core Philosophy

> Diagrams should argue, not display. Learn the foundational principles that make visual arguments effective.

# 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 Two Core Tests

Before you finalize any diagram, run it through these two critical tests:

### The Isomorphism Test

<Note>
  If you removed all text, would the structure alone communicate the concept? If not, redesign.
</Note>

The visual structure should mirror the conceptual structure. This is what separates a diagram from "text with boxes around it."

**Example**: If you're showing a concept that spawns multiple outputs, the diagram should use a fan-out pattern (central element with radiating arrows) — not a vertical list of equal boxes.

### The Education Test

<Note>
  Could someone learn something concrete from this diagram, or does it just label boxes?
</Note>

A good diagram teaches — it shows actual formats, real event names, concrete examples. It doesn't just say "Input" and "Output" — it shows what the input and output actually look like.

## Why This Matters

Most diagrams fail because they're formatted text, not visual arguments:

<CardGroup cols={2}>
  <Card title="Bad: Displaying" icon="xmark">
    * 5 equal boxes with labels
    * Card grid layout
    * Icons decorating text
    * Same container for everything
    * Everything in a box
  </Card>

  <Card title="Good: Arguing" icon="check">
    * Each concept has a shape that mirrors its behavior
    * Visual structure matches conceptual structure
    * Shapes that ARE the meaning
    * Distinct visual vocabulary per concept
    * Free-floating text with selective containers
  </Card>
</CardGroup>

## Shape As Meaning

The relationship between form and meaning should be direct:

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

<Tip>
  For multi-concept diagrams: **each major concept must use a different visual pattern**. No uniform cards or grids.
</Tip>

## Container Discipline

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

* It's the focal point of a section
* It needs visual grouping with other elements
* Arrows need to connect to it
* The shape itself carries meaning (decision diamond, etc.)
* It represents a distinct "thing" in the system

### Use Free-Floating Text When:

* It's a label or description
* It's supporting detail or metadata
* It describes something nearby
* Typography alone creates sufficient hierarchy
* It's a section title, subtitle, or annotation

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

  Aim for **less than 30% of text elements to be inside containers**.
</Warning>

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

**Key principle**: Lines + free-floating text often creates a cleaner result than boxes + contained text.

## Visual Vocabulary

Think of your diagram as having a vocabulary where each pattern carries semantic weight:

* **Ellipses** = soft, origin-like (starts, triggers) or destination-like (ends, results)
* **Rectangles** = contained actions, processes, steps
* **Diamonds** = decisions, conditions
* **Lines** = structure itself (timelines, trees, dividers)
* **Small dots (10-20px)** = markers, anchors, bullet points
* **No shape** = labels, descriptions, metadata

<Tip>
  **Rule of thumb**: Default to no container. Add shapes only when they carry meaning.
</Tip>