TOGETHER CCA Diagram Style Guide

Richtlinien fuer technische Diagramme in TOGETHER CCA Projekten.

Referenzen:

Farbpalette: ../../assets/colors/
D2 Variablen: ../../assets/colors/_colors.d2
User-Icon: ../../assets/icons/user.svg
Templates: ./templates/
AI Quick Reference: ../AI_QUICK_REFERENCE.md
Cookbook: ../cookbook/

0. Grundprinzipien

Simplicity First

Monochrom starten. Farbe nur hinzufuegen, wenn sie eine Frage des Lesers beantwortet.
Einfachheit zuerst. Lieber mehrere fokussierte Diagramme als ein komplexes.
Barrierefreiheit (Pflicht). Nie nur auf Farbe verlassen - immer mit Linienstaerke, Strichelung oder Labels kombinieren.

1. Tool-Auswahl

Tool	Verwendung	Output
D2	Alle Diagramm-Typen (Architecture, Sequence, State Machines, Flowcharts)	PNG (Azure DevOps), SVG (optional)
Mermaid	Nur in Ausnahmefaellen, wenn bevorzugt	Inline-Rendering
Visio	Legacy, komplexe manuelle Layouts	PDF-Export erforderlich

Standard: D2. AI-Agenten verwenden ausschliesslich D2.

2. Diagramm-Typen

2.1 Architecture Diagrams

Zweck: System-Kontext, Komponenten-Uebersicht, Datenfluesse.

direction: right

# Nesting fuer logische Gruppierung
system: "System Name" {
  style.fill: ${together-light}

  component: Component {
    shape: rectangle
  }
}

Patterns:

direction: right fuer Datenfluesse
Container mit style.fill fuer Gruppierung
shape: hexagon fuer Gateways/APIs

2.2 State Machines

Zweck: Status-Lifecycle, Workflow-Zustaende.

direction: right

# Terminal States: doppelter Rahmen
completed: Completed {
  style.fill: ${success}
  style.stroke: ${success-dark}
  style.stroke-width: 2
}

# Bedingte Transitions: dashed
state -> next: "Condition" {
  style.stroke-dash: 3
}

Patterns:

Enum-Werte im Label: Staged (0)
Terminal States mit stroke-width: 2
Dashed Lines fuer bedingte/System-Transitions

2.3 Flowcharts

Zweck: Prozesse, Entscheidungslogik.

direction: down

start: Start { shape: oval }
decision: Entscheidung? { shape: diamond }
end: Ende { shape: oval }

start -> decision
decision -> end: Ja

Patterns:

direction: down fuer Prozessfluesse
shape: diamond fuer Entscheidungen
shape: oval fuer Start/End

2.4 Network Diagrams

Zweck: Infrastruktur, Netzwerk-Topologie.

direction: right

zone: "Zone Name" {
  style.fill: ${background}

  server: Server {
    shape: rectangle
    icon: https://icons.terrastruct.com/azure/Compute/10021-icon-service-Virtual-Machine.svg
  }
}

Patterns:

Zonen als Container
Icons fuer Infrastruktur-Komponenten (optional)

2.5 Sequence Diagrams

Zweck: API-Interaktionen, Request/Response-Flows.

shape: sequence_diagram

client: "Client"
api: "API" {
  style.fill: ${together}
}
db: "DB" {
  shape: cylinder
}

client -> api: "POST /resource"
api -> db: "INSERT"
db -> api: "OK"
api -> client: "201 Created"

Patterns:

shape: sequence_diagram am Anfang
System-Farben fuer Participants (Context-Modus)
Kurze Participant-Namen
Self-calls: a -> a: "Processing"
Optional/bedingt: style.stroke-dash: 3

3. Visuelle Standards

3.1 Farb-Modi

Farben nach Zweck des Diagramms waehlen, nicht nach Diagramm-Typ:

Modus	Zweck	Knotenfarben	Kantenfarben
Context	Wer gehoert zu wem?	System-Zugehoerigkeit (Pflicht)	System-Herkunft
Internal	Wie funktioniert es intern?	Theme-Hierarchie	Datenfluss
Analysis	Probleme hervorheben	Container-Gruppen	Status (gut/schlecht)

Internal Mode: Theme-Hierarchie statt System-Farben

