breadcrumb-the-shire/docs/reference-frontend-css.md

# Frontend CSS

Letzte Aktualisierung: 2026-04-20

## Ziel

Diese Seite beschreibt die kompakte Standardstruktur für CSS in diesem Projekt: klar, wartbar und ohne Seiteneffekte.

## Struktur

- `/web/css/core.css`
  - zentraler Core-Entrypoint für die Default-Admin-Oberfläche.
- `/web/css/app-layers.css`
  - zentrale Layer-Reihenfolge + Vendor-Basis.
- `/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', ...)`.

Default-Template:

- `base` lädt Layer-/Token-Basis.
- `core` lädt den konsolidierten Core-Stack über `/web/css/core.css`.

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?
6. Contract-Check lokal ausführen: `bin/css-contract-check.sh`

## Module-CSS Token-Regel

1. Modul-CSS nutzt primär Core-Tokens (`--app-*`) statt eigener Farbwerte.
2. Modul-spezifische Variablen sind als Alias erlaubt, muessen aber auf Core-Tokens mappen.
3. Keine Legacy-/Phantom-Tokens (`--app-text`, `--app-hover`, `--app-border-light`) neu einführen.
4. Harte Hex-Fallbacks nur als Ausnahmefall, nicht als Standard.