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

Commit current styleguide updates

Browse Source
This commit is contained in:
Mathias Gläser
2026-06-22 18:11:38 +02:00
parent b595347f60
commit c1165315e6
11 changed files with 111 additions and 620 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.codex/skills/styleguide-erstellung/SKILL.md
+83 -90
View File
@@ -1,144 +1,137 @@
---
name: styleguide erstellung
description: Verwenden für jede Weiterentwicklung oder Prüfung des zentralen Styleguides: CSS, HTML, Tokens, Components, Patterns, Layouts, Templates, Doku oder Styleguide-Struktur. Erzwingt ein kaskadierendes, portalübergreifendes Design-System ohne lokale Insellösungen, Workarounds, Hardcoded Design Values oder redundante UI-Bausteine.
name: styleguide-erstellung
description: Verwenden für Arbeiten am zentralen Styleguide: CSS, HTML, Foundation Tokens, semantische Tokens, Components, Patterns, Layouts, Templates, Pages, Doku oder Styleguide-Struktur. Erzwingt ein kaskadierendes, portalübergreifendes Design-System. Keine lokalen Styles, Insel-Tokens, Overrides, Workarounds, hardcoded Design Values, redundanten UI-Bausteine oder visuellen Nachbauten.
---
# Styleguide-Erstellung
## Ziel
Pflege den Styleguide als zentrales Design-System für mehrere modulare Webportale.
Den Styleguide als zentrales Design-System für mehrere Webportale pflegen.
- Core: allgemeine Foundations, semantische Tokens, Components, Patterns und Guidelines für alle Portale.
- Portal-spezifisch: nur klar benannte Layouts/Templates/Pages, z. B. mit Portalname im Dateinamen.
- Ergebnis: cleanes, produktionsreifes Template ohne lokale Styles, Overrides, Workarounds, Legacy-Reste oder visuelle Nachbauten.
Zwingende Kaskade:
## Kaskade
`Foundation Tokens → semantische Tokens → Components → Patterns → Layouts → Templates/Pages → Usage Guidelines`
Immer diese Ebene wählen und einhalten:
Ergebnis muss clean, produktionsreif und frei von lokalen Insellösungen, Legacy-Resten und visuellen Nachbauten sein.
```text
Foundations → semantische Tokens → Components → Patterns → Layouts → Templates/Pages → Usage Guidelines
```
Downstream-Portale sollen Layout und Variation so weit wie möglich über CSS, semantische Tokens und vorhandene Bausteine lösen. HTML-Struktur nur ändern, wenn Semantik, Accessibility, Component-Grenzen oder fachliche Datenstruktur es erfordern.
Regeln:
## Token-Kaskade
- Foundations sind die einzige Quelle konkreter Designwerte: Farben, Typografie, Spacing, Radius, Shadows, Motion, Breakpoints, Z-Index, Containergrößen.
- Neue Foundation Tokens nur nach expliziter Freigabe; bestehende Foundation Tokens bevorzugt wiederverwenden.
- Semantische Tokens sind Aliase/Kaskaden auf Foundation Tokens; nie hardcoded Design Values.
- Components, Patterns, Layouts, Templates, Pages und HTML dürfen keine eigenen Foundation Tokens, lokalen `:root`-Blöcke oder hardcoded Design Values enthalten.
- Jede neue/geänderte CSS-Datei muss in `styleguide.css` importiert sein; `styleguide.css` ist der einzige CSS-Einstiegspunkt.
- Foundation Tokens sind die einzige Quelle roher Designwerte: Farben, Typografie, Spacing, Radius, Shadows, Motion, Breakpoints, Z-Index, Containergrößen.
- Neue Foundation Tokens nur nach expliziter Freigabe; bestehende bevorzugt wiederverwenden.
- Semantische Tokens kontextualisieren Foundation Tokens für konkrete Verwendung, z. B. Component, Pattern, Layout oder Page.
- Semantische Tokens müssen immer auf Foundation Tokens verweisen; nie auf hardcoded Design Values.
- Components, Patterns, Layouts, Templates, Pages und HTML dürfen keine direkten Foundation-Token-Zugriffe, lokalen `:root`-Blöcke, Insel-Tokens oder hardcoded Design Values enthalten.
- Lokale Tokens sind nur erlaubt, wenn sie echte semantische Tokens der passenden Ebene sind, zentral in der zuständigen CSS-Datei gepflegt und über `styleguide.css` importiert werden.
Technische CSS-Werte ohne Designentscheidung sind erlaubt, z. B. `display`, `position`, `overflow`, `width: 100%`, `height: auto`, `flex`, `min-width: 0`.
## Core vs. Portal
- Core: Foundations, globale semantische Tokens, Components und generische Patterns.
- Portal-spezifisch: nur klar benannte Layouts, Templates oder Pages mit Portalname im Dateinamen.
- Portal-spezifische Dateien dürfen Core-Bausteine komponieren, aber nicht duplizieren, überschreiben oder visuell nachbauen.
- Wird eine portal-spezifische Lösung mehrfach relevant, in den Core abstrahieren.
- Fachlogik und Dateninterpretation gehören ins jeweilige Portal/Fachmodul, nicht in den Styleguide.
## Ebenenregeln
### Core vs. Portal
- Foundations, globale semantische Tokens, Components und generische Patterns sind portalübergreifend.
- Portal-spezifische Layouts/Templates/Pages dürfen Core-Bausteine komponieren, aber nicht duplizieren, überschreiben oder visuell nachbauen.
- Portal-spezifische Dateien müssen eindeutig nach Portal benannt sein.
- Wird eine portal-spezifische Lösung für mehrere Portale relevant, abstrahiere sie in den Core.
- Fachliche Bedeutung oder Dateninterpretation gehört ins jeweilige Portal/owning Fachmodul, nicht in den Styleguide.
### Components
- Components sind kanonische UI-Bausteine.
- Ohne Freigabe nicht verändern: HTML, Klassen, Nesting, Semantik, Varianten.
- Ohne Freigabe keine Änderung an HTML, Klassen, Nesting, Semantik oder Varianten.
- Component-Internals nie von außen überschreiben.
- Components nie visuell nachbauen.
- Component-spezifische semantische Tokens in der zuständigen Component-Datei definieren; keine Insel-Tokens im Markup oder in Pages.
### Patterns
- Patterns komponieren bestehende Components für Anwendungsfälle.
- Erlaubt: Pattern-Klassen, Wrapper, Layout, Responsiveness.
- Patterns komponieren bestehende Components für wiederkehrende Anwendungsfälle.
- Erlaubt: Wrapper, Pattern-Klassen, Layout, Responsiveness.
- Verboten: Component-Optik duplizieren, Component-Internals stylen, Components ersetzen.
- Falls ein Pattern Component-Internals stylen müsste: stoppen und Component-Token/-Variante oder andere Architekturentscheidung vorschlagen.
- Pattern-spezifische semantische Tokens nur für Pattern-Kontext definieren und aus Foundations ableiten.
- Wenn ein Pattern Component-Internals stylen müsste: stoppen und Component-Token, Variante oder Architekturentscheidung vorschlagen.
### Layouts und Templates/Pages
### Layouts, Templates und Pages
- Layouts regeln Struktur, Container, Raster, Anordnung und Responsiveness.
- Templates/Pages sind reine Komposition aus Layouts, Patterns und Components.
- Sie dürfen keine neuen Foundations, Token-Logiken, Component-Varianten, lokalen Styles oder visuellen Regeln einführen.
### Dokumentation
Nachführen, wenn betroffen:
- `index.html` bei neuen HTML-Seiten
- `foundations.html` bei Foundation-Änderungen
- semantische Token-Seiten bei Token-Änderungen
- betroffene Component-, Pattern-, Layout-, Template- oder Page-Doku
- Templates/Pages sind Komposition aus Layouts, Patterns und Components.
- Layout, Abstände und Varianten primär über CSS und semantische Tokens lösen, nicht über zusätzliche HTML-Struktur.
- HTML-Struktur nur für Semantik, Accessibility, Component-Grenzen oder fachliche Datenstruktur erweitern.
- Keine neuen Foundations, Component-Varianten, lokalen Styles, Insel-Tokens oder visuellen Regeln einführen.
## CSS-Struktur
- Foundation Tokens: nur in vorgesehenen Foundation-/Base-Dateien, insbesondere `01-foundations.css` und, falls vorhanden/strukturell vorgesehen, `02-base.css`.
- Semantische Tokens: nur in vorgesehenen zentralen Token-Bereichen oder klar zugeordneten Component-/Pattern-/Layout-/Template-Dateien; immer über `styleguide.css` importiert.
- Components, Patterns, Layouts und Templates liegen in eigenen Dateien der passenden Ebene; keine Ebenen vermischen.
- Neue CSS-Datei nur bei klar neuer Verantwortung; sonst bestehende Datei erweitern.
- Portal-spezifische CSS-Dateien nur für klar abgegrenzte Layouts/Templates/Pages und mit Portalname im Dateinamen.
- Import-Reihenfolge: Foundations/Base → globale semantische Tokens → Components → Patterns → allgemeine Layouts → portal-spezifische Layouts → allgemeine Templates/Pages → portal-spezifische Templates/Pages.
- `styleguide.css` ist der einzige CSS-Einstiegspunkt. Jede neue/geänderte CSS-Datei muss dort importiert sein.
- Foundation Tokens nur in vorgesehenen Foundation-/Base-Dateien, insbesondere `01-foundations.css` und ggf. `02-base.css`.
- Semantische Tokens nur in zentralen Token-Bereichen oder in der zuständigen Component-/Pattern-/Layout-/Template-Datei.
- Components, Patterns, Layouts und Templates liegen in Dateien der passenden Ebene; keine Ebenen vermischen.
- Neue CSS-Dateien nur bei klar neuer Verantwortung; sonst bestehende Datei erweitern.
- Keine verwaisten oder unimportierten CSS-Dateien stehen lassen.
Import-Reihenfolge:
`Foundations/Base → globale semantische Tokens → Components → Patterns → allgemeine Layouts → portal-spezifische Layouts → allgemeine Templates/Pages → portal-spezifische Templates/Pages`
## Arbeitsablauf
Vor Umsetzung:
1. Task-Scope bestimmen.
2. Relevanten Code und Doku im Scope prüfen.
3. Ebene bestimmen.
4. Core oder portal-spezifische Erweiterung bestimmen.
5. Bestehende Tokens, Components, Patterns, Layouts und Templates auf Wiederverwendung prüfen.
6. Nötige Doku-Nachführung bestimmen.
7. Bei nicht belegten Punkten Rückfrage stellen.
1. Scope bestimmen.
2. Relevanten Code und Doku prüfen.
3. Richtige Ebene bestimmen.
4. Core oder portal-spezifisch entscheiden.
5. Bestehende Foundations, semantische Tokens, Components, Patterns, Layouts und Templates auf Wiederverwendung prüfen.
6. Prüfen, ob Layout per CSS statt zusätzlicher HTML-Struktur lösbar ist.
7. Betroffene Doku bestimmen.
8. Nicht belegte Punkte nicht umsetzen; bei Bedarf Rückfrage stellen.
Nicht belegte Punkte nicht umsetzen. Aussagen klassifizieren als: belegt, plausibel, nicht belegt.
Aussagen bei Unsicherheit klassifizieren als: belegt, plausibel, nicht belegt.
## Dokumentation
Nachführen, wenn betroffen:
- `index.html` bei neuen HTML-Seiten
- `foundations.html` bei Foundation-Änderungen
- Token-Doku bei semantischen Token-Änderungen
- betroffene Component-, Pattern-, Layout-, Template- oder Page-Doku
## Verbote
Nie einführen oder stehen lassen:
- lokale Styles, lokale `:root`-Blöcke, lokale Token-Blöcke
- lokale Styles, lokale `:root`-Blöcke oder lokale Token-Blöcke
- Insel-Tokens in Components, Patterns, Layouts, Templates, Pages oder HTML
- direkte Foundation-Token-Zugriffe außerhalb semantischer Token-Definitionen
- hardcoded Design Values außerhalb Foundations
- überlagernde Korrektur-Styles statt Ursachenbehebung
- Overrides statt Ursachenbehebung
- Workarounds, Quickfixes oder Legacy-Fehlmuster
- visuelle Nachbauten bestehender Components/Patterns
- portal-spezifische Duplikate von Core-Bausteinen
- Workarounds, Quickfixes, Legacy-Fehlmuster
- unnötige HTML-Wrapper nur für Optik/Layout
- unimportierte oder verwaiste CSS-Dateien
- Refactorings außerhalb Scope ohne Freigabe
Technische CSS-Werte ohne Designentscheidung sind erlaubt, z. B. `display`, `position`, `overflow`, `width: 100%`, `height: auto`, `flex`, `min-width: 0`.
## Abschluss
## Selbstbereinigung vor Abschluss
Vor Abschluss den bearbeiteten Scope aktiv bereinigen:
Vor jeder Abschlussmeldung aktiv bereinigen:
- lokale Insellösungen, Overrides, Workarounds, Legacy-Reste und unsaubere Zwischenlösungen im bearbeiteten Scope entfernen
- lokale Korrekturen auf die richtige Ebene zurückführen: Foundation, semantischer Token, Component, Pattern, Layout oder Template
- keine Aufgabe als fertig melden, solange lokale Styles, hardcoded Werte, visuelle Nachbauten, doppelte Token, unimportierte CSS-Dateien oder veraltete Doku vorhanden sind
## Abschlusscheck
Vor Abschluss bestätigen:
- `AGENTS.md` und dieser Skill beachtet
- richtige Ebene und Core/Portal-Zuordnung gewählt
- Kaskade eingehalten
- keine lokalen Styles, Overrides, Workarounds, Legacy-Reste oder hardcoded Design Values
- neue/geänderte Foundation Tokens korrekt gepflegt und freigegeben
- neue/geänderte semantische Tokens korrekt gepflegt, importiert und dokumentiert
- alle relevanten CSS-Dateien in `styleguide.css` importiert
- Components unverändert bzw. nur mit Freigabe geändert
- Patterns bauen auf Components; Layouts/Templates/Pages bauen auf Patterns/Components
- betroffene Doku nachgeführt
- bearbeiteter Scope ist clean und produktionsreif
## Ergebnisbericht
- Insellösungen, Insel-Tokens, Overrides, Workarounds und Legacy-Reste entfernen.
- lokale Korrekturen auf die richtige Ebene zurückführen: Foundation Token, semantischer Token, Component, Pattern, Layout oder Template.
- Doku und `styleguide.css` aktualisieren.
- sicherstellen, dass Layout-Änderungen primär über CSS und semantische Tokens gelöst sind.
- erst fertig melden, wenn der Scope clean und produktionsreif ist.
Kurz berichten:
- geänderte und geprüfte Dateien
- Ebene und Core/Portal-Einordnung
- verwendete/ergänzte Tokens und Bausteine
- geänderte/geprüfte Dateien
- gewählte Ebene und Core/Portal-Zuordnung
- verwendete oder ergänzte Foundation/semantische Tokens
- verwendete oder ergänzte Bausteine
- ob Layout per CSS statt Struktur gelöst wurde
- nachgeführte Doku
- entfernte Insellösungen/Workarounds, falls vorhanden
- Bestätigung von Abschlusscheck und Selbstbereinigung
- offene Punkte/Freigaben
- entfernte Insellösungen/Workarounds
- offene Punkte oder nötige Freigaben