D2 Diagram Quick Reference

Minimal reference for AI agents creating D2 diagrams.

Guiding Principles

1. Start monochrome. Add color only when it answers a question the reader would have.
2. Simplicity first. Prefer multiple focused diagrams over one complex diagram.
3. Accessibility (must). Don't rely on color alone - combine with thickness, dash pattern, or labels.

---

Color Modes

Choose based on the diagram's purpose, not its type:

Mode	Purpose	Node Colors	Edge Colors
Context	Who owns what?	System ownership (mandatory)	System of origin
Internal	How does it work inside?	Free-form / container-based	Data flow
Analysis	Highlighting distinctions	Container groupings	Status (quality, change)

---

Context Mode (Cross-System Diagrams)

Use when showing communication across system boundaries.

System Colors (mandatory)

System	Variable	Hex
Kundensysteme	${kundensystem}	#867FBB (purple)
VU-Systeme	${vu}	#8ED4A2 (green)
TOGETHER	${together}	#FFC056 (orange)
CCA	${cca}	#54A3D7 (blue)
Infrastruktur	${neutral}	#CCCCCC (gray)

Multi-VU Diagrams: Use ${vu-allianz}, ${vu-uniqa}, ${vu-zuerich}, etc. instead of generic ${vu}. See VU Logos → Markenfarben.

Product Colors: Use ${prd-boabot}, ${prd-cloudedi}, ${prd-myversum}, ${prd-proversum} for product-specific diagrams.

4-Tier Color System

Each color family has up to 4 tiers for different use cases:

Tier	Suffix	Use Case	Text Color
light	-light	Container backgrounds	dark text
base	(none)	Component fills	dark text
medium	-medium	Vibrant fills, emphasis	BLACK text
dark	-dark	Labels needing white text	WHITE text

Example:

# Container with light background
vu-system: "VU Integration" {
  style.fill: ${vu-light}

  # Component with base color
  adapter: "Adapter" {
    style.fill: ${vu}
  }

  # Emphasized component with medium (black text)
  api: "API Gateway" {
    style.fill: ${vu-medium}
    style.font-color: black
  }

  # Dark component (white text)
  core: "Core Service" {
    style.fill: ${vu-dark}
    style.font-color: white
  }
}

---

Text Color Rules (WCAG AA Compliant)

Dark tiers - use WHITE text

These colors pass WCAG AA (4.5:1+) for white text:

Variable	Hex	Contrast
${together-dark}	#A65F00	4.93:1
${vu-dark}	#2E7D42	5.09:1
${kundensystem-dark}	#5D5691	6.55:1
${cca-dark}	#0066B2	5.93:1
${neutral-dark}	#666666	5.74:1
${success-dark}	#1E7038	6.12:1
${error-dark}	#B32D2D	6.31:1

component: "Service" {
  style.fill: ${vu-dark}
  style.font-color: white
}

Medium tiers - use BLACK text

These vibrant colors need black text for contrast:

Variable	Hex	Contrast
${together-medium}	#FF9900	9.81:1
${vu-medium}	#69BA7A	8.91:1
${neutral-medium}	#999999	7.37:1
${success-medium}	#31AF5D	7.42:1
${error-medium}	#E54040	5.14:1

component: "API" {
  style.fill: ${together-medium}
  style.font-color: black
}

Base tiers - use dark text (default)

Base colors (${vu}, ${together}, etc.) work with default dark text.

---

Internal Mode (Single-System Diagrams)

Use when showing structure within one system.

Color Hierarchy

1. Produkt-Farbe (wenn vorhanden) → z.B. BOAbot #F49819
2. System-Farbe (Standard) → z.B. ${together} fuer TOGETHER-Interna
3. Fokus-Farbe (optional) → Komponenten können die Farbe des Zielsystems verwenden

Fokus-Farbe: Innerhalb eines Systems kann eine Komponente die Farbe des Systems verwenden, mit dem sie primaer interagiert. Z.B. ein VU-Adapter in einem TOGETHER-Service in ${vu} (gruen) statt orange.

Beispiel: BOA-API Internal

...@_colors.d2

boa: "BOA-API" {
  style.fill: ${together-light}

  controller: "KfzController" {
    style.fill: ${together}
  }

  # Fokus-Farbe: VU-Adapter in gruen (Zielsystem)
  dispatcher: "VU-Dispatcher" {
    style.fill: ${vu}
  }
}

Container Color Pattern

Each logical group gets a base color; items inside use lighter/darker variants:

feature: "Vergleichsrechner" {
  style.fill: "#e3f2fd"          # light blue container

  service: "KfzController" {
    style.fill: "#90caf9"        # darker blue component
  }
}

Collision warning: If using status colors on edges (red/green), avoid those for containers.

---

Analysis Mode (Highlighting Distinctions)

Use when highlighting quality, problems, or change status.

Status Colors

Category	Base	Medium (black text)	Dark (white text)
Green	${success}	${success-medium}	${success-dark}
Red	${error}	${error-medium}	${error-dark}
Yellow	${warning}	${warning-dark}	-
Gray	${neutral}	${neutral-medium}	${neutral-dark}

Keep it simple: If good/bad is enough, use green/red only.

Accessibility (must)

Combine color with at least one other cue:

Visual cue	Use for
Line thickness	Emphasis (thick = important)
Dashed/solid	Certainty (dashed = uncertain/optional)
Labels	Explicit meaning ("problematic", "OK")

# Good: color + thickness + label
a -> b: "Problematic coupling" {
  style.stroke: ${error-dark}
  style.stroke-width: 3
}

Require a legend when using status colors.

---

Import

...@_colors.d2

Copy _colors.d2 from v2/assets/colors/ to your docs/diagrams/ folder.

For project-specific component colors, see cookbook/discover-branding.md.

---

Shapes

Element	D2 Shape
Service, Process	rectangle
API, Gateway	hexagon
Database, Queue	cylinder
Decision	diamond
Start/End	oval
User/Actor	shape: image + icon: ./user.svg

Do NOT use shape: person - use user.svg icon instead.

Direction

• direction: right - data flows, architecture
• direction: down - process flows, flowcharts

Styling Rules

# Dashed lines for conditional/optional
connection: {
  style.stroke-dash: 3
}

# Terminal states get double stroke
end: {
  style.stroke-width: 2
}

---

Sequence Diagrams

shape: sequence_diagram

makler: "Makler" {
  shape: image
  icon: ./user.svg
}
api: "TOGETHER API" {
  style.fill: ${together}
}
vu: "VU Tarifrechner" {
  style.fill: ${vu}
}

makler -> api: "1. Anfrage"
api -> vu: "2. Berechnung"
vu -> api: "3. Ergebnis"
api -> makler: "4. Angebot"

AI agents: Always use D2. Mermaid is only for humans who prefer it.

---

Minimal Template (Context Mode)

...@_colors.d2

direction: right

user: "Makler" {
  shape: image
  icon: ./user.svg
}

together: "TOGETHER API" {
  shape: hexagon
  style.fill: ${together}
}

vu: "VU System" {
  style.fill: ${vu}
}

user -> together -> vu

---

Files to Copy

From tis-cca.styleguide/v2/:

• assets/colors/_colors.d2 -> your docs/diagrams/
• assets/icons/user.svg -> your docs/diagrams/

Full Documentation

• Cookbook: v2/guide/cookbook/ (recipes for AI agents)
• Style Guide: v2/guide/diagrams/style-guide.md
• Colors: v2/guide/colors/
• Color Preview: v2/assets/colors/color-tiers-preview.html