docs: add normative skill draft for styleguide application in portals

2026-06-01 11:45:27 +02:00
parent d5794576d1
commit 6efe9a90ae
1 changed files with 47 additions and 0 deletions
@@ -0,0 +1,47 @@
+# AGENTS.md — Skill: styleguide-anwendung
+
+## Zweck
+
+Dieser Skill regelt verbindlich die 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.
+
+## 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`
+
+## 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.
+
+## 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.
+
+## 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.