# Integrationsstrategie Styleguide -> WebApp_Aktienberater

Stand: 18. Mai 2026
Scope: Nur Einbindungsstrategie und Migrationsvorgehen fuer CSS. Keine Frontend-Umbauten in diesem Dokument.

## 1. Zielbild

`public/assets/styles.css` bleibt die produktiv eingebundene Datei, wird aber kuenftig deterministisch aus zwei klar getrennten Schichten erzeugt:

1. `styleguide` (upstream, read-only im Projektkontext)
2. `portal` (lokale App-spezifische Regeln)

Es gibt keine weitere manuelle Vollkopie von CSS-Bloecken in die Produktionsdatei.

## 2. Aktueller Ist-Zustand (belegt)

- Produktivseiten binden `public/assets/styles.css` ein.
- Es gibt keine lokale Styleguide-Kopie mehr im Zielrepo.
- `public/assets/styles.css` enthaelt derzeit einen Mischstand aus Styleguide-Teil plus Legacy-Teil.

Konsequenz: Updates und Debugging sind aktuell fehleranfaellig, weil keine harte Trennung zwischen upstream und lokal besteht.

## 3. Verbindliche Struktur (Soll)

Neue Quellstruktur im Zielrepo:

- `public/assets/styleguide.upstream.css`  
  Upstream-Quelle (aus dem Styleguide-Repo uebernommen, im Zielrepo read-only behandeln)
- `public/assets/styles.portal.css`  
  Lokale Portal-Ergaenzungen/Overrides (einzige lokale CSS-Quelle fuer App-spezifische Abweichungen)
- `public/assets/styles.css`  
  Build-Output fuer Produktivbetrieb (generiert, nicht manuell gepflegt)

## 4. Build-Reihenfolge (verbindlich)

Die Reihenfolge ist fix:

1. `public/assets/styleguide.upstream.css`
2. `public/assets/styles.portal.css`
3. Ausgabe nach `public/assets/styles.css`

Damit gilt:

- Standard liegt im Styleguide.
- Lokale Abweichungen liegen nur im Portal-Layer.
- Keine dritte Ebene mit ad-hoc CSS in Produktivdateien.

## 5. Migrationsphasen

### Phase A: Freeze und Trennung

- Bestehenden Zustand einfrieren (Baseline-Commit).
- Legacy-Abschnitte in `public/assets/styles.css` identifizieren.
- Lokale, weiterhin benoetigte Regeln nach `public/assets/styles.portal.css` verschieben.

### Phase B: Build-Einfuehrung

- Build-Skript einfuehren, das die zwei Quellen in fixer Reihenfolge zusammenfuehrt.
- `public/assets/styles.css` nur noch als Build-Output behandeln.

### Phase C: Bereinigung

- Doppelte `:root`-Definitionen und ueberschneidende Token schrittweise entfernen.
- Jede entfernte Legacy-Regel gegen produktive Screens verifizieren.

### Phase D: Regelbetrieb

- Neue UI-Änderungen nur noch in:
  - Styleguide-Repo (globale Patterns/Tokens) oder
  - `styles.portal.css` (projektlokale Spezifika)

## 5a. Verbindliche Migrationsreihenfolge

Die Ablösung erfolgt in fester Reihenfolge:

1. Login
2. Hauptliste
3. Detail
4. Admin

Pro Schritt gilt:

- Legacy-Regeln nur fuer den jeweiligen Bereich ablösen.
- Smoke-Test direkt nach jeder Ablösung.
- Erst nach bestandenem Test den naechsten Bereich migrieren.

## 5b. Verbindliche Exit-Kriterien (Legacy entfernt)

Die Migration ist erst abgeschlossen, wenn alle Punkte erfuellt sind:

1. `public/assets/styles.css` ist reiner Build-Output aus:
   - `public/assets/styleguide.upstream.css`
   - `public/assets/styles.portal.css`
2. In `public/assets/styles.css` existiert kein Legacy-Blockmarker mehr:
   - `LEGACY STYLES`
   - `To be migrated step by step to styleguide system`
3. Keine manuellen Produktivregeln mehr direkt in `public/assets/styles.css`.
4. Alle weiterhin benoetigten lokalen Abweichungen liegen ausschliesslich in `public/assets/styles.portal.css`.
5. Doppelte oder konkurrierende `:root`-Definitionen aus Legacy wurden entfernt.

## 6. Update-Prozess bei Styleguide-Änderungen

Ja, es braucht regulaere Updates im Zielrepo, sobald der Styleguide geaendert wurde.

Minimalprozess:

1. Neuen Styleguide-Stand nach `public/assets/styleguide.upstream.css` uebernehmen.
2. `public/assets/styles.css` neu bauen.
3. Kurztest der betroffenen Seiten (mindestens: Login, Hauptliste, Detail, Admin).
4. Falls Konflikte auftreten: nur `styles.portal.css` anpassen, nicht upstream patchen.

## 7. Guardrails

- Keine manuellen Hotfixes direkt in `public/assets/styles.css`.
- Keine Vermischung von Upstream-Regeln und Portalregeln in derselben Quelldatei.
- Keine erneute Vollkopie alter Legacy-Bloecke.
- Jede Portal-Abweichung braucht kurze Begruendung im Commit.

## 7a. Verbindliche Abnahme-Checkliste je Migrationsschritt

Vor dem Abschluss eines jeden Schritts:

1. Seite rendert ohne visuelle Regressionen in den betroffenen Hauptbereichen.
2. Interaktive Elemente bleiben funktionsfaehig (Buttons, Tabs, Filter, States).
3. Keine neuen direkten Anpassungen in `public/assets/styles.css`.
4. Diff zeigt nur:
   - Upstream-Update (`styleguide.upstream.css`) und/oder
   - lokale Portal-Regeln (`styles.portal.css`) und Build-Output.
5. Commit-Text dokumentiert kurz, welcher Legacy-Abschnitt abgeloest wurde.

## 8. Verantwortungsgrenze

- Styleguide-Repo: Design-System-Wahrheit (Tokens, Components, Patterns).
- WebApp_Aktienberater: Integration, lokale Komposition, produktive Einbindung.

Damit bleibt das System updatefaehig und driftarm, ohne laufende Frontend-Umsetzung zu blockieren.