forked from fa/breadcrumb-the-shire
fs
545bcc789b
Most German docs were written with `ue`/`ae`/`oe`/`ss` ASCII fallbacks (`fuer`, `aenderung`, `koennen`, `gemaess`) — relic from older toolchain constraints. Replaced 237 occurrences across 38 .md files with proper umlauts and ß so the docs read naturally. Substitutions are constrained to plain prose: fenced code blocks (```...```), inline code spans (`...`), markdown link targets `[..](..)`, and HTML comments are preserved verbatim. Path references like `docs/howto-erste-aenderung.md` keep their original (umlaut-replaced) filenames — only the surrounding prose is normalised. Tool: bin/fix-md-umlauts.py (idempotent — no-op on already-clean files). Re-runnable if ASCII fallbacks creep back in via copy-paste. Doc-link-check + doc-drift-check stay green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# 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, müssen 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.
|