Styleguide/docs/styleguide-integration-strategy.md

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.