Visual Pattern Library

​

Fan-Out (One-to-Many)

​

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

        ○
       ↗
  □ → ○
      ↘
       ○

​

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)

​

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

  ○ ↘
  ○ → □
  ○ ↗

​

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)

​

When to Use

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

​

ASCII Diagram

  label
  ├── label
  │   ├── label
  │   └── label
  └── label

​

Implementation Notes

• 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

project/
├── src/
│   ├── components/
│   ├── utils/
│   └── hooks/
└── tests/

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

​

Timeline (Sequence)

​

When to Use

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

​

ASCII Diagram

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)

​

When to Use

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

​

ASCII Diagram

  □ → □
  ↑   ↓
  □ ← □

​

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)

​

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)

​

When to Use

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

​

ASCII Diagram

  ○○○ → [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

{"raw": "data"} → Parser → Structured Object

Markdown → Renderer → HTML

Raw Logs → Filter → Error Events

​

Side-by-Side (Comparison)

​

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)

​

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

​

When to Use Lines

​

Why Lines + Text Beat Boxes

• 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

With Boxes (cluttered):     With Lines (clean):
┌─────────┐                 │
│ Step 1  │                 ├── Step 1
└─────────┘                 │   ├── Detail A
┌─────────┐                 │   └── Detail B
│ Step 2  │                 └── Step 2
└─────────┘

​

Pattern Selection Matrix

​

Combining 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

​

Anti-Patterns to Avoid

​

Card Grid Layout

┌────┐ ┌────┐ ┌────┐
│ A  │ │ B  │ │ C  │
└────┘ └────┘ └────┘
┌────┐ ┌────┐ ┌────┐
│ D  │ │ E  │ │ F  │
└────┘ └────┘ └────┘

​

Everything in Boxes

​

Uniform Shapes

​

No Connections