ADR: CSS-Variablen Token System für Event-Styling

Status: ✅ Accepted (Dezember 2025)
Datum: 2025-12-21
Kontext: Design System Consolidation für Jekyll + Decap CMS
Betroffen: assets/css/events.css, _includes/, _pages/, cms-static/

Problem Statement

Das Event-Management-System hatte fragmentierte Styling-Definition:

Vorher (Anti-Pattern)

- Farben in 5+ Orten definiert (hardcoded hex-Werte)
- Event-Card Badges: inline style="background-color: #hex"
- Filter-Buttons: inline style="background-color: #hex"
- veranstaltungen.md: 50+ Zeilen <style> Block mit !important
- CMS Admin: Farben nochmal in custom-admin.css (Duplikate)
- Keine zentrale Single Source of Truth

Probleme:

1. ❌ Änderungsfehler: Farbe an 5 Stellen ändern = 5x Fehlerquellen
2. ❌ Wartbarkeit: Kein klarer Ownership, wo welche Farbe definiert ist
3. ❌ Skalierbarkeit: Neuer Event-Typ = Code-Änderungen in 3+ Dateien
4. ❌ CMS Autonomie: custom-admin.css konnte nicht auf externe CSS zugreifen (Netlify Deploy)

Lösung: CSS-Variablen Token System

Design Entscheidungen

1. CSS-Variablen statt SCSS-Variablen

Gewählt: CSS Custom Properties (:root { --color-primary: ... })
Alternativ geprüft: SCSS Variables

Gründe für CSS-Variablen:

• ✅ Runtime-Austausch möglich (zukünftige Theme-Switcher)
• ✅ In DOM inspektion sichtbar (Developer-freundlich)
• ✅ Keine Build-Zeit Abhängigkeit
• ✅ JavaScript kann Werte ändern (z.B. für CMS Admin Colorization)

SCSS wäre besser wenn:

• Nur Jekyll, kein CMS
• Performance > Flexibilität

2. Two-Token Architecture (Jekyll + CMS getrennt)

Gewählt: Zwei separate :root Definitionen

• assets/css/events.css → Jekyll Public Site
• cms-static/admin/custom-admin.css → CMS Admin (autark)

Grund: cms-static/ wird autonomous zu Netlify deployed

├─ _site/                    ← GitHub Pages (Jekyll)
│  └─ assets/css/events.css
└─ cms-static/               ← Netlify (Decap CMS)
   └─ admin/custom-admin.css

Constraint: Keine cross-imports möglich. Jeder Teil muss self-contained sein.

3. Event-Type Farben: 3-File Sync Pattern

Gewählt: Single Source of Truth + zwei Replicas

# Primary (Jekyll)
_data/event_types.yml
  mach-mit-mathe:
    color: "#E8F4F8"

# Replica 1 (CMS Config)
cms-static/admin/event-types.json
  "mach-mit-mathe": {
    "color": "#E8F4F8"
  }

# Replica 2 (CMS Styling)
cms-static/admin/custom-admin.css
  :root {
    --event-color-mach-mit-mathe: #E8F4F8;
  }

Warum 3 Dateien?

• _data/event_types.yml = Single Source of Truth (Redakteure ändern hier)
• event-types.json = Wird von CMS JavaScript gelesen (Defaults)
• custom-admin.css = Styling muss lokal verfügbar sein

Trade-off: Manuelles Sync erforderlich
Nutzen: Autarke Deployments, keine Abhängigkeiten

4. CSS Custom Properties in HTML-Includes

Gewählt: style="--event-type-color: "

<!-- _includes/event-card.html -->
<article style="--event-type-color: ;">
  <!-- CSS nutzt: var(--event-type-color) -->
</article>

Warum nicht Inline-Style:

<!-- ❌ Anti-Pattern -->
<article style="border-left: ;">

<!-- ✅ Pattern -->
<article style="--event-type-color: ;">

Gründe:

• Trennung von Daten (–var) und Darstellung (CSS)
• CSS kann überschrieben werden (Responsive, Dark Mode)
• Wartbarer als Inline Color Attributes

Lint Warning: Inline styles sind normalerweise Anti-Pattern, aber hier:

• Notwendig für Template-Variablen
• CSS Custom Properties sind best practice
• Linter-Beschwerde ist akzeptabel (dokumentiert)

Implementierung

Phase 1: Token Definition ✅

