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

# Visual Pattern Library

> A comprehensive catalog of visual patterns for mapping concepts to shapes, including ASCII diagrams and usage guidelines

Each visual pattern represents a different conceptual behavior. Choose the pattern that **mirrors how the concept works**, not just what it's called.

<Note>
  The shape should BE the meaning. If you removed all text, would the structure alone communicate the concept?
</Note>

***

## Fan-Out (One-to-Many)

Central element with arrows radiating to multiple targets.

### When to Use

* Sources that spawn multiple outputs
* Product requirements that generate multiple features
* Root causes that trigger multiple effects
* Central hubs that distribute to many endpoints
* Single triggers that activate multiple handlers

### ASCII Diagram

```text theme={null}
        ○
       ↗
  □ → ○
      ↘
       ○
```

### Implementation Notes

* Use a central shape (rectangle or ellipse) as the origin
* Create arrows at different angles (e.g., -30°, 0°, +30°)
* Target shapes can be the same size (equal outputs) or different sizes (varying importance)
* Ensure adequate spacing (100px+ between targets)

### Example Use Cases

* A webhook event triggering multiple microservices
* A design system component library used by multiple applications
* A data source feeding multiple dashboards
* A user action triggering multiple side effects

***

## Convergence (Many-to-One)

Multiple inputs merging through arrows to a single output.

### When to Use

* Aggregation of multiple sources
* Funnels that consolidate many inputs
* Synthesis of disparate data
* Multiple contributors to a single result
* Decision points that consider multiple factors

### ASCII Diagram

```text theme={null}
  ○ ↘
  ○ → □
  ○ ↗
```

### Implementation Notes

* Multiple source shapes on the left or top
* Arrows converge to a single target
* Target should be visually distinct (different color, larger size, or different shape)
* Works well with a funnel visual metaphor (sources get closer as arrows approach target)

### Example Use Cases

* Multiple data streams aggregating into a single report
* Several validation checks determining a pass/fail result
* Multiple team inputs consolidated into a final decision
* Various microservices feeding data to a central dashboard

***

## Tree (Hierarchy)

Parent-child branching with connecting lines and **free-floating text** (no boxes needed).

### When to Use

* File systems and directory structures
* Organizational charts
* Taxonomies and categorizations
* Component hierarchies
* Menu structures

### ASCII Diagram

```text theme={null}
  label
  ├── label
  │   ├── label
  │   └── label
  └── label
```

### Implementation Notes

<Warning>
  Use `line` elements for the trunk and branches, **free-floating text** for labels. Do NOT put each label in a box.
</Warning>

* Vertical line for trunk
* Horizontal lines for branches
* Small dots (10-20px ellipses) at branch points (optional)
* Text positioned beside branches, not inside containers
* Use `fontSize` and `fontFamily` to create hierarchy (parent labels larger)

### Example Use Cases

```text theme={null}
project/
├── src/
│   ├── components/
│   ├── utils/
│   └── hooks/
└── tests/
```

* Folder structure visualization
* API endpoint hierarchy
* Navigation menu structure
* Component composition tree

***

## Timeline (Sequence)

Vertical or horizontal line with markers at intervals, labels beside each marker.

### When to Use

* Sequences of events over time
* Step-by-step processes
* Lifecycle stages
* Protocol message exchanges
* Historical progressions

### ASCII Diagram

```text theme={null}
Vertical:         Horizontal:
  ●─── Label 1    ● ──── ● ──── ● ──── ●
  │               │      │      │      │
  ●─── Label 2    L1     L2     L3     L4
  │
  ●─── Label 3
```

### Implementation Notes

* Main line: `type: "line"`, `strokeWidth: 2`
* Markers: small ellipses (10-20px diameter)
* Labels: free-floating text beside each marker
* Can add arrows between markers for directionality
* Horizontal for left-to-right flow, vertical for top-to-bottom

### Example Use Cases

