238 lines
9.1 KiB
Markdown
238 lines
9.1 KiB
Markdown
---
|
||
name: styleguide erstellung
|
||
description: Verwenden für jede Weiterentwicklung des Styleguides. Erzwingt eine sauber kaskadierende, skalierbare Design-System-Architektur mit klarer Trennung von Foundations, semantischen Tokens, Components, Patterns, Layouts, Templates und Usage Guidelines. Nutze diesen Skill immer, wenn CSS, HTML, Tokens, Components, Patterns, Layouts, Templates, Dokumentation oder Styleguide-Strukturen geändert, erweitert oder geprüft werden.
|
||
---
|
||
|
||
# Styleguide-Erstellung
|
||
|
||
## Ziel
|
||
|
||
Pflege und erweitere den Styleguide als skalierbares Design-System für große Webportale.
|
||
|
||
Jede Änderung muss:
|
||
|
||
- sauber kaskadieren,
|
||
- der richtigen Styleguide-Ebene zugeordnet sein,
|
||
- bestehende Bausteine respektieren,
|
||
- langfristig wartbar und wiederverwendbar sein,
|
||
- zentral über Foundation Tokens und semantische Tokens in `styleguide.css` steuerbar bleiben,
|
||
- ohne lokale Sonderlösungen, visuelle Nachbauten oder Workarounds auskommen.
|
||
|
||
## Verbindliche Struktur und Kaskade
|
||
|
||
Der Styleguide wird nach dieser Kaskade entwickelt:
|
||
|
||
```text
|
||
Foundations / Grundlagen
|
||
→ Semantische Tokens / Design Tokens
|
||
→ Components / Komponenten
|
||
→ Patterns / Muster
|
||
→ Layouts
|
||
→ Templates / Seitentemplates
|
||
→ Usage Guidelines / Anwendungsrichtlinien
|
||
```
|
||
|
||
Jede neue oder geänderte Lösung muss der passenden Ebene zugeordnet werden; Component- und Pattern-Kapitel dokumentieren dabei die semantischen Tokens, die dort verwendet werden.
|
||
|
||
## Ebenenregeln
|
||
|
||
### Foundations
|
||
|
||
Foundations sind die einzige Quelle für konkrete visuelle Werte, z. B. Farben, Typografie, Spacing, Grid, Icons, Shadows, Border-Radius, Motion, Breakpoints, Z-Index und Containergrößen.
|
||
|
||
Neue oder geänderte Foundation-Werte nur nach Rückfrage und expliziter Freigabe einführen.
|
||
|
||
### Semantische Tokens / Design Tokens
|
||
|
||
Semantische Tokens abstrahieren Foundation Tokens nach Bedeutung, Zweck oder Verwendung im Interface und werden zentral in `styleguide.css` gepflegt.
|
||
|
||
Sie benennen nicht den konkreten visuellen Wert, sondern die Rolle im System, z. B. `surface-button-active`, `text-button-process` oder `layout-input-label-width`.
|
||
|
||
Regeln:
|
||
|
||
- Keine hardcoded Design Values außerhalb der Foundations.
|
||
- Semantische Tokens sind Aliase oder Kaskaden auf Foundation Tokens.
|
||
- Neue oder geänderte semantische Tokens an der fachlich passenden Stelle in `styleguide.css` ergänzen.
|
||
- Struktur, Reihenfolge, Gruppierung, Kommentarlogik und Benennungssystematik von `styleguide.css` einhalten.
|
||
- Wenn CSS in Moduldateien (z. B. unter `styles/`) ausgelagert ist, muss jede neue oder umbenannte Moduldatei explizit per `@import` in `styleguide.css` eingehängt werden; unimportierte Moduldateien sind unzulässig.
|
||
- HTML-Dateien dürfen keine lokalen Token-Blöcke, keine eigenen `:root`-Definitionen und keine abweichenden Token-Definitionen enthalten.
|
||
- HTML-Dateien dürfen semantische Tokens nur aus `styleguide.css` referenzieren.
|
||
|
||
Ergänzungen semantischer Tokens dokumentieren mit:
|
||
|
||
- Token-Name
|
||
- Token-Typ: Foundation oder semantischer Token für Component, Pattern, Layout oder Template
|
||
- Wert oder Alias-Ziel
|
||
- kurzer Zweck
|
||
|
||
Wenn Foundation Tokens ergänzt oder geändert werden, `foundations.html` nachführen.
|
||
Wenn semantische Tokens für Components, Patterns, Layouts oder Templates ergänzt oder geändert werden, die passende Token-Dokumentation nachführen, insbesondere `semantic-tokens-components.html`, sofern dort die bestehende Struktur dafür vorgesehen ist.
|
||
|
||
### Components
|
||
|
||
Components sind kanonische, wiederverwendbare UI-Bausteine.
|
||
|
||
Component-Kapitel dokumentieren die semantischen Tokens, die eine Komponente verwendet, jeweils mit zugeordnetem Foundation Token und Verwendungszweck innerhalb der Komponente.
|
||
|
||
Ohne explizite Freigabe nicht erlaubt:
|
||
|
||
- Component-HTML verändern
|
||
- Component-Klassen verändern, ergänzen oder entfernen
|
||
- Component-Nesting verändern
|
||
- Component-Semantik verändern
|
||
- Component-Varianten erfinden
|
||
- Components visuell nachbauen
|
||
- Component-Internals von außen überschreiben
|
||
|
||
### Patterns
|
||
|
||
Patterns kombinieren bestehende Components für konkrete Anwendungsfälle.
|
||
|
||
Pattern-Kapitel dokumentieren die semantischen Tokens, die ein Pattern verwendet, jeweils mit zugeordnetem Foundation Token und Verwendungszweck innerhalb des Patterns.
|
||
|
||
Erlaubt:
|
||
|
||
- eigene Pattern-Klassen
|
||
- eigene Layout-/Wrapper-Strukturen
|
||
- Pattern-spezifische Responsiveness
|
||
- Pattern-spezifische Komposition
|
||
|
||
Nur erlaubt, wenn bestehende Components unverändert eingebettet werden.
|
||
|
||
Verboten ohne Freigabe:
|
||
|
||
```css
|
||
.pattern .component-internal-class { ... }
|
||
.pattern .sg-card-segment { ... }
|
||
.pattern .sg-button__label { ... }
|
||
```
|
||
|
||
Wenn ein Pattern Component-Internals stylen müsste, nicht umsetzen. Rückfrage stellen und begründen, ob ein Component-Token, eine Component-Variante oder eine andere architektonische Lösung nötig ist.
|
||
|
||
### Layouts
|
||
|
||
Layouts regeln Struktur, Container, Raster und Anordnung.
|
||
|
||
Layouts dürfen Flächen strukturieren, Spalten und Container definieren, Abstände zwischen größeren Bereichen steuern und responsive Seitenanordnung regeln.
|
||
|
||
Layouts dürfen keine Component-Optik ersetzen, keine Pattern-Logik nachbauen, keine Component-Internals überschreiben und keine lokalen Designwerte einführen.
|
||
|
||
### Templates
|
||
|
||
Templates beschreiben wiederkehrende Seitentypen.
|
||
|
||
Templates verwenden bestehende Layouts, Patterns und Components. Sie dürfen keine neuen visuellen Grundlagen, Component-Varianten oder Pattern-Logiken erfinden.
|
||
|
||
### Usage Guidelines
|
||
|
||
Usage Guidelines dokumentieren die korrekte Verwendung des Systems.
|
||
|
||
Sie klären insbesondere:
|
||
|
||
- wann welches Pattern verwendet wird,
|
||
- responsive Verhalten,
|
||
- Accessibility,
|
||
- Dos & Don’ts,
|
||
- Abgrenzung ähnlicher Components, Patterns, Layouts oder Templates.
|
||
|
||
Guidelines müssen präzise, praxisnah und konsistent mit der bestehenden Styleguide-Struktur formuliert werden.
|
||
|
||
## Arbeitsablauf
|
||
|
||
Vor jeder Umsetzung:
|
||
|
||
1. Task-Scope bestimmen.
|
||
2. Bestehenden Code und relevante Dokumentation im Scope analysieren.
|
||
3. Styleguide-Ebene der Änderung bestimmen.
|
||
4. Prüfen, ob bestehende Foundation Tokens, semantische Tokens, Components, Patterns, Layouts oder Templates verwendet werden können.
|
||
5. Offene oder nicht belegte Punkte klären.
|
||
|
||
Nicht umsetzen, solange eine notwendige Grundlage fehlt.
|
||
Wenn etwas nicht eindeutig im Code, in der Dokumentation oder in der Aufgabe belegt ist, Rückfrage stellen.
|
||
|
||
## Scope und Grenzen
|
||
|
||
Keine Änderungen außerhalb des expliziten Task-Scopes.
|
||
|
||
Nicht erlaubt ohne Freigabe:
|
||
|
||
- bestehende Components umbauen
|
||
- Foundation Tokens oder semantische Tokens umbenennen
|
||
- Kaskade von Foundation Tokens zu semantischen Tokens verändern
|
||
- CSS-Struktur aufräumen
|
||
- HTML-Struktur verbessern, wenn nicht beauftragt
|
||
- neue Foundation-Werte einführen
|
||
- neue Component-Varianten erfinden
|
||
- bestehende Dokumentationsstruktur neu sortieren
|
||
|
||
Neue HTML-Seiten nur dann in `index.html` ergänzen, wenn tatsächlich neue Seiten angelegt werden. Bei reinen Änderungen bestehender Seiten ist keine `index.html`-Anpassung erforderlich.
|
||
|
||
## Anti-Insellösung
|
||
|
||
Jede Lösung muss systemfähig sein.
|
||
|
||
Verboten:
|
||
|
||
- lokale Styles zur Umgehung der Architektur
|
||
- seitenlokale Sonderregeln statt zentraler Foundation Tokens oder semantischer Tokens
|
||
- visuelle Nachbauten bestehender Components
|
||
- Workarounds, die Architekturdefizite verdecken
|
||
- Legacy-Fehlmuster kopieren
|
||
- direkte Designwerte in Components, Patterns, Layouts, Templates oder HTML-Dateien
|
||
|
||
Technische CSS-Werte sind erlaubt, wenn sie keine Designentscheidung darstellen, z. B.:
|
||
|
||
```css
|
||
display: flex;
|
||
position: relative;
|
||
overflow: hidden;
|
||
min-width: 0;
|
||
width: 100%;
|
||
height: auto;
|
||
flex: 1 1 auto;
|
||
```
|
||
|
||
Wenn unklar ist, ob ein Wert eine Designentscheidung ist: Rückfrage stellen.
|
||
|
||
## Unsicherheiten
|
||
|
||
Bewerte relevante Aussagen als:
|
||
|
||
- **belegt**: direkt im Code oder in der Dokumentation nachweisbar
|
||
- **plausibel**: ableitbar, aber nicht eindeutig belegt
|
||
- **nicht belegt**: benötigt Rückfrage oder Freigabe
|
||
|
||
Nicht belegte Punkte dürfen nicht umgesetzt werden.
|
||
|
||
## Abschlusscheck
|
||
|
||
Vor Abschluss prüfen:
|
||
|
||
- richtige Styleguide-Ebene gewählt
|
||
- Kaskade Foundations → semantische Tokens → Components → Patterns → Layouts → Templates → Usage Guidelines eingehalten
|
||
- keine hardcoded Design Values außerhalb der Foundations
|
||
- neue oder geänderte semantische Tokens in `styleguide.css` gepflegt
|
||
- bestehende Struktur von `styleguide.css` eingehalten
|
||
- bei modularisiertem CSS: alle relevanten Moduldateien sind in `styleguide.css` importiert, keine verwaisten `styles/*.css`
|
||
- betroffene Dokumentation nachgeführt
|
||
- Components unverändert verwendet
|
||
- keine Component-Internals überschrieben
|
||
- Pattern-CSS steuert nur Komposition, Layout und Responsiveness
|
||
- Layout-CSS steuert nur Struktur und Anordnung
|
||
- Templates verwenden bestehende Layouts, Patterns und Components
|
||
- keine lokalen Token-Blöcke oder `:root`-Definitionen in HTML-Dateien
|
||
- keine Refactorings außerhalb Scope
|
||
- keine Insellösungen oder Workarounds eingeführt
|
||
|
||
## Ergebnisbericht
|
||
|
||
Nach Umsetzung kurz berichten:
|
||
|
||
- geänderte Dateien
|
||
- relevante geprüfte Dateien
|
||
- gewählte Styleguide-Ebene
|
||
- verwendete oder ergänzte Foundation Tokens und semantische Tokens
|
||
- verwendete Components, Patterns, Layouts oder Templates
|
||
- nachgeführte Dokumentation
|
||
- offene Punkte oder benötigte Freigaben
|