docs: restructure docs to diataxis and finalize DOCS-RESTRUCTURE-001

docs/reference-frontend-css.md

@@ -0,0 +1,78 @@
+# Frontend CSS
+
+Letzte Aktualisierung: 2026-03-06
+
+## Ziel
+
+Diese Seite beschreibt die kompakte Standardstruktur für CSS in diesem Projekt: klar, wartbar und ohne Seiteneffekte.
+
+## Struktur
+
+- `/web/css/app-layers.css`
+  - zentraler Entrypoint für Layer-Reihenfolge.
+- `/web/css/base`
+  - Variablen, Reset, Typografie, globale Tokens.
+- `/web/css/layout`
+  - Layout-Bausteine (Sidebar, Header, Main-Layout).
+- `/web/css/components`
+  - wiederverwendbare UI-Teile.
+- `/web/css/pages`
+  - seitenbezogene Styles mit engem Scope.
+- `/web/css/vendor-overrides`
+  - gezielte Overrides für externe Libraries.
+
+## Grundregeln
+
+1. Neue Styles immer so lokal wie möglich einordnen:
+   - erst `components`/`layout`,
+   - `pages` nur bei echtem Seitenspezifikum.
+2. Keine globalen Überschreibungen ohne Scope.
+3. Bestehende CSS-Variablen bevorzugen, keine neuen Farbwerte „inline“ verteilen.
+4. Vendor-Anpassungen ausschließlich in `/web/css/vendor-overrides`.
+
+## Entscheidungsmatrix: Neue Datei oder bestehende erweitern?
+
+| Situation | Empfehlung | Zielpfad |
+| --- | --- | --- |
+| Bestehende Komponente bekommt kleine visuelle Erweiterung | Bestehende Datei erweitern | `/web/css/components/<bestehend>.css` |
+| Neuer wiederverwendbarer UI-Baustein (mind. auf 2 Seiten) | Neue Komponentendatei anlegen | `/web/css/components/<neu>.css` |
+| Änderung betrifft globales Layout (Sidebar, Header, Main) | Bestehende Layout-Datei erweitern | `/web/css/layout/<bestehend>.css` |
+| Änderung ist nur für eine konkrete Seite relevant | Neue/ bestehende Seiten-Datei nutzen | `/web/css/pages/<seite>.css` |
+| Externe Library muss übersteuert werden (Grid.js, Swagger UI) | Nur Vendor-Override ändern | `/web/css/vendor-overrides/<vendor>.css` |
+| Neue Farben/Abstände/Typografie-Tokens werden benötigt | Erst Variablen in Base ergänzen, dann verwenden | `/web/css/base/*` |
+
+Kurzregel:
+- **Bestehende Datei erweitern**, wenn Scope und Verantwortung klar gleich bleiben.
+- **Neue Datei anlegen**, wenn ein neuer klarer Verantwortungsbereich entsteht.
+
+## Einbindung von Styles
+
+Asset-Gruppen werden in `/config/assets.php` registriert.  
+Seiten laden bei Bedarf Gruppen über `Buffer::set('style_groups', ...)`.
+
+Beispiel (Action):
+
+```php
+Buffer::set('style_groups', json_encode(['api-docs']));
+```
+
+## Benennungs- und Scope-Konvention
+
+- Klassen konsistent mit `app-`-Präfix halten, wenn es eigene Komponenten sind.
+- Status/Varianten über bestehende Attribute/Klassen abbilden (z. B. `data-variant`), nicht über zusätzliche Einmal-Klassen.
+- Selektoren kurz halten, keine unnötig tiefen Ketten.
+
+## Grid/Vendor
+
+- Grid.js-spezifische Anpassungen: `/web/css/vendor-overrides/gridjs.css`
+- Swagger UI-spezifische Anpassungen: `/web/css/vendor-overrides/swagger-ui.css`
+
+Regel: Vendor-Overrides nur für Bibliotheks-Selektoren; projektspezifische UI-Stile in `components`/`pages`.
+
+## Checkliste vor Merge
+
+1. Liegt die Datei im richtigen Ordner (`components`, `layout`, `pages` oder `vendor-overrides`)?
+2. Ist die Asset-Gruppe in `/config/assets.php` korrekt?
+3. Wird die Gruppe auf der Zielseite wirklich geladen (`style_groups`)?
+4. Gibt es ungewollte Seiteneffekte auf anderen Seiten?
+5. Sind bestehende Variablen/Konventionen eingehalten?