From d92817f1791e30748bebb124f74f2ed8b6ff732b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mathias=20Gla=CC=88ser?= Date: Mon, 1 Jun 2026 11:48:54 +0200 Subject: [PATCH] feat(skill): add styleguide-anwendung skill for strict 1:1 portal usage --- .codex/skills/styleguide-anwendung/SKILL.md | 63 +++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 .codex/skills/styleguide-anwendung/SKILL.md diff --git a/.codex/skills/styleguide-anwendung/SKILL.md b/.codex/skills/styleguide-anwendung/SKILL.md new file mode 100644 index 0000000..5676958 --- /dev/null +++ b/.codex/skills/styleguide-anwendung/SKILL.md @@ -0,0 +1,63 @@ +--- +name: styleguide-anwendung +description: Verwenden fuer die verbindliche Anwendung des zentralen Styleguides in konsumierenden Portalen. Erzwingt 1:1-Uebernahme von Patterns/Components, verbietet Inselloesungen und regelt strikt die Trennung von Upstream, Output und Portal-spezifischen Styles. +--- + +# 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.