* User registration flow: Email → Verify → Profile → Complete
* API request lifecycle: Request → Auth → Process → Response
* Deployment pipeline stages
* Event sequence in a protocol handshake

***

## Spiral/Cycle (Continuous Loop)

Elements in sequence with an arrow returning to the start.

### When to Use

* Feedback loops
* Iterative processes
* Continuous improvement cycles
* Evolutionary systems
* Recurring workflows

### ASCII Diagram

```text theme={null}
  □ → □
  ↑   ↓
  □ ← □
```

### Implementation Notes

* Arrange elements in a square or circular pattern
* Use arrows to show progression direction
* Final arrow returns to the first element
* Can add labels on arrows for transitions
* Consider adding a center label for the cycle name

### Example Use Cases

* Agile sprint cycle: Plan → Build → Test → Review → Plan
* CI/CD loop: Code → Build → Test → Deploy → Monitor → Code
* User feedback loop: Use → Feedback → Improve → Release → Use
* Retry mechanism: Try → Fail → Wait → Retry

***

## Cloud (Abstract State)

Overlapping ellipses with varied sizes.

### When to Use

* Abstract context or environment
* Memory or conversation state
* Fuzzy or undefined boundaries
* Mental models or concepts
* Ambient information

### Implementation Notes

* Use 3-5 overlapping ellipses
* Vary sizes and positions for organic feel
* Lower opacity creates depth (though default is opacity: 100)
* Use soft colors from the color palette
* Can contain free-floating text inside

### Example Use Cases

* "Context" surrounding a user session
* Conversation memory in an AI system
* "Mental model" concept in UX design
* Ambient data collected over time

***

## Assembly Line (Transformation)

Input → Process Box → Output with clear before/after contrast.

### When to Use

* Transformations and conversions
* Data processing pipelines
* Format changes
* State transitions
* Refinement processes

### ASCII Diagram

```text theme={null}
  ○○○ → [PROCESS] → □□□
  chaos              order
```

### Implementation Notes

* **Input**: Show actual sample data (not just "Input" label)
* **Process**: Rectangle or diamond with clear action verb
* **Output**: Show transformed result (not just "Output" label)
* Use visual contrast: different shapes or colors for before vs after
* Add arrows between each stage

### Example Use Cases

```text theme={null}
{"raw": "data"} → Parser → Structured Object

Markdown → Renderer → HTML

Raw Logs → Filter → Error Events
```

<Tip>
  **Show what things actually look like**, not just what they're called. Use actual format examples.
</Tip>

***

## Side-by-Side (Comparison)

Two parallel structures with visual contrast.

### When to Use

* Before/after comparisons
* Option A vs Option B
* Trade-off analysis
* Migration paths (old vs new)
* Parallel workflows

### Implementation Notes

* Use vertical divider line to separate sections
* Mirror structure on both sides for easy comparison
* Use color contrast: different background colors or stroke colors
* Label each side clearly ("Before/After", "Option A/Option B")
* Align corresponding elements horizontally

### Example Use Cases

* **Old API** | **New API** (showing endpoint changes)
* **Client-side** | **Server-side** (showing where logic runs)
* **Monolith** | **Microservices** (showing architectural shift)
* **Manual Process** | **Automated Process**

***

## Gap/Break (Separation)

Visual whitespace or barrier between sections.

### When to Use

* Phase changes in a process
* Context resets or boundaries
* Ownership transitions
* Time gaps
* Conceptual separations

### Implementation Notes

* Use whitespace (200px+ gap)
* Or use a dashed line divider
* Or use a label in the gap ("24 hours later", "Context Switch")
* Can combine with color change (before gap uses blue theme, after gap uses green)

### Example Use Cases

* Build phase → (gap) → Deploy phase
* User action → (network boundary) → Server processing
* Development → (handoff) → QA → (handoff) → Production
* Synchronous → (await) → Asynchronous