Wenn ein Diagramm nur ein System zeigt (z.B. BOA-API intern), wird bei System-Farben alles gleich eingefaerbt → keine visuelle Hierarchie.

Empfehlung fuer Internal Mode:

Keine expliziten Container-Fills setzen → Theme uebernimmt Hierarchie
Semantische Farben nur bei System-Affinitaet (z.B. SoaGfx → CCA-blau, VU-Adapter → VU-gruen)
Theme 1 (Neutral Grey) oder Custom Theme verwenden

# Falsch: Alles orange weil "ist ja TOGETHER"
feature: {
  style.fill: ${together-light}
  component: { style.fill: ${together} }
}

# Richtig: Theme macht Hierarchie, Farbe nur wo relevant
feature: {
  # kein fill
  soagfx: { style.fill: ${cca} }      # CCA-Affinitaet
  vu_adapter: { style.fill: ${vu} }   # VU-Affinitaet
}

3.2 Farbpaletten

Modus-spezifische Paletten

Palette	Modus	Import
`_colors-context.d2`	Context	System-Farben + Alt-Varianten
`_colors-internal.d2`	Internal	Hierarchie-Ramps + System-Farben
`_colors-analysis.d2`	Analysis	Status-Farben + System-Alt
`_colors.d2`	Alle	Vollstaendige Palette

Setup:

# Modus-spezifische Palette kopieren
cp path/to/tis-cca.styleguide/v2/assets/colors/_colors-internal.d2 docs/

# Oder vollstaendige Palette
cp path/to/tis-cca.styleguide/v2/assets/colors/_colors.d2 docs/

Hierarchie-Ramps (Internal Mode)

Fuer Container-Nesting in Internal Mode. Eine Ramp pro Diagramm waehlen:

Ramp	Farben	Empfohlen fuer
`slate-1..4`	Grau (neutral)	Default, alle Hintergruende
`sand-1..4`	Braun (warm)	CCA-Hintergrund
`lavender-1..4`	Lila	Alle Hintergruende ✓
`teal-1..4`	Blaugruen	TOGETHER-Hintergrund
`turquoise-1..4`	Cyan	TOGETHER-Hintergrund
`fandango-1..4`	Rose/Pink	Alle Hintergruende ✓

Kombinationen mit System-Hintergrund:

System-Hintergrund	Beste Ramps	Vermeiden
TOGETHER (orange)	Slate, Lavender, Teal, Turquoise, Fandango	Sand (aehnlich warm)
CCA (blau)	Sand, Lavender, Fandango	Turquoise, Slate (aehnlich blau)

...@_colors-internal.d2

# Hierarchie mit Lavender-Ramp
outer: { style.fill: ${lavender-1} }
  middle: { style.fill: ${lavender-2} }
    inner: { style.fill: ${lavender-3} }
      leaf: { style.fill: ${lavender-4} }

Alt-Farben (Konflikt-Vermeidung)

Jede System-Farbe hat eine Alternative fuer Faelle wo die Primaer-Farbe mit Status-Farben kollidiert:

System	Primaer	Alt	Konflikt mit
Together	`${together}`	`${together-alt}`	warning (orange)
CCA	`${cca}`	`${cca-alt}`	info (blau)
VU	`${vu}`	`${vu-alt}`	success (gruen)
Kundensystem	`${kundensystem}`	`${kundensystem-alt}`	-

System-Farben (Context-Modus)

Farben importieren

# Vollständige Palette
...@../../../assets/colors/_colors.d2

# Oder modus-spezifisch
...@../../../assets/colors/_colors-context.d2
...@../../../assets/colors/_colors-internal.d2
...@../../../assets/colors/_colors-analysis.d2

Farbkategorien

Kategorie	Variable	Verwendung
Kundensysteme	`${kundensystem}`	DMS, CRM, externe Partner (lila)
VU-Systeme	`${vu}`, `${vu-dark}`	Versicherungs-Systeme (gruen)
CCA	`${cca}`, `${cca-dark}`	CCA Produkte (blau)
TOGETHER	`${together}`, `${together-dark}`	TOGETHER Platform (orange)
Infrastruktur	`${neutral}`	Server, Netzwerk (grau)

Varianten:

