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

name, description

name

description

styleguide erstellung

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:

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:

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

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