gitea_admin/Styleguide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify strict CSS read scope and streamline AGENTS guide

Browse Source
This commit is contained in:
Mathias Gläser
2026-05-25 08:32:00 +02:00
parent 3e9c273823
commit b659bbc652
1 changed files with 37 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+37 -58
View File
@@ -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).