gitea_admin/erp_naurua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync styleguide 2026.05.18.1

Browse Source
This commit is contained in:
Mathias Gläser
2026-06-04 13:56:17 +02:00
parent f26d848d21
commit 2603c326b2
5 changed files with 28 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/styleguide/components/cards.html
+17
View File
@@ -63,6 +63,23 @@
</div>
</section>
<!-- Component: Basic Card -->
<section id="component-basic-card">
<p class="sg-preview-label">Component: Basic Card</p>
<div class="sg-preview-area">
<article class="sg-card" data-component="basic-card">
<div class="sg-card-segment sg-card-segment--body sg-card-segment--gray" data-component-part="card-body">
<p class="sg-body">
Basic Card mit nur einem Segment und hellgrauer Fläche gemäss Token.
</p>
</div>
</article>
</div>
</section>
<!-- Component: Content Card -->
<section id="component-content-card">
<p class="sg-preview-label">Component: Content Card</p>
docs/styleguide/docs/portal_sync_flow.md
+9 -10
View File
@@ -2,10 +2,16 @@
## Ziel
Der Styleguide bleibt in diesem Repository die Source of Truth. Das Portal holt:
Der Styleguide bleibt in diesem Repository die Source of Truth. Der Sync verteilt den freigegebenen Stand in beide Portal-Repos:
- den deploy-relevanten CSS-Upstream versioniert als `public/assets/styleguide.upstream.css`
- die vollstaendige Styleguide-Dokumentation gespiegelt nach `docs/styleguide`
- die portal-spezifische Fertig-CSS-Datei als `public/assets/styles.css`
Zielrepos:
- `WebApp_Aktienberater`
- `erp_naurua`
## Vorbereitung
@@ -21,19 +27,12 @@ Beispiel:
--commit-portal
```
Optional kann der Zielpfad ueberschrieben werden:
```bash
./scripts/sync_styleguide_to_webapp_aktienberater.sh \
--portal-repo "/absoluter/pfad/zum/portalrepo" \
--commit-portal
```
## Ergebnis im Portalrepo
- `public/assets/styleguide.upstream.css` aktualisiert
- `public/assets/styleguide.upstream.meta.json` aktualisiert (Version, Commit, Zeitstempel)
- `docs/styleguide` gespiegelt (mit `--delete`, ohne `.git`, `.codex`, `AGENTS.md`, `scripts/`)
- `public/assets/styles.css` aktualisiert
- Optional: automatischer Commit + Push im Portalrepo
## Standardprozess je Release
@@ -42,4 +41,4 @@ Optional kann der Zielpfad ueberschrieben werden:
2. `VERSION` erhoehen
3. Styleguide commit + push
4. Sync-Skript ausfuehren
5. Portal Smoke-Test
5. Beide Portalrepos Smoke-Testen
docs/styleguide/docs/skill-styleguide-anwendung.md
-58
View File
@@ -1,58 +0,0 @@
# AGENTS.md — Skill: styleguide-anwendung
## Zweck
Dieser Skill regelt verbindlich die fachlich korrekte Anwendung des zentralen Styleguides in konsumierenden Portalen.
## Scope
- Gilt nur fuer konsumierende Portal-Repositories.
- Gilt fuer die Anwendung von Tokens, Components, Patterns, Layouts und Templates aus dem Styleguide.
## Verbindliche Regeln
1. Reuse first: Styleguide-Bausteine MUESSEN 1:1 angewendet werden; visuelle Nachbauten sind verboten.
2. Components MUESSEN in Struktur, Klassenlogik und Semantik unveraendert bleiben.
3. Wenn ein passender Baustein existiert, SIND lokale Sondervarianten und Inselloesungen verboten.
4. Lokale Designentscheidungen ausserhalb des Styleguide-Systems sind verboten (Farben, Spacing, Typography, Radius, Shadow, States).
5. Ueberschreibungen von Component-Internals aus dem Portal-Kontext sind verboten.
6. Portal-spezifische Regeln sind nur zulaessig, wenn kein passender Baustein existiert, der Need fachlich belegt ist und keine Duplikation entsteht.
7. Jede lokale Abweichung MUSS minimal, rueckbaubar, klar begruendet und auf den konkreten Portal-Kontext begrenzt sein.
8. `public/assets/styles.css` ist read-only; manuelle Portal-Styles darin sind verboten.
9. `public/assets/styleguide.upstream.css` ist read-only; Upstream wird nie lokal gepatcht.
10. Eigene Portal-Styles duerfen ausschliesslich in `public/assets/styles.portal.css` gepflegt werden.
## 1:1-Uebernahmepflicht (kritisch)
Wenn ein Pattern oder Component aus dem Styleguide vorgegeben ist, gilt:
1. HTML-Struktur wird 1:1 uebernommen (kein vereinfachtes oder umgebautes Markup).
2. Klassenbezeichnungen werden 1:1 uebernommen (keine Umbenennungen, keine Teilmengen).
3. Alle dokumentierten States werden umgesetzt (z. B. default, hover, focus, active, disabled, selected).
4. Alle dokumentierten Interaktionen/Funktionalitaeten werden umgesetzt (keine Teilimplementierung).
5. Accessibility-Merkmale werden 1:1 uebernommen (ARIA, Labels, Keyboard-Fokus, semantische Elemente).
6. "Sinngemaesse" Nachimplementierung ist unzulaessig; erlaubt ist nur die vollstaendige Uebernahme oder eine explizit freigegebene Abweichung.
## Guardrails
- Keine Umgehung des Styleguides durch Inline-Styles oder seitenlokale Ad-hoc-CSS-Dateien.
- Keine erneute Einfuehrung von Legacy-CSS-Bloecken oder lokalen Vollkopien von Styleguide-Regeln.
- Keine Mischung von Upstream-Logik und Portal-Logik in derselben Quelldatei.
- Konflikte mit Upstream werden nicht durch Hotfixes in Output-Dateien geloest.
## Arbeitsmodus bei Aenderungen
1. Zuerst pruefen: Deckt ein bestehender Styleguide-Baustein den Fall ab.
2. Wenn ja: unveraendert uebernehmen (Pfad endet hier).
3. Wenn nein: minimalen Portal-Zusatz in `styles.portal.css` umsetzen, ohne Component-Internals zu beruehren.
4. Betroffene Views auf visuelle und funktionale Regressionen testen.
5. Lokale Abweichung im Commit mit kurzer fachlicher Begruendung dokumentieren.
## Abnahmekriterien
- Vorhandene Styleguide-Bausteine wurden priorisiert und nicht lokal dupliziert.
- Keine Portalregel greift in Component-Internals ein.
- Alle lokalen Regeln sind auf das notwendige Minimum begrenzt.
- `styles.css` und `styleguide.upstream.css` sind frei von manuellen Portal-Handedits.
- Lokale Regeln in `styles.portal.css` sind fachlich begruendet und rueckbaubar dokumentiert.
- Vorgegebene Patterns/Components sind in HTML, Klassen, States, Interaktionen und A11y vollstaendig 1:1 uebernommen.
docs/styleguide/docs/styleguide-integration-strategy.md
-136
View File
@@ -1,136 +0,0 @@
# 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.
public/assets/styleguide.upstream.meta.json
+2 -2
View File
@@ -1,7 +1,7 @@
{
"styleguideVersion": "2026.05.18.1",
"styleguideCommit": "0b8ec3f",
"syncedAtUtc": "2026-06-03T14:29:03Z",
"styleguideCommit": "1281178",
"syncedAtUtc": "2026-06-04T11:56:17Z",
"sourceRepo": "/Users/mathias/Documents/Dokumente Chouchou/Codebases/Styleguide",
"mirroredDocsPath": "docs/styleguide"
}