-light Suffix: Container-Hintergrund (z.B. ${vu-light})
-dark Suffix: Rahmen, Betonung (z.B. ${vu-dark})
Basis: Komponenten-Fuellung (z.B. ${vu})

Status-Farben (Analysis-Modus)

Kategorie	Hell	Standard	Dunkel	Verwendung
Rot	`${error}`	-	`${error-dark}`	Problematisch, blockierend
Gelb	`${warning-light}`	`${warning}`	`${warning-dark}`	Untersuchen, unsicher
Gruen	`${success}`	-	`${success-dark}`	OK, verifiziert
Grau	`${neutral-light}`	`${neutral}`	`${neutral-dark}`	Neutral, unveraendert

Einfach halten: Wenn gut/schlecht reicht, nur gruen/rot verwenden.

3.3 Barrierefreiheit (Pflicht)

Rot-Gruen-Blindheit ist haeufig. Farbe immer mit mindestens einem weiteren Hinweis kombinieren:

Visueller Hinweis	Verwendung
Linienstaerke	Betonung (dick = wichtig)
Strichelung	Sicherheit (gestrichelt = unsicher/optional)
Labels	Explizite Bedeutung ("problematisch", "OK")

# Gut: Farbe + Staerke + Label
a -> b: "Problematische Kopplung" {
  style.stroke: "#E54040"
  style.stroke-width: 3
}

Bei Status-Farben immer eine Legende einfuegen.

3.4 Container-Farben (Internal/Analysis-Modus)

Farb-Hierarchie fuer Interna

Produkt-Farbe (wenn vorhanden) → z.B. BOAbot #F49819, OMDSmanager #0066B2
System-Farbe (Standard) → z.B. ${together} fuer TOGETHER-Interna
Fokus-Farbe (optional) → Komponenten koennen 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 - um den Zweck zu verdeutlichen.

Beispiel: Internal Mode mit Fokus-Farben

...@_colors.d2

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

  controller: "KfzController" {
    style.fill: ${together}       # System-Farbe
  }

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

Container-Pattern

Jede logische Gruppe bekommt eine Basisfarbe; Elemente darin heller/dunkler:

feature: "Vergleichsrechner" {
  style.fill: "#e3f2fd"          # heller Container

  service: "KfzController" {
    style.fill: "#90caf9"        # dunklere Komponente
  }
}

Kollisions-Warnung: Bei Status-Farben auf Kanten (rot/gruen) diese nicht fuer Container verwenden.

3.5 Projekt-spezifische Farben

Fuer konsistente Komponenten-Farben ueber mehrere Diagramme:

docs/.branding/_project-colors.d2 anlegen
Projekt-Komponenten definieren
In Diagrammen importieren

# docs/.branding/_project-colors.d2
vars: {
  soa-gfx: "#90caf9"
  identity-server: "#ffcc80"
}

Siehe Cookbook: discover-branding fuer Details.

3.6 Shape-Semantik

Shape	D2	Bedeutung
Rechteck	`rectangle`	Service, Prozess, State
Zylinder	`cylinder`	Datenspeicher, Queue
Hexagon	`hexagon`	Gateway, API-Endpoint (nur kurze Labels!)
Raute	`diamond`	Entscheidung
User-Icon	`icon: ./user.svg`	Benutzer, Akteur (siehe 3.6.2)
Oval	`oval`	Start/End, Event
Step	`step`	Prozessschritt
Cloud	`cloud`	Externe Services

3.6.1 Hexagon-Groesse bei APIs

Hexagons skalieren mit Inhalt und werden bei Listen/mehrzeiligem Text sehr gross.

Inhalt	Empfehlung
Kurzes Label ("API Gateway")	`hexagon` ✓
Endpoint-Liste	`rectangle` oder separate Nodes

# Falsch: Hexagon mit Liste wird riesig
api: "Public API" {
  shape: hexagon
  # POST /comparisons
  # POST /offers
  # ...
}

# Richtig: Hexagon als Label, Endpoints separat
api: "Public API" { shape: hexagon }
endpoints: {
  post_compare: "POST /comparisons"
  post_offers: "POST /offers"
}
api -> endpoints

3.6.2 User-Icon fuer Akteure

Fuer Benutzer/Akteure das eigene user.svg Icon verwenden statt shape: person:

