Styleguide/.codex/skills/styleguide-erstellung/SKILL.md

---

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