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

---

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.

Styleguide-Erstellung

Ziel

Pflege den Styleguide als zentrales Design-System für mehrere modulare Webportale.

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

Kaskade

Immer diese Ebene wählen und einhalten:

Foundations → semantische Tokens → Components → Patterns → Layouts → Templates/Pages → Usage Guidelines

Regeln:

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

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.
• Component-Internals nie von außen überschreiben.
• Components nie visuell nachbauen.

Patterns

• Patterns komponieren bestehende Components für Anwendungsfälle.
• Erlaubt: Pattern-Klassen, Wrapper, 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.

Layouts und Templates/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

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.

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.

Nicht belegte Punkte nicht umsetzen. Aussagen klassifizieren als: belegt, plausibel, nicht belegt.

Verbote

Nie einführen oder stehen lassen:

• lokale Styles, lokale :root-Blöcke, lokale Token-Blöcke
• hardcoded Design Values außerhalb Foundations
• überlagernde Korrektur-Styles statt Ursachenbehebung
• visuelle Nachbauten bestehender Components/Patterns
• portal-spezifische Duplikate von Core-Bausteinen
• Workarounds, Quickfixes, Legacy-Fehlmuster
• 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.

Selbstbereinigung vor Abschluss

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

Kurz berichten:

• geänderte und geprüfte Dateien
• Ebene und Core/Portal-Einordnung
• verwendete/ergänzte Tokens und Bausteine
• nachgeführte Doku
• entfernte Insellösungen/Workarounds, falls vorhanden
• Bestätigung von Abschlusscheck und Selbstbereinigung
• offene Punkte/Freigaben