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

# Shape Meaning

> Guidelines for choosing shapes based on semantic purpose, and rules for when to use containers vs free-floating text

Choose shape based on **what it represents**—or use no shape at all.

<Note>
  The shape should BE the meaning. Not every piece of text needs a box around it.
</Note>

***

## Shape Selection Table

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

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

***

## Semantic Shapes

### Ellipse (Circular/Oval)

**Use for:**

* **Start points**: User actions, triggers, events that initiate a flow
* **End points**: Final results, outputs, completions
* **Timeline markers**: Small dots (10-20px) along a timeline
* **Cloud elements**: Overlapping ellipses for abstract context

**Why ellipse:**

* Soft, approachable (no hard edges)
* Implies flow and continuity
* Visually distinct from process boxes
* Traditional for start/end in flowcharts

**Example use cases:**

```text theme={null}
● User clicks button    (start trigger)
● API returns response  (end result)
● Event emitted        (timeline marker)
```

### Rectangle (Box)

**Use for:**

* **Processes**: Actions, transformations, operations
* **Components**: Discrete system components
* **Containers**: When grouping related elements
* **Evidence artifacts**: Code snippets, data examples

**Why rectangle:**

* Implies containment and structure
* Clear boundaries
* Good for housing text or nested elements
* Traditional for process steps

**Example use cases:**

```text theme={null}
┌─────────────────┐
│ Validate Input  │  (process step)
└─────────────────┘

┌─────────────────┐
│ Auth Service    │  (system component)
└─────────────────┘
```

### Diamond

**Use for:**

* **Decisions**: Yes/no, if/else, conditional branches
* **Routing**: Logic that determines path
* **Validation**: Checks that pass or fail

**Why diamond:**

* Universal symbol for decision points
* Visual suggests branching
* Arrows naturally exit from sides/corners

**Example use cases:**

```text theme={null}
    ◇ Valid?
   ↙     ↘
  Yes    No
```

### Lines (No Container)

**Use for:**

* **Tree structures**: Parent-child hierarchies
* **Timelines**: Sequences of events
* **Dividers**: Section separators
* **Flow spines**: Central axis for related elements

**Why lines:**

* Minimal visual weight
* Emphasizes relationships over elements
* Cleaner than boxes for hierarchies
* More whitespace = better readability

**Example use cases:**

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

***

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

<CardGroup cols={2}>
  <Card title="Focal Point" icon="bullseye">
    It's the main subject of a section and needs emphasis
  </Card>

  <Card title="Grouping" icon="object-group">
    It needs visual grouping with other elements inside it
  </Card>

  <Card title="Connection Point" icon="arrow-pointer">
    Arrows need to connect to it (requires binding)
  </Card>

  <Card title="Semantic Meaning" icon="shapes">
    The shape itself carries meaning (decision diamond, start ellipse)
  </Card>

  <Card title="System Entity" icon="cube">
    It represents a distinct "thing" in the system (component, service, database)
  </Card>
</CardGroup>

### Use Free-Floating Text When...

<CardGroup cols={2}>
  <Card title="Labels" icon="tag">
    It's a label or description of something else
  </Card>

  <Card title="Supporting Detail" icon="file-lines">
    It's metadata, annotations, or clarifying information
  </Card>

  <Card title="Descriptions" icon="comment">
    It describes something nearby but isn't the thing itself
  </Card>

  <Card title="Titles" icon="heading">
    Typography alone creates sufficient hierarchy
  </Card>

  <Card title="Hierarchy" icon="bars-staggered">
    It's a section title, subtitle, or heading
  </Card>
</CardGroup>

***

## The Container Test

For each boxed element, ask:

<Steps>
  <Step title="Would this work as free-floating text?">
    If yes, remove the container.
  </Step>

  <Step title="Does the shape add semantic meaning?">
    If no, remove the container.
  </Step>

  <Step title="Do arrows need to connect to this?">
    If no and it's not a focal point, remove the container.
  </Step>

  <Step title="Is this text part of a group that needs visual containment?">
    If no, remove the container.
  </Step>
</Steps>

<Tip>
  After applying the container test, aim for less than 30% of your text elements to be inside containers.
</Tip>

***

## Typography as Hierarchy

Use font size, weight, and color to create visual hierarchy **without boxes**.

### Font Size Hierarchy

| Purpose            | Font Size | Use                                 |
| ------------------ | --------- | ----------------------------------- |
| Main title         | 28-32px   | Diagram title or hero section label |
| Section headers    | 20-24px   | Major section names                 |
| Subsection headers | 16-18px   | Sub-section labels                  |
| Body text          | 14-16px   | Primary content, labels             |
| Details/metadata   | 10-12px   | Annotations, fine print             |

