138 lines
7.0 KiB
Markdown
138 lines
7.0 KiB
Markdown
---
|
|
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
|
|
|
|
Den Styleguide als zentrales Design-System für mehrere Webportale pflegen.
|
|
|
|
Zwingende Kaskade:
|
|
|
|
`Foundation Tokens → semantische Tokens → Components → Patterns → Layouts → Templates/Pages → Usage Guidelines`
|
|
|
|
Ergebnis muss clean, produktionsreif und frei von lokalen Insellösungen, Legacy-Resten und visuellen Nachbauten sein.
|
|
|
|
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.
|
|
|
|
## Token-Kaskade
|
|
|
|
- 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
|
|
|
|
### Components
|
|
|
|
- Components sind kanonische UI-Bausteine.
|
|
- 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 wiederkehrende Anwendungsfälle.
|
|
- Erlaubt: Wrapper, Pattern-Klassen, Layout, Responsiveness.
|
|
- Verboten: Component-Optik duplizieren, Component-Internals stylen, Components ersetzen.
|
|
- 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, Templates und Pages
|
|
|
|
- Layouts regeln Struktur, Container, Raster, Anordnung und Responsiveness.
|
|
- 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
|
|
|
|
- `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. 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.
|
|
|
|
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 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
|
|
- Overrides statt Ursachenbehebung
|
|
- Workarounds, Quickfixes oder Legacy-Fehlmuster
|
|
- visuelle Nachbauten bestehender Components/Patterns
|
|
- portal-spezifische Duplikate von Core-Bausteinen
|
|
- unnötige HTML-Wrapper nur für Optik/Layout
|
|
- unimportierte oder verwaiste CSS-Dateien
|
|
- Refactorings außerhalb Scope ohne Freigabe
|
|
|
|
## Abschluss
|
|
|
|
Vor Abschluss den bearbeiteten Scope aktiv bereinigen:
|
|
|
|
- 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/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
|
|
- offene Punkte oder nötige Freigaben
|