Zum Hauptinhalt springen

D2 Diagram Quick Reference

Minimal reference for AI agents creating D2 diagrams.

🤖 Generated with Claude Code

⚠️ Not yet reviewed

Co-Authored-By: Claude (noreply@anthropic.com)

Guiding Principles (MUST / SHOULD)​

  1. Start monochrome. Color SHOULD be added only when it answers a question the reader would have.
  2. Simplicity first. Several focused diagrams SHOULD be preferred over one complex diagram.
  3. Accessibility. A diagram MUST NOT rely on color alone - combine it with thickness, dash pattern, or labels.

Color Modes​

The mode MUST be chosen by the diagram's purpose, not by its type:

ModePurposeNode ColorsEdge Colors
ContextWho owns what?System ownership (MUST)System of origin
InternalHow does it work inside?Free-form / container-basedData flow
AnalysisHighlighting distinctionsContainer groupingsStatus (quality, change)

Context Mode (Cross-System Diagrams)​

Use when showing communication across system boundaries.

System Colors (MUST)​

SystemVariableHex
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:

TierSuffixUse CaseText Color
light-lightContainer backgroundsdark text
base(none)Component fillsdark text
medium-mediumVibrant fills, emphasisBLACK text
dark-darkLabels needing white textWHITE 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 (MUST — WCAG AA Compliant)​

Dark tiers - WHITE text​

These colors pass WCAG AA (4.5:1+) for white text and MUST be paired with white text:

VariableHexContrast
${together-dark}#A65F004.93:1
${vu-dark}#2E7D425.09:1
${kundensystem-dark}#5D56916.55:1
${cca-dark}#0066B25.93:1
${neutral-dark}#6666665.74:1
${success-dark}#1E70386.12:1
${error-dark}#B32D2D6.31:1
component: "Service" {
style.fill: ${vu-dark}
style.font-color: white
}

Medium tiers - BLACK text​

These vibrant colors MUST be paired with black text to reach sufficient contrast:

VariableHexContrast
${together-medium}#FF99009.81:1
${vu-medium}#69BA7A8.91:1
${neutral-medium}#9999997.37:1
${success-medium}#31AF5D7.42:1
${error-medium}#E540405.14:1
component: "API" {
style.fill: ${together-medium}
style.font-color: black
}

Base tiers - dark text (default)​

Base colors (${vu}, ${together}, etc.) work with the default dark text and MAY be left as they are.


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} für 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 primär interagiert. Z.B. ein VU-Adapter in einem TOGETHER-Service in ${vu} (grün) 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 grün (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: Where status colors (red/green) are used on edges, they MUST NOT also be used for containers.


Analysis Mode (Highlighting Distinctions)​

Use when highlighting quality, problems, or change status.

Status Colors​

CategoryBaseMedium (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: Where good/bad is enough, green/red alone SHOULD be used.

Accessibility (MUST)​

Color MUST be combined with at least one other cue:

Visual cueUse for
Line thicknessEmphasis (thick = important)
Dashed/solidCertainty (dashed = uncertain/optional)
LabelsExplicit meaning ("problematic", "OK")
# Good: color + thickness + label
a -> b: "Problematic coupling" {
style.stroke: ${error-dark}
style.stroke-width: 3
}

A legend MUST be provided whenever status colors are used.


Import​

...@_colors.d2

Every diagram MUST import the shared palette and MUST NOT hardcode hex values. Inside this repository, import it relatively from assets/colors/ — never copy it. The number of ../ depends on how deep the diagram sits, for example from development/ci-cd/diagrams/:

...@../../../assets/colors/_colors.d2

From another repository, copy assets/colors/_colors.d2 next to your .d2 sources, or fetch it from the CDN (see Brand Guide).

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


Shapes​

ElementD2 Shape
Service, Processrectangle
API, Gatewayhexagon
Database, Queuecylinder
Decisiondiamond
Start/Endoval
User/Actorshape: image + icon: ./user.svg

shape: person MUST NOT be used - use the 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 MUST 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

Shared Files​

Both live in assets/ at the root of this repository:

FilePurpose
assets/colors/_colors.d2the palette every diagram imports
assets/icons/user.svgthe person icon (D2's shape: person MUST NOT be used)

Diagrams in this repository reference them relatively, as products/shared/identity/diagrams/sls-sso-flow.d2 does. Diagrams in another repository copy them, or load them from the CDN.

Full Documentation​

  • Brand Guide — index, colours, logos, CDN paths
  • Cookbook — recipes for AI agents
  • Style Guide — the full D2 rules
  • Colors — interactive palettes
  • Colour preview: assets/colors/color-tiers-preview.html