59 lines
3.4 KiB
Markdown
59 lines
3.4 KiB
Markdown
# 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.
|