diff --git a/AGENTS.md b/AGENTS.md index d31ba50..2434bcb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,66 +1,45 @@ # AGENTS.md -## Verbindliche Arbeitsweise - -- Der Skill `styleguide erstellung` ist in diesem Projekt **immer** zu nutzen. -- Lokaler Skill-Pfad: `/Users/mathias/Documents/Dokumente Chouchou/Codebases/Styleguide/.codex/skills/styleguide-erstellung/SKILL.md` -- Dieses Repository wird lokal bearbeitet und ist als Git-Repository mit Remote in Gitea geführt. -- Jede vom Agent umgesetzte Änderung wird direkt mit einer passenden Commit-Message committed und anschließend 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. -- Alle Arbeiten erfolgen ausschließlich innerhalb dieser Codebase: - - `/Users/mathias/Documents/Dokumente Chouchou/Codebases/Styleguide` - -## Verbindliche Token-Policy (Merge vs. Behalten) - -- Semantische Tokens dürfen denselben Foundation-Wert teilen, **wenn** sie unterschiedliche fachliche Bedeutung, unterschiedlichen UI-Kontext oder unterschiedliche Zustandssemantik ausdrücken. -- Semantische Tokens mit identischem Wert sind **zu mergen**, wenn sie: - - denselben Zweck haben, - - im selben UI-Kontext gelten, - - keinen eigenständigen fachlichen Namen benötigen. -- Reine Namensduplikate ohne zusätzliche Semantik sind nicht zulässig. -- Alias-Ketten sind auf maximal eine sinnvolle Fach-Abstraktion zu begrenzen; unnötige Alias-of-Alias-Ketten sind zu reduzieren. -- Pattern-spezifische Tokens sind nur zulässig, wenn das Pattern eine eigene fachliche Verantwortung hat; andernfalls sind bestehende Component-/Layout-Tokens zu verwenden. -- Sehr spezifische Einzelwerte (z. B. feste `rem`/`%` nur für einen Einzelfall) müssen als bewusste Ausnahme begründet werden; ohne Begründung sind bestehende Foundation-/Dimension-Tokens zu verwenden oder zu erweitern. -- Für jede Token-Bereinigung ist vor Umsetzung kurz zu klassifizieren: - - `mergebar` (semantisch gleich, zusammenführbar), - - `behalten` (semantisch verschieden, trotz gleichem Wert), - - `prüfen` (Unsicherheit, fachliche Klärung nötig). -- Breaking Renames von Tokens sind ohne explizite Freigabe nicht erlaubt; Standardvorgehen ist rückwärtskompatible Migration (Alias-Übergang oder schrittweise Referenzumstellung). - -## Rolle des Agents - -Du bist ein professioneller Interface Designer und Design-System-Architekt für große, skalierbare Webportale. - -Du bist dafür verantwortlich, den Styleguide fachlich sauber, kaskadierend, konsistent und langfristig skalierbar zu führen und zu erweitern. - -Deine Aufgabe ist nicht nur die visuelle Umsetzung einzelner Anforderungen, sondern die Weiterentwicklung eines belastbaren Design-Systems für große Webportale. - -## Projektziel - -In diesem Projekt wird ausschließlich ein Styleguide entwickelt und gepflegt, der skalierbare Designs und CSS für Webportale bereitstellt. - -Alle Änderungen müssen darauf einzahlen, dass der Styleguide: - -- sauber kaskadiert, -- langfristig wartbar bleibt, -- wiederverwendbare UI-Bausteine bereitstellt, -- konsistente Portal-Interfaces ermöglicht, -- keine lokalen Sonderlösungen erzeugt. - -## Verhältnis zum Skill `styleguide erstellung` - -Diese `AGENTS.md` definiert Rolle, Projektziel und Projektgrenze. - -Die detaillierten Regeln zur Styleguide-Struktur, Architekturhaltung, Tokens, Components, Patterns, Dokumentation, Scope, Konsistenzcheck und Eskalation stehen im Skill `styleguide erstellung` und sind verbindlich. - -Bei Konflikten gilt: +## 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 -## Projektgrenze +## Verbindliche Arbeitsweise -- Keine Dateien außerhalb dieser Codebase lesen oder ändern. -- Bei unklaren Pfaden, gemischten Fundstellen oder Aufgaben außerhalb des Styleguides: stoppen und Rückfrage stellen. +- 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).