Cause-Effect Diagram Style Guide

Cause-effect diagrams visualize causal relationships between factors. They’re defined in YAML under the causeEffectGraph property of entities.

View all diagrams: /diagrams

Quick Reference

- id: tmc-compute
  causeEffectGraph:
    title: "What Drives Effective AI Compute?"
    primaryNodeId: effective-compute
    nodes:
      - id: effective-compute
        label: Effective Compute
        type: effect
    edges:
      - source: chip-supply
        target: effective-compute
        strength: strong
        effect: increases

Node Types

Type	Purpose	Color
`leaf`	Root inputs, external factors	Teal
`cause`	Derived factors from leaves	Light gray
`intermediate`	Direct contributing factors	Darker gray
`effect`	Target outcome(s)	Amber

Node Properties: id (required), label (required), type (required), description, confidence (0-1), color, scores

View Node Properties Reference

Property	Required	Description
`id`	Yes	Unique identifier (kebab-case)
`label`	Yes	Display text (2-5 words)
`type`	Yes	One of: `leaf`, `cause`, `intermediate`, `effect`
`description`	No	Brief explanation (shown on hover)
`confidence`	No	0-1 confidence in this node’s relevance
`color`	No	Semantic color name (see Semantic Colors)
`scores`	No	Rating dimensions (see Node Scores)

Edge Properties

Property	Values	Visual Effect
`strength`	`weak`, `medium`, `strong`	Line thickness
`confidence`	`low`, `medium`, `high`	Line style (dashed → solid)
`effect`	`increases`, `decreases`, `mixed`	Arrow color (blue, red, gray)

Guidelines: Use strong for direct, well-established causal links. Use weak for speculative connections.

Semantic Colors

Use colors sparingly—about half of nodes should remain grey/neutral.

Color	Use For
`rose`/`red`	Risk factors, threats
`emerald`/`green`	Defensive factors, countermeasures
`violet`/`purple`	Key uncertainties, critical questions
`teal`/`blue`	Power centers, structural factors
`slate`/`gray`	Neutral, well-known factors
`amber`	Warnings (effect nodes use amber by default)

View Color Guidelines & Example

Guidelines:

Color ~50% of nodes; leave the rest grey/slate
Reserve colors for most critical nodes
Use slate for well-known factors or aggregation nodes

Example:

nodes:
  - id: key-threat
    label: Major Threat
    type: intermediate
    color: red
  - id: countermeasure
    label: Defense System
    type: leaf
    color: emerald
  - id: technical-detail
    label: Implementation Detail
    type: leaf
    color: slate

Node Scores

Optional

Nodes can have four scoring dimensions (1-10) for interactive visualization.

Dimension	Description
`novelty`	How surprising (1=common knowledge, 10=very surprising)
`sensitivity`	Downstream impact if changed (1=minimal, 10=huge cascading)
`changeability`	How tractable (1=fixed, 10=highly changeable)
`certainty`	How well understood (1=deep uncertainty, 10=well established)

View Scoring Guidelines & Example

Score	Novelty	Sensitivity	Changeability	Certainty
1-3	Common knowledge	Minimal impact	Fixed/immutable	Deep uncertainty
4-6	Somewhat familiar	Moderate impact	Somewhat malleable	Mixed evidence
7-10	Surprising insight	Huge cascading	Highly tractable	Well established

Example:

- id: ai-biology-knowledge
  label: AI Biology Knowledge
  type: leaf
  scores:
    novelty: 5
    sensitivity: 8
    changeability: 3
    certainty: 5
  color: rose

Layout Best Practices

Guideline	Recommendation
Maximum nodes	15-20 (split larger diagrams)
Maximum edges	30-40
Nodes per layer	4-5 max horizontal

Layer Organization:

Layer 1: leaf nodes (root causes)
    ↓
Layer 2: cause nodes (derived)
    ↓
Layer 3: intermediate nodes (direct factors)
    ↓
Layer 4: effect nodes (outcomes)

When to Use