***

## Lines as Structure

Use lines (type: `line`, not arrows) as primary structural elements instead of boxes.

### When to Use Lines

<CardGroup cols={2}>
  <Card title="Timelines" icon="timeline">
    Vertical or horizontal line with small dots at intervals, free-floating labels beside each dot
  </Card>

  <Card title="Tree Structures" icon="diagram-project">
    Vertical trunk line + horizontal branch lines, with free-floating text labels (no boxes needed)
  </Card>

  <Card title="Dividers" icon="grip-lines">
    Thin dashed lines to separate sections
  </Card>

  <Card title="Flow Spines" icon="arrow-right">
    A central line that elements relate to, rather than connecting boxes
  </Card>
</CardGroup>

### Why Lines + Text Beat Boxes

<Tip>
  Lines + free-floating text often creates a cleaner result than boxes + contained text.
</Tip>

**Benefits:**

* Less visual clutter
* Clearer hierarchy through typography alone
* Faster to scan (eye follows lines naturally)
* More whitespace (improves readability)
* Easier to maintain and edit

### ASCII Comparison

```text theme={null}
With Boxes (cluttered):     With Lines (clean):
┌─────────┐                 │
│ Step 1  │                 ├── Step 1
└─────────┘                 │   ├── Detail A
┌─────────┐                 │   └── Detail B
│ Step 2  │                 └── Step 2
└─────────┘
```

***

## Pattern Selection Matrix

Quick reference for choosing the right pattern:

| Concept Behavior  | Pattern       | Visual Signature             |
| ----------------- | ------------- | ---------------------------- |
| One → Many        | Fan-out       | Center → radial arrows       |
| Many → One        | Convergence   | Multiple → single funnel     |
| Parent → Children | Tree          | Lines + free-floating labels |
| Sequential steps  | Timeline      | Line + dots + labels         |
| Repeating cycle   | Spiral/Cycle  | Arrows forming loop          |
| Fuzzy context     | Cloud         | Overlapping ellipses         |
| Before → After    | Assembly Line | Input → Process → Output     |
| A vs B            | Side-by-Side  | Parallel structures          |
| Phase boundary    | Gap/Break     | Whitespace or divider        |

***

## Combining Patterns

Complex diagrams often combine multiple patterns:

### Example: API Request Flow

1. **Timeline** for the main request sequence
2. **Fan-out** when the request triggers multiple services
3. **Convergence** when responses aggregate
4. **Assembly line** to show data transformation
5. **Gap** to show network boundary between client and server

### Example: System Architecture

1. **Tree** for component hierarchy
2. **Side-by-side** to compare old vs new architecture
3. **Cloud** to show shared context/state
4. **Fan-out** for event distribution

<Warning>
  Each major concept should use a **different** pattern. Don't repeat the same visual structure for different concepts.
</Warning>

***

## Anti-Patterns to Avoid

### Card Grid Layout

**Bad:**

```text theme={null}
┌────┐ ┌────┐ ┌────┐
│ A  │ │ B  │ │ C  │
└────┘ └────┘ └────┘
┌────┐ ┌────┐ ┌────┐
│ D  │ │ E  │ │ F  │
└────┘ └────┘ └────┘
```

**Why it's bad:** No relationships shown, no hierarchy, no flow. This is a **display**, not an **argument**.

**Better:** Use different patterns based on what each concept does. Maybe A fans out to B and C, D and E converge to F, etc.

### Everything in Boxes

**Bad:** Every piece of text wrapped in a rectangle

**Better:** Default to free-floating text, add containers only when they serve a purpose (grouping, connection points, semantic meaning)

### Uniform Shapes

**Bad:** All rectangles or all ellipses

**Better:** Shape follows function (ellipse for start/end, rectangle for process, diamond for decision, etc.)

### No Connections

**Bad:** Proximity alone to show relationships

**Better:** Explicit arrows or lines between related elements