/* assets/css/events.css */
:root {
  --color-primary: #003d82;
  --color-primary-strong: #002855;
  --color-primary-stronger: #001a3d;
  --color-surface: #ffffff;
  --color-surface-muted: #f5f5f5;
  --color-surface-soft: #f9f9f9;
  --color-border: #d0d0d0;
  --color-text: #111111;
  --color-text-muted: #444444;
  --color-link: #0066cc;
  --color-link-strong: #004999;
  --color-focus: #ffd700;
  --radius-sm: 6px;
  --radius-md: 8px;
  --shadow-soft: 0 2px 8px rgba(0, 0, 0, 0.1);
  --shadow-hover: 0 4px 16px rgba(0, 0, 0, 0.15);
}

Phase 2: Component Refactor ✅

.event-card {
  border-left: 4px solid var(--event-type-color, var(--color-border));
  box-shadow: var(--shadow-soft);
}

.event-filter-btn--type {
  background-color: var(--event-type-color);
}

Phase 3: Template Updates ✅

<button style="--event-type-color: ;">
  
</button>

Vorteile

Nachteile & Trade-offs

Zukünftige Erweiterungen

1. Dark Mode Support

@media (prefers-color-scheme: dark) {
  :root {
    --color-primary: #0066ff;
    --color-surface: #1a1a1a;
  }
}

2. Theme Switcher (Client-Side)

document.documentElement.style.setProperty(
  '--color-primary',
  '#ff0000'
);

3. Zusätzliche Komponenten

• Blog-Post Styling
• Formular-Styling
• Table Styling → Alle könnten --color-primary, --radius-sm, etc. nutzen

4. Token Export zu Design Tools

npm run export-tokens  # → tokens.json für Figma

Ähnliche Systeme (für Referenz)

• Tailwind CSS: Utility-first, vordefinierte Tokens
• Material Design: Token-basierte Theming
• Carbon Design System: CSS Custom Properties für theming

Diese Lösung: Minimalistisch, Jekyll-freundlich, Decap CMS kompatibel

Testing & Validation

✅ Durchgeführt:

• Visueller Test aller Event-Card Typen
• Filter-Button Farbkonsistenz
• Hover/Focus States
• Responsive Verhalten
• CMS Admin Styling

❌ Nicht vorhanden (für Zukunft):

• Automated CSS regression tests
• Color contrast WCAG Validator (automated)
• Token sync validator (CI/CD Check)

Lessons Learned

✅ Was gut lief

1. CSS Custom Properties: Sehr flexibel, einfach zu debuggen
2. Token Definition in :root: Zentral, gut zu finden
3. Jekyll + CMS Trennung: Erzwang klare Grenzen

⚠️ Häufige Fehler (für Zukunft)

1. Token-Namen nicht konsistent
   → Guideline: --[category]-[element]-[state]
   → Beispiel: --color-primary-strong, nicht --primary-dark

2. Fallback vergessen
   → IMMER: var(--color-primary, #003d82)

3. 3-File-Sync vergessen
   → Bei Event-Typ Farb-Änderung alle 3 Dateien updaten!

4. Inline Styles in anderen Komponenten einschleichen
   → Neue Features sollten Tokens verwenden

Für zukünftige LLMs / Entwickler

Wenn du Farben ändern willst:

1. Ist es ein Token (überall benutzt)? → assets/css/events.css :root
2. Ist es ein Event-Typ? → _data/event_types.yml + 2x Replicas
3. Ist es nur eine Komponente? → Komponenten-spezifische Variable

Wenn du Fehler debuggen willst:

1. Browser DevTools: Inspect Element → Computed Styles
2. Suche nach var(-- im Code
3. Fallback-Wert funktioniert? → CSS Variable nicht gefunden
4. 3-Datei-Sync korrekt? → Besonders bei Event-Typ Farben

Wenn du neue Komponenten baust:

1. Immer Tokens verwenden (var(--color-*), var(--radius-*), etc.)
2. Nie Hardcoded Hex-Werte
3. Fallback mitdenken: var(--color-primary, #003d82)

Links zu verwandten Dokumenten

• DESIGN_SYSTEM.md – Token-Übersicht & Checklisten
• VERANSTALTUNGEN_TECHNIK.md – Event-System Architektur
• assets/css/events.css – Token-Definitions-Datei
• cms-static/admin/custom-admin.css – CMS-spezifische Tokens

Approval & Status