Initial commit

docs/design-system.md

@@ -0,0 +1,114 @@
+# Designsystem
+
+Das Frontend verwendet ein eigenes, schlankes Designsystem ohne externe
+UI-Library. Es besteht aus zentralen CSS Custom Properties, globalen
+Grundklassen und wenigen Angular-UI-Komponenten unter
+`apps/frontend/src/app/shared/ui`.
+
+## Prinzipien
+
+- sachliche Business-Oberflaeche statt Marketing-Optik
+- mobile first, keine globale Mindestbreite
+- klare Hierarchie durch Typografie, Abstand und Rahmen
+- Farben immer semantisch ueber Tokens
+- sichtbare Fokuszustaende und grosse Touch-Flaechen
+- Komponenten nur dort, wo sie Verhalten oder Wiederverwendung bringen
+
+## Tokens
+
+Die Tokens liegen in `apps/frontend/src/styles/_tokens.scss` und werden ueber
+`apps/frontend/src/styles.scss` eingebunden.
+
+Wichtige Gruppen:
+
+- Farben: `--color-primary`, `--color-danger`, `--color-surface`,
+  `--color-text-primary`, `--color-border`, `--color-focus`
+- Abstaende: `--space-1` bis `--space-9`
+- Typografie: `--font-size-xs` bis `--font-size-2xl`, `--line-height-*`,
+  `--font-weight-*`
+- Layout: `--container-width`, `--sidebar-width`, `--header-height`,
+  `--touch-target`, `--input-height`, `--button-height`
+- Oberflaeche: `--radius-*`, `--shadow-*`, `--z-*`, `--transition-*`
+
+Feature-Komponenten duerfen keine direkten Hex-Farben enthalten. Neue Farben
+werden zuerst als semantische Tokens angelegt.
+
+## Globale Klassen
+
+Globale Klassen sind bewusst begrenzt:
+
+- Layout: `.ui-page`, `.ui-page-header`, `.ui-grid`, `.ui-card`,
+  `.ui-toolbar`, `.ui-actions`
+- Formulare: `.ui-form`, `.ui-form-field`, `.ui-control`, `.ui-checkbox`,
+  `.ui-field-error`
+- Buttons: `.ui-button`, `.ui-icon-button`
+- Tabellen: `.ui-table-wrap`, `.ui-table`
+- Status: `.ui-badge`, `.ui-badge--success`, `.ui-badge--warning`,
+  `.ui-badge--danger`, `.ui-badge--info`
+- Utilities: `.visually-hidden`, `.truncate`, `.stack`, `.cluster`,
+  `.full-width`, `.text-muted`
+
+Keine neuen Utility-Klassen einfuehren, wenn eine lokale Klasse oder bestehende
+UI-Komponente ausreicht.
+
+## Angular-Komponenten
+
+Wiederverwendbare UI-Bausteine:
+
+- `UiButtonComponent`
+- `UiIconComponent`
+- `UiIconButtonComponent`
+- `UiFormFieldComponent`
+- `UiStatusBadgeComponent`
+- `UiConfirmDialogComponent`
+- `ToastService` und `UiToastHostComponent`
+- `UiEmptyStateComponent`
+- `UiLoadingStateComponent`
+- `UiPaginationComponent`
+- `UiPageHeaderComponent`
+
+Neue Feature-Seiten sollen diese Bausteine bevorzugen, wenn sie Button-, Badge-,
+Dialog-, Toast-, Empty-, Loading- oder Pagination-Verhalten brauchen.
+
+## Responsive Regeln
+
+- Mobile Layouts sind einspaltig.
+- Aktionen duerfen mobil untereinander stehen und volle Breite nutzen.
+- Business-Listen werden mobil als Karten dargestellt.
+- Tabellen liegen in `.ui-table-wrap`, wenn eine echte Tabelle sinnvoll bleibt.
+- Touch-Ziele orientieren sich an `--touch-target`.
+- Breakpoints werden in rem formuliert und nicht nach Geraetetyp benannt.
+
+## Accessibility
+
+- native HTML-Elemente vor ARIA verwenden
+- interaktive Elemente sind Buttons oder Links
+- sichtbare Fokuszustaende nicht entfernen
+- Labels ersetzen Placeholder nicht
+- Fehlertexte stehen direkt am Feld
+- Status ist nicht nur Farbe, sondern auch Text/Marker
+- Dialoge setzen Fokus, schliessen per Escape und geben Fokus zurueck
+- Navigation und Drawer sind per Tastatur bedienbar
+- Animationen respektieren `prefers-reduced-motion`
+
+## Entwicklungsseite
+
+Die interne Referenzseite liegt unter:
+
+```text
+/dev/design-system
+```
+
+Sie ist mit `devOnlyGuard` geschuetzt und im Production-Modus nicht matchbar.
+Sie ersetzt kein Storybook, sondern zeigt die vorhandenen Tokens und Komponenten
+innerhalb der echten Anwendung.
+
+## Regeln fuer neue UI
+
+1. Bestehende UI-Komponenten oder globale Klassen wiederverwenden.
+2. Keine direkte Hex-Farbe in Feature-Komponenten.
+3. Keine neue UI-Library einfuehren.
+4. Keine tiefen Selektoren, kein `::ng-deep`, kein unkontrolliertes
+   `!important`.
+5. Keine klickbaren `div`-Elemente als Ersatz fuer Buttons oder Links.
+6. Verhalten mit Vitest testen, insbesondere Accessibility-relevante Zustaende.