Use Case	Format
Causal model (5-20 factors)	CauseEffectGraph
Simple flow (3-5 steps)	Mermaid flowchart
Taxonomy/hierarchy	Table or Mermaid
2x2 matrix	Mermaid quadrant

YAML Schema

View Full Schema Reference

causeEffectGraph:
  title: "Diagram Title"           # Optional
  description: "Brief explanation" # Optional
  primaryNodeId: "main-effect"     # Optional, highlights this node

  nodes:
    - id: node-id                  # Required: unique identifier
      label: "Node Label"          # Required: display text
      type: leaf                   # Required: leaf|cause|intermediate|effect
      description: "Hover text"    # Optional
      confidence: 0.8              # Optional: 0-1
      color: rose                  # Optional: semantic color
      scores:                      # Optional: 1-10 ratings
        novelty: 5
        sensitivity: 8
        changeability: 3
        certainty: 5

  edges:
    - source: cause-node           # Required
      target: effect-node          # Required
      strength: strong             # Optional: weak|medium|strong
      confidence: high             # Optional: low|medium|high
      effect: increases            # Optional: increases|decreases|mixed
      label: "edge label"          # Optional

Common Patterns

View Pattern Examples

Simple Causal Chain:

nodes:
  - { id: a, label: Root Cause, type: leaf }
  - { id: b, label: Mediator, type: intermediate }
  - { id: c, label: Outcome, type: effect }
edges:
  - { source: a, target: b, strength: strong }
  - { source: b, target: c, strength: strong }

Multiple Converging Causes:

nodes:
  - { id: a, label: Factor A, type: leaf }
  - { id: b, label: Factor B, type: leaf }
  - { id: c, label: Factor C, type: leaf }
  - { id: outcome, label: Outcome, type: effect }
edges:
  - { source: a, target: outcome, strength: strong }
  - { source: b, target: outcome, strength: medium }
  - { source: c, target: outcome, strength: weak }

Hierarchical Factors:

nodes:
  # Root inputs
  - { id: input-1, label: External Factor, type: leaf }
  - { id: input-2, label: Resource, type: leaf }
  # Derived
  - { id: derived, label: Combined Effect, type: cause }
  # Direct
  - { id: direct-1, label: Capability, type: intermediate }
  - { id: direct-2, label: Constraint, type: intermediate }
  # Target
  - { id: outcome, label: Final Outcome, type: effect }
edges:
  - { source: input-1, target: derived }
  - { source: input-2, target: derived }
  - { source: derived, target: direct-1 }
  - { source: derived, target: direct-2 }
  - { source: direct-1, target: outcome, strength: strong }
  - { source: direct-2, target: outcome, strength: medium, effect: decreases }

Anti-Patterns

View Common Mistakes

Too Many Leaf Nodes (8+) Fix: Group into intermediate nodes or split diagrams.

Feedback Loops in Edges

# Bad: Creates cycles
edges:
  - { source: a, target: b }
  - { source: b, target: c }
  - { source: c, target: a }  # Loop!

Fix: Remove loop edge, note in description.

Long Node Labels

# Bad
- { id: x, label: "This is a very long label" }
# Good
- { id: x, label: "Key Factor", description: "Details here" }

All Same Strength

# Bad: No visual hierarchy
edges:
  - { source: a, target: x, strength: medium }
  - { source: b, target: x, strength: medium }
# Good: Differentiate
edges:
  - { source: a, target: x, strength: strong }
  - { source: b, target: x, strength: weak }

Integration

With TransitionModelContent: Diagrams auto-render for entities with causeEffectGraph.

Standalone Viewer: /diagrams?entity=tmc-compute

View Color Reference Tables

Node Colors by Type:

Type	Background	Text	Border
`leaf`	teal-100	teal-700	teal-300
`cause`	slate-200	slate-700	slate-400
`intermediate`	slate-300	slate-800	slate-500
`effect`	amber-100	amber-800	amber-400

Edge Colors by Effect:

Effect	Color	Meaning
`increases`	Blue	Positive correlation
`decreases`	Red	Negative correlation
`mixed`	Gray	Context-dependent