Skip to main content
Choose shape based on what it represents—or use no shape at all.
The shape should BE the meaning. Not every piece of text needs a box around it.

​
Shape Selection Table

Concept TypeShapeWhy
Labels, descriptions, detailsnone (free-floating text)Typography creates hierarchy
Section titles, annotationsnone (free-floating text)Font size/weight is enough
Markers on a timelinesmall ellipse (10-20px)Visual anchor, not container
Start, trigger, inputellipseSoft, origin-like
End, output, resultellipseCompletion, destination
Decision, conditiondiamondClassic decision symbol
Process, action, steprectangleContained action
Abstract state, contextoverlapping ellipseFuzzy, cloud-like
Hierarchy nodelines + text (no boxes)Structure through lines
Rule: Default to no container. Add shapes only when they carry meaning. Aim for less than 30% of text elements to be inside containers.

​
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: 
● 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: 
┌─────────────────┐
│ 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: 
    ◇ 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: 
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…

Focal Point

It’s the main subject of a section and needs emphasis

Grouping

It needs visual grouping with other elements inside it

Connection Point

Arrows need to connect to it (requires binding)

Semantic Meaning

The shape itself carries meaning (decision diamond, start ellipse)

System Entity

It represents a distinct “thing” in the system (component, service, database)

​
Use Free-Floating Text When…

Labels

It’s a label or description of something else

Supporting Detail

It’s metadata, annotations, or clarifying information

Descriptions

It describes something nearby but isn’t the thing itself

Titles

Typography alone creates sufficient hierarchy

Hierarchy

It’s a section title, subtitle, or heading

​
The Container Test

For each boxed element, ask:
1

Would this work as free-floating text?

If yes, remove the container.
2

Does the shape add semantic meaning?

If no, remove the container.
3

Do arrows need to connect to this?

If no and it’s not a focal point, remove the container.
4

Is this text part of a group that needs visual containment?

If no, remove the container.
After applying the container test, aim for less than 30% of your text elements to be inside containers.

​
Typography as Hierarchy

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

​
Font Size Hierarchy

PurposeFont SizeUse
Main title28-32pxDiagram title or hero section label
Section headers20-24pxMajor section names
Subsection headers16-18pxSub-section labels
Body text14-16pxPrimary content, labels
Details/metadata10-12pxAnnotations, fine print

​
Example: Section Title Without Container

Bad: 
┌──────────────────────┐
│   Backend Services   │  ← Unnecessary box
└──────────────────────┘
Good: 
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

●─── Event 1
│
●─── Event 2
│
●─── Event 3
Small ellipse (10-20px) + free-floating text label

​
Bullet Points

● Key feature one
● Key feature two  
● Key feature three
Use small dots instead of rectangles or large shapes

​
Connection Nodes

     ●
   ↗ │ ↘
  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 page for detailed guidelines on styling these containers.

​
Color Follows Semantics

Shapes aren’t just geometric—they carry semantic meaning through color.
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.

​
Semantic Color Mapping

Semantic PurposeFill ColorStroke Color
Start/TriggerLight blueDarker blue
End/ResultLight greenDarker green
DecisionLight yellowDarker yellow/orange
ProcessNeutral lightNeutral dark
Error/WarningLight redDarker red
AI/AutomatedLight purpleDarker purple
Do not invent new colors. If a concept doesn’t fit an existing semantic category, use Primary/Neutral or Secondary.

​
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: 
┌──────┐ ┌──────┐ ┌──────┐
│Title │ │Label │ │Note  │
└──────┘ └──────┘ └──────┘
Good: 
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

  • Labels and descriptions
  • Section titles and headers
  • Annotations and metadata
  • Supporting details
  • Any text where typography alone creates hierarchy
  • Start triggers and inputs
  • End results and outputs
  • Timeline markers (small, 10-20px)
  • Cloud elements (overlapping, for abstract context)
  • Process steps and actions
  • System components
  • Evidence artifacts (code, data)
  • Grouping containers
  • Decisions (yes/no, if/else)
  • Routing logic
  • Validation checks
  • Tree hierarchies
  • Timelines
  • Section dividers
  • Flow spines

Build docs developers (and LLMs) love

Get started for freeTalk to us