--- 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