### Example: Section Title Without Container

**Bad:**

```text theme={null}
┌──────────────────────┐
│   Backend Services   │  ← Unnecessary box
└──────────────────────┘
```

**Good:**

```text theme={null}
Backend Services  ← 24px, bold, free-floating
```

The larger font size and bold weight create sufficient visual hierarchy. No box needed.

***

## Small Markers Instead of Shapes

Instead of full shapes, use small dots (10-20px ellipses) as:

### Timeline Markers

```text theme={null}
●─── Event 1
│
●─── Event 2
│
●─── Event 3
```

Small ellipse (10-20px) + free-floating text label

### Bullet Points

```text theme={null}
● Key feature one
● Key feature two  
● Key feature three
```

Use small dots instead of rectangles or large shapes

### Connection Nodes

```text theme={null}
     ●
   ↗ │ ↘
  A  B  C
```

Small dot as hub, free-floating text for connected items

### Visual Anchors

Small shape + nearby text creates visual relationship without heavy container

***

## Special Case: Evidence Artifacts

For **code snippets** and **data examples** in technical diagrams:

**Always use a container** (rectangle) because:

* Groups multiple lines of code/data together
* Creates clear boundaries for technical content
* Differentiates examples from explanatory text
* Allows for background color to improve readability

See the [Evidence Artifacts](/concepts/evidence-artifacts) page for detailed guidelines on styling these containers.

***

## Color Follows Semantics

Shapes aren't just geometric—they carry semantic meaning through color.

<Note>
  All color choices must come from `references/color-palette.md`. Each semantic purpose (start, end, decision, AI, error, etc.) has a specific fill/stroke pair.
</Note>

### Semantic Color Mapping

| Semantic Purpose | Fill Color    | Stroke Color         |
| ---------------- | ------------- | -------------------- |
| Start/Trigger    | Light blue    | Darker blue          |
| End/Result       | Light green   | Darker green         |
| Decision         | Light yellow  | Darker yellow/orange |
| Process          | Neutral light | Neutral dark         |
| Error/Warning    | Light red     | Darker red           |
| AI/Automated     | Light purple  | Darker purple        |

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

***

## Shape Combinations

Complex diagrams combine multiple shape types:

### Example: User Authentication Flow

1. **Ellipse**: "User enters credentials" (start trigger)
2. **Rectangle**: "Validate credentials" (process)
3. **Diamond**: "Valid?" (decision)
4. **Rectangle**: "Generate token" (process)
5. **Ellipse**: "Authenticated" (end result)

Each shape choice reinforces the step's semantic role.

### Example: Data Pipeline

1. **Ellipse**: Raw data source (input)
2. **Rectangle**: Parser (process)
3. **Rectangle**: Validator (process)
4. **Diamond**: Valid? (decision)
5. **Rectangle**: Transformer (process)
6. **Ellipse**: Structured output (result)

***

## Anti-Patterns

### Everything in Rectangles

**Bad:**

```text theme={null}
┌──────┐ ┌──────┐ ┌──────┐
│Title │ │Label │ │Note  │
└──────┘ └──────┘ └──────┘
```

**Good:**

```text theme={null}
Title          (28px, free-floating)
  Label        (16px, free-floating)
    Note       (12px, free-floating)
```

### Shapes Without Semantic Meaning

**Bad:** Using ellipse for a process step (should be rectangle)

**Bad:** Using rectangle for a start trigger (should be ellipse)

**Good:** Shape matches semantic purpose from the table above

### Decorative Containers

**Bad:** Box around text just to "make it look designed"

**Good:** Container serves a purpose (grouping, connection, semantic meaning)

***

## Quick Reference

<AccordionGroup>
  <Accordion title="When to use NO container">
    * Labels and descriptions
    * Section titles and headers
    * Annotations and metadata
    * Supporting details
    * Any text where typography alone creates hierarchy
  </Accordion>

  <Accordion title="When to use ELLIPSE">
    * Start triggers and inputs
    * End results and outputs
    * Timeline markers (small, 10-20px)
    * Cloud elements (overlapping, for abstract context)
  </Accordion>

  <Accordion title="When to use RECTANGLE">
    * Process steps and actions
    * System components
    * Evidence artifacts (code, data)
    * Grouping containers
  </Accordion>

  <Accordion title="When to use DIAMOND">
    * Decisions (yes/no, if/else)
    * Routing logic
    * Validation checks
  </Accordion>

  <Accordion title="When to use LINES">
    * Tree hierarchies
    * Timelines
    * Section dividers
    * Flow spines
  </Accordion>
</AccordionGroup>