# AGENTS.md

## Auftrag

Arbeite in diesem Repository wie an einem kleinen, dateibasierten CSS-Framework. Halte die Architektur schlicht, nachvollziehbar und tokenbasiert.

## Verbindliche Regeln

0. Du kannst stets die `REPO_MAP.md` als Quelle für Informationen nutzen. Verfügbare Prompt-Checklisten in `.opencode/commands/`: `create-component.md`, `add-token.md`, `sync-docs.md`
1. Jede fachliche oder visuelle Aenderung wird in `README.md` dokumentiert.
2. Jede neue oder geaenderte Komponente bekommt in `index.html` eine passende Beispielimplementierung oder eine aktualisierte Demo.
3. Arbeite classless first. Neue Klassen nur einfuehren, wenn semantisches HTML in `base.css` nicht ausreicht.
4. Arbeite token first. Farben, Spacing, Typografie, Radius, Schatten und Transitionen nicht hart verdrahten, sondern ueber `tokens.css` loesen.
5. Aendere in der niedrigsten sinnvollen Schicht: `tokens.css` fuer Systemwerte, `base.css` fuer Element-Styles, `components.css` fuer Komponenten, `utilities.css` fuer kleine Helfer.
6. Halte Utilities klein. Keine Utilities bauen, die komplette Komponenten ersetzen.
7. Nutze bestehende Layoutmuster wie `container`, `stack`, `cluster`, `grid` und `with-sidebar`, bevor du neue Strukturklassen erfindest.
8. Behalte die bestehende Sprache bei: Repo-Dokumentation und Kommentare sind deutsch.
9. Aendere `main.css` nur, wenn sich die Schichtenstruktur des Frameworks wirklich aendert.
10. Minimales JavaScript ist erlaubt wenn: (a) CSS die Aufgabe nicht sinnvoll loesen kann, (b) die Funktion framework-unabhaengig ist und ohne HTMX funktioniert, (c) sie in `framework.js` gehoert und (d) sie in der JS-API-Tabelle in `README.md` dokumentiert wird. Jede Funktion bekommt zusaetzlich eine `data-action` im Objekt `frameworkActions`. Ausnahme: Dark Mode liegt in `theme.js`, weil es vor dem Rendern laufen muss. Projektspezifische Logik (z. B. scrollbasierte Nav) gehoert in eine eigene Datei der Consumer-App, nie in einen Inline-`<script>`. Kein JavaScript fuer rein visuelle Aufgaben.
11. Jede neue oder geaenderte Komponente muss in `.opencode/skills/SKILL.md` (Schnellreferenz-Snippet) und `.opencode/skills/references/components.md` (vollstaendiges Beispiel mit allen Varianten) eingetragen werden. Bei neuen JS-Funktionen zusaetzlich die JS-API-Tabelle in `README.md` aktualisieren.
12. CSP-fest bleiben: keine `on…`-Attribute, keine `style`-Attribute, kein Inline-`<script>` oder `<style>` – weder im Framework noch in Beispielen, Demo und Doku. Stattdessen `data-action`, Klassen, Dateien. Variable Werte (z. B. Fortschritt) ueber `data-…`-Attribute, die `framework.js` per DOM setzt.

## Was zu vermeiden ist

- Keine neuen Abhaengigkeiten, Build-Tools oder Preprocessor ohne explizite Anforderung.
- Kein Tailwind-artiges Wachstum von Utility-Klassen.
- Keine stillen Umbenennungen bestehender Klassen ohne Anpassung von `README.md` und `index.html`.
- Keine README-Aussagen ueber Features, die im aktiven Stand des Repos nicht existieren.

## Mindestvalidierung nach Aenderungen

1. Betroffene Datei auf Syntax- oder LSP-Fehler pruefen (CSS: ausgeglichene Klammern, keine harten Werte).
2. `index.html` mit der Aenderung als Demo- und Sichtpruefflaeche aktuell halten — inklusive Sidebar-Link.
3. `README.md` auf denselben Stand bringen wie Code und Demo.
4. Bei neuen JS-Funktionen: JS-API-Tabelle in `README.md` erganzen.
5. `.opencode/skills/SKILL.md` und `.opencode/skills/references/components.md` auf aktuellen Stand bringen.
6. Falls notwendig, aktualisiere die `REPO_MAP.md` entsprechend.

## Dieses Framework in FastAPI-Apps einsetzen

Fuer Agenten, die in einer Consumer-App (FastAPI + Jinja2 + HTMX) mit diesem Framework arbeiten:

- **Komponenten und Tokens:** `.opencode/skills/SKILL.md`
- **Basis-Template, HTMX-Muster, FastAPI-Patterns:** `.opencode/skills/references/jinja2.md`

Die Datei `jinja2.md` enthaelt ein fertiges `base.html`, alle gaengigen HTMX-Patterns, Formular-Validation mit Pydantic und Dos & Don'ts fuer den Einsatz in FastAPI-Apps.