# Richtig: Eigenes User-Icon (shape: image fuer rahmenlose Darstellung)
Makler: "Makler/Vermittler" {
  shape: image
  icon: ./user.svg
}

# Falsch: D2 person shape (nicht verwenden)
Makler: "Makler/Vermittler" {
  shape: person
}

Hinweis: Das user.svg ist im Styleguide unter v2/assets/icons/user.svg verfuegbar. Siehe Icons fuer Details.

3.7 Kontrast-Regeln

# Dunkle Farben (Stufe 7+) → weisse Schrift
dark: {
  style.fill: ${cca-dark}
  style.font-color: white
}

# Helle Farben (Stufe 0-4) → keine Angabe
light: {
  style.fill: ${together}
}

3.8 Connections

Stil	D2	Bedeutung
Solid	(default)	Direkter Fluss, Hauptpfad
Dashed	`style.stroke-dash: 3`	Optional, bedingt, System-gesteuert
Colored	`style.stroke: ${success-dark}`	Status-abhaengige Transition

4. Naming Conventions

4.1 Dateinamen

Pattern: {domain}-{type}.d2

provision-request-state-machine.d2
staging-overview.d2
benutzer-flow.d2

4.2 Element-IDs

kebab-case fuer Container: staging-layer, external-sources
Kurz und sprechend: ad, db, api
Keine Umlaute: benutzer nicht benuetzer

4.3 Labels

Domain-Begriffe auf Deutsch: Benutzer, Vermittler, Sachbearbeiter
Technische Begriffe auf Englisch: API, Database, Processing
Status mit Enum-Werten: Staged (0), Completed (3)

5. Datei-Organisation

project/
└── docs/
    └── diagrams/
        ├── overview.d2
        ├── overview.png       # Rendered output
        └── state-machine.d2

Anforderungen:

Source (.d2) und Output (.png) gemeinsam committen
Relative Pfade in Markdown mit ./ Prefix
PNG fuer Azure DevOps Kompatibilitaet

6. Templates

Vorlagen in ./templates/:

architecture-template.d2 - System-Uebersicht
flowchart-template.d2 - Prozess-Diagramm
state-machine-template.d2 - Status-Lifecycle
network-template.d2 - Infrastruktur

Kopieren und anpassen fuer neue Diagramme.

7. Rendering

# PNG (empfohlen fuer Azure DevOps)
d2 diagram.d2 diagram.png

# SVG (optional)
d2 diagram.d2 diagram.svg

7.1 Theme-Empfehlung

Bei Verwendung der Styleguide-Farbpalette Theme 1 (Neutral Grey) verwenden:

d2 --theme 1 diagram.d2 diagram.png

Theme	ID	Verwendung
Neutral Grey	`1`	Empfohlen bei Custom Colors - neutrale Basis ohne Farbkonflikte
Default	`0`	Nur fuer Diagramme ohne eigene Farbpalette
Colorblind Clear	`8`	Alternative fuer Barrierefreiheit

Grund: D2's Default-Theme verwendet eigene Container-Fills die mit der Styleguide-Palette (besonders Orange/Together) kollidieren koennen.

8. Common Patterns

8.1 Error Flows

Fehler-Pfade mit Rot + Gestrichelter Linie darstellen:

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

user -> api: "Request"
api -> db: "Query"
db -> api: "Timeout" {
  style.stroke: ${error-dark}
  style.stroke-dash: 3
  style.stroke-width: 2
}
api -> user: "500 Error" {
  style.stroke: ${error-dark}
  style.stroke-dash: 3
}

Best Practice: Error-Pfade mit Label beschriften (z.B. "Timeout", "Validation Failed").

8.2 Authentication Flows

Auth-Steps mit Lock-Icon oder Protokoll-Label:

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

client: "Client App" {
  style.fill: ${kundensystem}
}
auth: "Auth Server" {
  style.fill: ${together}
}
api: "Protected API" {
  style.fill: ${cca}
}

client -> auth: "1. Login (OAuth2)" {
  style.stroke-width: 2
}
auth -> client: "2. JWT Token"
client -> api: "3. Request + Bearer Token" {
  style.stroke-width: 2
}
api -> client: "4. Protected Data"

