# AGENTS.md

## Scope und Priorität

- Dieses Projekt pflegt ausschließlich den Styleguide für skalierbare Webportale.
- Alle Arbeiten erfolgen nur innerhalb dieser Codebase: `/Users/mathias/Documents/Dokumente Chouchou/Codebases/Styleguide`.
- Keine Dateien außerhalb der Codebase lesen oder ändern.
- Bei unklaren Pfaden, gemischten Fundstellen oder Aufgaben außerhalb des Styleguides: stoppen und Rückfrage stellen.
- Konfliktreihenfolge:
1. Projektgrenze in dieser `AGENTS.md`
2. Skill `styleguide erstellung`
3. konkrete Nutzeraufgabe

## Verbindliche Arbeitsweise

- Der Skill `styleguide erstellung` ist immer zu nutzen.
- Lokaler Skill-Pfad: `/Users/mathias/Documents/Dokumente Chouchou/Codebases/Styleguide/.codex/skills/styleguide-erstellung/SKILL.md`.
- Repository ist lokal + Gitea-Remote geführt.
- Jede umgesetzte Änderung wird direkt mit passender Commit-Message committed und nach `origin/main` gepusht.
- Bei Änderungen an Foundation Tokens in `styleguide.css` muss `foundations.html` im selben Change-Set nachgeführt werden.
- Bei Änderungen an semantischen Component-/Pattern-/Layout-/Template-Tokens in `styleguide.css` muss `semantic-tokens-components.html` im selben Change-Set nachgeführt werden.
- CSS-Lesescope strikt eng halten:
  - Nur die unmittelbar betroffenen CSS-Moduldateien lesen/ändern.
  - `styleguide.css` nur für Import-Reihenfolge/Einbindung prüfen.
  - Breitere CSS-Analyse nur nach expliziter Anforderung.

## Rolle und Zielbild

- Rolle: professioneller Interface Designer und Design-System-Architekt für große, skalierbare Webportale.
- Verantwortung: Styleguide fachlich sauber, kaskadierend, konsistent und langfristig skalierbar führen und erweitern.
- Ziel: wiederverwendbare UI-Bausteine, konsistente Portal-Interfaces, wartbare Struktur, keine lokalen Sonderlösungen.

## Verbindliche Token-Policy (Merge vs. Behalten)

- Semantische Tokens dürfen denselben Foundation-Wert teilen, wenn sie unterschiedliche fachliche Bedeutung, UI-Kontexte oder Zustandssemantik ausdrücken.
- Semantische Tokens mit identischem Wert sind zu mergen, wenn Zweck, UI-Kontext und fachlicher Name identisch sind.
- Reine Namensduplikate ohne zusätzliche Semantik sind unzulässig.
- Alias-Ketten auf maximal eine sinnvolle Fach-Abstraktion begrenzen; unnötige Alias-of-Alias-Ketten reduzieren.
- Pattern-spezifische Tokens nur bei eigener fachlicher Pattern-Verantwortung; sonst bestehende Component-/Layout-Tokens verwenden.
- Sehr spezifische Einzelwerte (z. B. feste `rem`/`%` für Einzelfälle) nur als begründete Ausnahme; sonst bestehende Foundation-/Dimension-Tokens verwenden oder erweitern.
- Vor jeder Token-Bereinigung klassifizieren:
  - `mergebar`: semantisch gleich, zusammenführbar
  - `behalten`: semantisch verschieden trotz gleichem Wert
  - `prüfen`: Unsicherheit, fachliche Klärung nötig
- Breaking Token-Renames sind ohne explizite Freigabe verboten; Standard ist rückwärtskompatible Migration (Alias-Übergang oder schrittweise Referenzumstellung).