From 0e2f734bf620aa61746d916e6876918867c626d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mathias=20Gla=CC=88ser?= Date: Mon, 1 Jun 2026 11:47:11 +0200 Subject: [PATCH] docs: tighten styleguide application skill with best-practice guardrails --- docs/skill-styleguide-anwendung.md | 55 +++++++++++++++--------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/docs/skill-styleguide-anwendung.md b/docs/skill-styleguide-anwendung.md index e742eea..3191441 100644 --- a/docs/skill-styleguide-anwendung.md +++ b/docs/skill-styleguide-anwendung.md @@ -2,46 +2,45 @@ ## Zweck -Dieser Skill regelt verbindlich die Anwendung des zentralen Styleguides in konsumierenden Portalen. +Dieser Skill regelt verbindlich die fachlich korrekte Anwendung des zentralen Styleguides in konsumierenden Portalen. ## Scope -- Gilt nur fuer Portal-Repositories, die den Styleguide per Sync-Skript uebernehmen. -- Gilt nur fuer die CSS-Integrationsschicht im Portal. +- Gilt nur fuer konsumierende Portal-Repositories. +- Gilt fuer die Anwendung von Tokens, Components, Patterns, Layouts und Templates aus dem Styleguide. ## Verbindliche Regeln -1. `public/assets/styleguide.upstream.css` ist Upstream und read-only. -2. `public/assets/styles.css` ist Build-/Sync-Output und read-only. -3. Eigene Portal-Styles duerfen ausschliesslich in `public/assets/styles.portal.css` gepflegt werden. -4. Direkte manuelle Aenderungen in `public/assets/styles.css` sind verboten. -5. Direkte manuelle Aenderungen in `public/assets/styleguide.upstream.css` sind verboten. -6. Bei jedem Styleguide-Update wird ausschliesslich synchronisiert und danach `styles.css` neu erzeugt/uebernommen. -7. Konflikte nach Sync werden nur in `styles.portal.css` geloest, nie durch Patchen von Upstream-Dateien. -8. Es darf keine weitere lokale Vollkopie des Styleguides in anderen Portaldateien geben. -9. Produktiv eingebunden wird nur `public/assets/styles.css`. -10. Die Reihenfolge der CSS-Quellen bleibt strikt: - - `public/assets/styleguide.upstream.css` - - `public/assets/styles.portal.css` - - Ausgabe: `public/assets/styles.css` +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. ## Guardrails -- Keine `:root`-Duplikate aus lokalen Legacy-Bloecken in produktiven Zielpfaden. -- Keine Umgehung durch Inline-Styles oder seitenlokale CSS-Dateien als Ersatz fuer `styles.portal.css`. -- Keine Vermischung von Upstream- und Portal-Verantwortung in derselben Quelldatei. +- 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. Styleguide-Sync ausfuehren. -2. Ergebnisdateien aktualisieren lassen. -3. Nur notwendige Portal-Abweichungen in `styles.portal.css` anpassen. -4. Smoke-Test der betroffenen Seiten. -5. Commit mit kurzer Begruendung der lokalen Abweichungen. +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 -- `styles.css` enthaelt keine manuell gepflegten Portalregeln. -- Portal-spezifische Regeln liegen vollstaendig in `styles.portal.css`. -- Upstream-Datei bleibt unveraendert durch lokale Handedits. -- Nach Sync und Build gibt es keine visuelle Regression in den betroffenen Kernseiten. +- 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.