Best Practice: Nummerierte Steps für Sequenz, wichtige Auth-Schritte dicker zeichnen.

8.3 Async Communication

Queues mit Cylinder-Shape + Dashed Lines:

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

producer: "Producer" {
  style.fill: ${together}
}
queue: "Message Queue" {
  shape: cylinder
  style.fill: ${neutral}
}
consumer: "Consumer" {
  style.fill: ${cca}
}

producer -> queue: "Publish" {
  style.stroke-dash: 3
}
queue -> consumer: "Subscribe" {
  style.stroke-dash: 3
}

Best Practice: Async-Connections immer gestrichelt, Queue als Cylinder.

8.4 External Systems

Externe Systeme (Partner, VU) mit Cloud-Shape oder VU-Farbe:

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

internal: "TOGETHER API" {
  style.fill: ${together}
}
vu: "VU System" {
  shape: cloud
  style.fill: ${vu}
}
partner: "Partner API" {
  shape: cloud
  style.fill: ${neutral}
}

internal -> vu: "HTTPS"
internal -> partner: "REST"

Best Practice: Cloud-Shape für externe Systeme, VU-Farbe für Versicherungen.

0. Grundprinzipien​

Simplicity First​

1. Tool-Auswahl​

2. Diagramm-Typen​

2.1 Architecture Diagrams​

2.2 State Machines​

2.3 Flowcharts​

2.4 Network Diagrams​

2.5 Sequence Diagrams​

3. Visuelle Standards​

3.1 Farb-Modi​

Internal Mode: Theme-Hierarchie statt System-Farben​

3.2 Farbpaletten​

Modus-spezifische Paletten​

Hierarchie-Ramps (Internal Mode)​

Alt-Farben (Konflikt-Vermeidung)​

System-Farben (Context-Modus)​

Farben importieren​

Farbkategorien​

Status-Farben (Analysis-Modus)​

3.3 Barrierefreiheit (Pflicht)​

3.4 Container-Farben (Internal/Analysis-Modus)​

Farb-Hierarchie fuer Interna​

Beispiel: Internal Mode mit Fokus-Farben​

Container-Pattern​

3.5 Projekt-spezifische Farben​

3.6 Shape-Semantik​

3.6.1 Hexagon-Groesse bei APIs​

3.6.2 User-Icon fuer Akteure​

3.7 Kontrast-Regeln​

3.8 Connections​

4. Naming Conventions​

4.1 Dateinamen​

4.2 Element-IDs​

4.3 Labels​

5. Datei-Organisation​

6. Templates​

7. Rendering​

7.1 Theme-Empfehlung​

8. Common Patterns​

8.1 Error Flows​

8.2 Authentication Flows​

8.3 Async Communication​

8.4 External Systems​

9. Checkliste​

0. Grundprinzipien

Simplicity First

1. Tool-Auswahl

2. Diagramm-Typen

2.1 Architecture Diagrams

2.2 State Machines

2.3 Flowcharts

2.4 Network Diagrams

2.5 Sequence Diagrams

3. Visuelle Standards

3.1 Farb-Modi

Internal Mode: Theme-Hierarchie statt System-Farben

3.2 Farbpaletten

Modus-spezifische Paletten

Hierarchie-Ramps (Internal Mode)

Alt-Farben (Konflikt-Vermeidung)

System-Farben (Context-Modus)

Farben importieren

Farbkategorien

Status-Farben (Analysis-Modus)

3.3 Barrierefreiheit (Pflicht)

3.4 Container-Farben (Internal/Analysis-Modus)

Farb-Hierarchie fuer Interna

Beispiel: Internal Mode mit Fokus-Farben

Container-Pattern

3.5 Projekt-spezifische Farben

3.6 Shape-Semantik

3.6.1 Hexagon-Groesse bei APIs

3.6.2 User-Icon fuer Akteure

3.7 Kontrast-Regeln

3.8 Connections

4. Naming Conventions

4.1 Dateinamen

4.2 Element-IDs

4.3 Labels

5. Datei-Organisation

6. Templates

7. Rendering

7.1 Theme-Empfehlung

8. Common Patterns

8.1 Error Flows

8.2 Authentication Flows

8.3 Async Communication

8.4 External Systems

9. Checkliste