forked from fa/breadcrumb-the-shire
86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# Frontend CSS
|
|
|
|
Letzte Aktualisierung: 2026-03-19
|
|
|
|
## 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?
|
|
|
|
## 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.
|