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
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?
Why This Matters
Most diagrams fail because they’re formatted text, not visual arguments:Bad: Displaying
- 5 equal boxes with labels
- Card grid layout
- Icons decorating text
- Same container for everything
- Everything in a box
Good: Arguing
- 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
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) |
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
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